Creating a notification task

The user can use Engagement on their API Manager to receive notifications based on the defined criteria.

Before you begin

You must have at least one active Analytics service to use Engagement in the API Manager. When you create your notification task, you must fulfill the following criteria:

  • Each rule can have only up to 7 filter criteria and 5 triggers.
  • Each trigger can have only up to 3 actions.

About this task

The Engagement feature in the API Manager helps the user to create complex workflows that automate tasks and enhance the overall API management experience. Based on the criteria defined while creating notification tasks, each user receives notifications.

Create a notification task

To use Engagement, click Engagement icon on the API Manager and specify the criteria as required.

You can create a notification task by configuring a destination, rules, triggers, and actions.
  1. Configure a destination, which is the definition of the HTTP(S) endpoint that will receive the notification tasks. For more information, see Create a destination.
  2. Configure a rule, which is the job that runs on a defined schedule and send queries to the data source. For more information, see Create a rule.
  3. Configure a trigger, which define the conditions that generate events. For more information, see Add triggers.
  4. Configure an action, which defines what happens after a notification task is triggered. For more information, see Add actions.

Create a destination

  1. Click the Destinations tab.
  2. Click Create and provide the following details:
    1. In the Title, provide a Title for the destination.
    2. In the Description box, provide a description.
    3. In the Configuration section, select the type. The available types are Webhook, PagerDuty, and Slack. When you add types, the system displays fields that vary depending on the selected destination type.
    4. To configure Webhook, complete the following steps:
      1. Select Webhook as the type.
      2. Select an option from the Method list to specify the HTTP method for the destination. The available options are POST, PUT, and PATCH.
      3. In the Webhook URL field, enter the target HTTP(S) endpoint.
      4. Optional: Click Add + to include extra HTTP headers.
    5. To configure PagerDuty, complete the following steps:
      1. Select PagerDuty as the type.
      2. Enter your pagerduty integration routing key in Routing key field. For more information about pagerduty integration, see Services and Integrations.
        Note: When integrating with PagerDuty, select Events API v2 as the integration type.
    6. To configure Slack, complete the following steps:
      1. Select Slack as the type.
      2. In the Token field, enter the Slack API token.
      3. In the Channel ID field, enter your Channel ID. For more information about Token and Channel ID, see How to quickly get and use a Slack API bot token.
        Note: Use the Channel ID, not the channel's name. For example: C1234567890.
    7. To configure Kafka HTTP Bridge, complete the following steps:
      1. Select Webhook as the type.
      2. Select an option from the Method list to specify the HTTP method for the destination. The available options are POST, PUT, and PATCH.
      3. In the Webhook URL field, enter the target HTTP(S) endpoint.
        http://<route-name>.apps.<cluster-name>.<namespace>.com/topics/<topic-name>
        For more information about Kafka HTTP Bridge configuration, see Connecting over HTTP with Kafka Bridge.
      4. Click Add + to add an HTTP header.
      5. In the Name filed, enter content-type.
      6. In the Value field, enter application/vnd.kafka.json.v2+json.
      7. Define the JSON payload to be sent to the Kafka topic in the trigger action of your rule.
      Note: Check your Kafka setup and adjust the payload format if needed. The following example shows a JSON message format required by some Kafka implementations:
      {
           "records": [
              {
                  "key": "my-key",
                  "value": "my-value"
              }
          ]
      }
    8. To configure IBM MQ, complete the following steps:
      1. Select Webhook as the type.
      2. Select an option from the Method list to specify the HTTP method for the destination. The available options are POST, PUT, and PATCH.
      3. In the Webhook URL field, enter the target HTTP(S) endpoint.
        https://<host>:<port>/ibmmq/rest/v3/messaging/qmgr/<your_qm_name>/queue/<your_queue_name>/message
        For more information about IBM MQ messaging REST API, see IBM MQ messaging REST API.
      4. Click Add + to add an HTTP header.
      5. In the Name filed, enter content-type.
      6. In the Value field, enter the value of the content type you are using, for example: text/plain;charset=utf-8.
      7. Click Add + to add a second HTTP header.
      8. In the Name filed, enter authorization.
      9. In the Value field, enter Basic <base64encodedstring>.

        Where:

        • base64encodedstring is the username:password base 64 encoded.
      10. Click Add + to add a third HTTP header.
      11. In the Name filed, enter ibm-mq-rest-csrf-token.
      12. You can leave the value field blank.
        Note: Ensure that this header is included, even if the value field is blank, as the IBM MQ Queue Manager rejects the payload without it.
    9. To configure IBM Cloud Event Notification Service, complete the following steps:
      Note: The destinations in IBM Cloud Event Notification Service are not linked to the destinations in API Connect. You must configure the destination in IBM Cloud Event Notification Service before configuring Engagement in API Connect.
      1. Select Webhook as the type.
      2. Select POST from the Method list to specify the HTTP method for the destination.
      3. In the Webhook URL field, enter the target HTTP(S) endpoint.
        {base_url}/v1/instances/{instance_id}/notifications 
        Where:
        base_url
        Enter the base URL path
        instance_id
        Enter the identifier corresponding to the instance
        For more information about IBM Cloud Event Notification Service, see Event notifications API.
      4. Click Add + to add an HTTP header.
      5. In the Name filed, enter content-type.
      6. In the Value field, enter application/json.
      7. Click Add + to add a second HTTP header.
      8. In the Name filed, enter Authorization.
      9. In the Value field, enter your IAM token.
      10. Define the JSON payload that you want to send to the notification service in the trigger action of your rule. For more information, see Event notifications API.
  3. Click Create.

