App Setup Events

Some apps may require a certain amount of setup in order to function correctly. For example apps that need to react to External Events require a webhook to be created when the app is installed and deleted when it is uninstalled. Another example is when an app needs an initial set of values to be populated in the data store. These use cases can be achieved with the following app setup events:

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 a 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 Freshdesk account ID
domain string Freshdesk account domain
event string Name of the event
region string Region where the app is installed, will be either "US", "EU", or "EUC"
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
12
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 function for an event.


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."});

Sample code with successful response:

Copied Copy
1
2
3
4
5
6
7
8
9
10
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
9
10
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
{ "timestamp" : 1496400354326, "account_id" : 13, "domain" : "sample.freshdesk.com", "event" : "onAppInstall", "region" : "US", "iparams": null }
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."});

Sample code with successful response:

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

Sample code with failure response:

Copied Copy
1
2
3
4
5
6
7
8
9
10
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
{ "timestamp" : 1496400354326, "account_id" : 13, "domain" : "sample.freshdesk.com", "event" : "onAppUninstall", "region" : "US", "iparams": null }

Log in with your Freshdesk account

Enter your helpdesk URL to proceed to login

Proceed

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