App Setup Events

These events are triggered when the user installs or uninstalls your app from the Marketplace:

The app setup events are synchronous which means that the callback method for the event can decide whether to allow or disallow the completion of the event. For example, during installation, you want to register a webhook or store some initial values in the database. If these actions fail, the app may not function correctly and hence the callback should disallow the installation.

Payload

When an app setup event occurs, the corresponding method in the server.js is invoked and the following payload is passed to the app to enable it to get context about the event:

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
{ "account_id" : "value", "domain" : "value", "event" : "value", "region" : "value", "timestamp" : "value", "iparams" : { "Param1" : "value", "Param2" : "value" } }
EXPAND ↓

Attribute Type Description
account_id number Freshservice account ID
domain string Freshservice account domain
event string Name of the event
region string Region where the app is installed, will be either "US", "EU", "EUC", or "AUS"
timestamp number App Installation timestamp in the epoch format
iparams object Installation parameters

Registration

In order for the appropriate method to be called when an app setup event occurs, an event listener should be added. This should be done in the format as shown in the sample below.


server.js Copied Copy
1
2
3
4
5
6
7
8
9
10
11
exports = { events: [ { event: "eventName", callback: "eventCallbackMethod" }], eventCallbackMethod: function(payload) { console.log("Logging arguments from the event: " + JSON.stringify(payload)); // If the setup is successful renderData(); // If there is an error during the setup renderData({message: "Error message"}); } }
EXPAND ↓

Note:
1. You should include the event and the callback definition within the exports block.
2. You should include only one callback method for an event.
3. You should only use valid keys - event and callback, usage of other keys will throw an error.

onAppInstall

This event occurs when the Install button is clicked. The registered callback method for the onAppInstall event will be executed in response to this event.

To denote that the callback was successful, the developer must use the renderData() method without any arguments. The installation of the app will then proceed.

renderData();

If an error occurred in the callback, the developer should pass a relevant error message using the renderData() method. The message should be of type string and should not exceed 60 characters:

renderData({message: "Installation failed due to network error."});

Follow the format below to include the event in the server.js:

Copied Copy
1
2
3
4
5
6
7
8
9
exports = { events: [ { event: "onAppInstall", callback: "onAppInstallCallback" }], onAppInstallCallback: function(payload) { console.log("Logging arguments from onAppInstallevent: " + JSON.stringify(payload)); // If the setup is successful renderData(); } }

Sample code with failure response:

Copied Copy
1
2
3
4
5
6
7
8
exports = { events: [{ event: "onAppInstall", callback: "onAppInstallCallback" }], onAppInstallCallback: function(payload) { console.log("Logging arguments from onAppInstallevent: " + JSON.stringify(payload)); // If there is an error during the setup, see screenshot below renderData({message: "Invalid API Key"}); } }

Sample Payload
1
2
3
4
5
6
7
8
9
10
11
{ "account_id" : 13, "domain" : "sample.freshservice.com", "event" : "onAppInstall", "timestamp" : 1496400354326, "region" : "US", "iparams": { "username": "Rachel", "url": "http://sample.freshservice.com" } }
EXPAND ↓
onAppUninstall

This event occurs when the uninstall icon is clicked. The registered callback method for the onAppUninstall event will be executed in response to this event.

To denote that the callback was successful, the developer must use the renderData() method without any arguments. The uninstallation of the app will then proceed.

renderData();

If an error occurred in the callback, the developer should pass a relevant error message using the renderData() method. The message should be of type string and should not exceed 60 characters:

renderData({message: "Uninstallation failed due to network error."});

You should follow the below format to include the event in the server.js:

Copied Copy
1
2
3
4
5
6
7
8
9
exports = { events: [ { event: "onAppUninstall", callback: "onAppUninstallCallback" }], onAppUninstallCallback: function(payload) { console.log("Logging arguments from onAppUninstall event: " + JSON.stringify(payload)); // If the setup is successful renderData(); } }

Sample code with failure response:

Copied Copy
1
2
3
4
5
6
7
8
9
exports = { events: [ { event: "onAppUninstall", callback: "onAppUninstallCallback" }], onAppUninstallCallback: function(payload) { console.log("Logging arguments from onAppUninstall event: " + JSON.stringify(payload)); // If there is an error during the setup, see screenshot below renderData({message: "Uninstallation failed due to network error."}); } }
Sample Payload
1
2
3
4
5
6
7
8
9
10
11
{ "timestamp" : 1496400354326, "account_id" : 13, "domain" : "sample.freshservice.com", "event" : "onAppUninstall", "region" : "US", "iparams": { "username": "Rachel", "domain": "sample.freshservice.com" } }
EXPAND ↓
Local Testing

You can easily test your app in your machine by simulating events. Also, you can test different scenarios by directly modifying the payload.

Note:
As the testing is only a simulation of events, an actual event will not be recorded in the back end. If you need an actual ticket/contact to be created, it is recommended that you publish your app as a custom app and test the operation manually.

To simulate events for local testing, follow the procedure outlined below.

  1. In your console, navigate to your project directory and execute the following command. $ fdk run
  2. Open your browser and enter the following URL to start testing your app: http://localhost:10001/web/events.
  3. Select the event that you want to simulate.
  4. Once you select an event, the corresponding event payload is displayed. Edit the values and then click Simulate. When you edit the payload, ensure that you adhere to the JSON format.
  5. If the event is successfully simulated, you will see Success displayed.
  6. If there is a problem, you will see Failed displayed. Check if the payload is valid and then resume testing.

Log in with your Freshservice account

Enter your helpdesk URL to proceed to login

Proceed

By clicking "Proceed", you agree to our Terms of Use.