Configure external events

External events are events that occur in an external product or a third-party service. You can enable external events to trigger apps. To do this:

1. Generate a target URL - link to where the app receives webhook data.
2. Create a webhook in the external product or service, to subscribe to external events. When creating a webhook specify the target URL for the webhook to send data.
3. Configure event listeners in manifest.json. When an external event occurs, the webhook uses the target URL, notifies the app about the external event, and sends data to the app. The configured event listener invokes a callback method.
4. In server.js, define the callback method. The app logic in the callback method runs with the help of the event-specific payload passed to the callback method.

When an external event occurs, the external product passes an event-specific payload as webhook data to the target URL (app framework). This data is passed as payload to the external event’s callback method. The payload is a JSON object with the following attributes.

To generate a webhook URL when an app is installed and use the URL to register the webhook:

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

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

   manifest.json

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

3. Navigate to the server.js file.

4. In the callback method associated with the onAppInstall event,

   1. Include the generateTargetUrl() method. The webhook URL generated is unique for each app installation.
   2. Include an API request to the external product, for webhook registration. In the API request, ensure to specify the authorization mechanism (Basic) and the JSON object that the external product requires to successfully register the webhook.
   manifest.json

    exports = {
      onAppInstallHandler: function(payload) {
        generateTargetUrl()
        .then(function(url) {
          //Include API call to the third party to register your webhook
        },
        function(err) {
          // Handle error
        });
      }
    };

   Notes:
   • The generateTargetUrl() method is supported only in onAppInstall() and product event callbacks.
   • You can register multiple webhooks in this callback method.

5. When a webhook is successfully registered, the external product sends a webhook id. This webhook id can be used to deregister the webhook, when the app is uninstalled. In the callback method, include a mechanism to store the webhook id.

To subscribe to an external event and call a corresponding callback method, when the event occurs:

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

2. In the modules.common.events object, specify the external event and the corresponding callback method.

   manifest.json

     "modules": {
       "common": {
         "events": {
           "onAppInstall": {
             "handler": "onAppInstallHandler"
           },
           "onExternalEvent": {
             "handler": "onExternalEventHandler"
           }
         }
       }
     }

   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.

   server.js

    exports = {
      onAppInstallHandler: function(payload) {
        generateTargetUrl()
          .then(function(url) {
            //API call to the external product to register the webhook.
        })
          .fail(function(err) {
            // Handle error
        });
      },
      onExternalEventHandler: function(payload) {
        //This is the callback function definition.
        //Include the logic to perform any action.
        console.log("Logging arguments from the event:" + JSON.stringify(payload));
      }
    }

To automatically deregister a webhook, when an app is uninstalled:

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

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

   manifest.json

     "modules": {
       "common": {
         "events": {
           "onAppInstall": {
             "handler": "onAppInstallHandler"
           },
           "onExternalEvent": {
             "handler": "onExternalEventHandler"
           },
           "onAppUninstall": {
             "handler": "onAppUninstallHandler"
           }
         }
       }
     }

3. Navigate to the server.js file.

4. In the callback method associated with the onAppUninstall event,

   1. Include the mechanism to retrieve the webhook id saved during app installation.
   2. Include an API request to the external product, for webhook deregistration.
   server.js

    exports = {
      onAppInstallHandler: function(payload) {
        generateTargetUrl()
          .then(function(url) {
          //API call to the external product to register the webhook.
        })
          .fail(function(err) {
          // Handle error
        });
      },
      onExternalEventHandler: function(payload) {
        //This is the callback function definition.
        //Include the logic to perform any action.
        console.log("Logging arguments from the event:" + JSON.stringify(payload));
      },
      onAppUninstallHandler: function(payload) {
        //Include API call to the external product to deregister the webhook
      }
    }

1. From the command line, navigate to the directory that contains the app related files and run the fdk run command. The FDK starts the local test server. The test URLs to access the product UI, the App Settings page (or Custom installation page), and the URL to the serverless events simulation page are displayed.

2. Navigate to the system settings page at http://localhost:10001/system_settings. All modules configured in the App manifest are listed.

3. In the system settings page,

   1. Select the modules for which you want to test the app logic. The Enter account URL section is displayed, with a prompt to enter the account URLs for all selected modules.
   2. In the Enter account URL section, enter valid account URL(s) for the product(s) to which the selected modules belong. During app testing, this URL plays the role of the currentHost. Based on the currentHost, the currentHost.subscribed_modules and currentHost.endpoint_urls are determined.
   3. Click Continue.

4. If you have configured installation parameters for the app, the App Settings page is displayed at http://localhost:10001/custom_configs. Enter appropriate values for the installation parameters and click Install.

   Note:If you have not configured any installation parameters, a page is displayed with information on the configured system settings. A message stating that the app does not have an installation page is displayed.

5. Navigate to http://localhost:10001/web/test to test the serverless events that the app uses. All modules that you select in the system settings page, for which serverless events are registered in the app manifest, are listed in the Select module drop-down.

   Note:The payloads of all serverless events that are registered in the app manifest are populated in the server/test_data folder. During the actual runtime, the payloads that are passed to the serverless event contain the currentHost attribute. In the local simulation, the payloads in server/test_data do not contain this attribute. During testing, the modules and account URLs entered in the system settings page are passed as the currentHost data.

6. From the Select module drop-down, select Common. The Select an event drop-down is displayed and it lists all the events configured (in the app manifest) for the common module.

7. From the Select an event drop-down, select onExternalEvent. The payload for the event is populated on the page.

8. Click Simulate. If the event is simulated successfully, the Simulate button’s display name changes to Success. The event payload is added to the <app's root directory>/server/test_data folder.

9. To test more events, select another appropriate module and event and click Simulate. If the event simulation fails because of invalid payload data, the Simulate button’s display name changes to Failed. Modify the payload appropriately and click Simulate.

Note:To test a serverless app, use the latest version of Chrome. The FDK uses the node module ngrok to create secure tunnels between a local FDK instance and the ngrok cloud. According to ngrok.io, ngrok exposes local servers behind NATs and firewalls to the Internet, over secure tunnels. The FDK leverages this feature to expose the webhook registered in external products, to test external events app integrations.

To test external events by using ngrok:

1. From the command line, navigate to the directory that contains the app related files and run the following command:

   fdk run --tunnel

2. If you have ngrok authorization privileges, run the following command:

   fdk run --tunnel --tunnel-auth

   The tunnel is opened and an appropriate message specifying the URL to test serverless events is displayed.
3. In the address bar of the browser, enter https://localhost:10001/web/test. A dialog box is displayed.
4. Click Select an event. The events configured in the server.js file are displayed (onAppInstall, onAppUninstall, and onExternalEvent).
5. Click onAppInstall. The webhook is registered in the external product.
6. Navigate to the external product and simulate the event to which the webhook has subscribed. The event specific webhook data is sent to the app.