Creating custom event sources with an integration broker

Edit online

In addition to the built-in event source integration types provided by event management, you can create custom integrations to receive event information from other sources by using an integration broker.

About this task

For example, as a service provider, you might want to set up a custom event source type that your customers can use to integrate with a monitoring system you provide. The custom event source uses an integration broker to create an event source instance in event management to which you can post events via a webhook.

Event management provides a sample application that demonstrates how to create an integration broker that can be used to set up a custom event source integration. Use the sample application and modify it to create your own integration broker that suits your needs. For more information, see https://github.com/IBM-Bluemix/cloud-event-management-sample.

Note: The sample application provides an example of how to create a custom event source configuration that can post event information to event management. The sample is a Node.js application. You can use other methods, but ensure you follow the same high level steps to create and configure your integration broker for event management.

To create an integration broker using the sample application:

Procedure

  1. Develop the integration broker:
    1. Go to https://github.com/IBM-Bluemix/cloud-event-management-sample.
    2. Download the sample application package, extract it, and run the application as described in the README.
    3. Modify the application to suit your requirements by changing the following settings:
      • Set the integration controller host URL in manifest.yml as provided by IBM®. The integration controller is a component of event management.
      • Set the UI properties for configuring the custom event source integration in eventSourceCatalog.yaml. For example, specify the label and description that is displayed on the UI for configuring the custom event source.
        Note: You can have multiple integration brokers. A single broker can support one or more integration types. To define more than one event source integration type for a single broker, define each in the eventSourceCatalog.yaml file. You can duplicate the parameters to define the integrations. Ensure that the value of the id field is unique for each integration type.
        Important: While you can have more than one integration type defined for a broker, access to the integrations is controlled through each broker. This means if a customer is granted access to the broker, they will have access to all integrations defined for the broker. If you want to grant different customers access to different integrations, then you must create a separate broker for each event source integration, and set up access per broker as described in step 3.
      • Define how the event details from your source map to event management events. You define the mapping in section // Map a Prometheus event to a Cloud Event Management event of the sample webhook.js file.
        Note: Event information processed by event management must comply with the event format defined by the event management API as described in the API documentation. For more information about the Cloud Event Management APIs, see Cloud Event Management API documentation.

        The broker will map the events to a JSON string and posts it to the API at https://integration_controller_hostname/api/events/v1.

  2. Register the broker with the event management integration controller using the brokers.js register command option, for example:
    brokers.js register -t "bearer eyJhbGciOiJIUzI1NiIsImtpZCI6Imt" -n "Partners Inc" -r https://prod-integration-controller.mybluemix.net -a "abc@us.ibm.com" -a "def@ie.ibm.com" -u https://myapp.mybluemix.net/api/broker -v "CustomerSub1" -v "CustomerSub2"

    Where

    • -t: The bearer token for the IBM cloud foundry user.
    • -n: The broker name to register with the integration controller. This is a unique label to designate the broker.
    • -r: The integration controller as defined in the manifest.yml file.
    • -a: Additional user IDs that have access to manage the broker. The user making the register request is automatically added as an authorized user.
    • -u: The broker API URL to register with integration controller.
    • -v: The subscription or tenant IDs for the customers or users that have access to the integrations managed by the broker.

    After registering the broker, the custom event source configuration is displayed on the event management UI under Administration > Event sources > Configure an event source. Each registered broker displays a configuration tile. The UI can then be used to set up an integration with the event source.

    Note: The broker can be deployed on any host. The event information is then sent to the broker on that host via the webhook provided when setting up the event source integration. The broker then forwards the information to the integration controller, and it gets processed in event management.
  3. Provide your customers access to the custom event source integration you set up with the broker. To grant access, add customer subscription or tenant IDs to the broker.
    You can do this when registering the broker by using the brokers.js register -v option as described in the previous step.
    You can also do this later using the brokers.js update option as follows: brokers.js update –v string for subscription or tenant ID. You can use the update option to remove access the same way.
    Note: Event management provides an API to interact with the integration brokers. Use the brokers.js script to communicate with the API to register your integration, update it, retrieve information about it, and remove it. For more information about the brokers.js options, see the broker.js help command.

Results

After following these steps, your users can set up an integration with the custom event source using the event management UI, and start receiving events from the source. They can then work with the events and their incidents using the event management features.