Create a rule

Note: The maximum number of rules that you can create per provider organization is 10, while the maximum number of rules that you can create across all analytics services within the organization is 10,000.
  1. Click the Rules tab.
  2. Click Create and provide the following details:
    1. In the Title field, provide a Title for the rule.
    2. In the Schedule section, specify a schedule to run this rule. You can specify a schedule either by defining a time interval or a cron string.
    3. Click Next to select data and define query.
    4. In the Select data section, select an option from the Data source list based on the data against which you want to run the rule.
    5. In the Query section, define the aggregation metric that you want to use for the query. The default is a count of matching records. You can also use mathematical aggregations for numerical fields, such as the maximum value or the average over a time period.
    6. In the Data time range for the last fields, enter the time range based on how far back in the past you want to run the search for matching data items.
    7. Click Add filter + to select up to 7 data filters to based on the data you want to include while running the query. You can use any of the analytics event record fields.
    8. Click Add group by + to select a group based on how you want to group the selected data and streamline the target criteria. For example, a rule that matches 10 API events with a status code of 500 within a 24-hour period can use Group by on api_name to call for 10 matching events for an individual API as opposed to a total across all events for all APIs.
    9. Click Next to configure triggers.

    Add triggers:

    1. Click Add trigger +. You can add up to 5 triggers.
    2. In the Trigger details section, provide a Title for the trigger and then, select the severity level and trigger condition from the corresponding lists.
    3. Define the numerical target, which allows a single rule to have multiple triggers with different severity and trigger conditions. When the specified criteria are met, each trigger can trigger up to 3 actions, which then invokes different endpoints or with different payloads.

    Add actions:

    1. Click Add action + to configure the action that happens when the trigger criteria are met.
    2. In the Trigger action section, provide a title for the action, and from the Destination list, select the destination to be invoked when the criteria are met.
    3. Enable throttling and define the throttling window to prevent invoking multiple triggers for the same rule in the same time period.
    4. In the Payload section, provide a message subject and a payload value. You can add context variables in the Payload field based on the task payload information you want to display in the destination. For more information, see Context variables in the task payload.
      Note: The message subject is not sent to the HTTP endpoint. The payload value acts as the HTTP body of the notification task that is sent to the destination endpoint
  3. Click Save.
  4. Click Finish.

What you did in this task

On your API Manager, you used Engagement to automate notification tasks based on the specified criteria. The Task status tab displays the latest notification tasks for each trigger.