Configure scheduled events

Scheduled events are events that you can create with the purpose of triggering certain app actions.

To configure scheduled events and enable your app to react to these events,

1. Create scheduled events.

2. Subscribe to a scheduled event by configuring an event listener: In manifest.json, include the events attribute within the modules.common object, specifying the scheduled-event’s name and the corresponding callback method as follows:

   "modules": {
     "common": {
       "events": {
         "<eventName>": {
           "handler": "<eventCallbackMethod>"
         }
       }
     }
   }

   On schedules, the events occur and pass a payload (data) to the listeners that have subscribed to the event. The event listener invokes the registered callback method and passes a standard payload to the method. As part of this payload, the event listener passes the data that it received from the scheduled event.

3. Navigate to the server.js file. In the exports block, enter the callback function/method definition.

   Sample server.js

   exports = {
     onScheduledEventHandler: function(payload) {
       console.log("Logging arguments from onScheduledEvent: " + JSON.stringify(payload));
       if (payload.data.account_id === "3") {
       //app logic
       }
     }
   };

Important:Ensure that only one callback function/method is defined for an event.

Note:The default app execution timeout is 20 seconds. If the request timeout is increased to 20, 25, or 30 seconds, the app execution timeout is extended to 40 seconds.

Sample use case: The app can poll an external product every hour for updates and make corresponding changes in the Freshworks product.

To create one-time or recurring scheduled events, the developer platform offers the $schedule interface. As part of the app logic you can,

• Create a scheduled event.
• Fetch the details of a created event.
• Update the scheduled event.
• Delete the scheduled event.

Use the following interface call syntax (and the SAMPLE SERVER.JS on the right pane) to create a scheduled event.

$schedule.create({
  name: "<scheduled-event-name>",
  data: {<JSON object payload passed to event listener>},
  schedule_at: "<time when the event should occur, in UTC format>",
});

As part of the app logic, you can fetch the details of a scheduled event and decide to act on it - such as updating or deleting the schedule. Use the following interface call (and the sample SERVER.JS on the right pane) to fetch the details of a scheduled event.

$schedule.fetch({name: "<scheduled-event-name>"});

As part of the app logic, an app can modify an existing schedule. Use the following interface call syntax (and the sample SERVER.JS on the right pane) to modify a scheduled event.

$schedule.update({name: "<scheduled-event-name>", schedule_at: "<updated-value>"});

As part of the app logic, an app can delete an existing schedule. Use the following interface call syntax (and the sample SERVER.JS on the right pane) to delete a scheduled event.

$schedule.delete({name: "<scheduled-event-name>"});

When the scheduled event occurs, the configured event listeners invoke the registered callback method and pass a standard payload.

1. From the command line, navigate to the directory that contains the app related files and run the fdk run command. The FDK starts the local test server. The test URLs to access the product UI, the App Settings page (or Custom installation page), and the URL to the serverless events simulation page are displayed.

2. Navigate to the system settings page at http://localhost:10001/system_settings. All modules configured in the App manifest are listed.

3. In the system settings page,

   1. Select the modules for which you want to test the app logic. The Enter account URL section is displayed, with a prompt to enter the account URLs for all selected modules.
   2. In the Enter account URL section, enter valid account URL(s) for the product(s) to which the selected modules belong. During app testing, this URL plays the role of the currentHost. Based on the currentHost, the currentHost.subscribed_modules and currentHost.endpoint_urls are determined.
   3. Click Continue.

4. If you have configured installation parameters for the app, the App Settings page is displayed at http://localhost:10001/custom_configs. Enter appropriate values for the installation parameters and click Install.

   Note:If you have not configured any installation parameters, a page is displayed with information on the configured system settings. A message stating that the app does not have an installation page is displayed.

5. Navigate to http://localhost:10001/web/test to test the serverless events that the app uses. All modules that you select in the system settings page, for which serverless events are registered in the app manifest, are listed in the Select module drop-down.

   Note:The payloads of all serverless events that are registered in the app manifest are populated in the server/test_data folder. During the actual runtime, the payloads that are passed to the serverless event contain the currentHost attribute. In the local simulation, the payloads in server/test_data do not contain this attribute. During testing, the modules and account URLs entered in the system settings page are passed as the currentHost data.

6. From the Select module drop-down, select Common. The Select an event drop-down is displayed and it lists all the events configured (in the app manifest) for the common module.

7. From the Select an event drop-down, select onScheduledEvent. The payload for the event is populated on the page.

8. Click Simulate. If the event is simulated successfully, the Simulate button’s display name changes to Success. The event payload is added to the <app's root directory>/server/test_data folder.

9. To test more events, select another appropriate module and event and click Simulate. If the event simulation fails because of invalid payload data, the Simulate button’s display name changes to Failed. Modify the payload appropriately and click Simulate.