Service Brokers

This guide explains how to associate an Itential Automation Platform (IAP) service with a broker.

What Brokering Does

Associating a service with an IAP broker means the service agrees to implement the broker's interface. Basically, the service will supply a particular set of functions declared by the broker. For example, a broker named trope might support functions foo, bar, and baz. If we create a service that implements the trope broker, then it must define the functions foo, bar, and baz. If it does not define these functions an error will occur during runtime if the function is called by the brokering system.

Brokering allows for a service to be used conceptually to perform operations. A concept that could be brokered is operations that are performed on a network device. To illustrate the concept, we will call our example the device broker. This broker might have functions such as addDevice, getDevice, and deleteDevice. Now say that we have three different services that talk to three different network managers that can perform the addDevice, getDevice, and deleteDevice operations. We could associate these three services with the device broker so we can reference the concept of a device instead of a specific service. In other words, you can now perform the addDevice, getDevice, and deleteDevice operations by referencing the device broker instead of one of the three services specifically.

How to Associate a Broker

To associate a service with a broker or group of brokers add it to the pronghorn.json brokers array. You can add the brokers array at the root of the configuration if it does not exist. In this pronghorn.json example the device and method brokers have been added.

  {
    "id": "@itential/adapter-example",
    "export": "EXAMPLE",
    "title": "EXAMPLE",
    "src": "src.js",
    "type": "Adapter",
    "brokers": [
      "device",
      "method"
    ],
    "roles": [
      "admin"
    ],
    "topics": {},
    "views": [],
    "methods": []
  }

When the service is installed in IAP, the broker associations will be added to the service configuration automatically. The service is now associated with the brokers.

  {
    "loggerProps": {
      "description": "Logging",
      "log_max_files": 100,
      "log_max_file_size": 1048576,
      "log_level": "info",
      "log_directory": "./logs",
      "log_filename": "example.log",
      "console_level": "warn"
    },
    "isEncrypted": false,
    "model": "@itential/adapter-example",
    "name": "example_adapter",
    "type": "Adapter",
    "properties": {
      "id": "example_adapter",
      "type": "EXAMPLE",
      "properties": {},
      "groups": [],
      "brokers": [
        "device",
        "method"
      ]
    }
  }