Configure app set-up events

App set-up events are events that occur when an app is installed from the Freshworks Marketplace, updated to the latest version, or uninstalled. An app set-up 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 set-up event to disallow installation if the webhook registration fails.

To configure and use the app set-up events:

1. From your app’s root directory, navigate to manifest.json.

2. Subscribe to an event by configuring an event listener. To do this, include the events attribute, specifying the app set-up event and the corresponding callback methods as follows:

   manifest.json

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

   When an app set-up event occurs, the corresponding event listener invokes a callback method and passes a standard payload to the method.

3. In server.js, define the callback function.

When an app set-up event occurs, a payload is passed to the callback method. The payload is a JSON object with the following attributes.

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

To configure the onAppInstall event:

1. Subscribe to the onAppInstall event by using the following sample manifest.json content:

   manifest.json

   "events": {
    "onAppInstall": {
      "handler": "onAppInstallCallback"
    }
   }

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

   server.js

   exports = {
    onAppInstallCallback: function(payload) {
      console.log("Logging arguments from onAppInstallevent: " + JSON.stringify(payload));
      // If the setup is successful
      renderData();
     }
   }

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

   server.js

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

After you upload a new version of your app, in the Apps gallery > MANAGE APPS, an Update button is displayed next to the app (for admin users). If the admin clicks the button and updates the app, the new app version is installed and the afterAppUpdate event is triggered.

In your new version’s app files, you can:

• Subscribe to the event by configuring event and its corresponding callback function.
• Use the callback function to carry out certain app actions. To let an app user continue using the updated version, in the callback function definition, as part of the app logic, use the renderData() method without any arguments.
• If any mandatory action that must be carried out as part of the app set-up (update) fails, if the mandatory parameters that are required to carry out the app actions are unavailable, or in any such error scenarios, use the registered callback function to revert to the earlier installed app version. To perform this, use an error object as the argument of the renderData() method - renderData({error-object}).

error-object attribute

To configure the afterAppUpdate event:

1. Subscribe to the afterAppUpdate event by using the following sample manifest.json content:

   manifest.json

   "events": {
    "afterAppUpdate": {
      "handler": "afterAppUpdateCallback"
    }
   }

2. Define the corresponding callback that does not interrupt usage of the updated app, by using the following sample server.js content:

   server.js

   exports = {
    afterAppUpdateCallback: function(payload) {
      console.log("Logging arguments from onAppInstallevent: " + JSON.stringify(payload));
      // If the setup is successful
      renderData();
     }
   }

3. Define the corresponding callback that reverts the app to the earlier installed version if a mandatory action fails, by using the following sample server.js content:

   server.js

   exports = {
    afterAppUpdateCallback: function(payload) {
      console.log("Logging arguments from afterAppUpdate event: " + JSON.stringify(payload));
      // To revert to earlier installed app version.
     renderData({message: "Updating to the latest version of the app failed due to network error."});
     }
    }

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

To configure the onAppUninstall event:

1. Subscribe to the onAppUninstall event by using the following sample manifest.json content:

   manifest.json

   "events": {
    "onAppUninstall": {
      "handler": "onAppUninstallCallback"
    }
   }

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

   server.js

   exports = {
    onAppUninstallCallback: function(payload) {
      console.log("Logging arguments from onAppUninstallevent: " + JSON.stringify(payload));
      // If all mandatory uninstallation actions are successful
      renderData();
     }
   }

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

   server.js

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

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.

   Select an event to simulate

   Note: To test app setup events, select onAppInstall, afterAppUpdate, or onAppUninstall.

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.