How to use custom app integrations with Integrator's ToolKit

In this tutorial, you will learn how to create a custom app configuration JSON file containing custom apps to be used with Integrator's ToolKit to enable integrations with those apps.

Prerequisites

In order to enable integrations for a custom app with ToolKit, the following details are required:

1. App name - The name of the application. e.g. "ACME Weapon Detector"
2. Package name - The package name of the application, which can be obtained by browsing to the WebUI of the app and looking at the address bar contents. e.g. "com.acme.detector.weapon"
3. Triggers - The messages that are transmitted by the application, and what they do. These can usually be found in the apps' integration documents on the Application Store. e.g. one message could be "sst:/acme/weapon" when "weapons are detected". An app could send more than one message - note the messages that are relevant for your integration use cases. The terminologies used here could be "topic" or "channel".

Note: If the app does not transmit any messages through one of our platform's supported mechanisms (e.g. DataTrolley, MessageBroker), then integration with this app is not yet possible. Please reach out to either the developer or Azena Support to request the developer have their apps transmit messages.

Create an app configuration JSON file

Single app

The configuration file is a JSON formatted such that the details from the previous section are populated as,

[
  {
    "appName": "ACME Weapon Detector",
    "packageName":"com.acme.detector.weapon",
    "triggers":[
      {
        "topicName": "sst:/acme/weapon",
        "topicDescription": "Occurs when weapons in general are detected.",
        "conditions":[]
      }
    ]
  }
]

Single app with multiple messages

Let's suppose this app also transmits messages for "pistol", then we can additionally add this message as,

[
  {
    "appName": "ACME Weapon Detector",
    "packageName":"com.acme.detector.weapon",
     "triggers":[
      {
        "topicName": "sst:/acme/pistol",
        "topicDescription": "Occurs when pistols are detected.",
        "conditions":[]
      },
      {
        "topicName": "sst:/acme/weapon",
        "topicDescription": "Occurs when weapons in general are detected.",
        "conditions":[]
      }
    ]
  }
]

Multiple apps

It is possible to add multiple apps. Let's suppose we also want to add another app called "Passionfruit FanFinder". This can be done by,

[
  {
    "appName": "ACME Weapon Detector",
    "packageName":"com.acme.detector.weapon",
    "triggers":[
      {
        "topicName": "sst:/acme/pistol",
        "topicDescription": "Occurs when pistols are detected.",
        "conditions":[]
      },
      {
        "topicName": "sst:/acme/weapon",
        "topicDescription": "Occurs when weapons in general are detected.",
        "conditions":[]
      }
    ]
  },
  {
    "appName": "Passionfruit FanFinder",
    "packageName":"com.passionfruit.fanfinder",
    "triggers":[
      {
        "topicName": "pf/alpha",
        "topicDescription": "Occurs when alpha type fans are found.",
        "conditions":[]
      }
    ]
  }
]

How to use the custom app configuration JSON file

Now that you've created a custom configuration JSON file, the next step is to use it in Integrator's ToolKit. This can be done as,

1. Open Integrator's ToolKit
2. Click "Settings"
3. Under the "Apps" section, select the "Custom" option
4. Click "Upload" (or if you already have a previously-selected custom file, click the "Edit" icon)
5. Select the newly-created custom JSON file
6. Click "Home"
7. Click "Create Event"
8. Verify that your custom apps are now visible in the "Select an app" list
9. Select one of the apps
10. Verify that the expected app messages are visible

Note: By using a custom app configuration file, you will only be able to create events using these specific apps. The apps supported by the default app configuration file will no longer be available for use, unless you revert back to using the Default configuration.