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 on the API
Manager and
specify the criteria as required.
- 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. - 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. - Configure a
trigger
, which define the conditions that generate events. For more information, see Add triggers. - Configure an
action
, which defines what happens after a notification task is triggered. For more information, see Add actions.
Create a destination
- Click the Destinations tab.
- Click Create and provide the following details:
- In the
Title
, provide a Title for the destination. - In the Description box, provide a description.
- 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.
- To configure Webhook, complete the following steps:
- Select Webhook as the
type
. - Select an option from the
Method
list to specify the HTTP method for the destination. The available options arePOST
,PUT
, andPATCH
. - In the
Webhook URL
field, enter the target HTTP(S) endpoint. - Optional: Click Add + to include extra HTTP headers.
- Select Webhook as the
- To configure PagerDuty, complete the following steps:
- Select PagerDuty as the type.
- Enter your pagerduty integration routing key in
Routing key
field. For more information aboutpagerduty integration
, see Services and Integrations.Note: When integrating with PagerDuty, select Events API v2 as the integration type.
- To configure Slack, complete the following steps:
- Select Slack as the type.
- In the
Token
field, enter the Slack API token. - In the
Channel ID
field, enter your Channel ID. For more information aboutToken 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
.
- To configure Kafka HTTP Bridge, complete the following steps:
- Select Webhook as the
type
. - Select an option from the
Method
list to specify the HTTP method for the destination. The available options arePOST
,PUT
, andPATCH
. - In the
Webhook URL
field, enter the target HTTP(S) endpoint.
For more information abouthttp://<route-name>.apps.<cluster-name>.<namespace>.com/topics/<topic-name>
Kafka HTTP Bridge
configuration, see Connecting over HTTP with Kafka Bridge. - Click Add + to add an HTTP header.
- In the
Name
filed, enter content-type. - In the
Value
field, enter application/vnd.kafka.json.v2+json. - 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" } ] }
- Select Webhook as the
- To configure IBM MQ, complete the following steps:
- Select Webhook as the
type
. - Select an option from the
Method
list to specify the HTTP method for the destination. The available options arePOST
,PUT
, andPATCH
. - In the
Webhook URL
field, enter the target HTTP(S) endpoint.
For more information abouthttps://<host>:<port>/ibmmq/rest/v3/messaging/qmgr/<your_qm_name>/queue/<your_queue_name>/message
IBM MQ messaging REST API
, see IBM MQ messaging REST API. - Click Add + to add an HTTP header.
- In the
Name
filed, enter content-type. - In the
Value
field, enter the value of the content type you are using, for example:text/plain;charset=utf-8
. - Click Add + to add a second HTTP header.
- In the
Name
filed, enter authorization. - In the
Value
field, enter Basic <base64encodedstring>.Where:
base64encodedstring
is theusername:password
base 64 encoded.
- Click Add + to add a third HTTP header.
- In the
Name
filed, enter ibm-mq-rest-csrf-token. - 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.
- Select Webhook as the
- 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.
- Select Webhook as the
type
. - Select
POST
from theMethod
list to specify the HTTP method for the destination. - In the
Webhook URL
field, enter the target HTTP(S) endpoint.
Where:{base_url}/v1/instances/{instance_id}/notifications
- base_url
- Enter the base URL path
- instance_id
- Enter the identifier corresponding to the instance
IBM Cloud Event Notification Service
, see Event notifications API. - Click Add + to add an HTTP header.
- In the
Name
filed, enter content-type. - In the
Value
field, enter application/json. - Click Add + to add a second HTTP header.
- In the
Name
filed, enter Authorization. - In the
Value
field, enter your IAM token. - 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.
- Select Webhook as the
- In the
- Click Create.
Create a rule
- Click the Rules tab.
- Click Create and provide the following details:
- In the
Title
field, provide a Title for the rule. - 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.
- Click Next to select data and define query.
- 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.
- 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.
- 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.
- 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.
- 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
onapi_name
to call for 10 matching events for an individual API as opposed to a total across all events for all APIs. - Click Next to configure triggers.
Add triggers:
- Click Add trigger +. You can add up to 5 triggers.
- In the Trigger details section, provide a Title for the trigger and then, select the severity level and trigger condition from the corresponding lists.
- 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:
- Click Add action + to configure the action that happens when the trigger criteria are met.
- 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.
- Enable throttling and define the throttling window to prevent invoking multiple triggers for the same rule in the same time period.
- 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
- In the
- Click Save.
- 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.