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, specifying the scheduled-event’s name and the corresponding callback method as follows:

    "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.

Call to attention:

There are two payloads in play here:

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

Take a look at the Scheduled events Freshdesk sample app for a demonstration of this feature.

Create scheduled events

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

Create event

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

Syntax
$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>",
});

$schedule interface call attributes

  • namestringRequired

    Unique identifier of the schedule.

  • dataobjectRequired

    Payload passed to the event listener. From the listener, this payload is again passed to the callback as part of the standard callback payload. When creating a schedule, ensure that the payload is a JSON payload and the size does not exceed 4 KB.

  • schedule_atstringRequired

    Time at which the schedule is triggered.

    For recurring events, it is the time when the event starts occurring.

  • repeatobject

    Required for recurring schedules

    Repeat pattern for recurring schedules.

Fetch details of a scheduled event

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.

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

Update scheduled event

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.

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

Delete scheduled event

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.

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

Attributes of the payload to callback

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

  • account_idstring

    The Freshdesk account ID.

  • dataobject

    Payload that is passed to the event listener when the event occurs.

  • domainstring

    The Freshdesk account domain.

  • eventstring

    The name of the event (onScheduledEvent).

  • iparamsobject

    Installation parameters.

  • regionstring

    Region where the Freshdesk account is deployed.

    Possible values: US, EU, EUC, AUS, and IND.

  • timestampinteger

    Represents the time (epoch format) when the event was received.

Test

Notes:
  • Use the latest version of Chrome browser.
  • Ensure that the onScheduledEvent.json file, which contains the sample payload to test scheduled events, is available at <app's root directory>/server/test_data.

When testing scheduled events on your computer, schedules will be triggered at the specified time and frequency after they are created or updated.

To simulate an event and test your app:

  1. From the command line, navigate to the directory that contains the app related files and run the following command.
    fdk run
  2. In the address bar of the browser, enter https://localhost:10001/web/test. A dialog box is displayed.
  3. Click Select an event. The list of all events configured in the server.js file is displayed. Note: To test scheduled events, select onScheduledEvent.
  4. Select an event. The corresponding payload is displayed. To test a different scenario other than the default, edit the payload.
  5. Click Simulate. If the event is successfully simulated, the Simulate button changes to a Success button. If the event simulation fails because of invalid payload data, the Simulate button changes to a Failed button. Modify the payload appropriately and click Simulate.