App Setup Events

Events that occur when an app is installed from the Freshworks Marketplace or uninstalled are termed as app setup events. An app setup event is a synchronous event and you can enable your app to decide whether the event should reach completion. For example, if a webhook has to be registered during app installation, you can use the app setup event to disallow installation if the webhook registration fails. You can configure event listeners in the manifest.json file. When an app setup event occurs, the corresponding event listener invokes a callback method defined in server.js and passes a standard payload to the method.

Configure Events

To register an app setup event and the corresponding callback:

  1. From your app’s root directory, navigate to the manifest.json file.
  2. Include the events attribute, specifying the app setup event (possible events: onAppInstall and onAppUninstall) and the corresponding callback methods as follows:
    Copied Copy
    1
    2
    3
    4
    5
    "events": { "<eventName>": { "handler": "<eventCallbackMethod>" } }

    Note: Include only one callback method for an event.

  3. Navigate to the server.js file.
  4. In the exports block, enter the callback function definition as follows:
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    exports = { // args is a JSON block containing the payload information // args["iparam"] will contain the installation parameter values //eventCallbackMethod is the call-back function name specified in manifest.json eventCallbackMethod: function(args) { 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 ↓

Payload Attributes

When an app setup event occurs, a payload is passed to the callback method.

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 ↓

The payload is a JSON object with the following attributes.

Attribute Type Description
account_id string Identifier of the Freshsales account, auto-generated when the account is configured for a business.
domain string Domain name for the Freshsales account.
event string Identifier of the app setup event.
Possible values: onAppInstall, onAppUninstall
region string Region where the Freshsales account is deployed.
Possible values: US, EU, EUC, AUS, and IND
timestamp number Timestamp of when the app setup event occurs, specified in the epoch format.
iparams object Installation parameters specified as a JSON object of <parameter name>: <parameter value> pairs.

Sample payload Copied Copy
1
2
3
4
5
6
7
{ "timestamp": 1583839686, "account_id": "12345", "domain": "https://sample.myfreshworks.com", "event": "onAppInstall", "region": "US" }
EXPAND ↓
onAppInstall

When an app user clicks the Install button corresponding to the app, the onAppInstall event is triggered. For app installation to reach completion, in the callback function definition, use the renderData() method without any arguments. To disallow app installation if a mandatory action fails, use an error object as the argument - renderData({error-object}).

error-object attribute
Attribute Name Data Type Description
message
Mandatory
string Message indicating why the mandatory action failed. Should not exceed 60 characters.

For example,

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

Register the onAppInstall event by using the following sample manifest.json content:

Copied Copy
1
2
3
4
5
"events": { "onAppInstall": { "handler": "onAppInstallCallback" } }

Define the corresponding callback that allows completion of installation by using the following sample server.js content:

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

Define the corresponding callback that disallows installation if a mandatory action fails, by using the following sample server.js content:

Copied Copy
1
2
3
4
5
6
7
exports = { 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"}); } }
onAppUninstall

When an app user clicks the Uninstall button corresponding to the app, the onAppUninstall event is triggered.
For app uninstallation to reach completion, in the callback function definition, use the renderData() method without any arguments. To disallow app uninstallation if a mandatory action fails, use an error object as the argument - renderData({error-object}).

error-object attribute
Attribute Name Data Type Description
message
Mandatory
string Message indicating why the mandatory action failed. Should not exceed 60 characters.

For example,

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

Register the onAppUninstall event by using the following sample manifest.json content:

Copied Copy
1
2
3
4
5
"events": { "onAppUninstall": { "handler": "onAppUninstallCallback" } }

Define the corresponding callback that allows completion of uninstallation by using the following sample server.js content:

Copied Copy
1
2
3
4
5
6
7
exports = { onAppUninstallCallback: function(payload) { console.log("Logging arguments from onAppUninstallevent: " + JSON.stringify(payload)); // If all mandatory uninstallation actions are successful renderData(); } }

Define the corresponding callback that disallows uninstallation if a mandatory action fails, by using the following sample server.js content:

Copied Copy
1
2
3
4
5
6
7
exports = { onAppUninstallCallback: function(payload) { console.log("Logging arguments from onAppUninstallevent: " + JSON.stringify(payload)); // If there is an error during uninstallation renderData({message: "Uninstallation failed due to network error"}); } }
Test

For information on how to test app setup events, see Test the App.