Enabling event notifications for IBM OpenPages
As an administrator of IBM OpenPages, you might want to send notifications of events in IBM OpenPages to other users, or human destinations, by using email, SMS, or other supported delivery channels. Additionally, you might want to send these notifications of events to other applications to build logic by using event-driven programming that uses webhooks, for example. This is made possible by the integration between IBM OpenPages and IBM Cloud® Event Notifications.
To send information to Event Notifications, you must connect your IBM OpenPages instance to Event Notifications. For more information about working with Event Notifications, see Getting started with Event Notifications.
How events are collected and sent by IBM OpenPages
When an event of interest takes place in your IBM OpenPages instance, IBM OpenPages communicates with a connected Event Notifications instance to forward a notification to a supported destination.
Currently, IBM OpenPages supports only email destinations.
IBM OpenPages uses a simplified event model where all alert notifications are sent using a single event type (com.ibm.cloud.openpages.event). The differentiation between different types of notifications happens at the content level
within the event payload, which follows the CloudEvents v1.0 specification.
Events for IBM OpenPages
The following table lists the IBM OpenPages events. All events are under the com.ibm.cloud.openpages.event subtype.
| Event type | Description |
|---|---|
com.ibm.cloud.openpages.event |
Generic IBM OpenPages event for all alert notifications |
Event payload format
IBM OpenPages sends notifications following the CloudEvents v1.0 specification. Each event contains structured information about the notification, including recipient details and the complete email content.
Payload structure
The following example shows the structure of an event payload sent from IBM OpenPages to Event Notifications:
{
"specversion": "1.0",
"id": "crn:v1:staging:public:openpages:global:a/2ac0a95fe03740b6977da3d5333898f3:eb51158d-405e-404c-a1c7-79bf2122dc9c::1967579992",
"source": "openpages",
"type": "com.ibm.cloud.openpages.event",
"ibmensourceid": "crn:v1:staging:public:openpages:global:a/2ac0a95fe03740b6977da3d5333898f3:eb51158d-405e-404c-a1c7-79bf2122dc9c::",
"ibmendefaultshort": "<truncated body>",
"ibmendefaultlong": "<truncated body>",
"message_subject": "<email subject>",
"message_html_body": "<!DOCTYPE HTML> <html> <head></head> <body style=\"font-family: ibm-plex-sans,HelveticaNeue,Helvetica,Arial,sans-serif; font-size: 14px;\"> <h1 style=\"font-size: 20px; font-weight: 300; padding: 22px 24px;\"><span style=\"font-weight: 600\">IBM OpenPages</span></h1> <hr style=\"margin: 0; border-bottom: 2px solid #0f62fe\" /> <div style=\"padding: 8px 24px 32px; background-color: #f3f3f3;\"> <h2 style=\"font-size: 14px; font-weight: 600; margin: 24px 0 8px;\">Workflow name:</h2> <p style=\"margin: 0\">Requirement Evaluation</p> <h2 style=\"font-size: 14px; font-weight: 600; margin: 24px 0 8px;\">Object type:</h2> <p style=\"margin: 0\">Requirement Evaluation</p> </div> <div style=\"padding: 8px 24px 160px;\"> <h2 style=\"font-size: 14px; font-weight: 600; margin: 24px 0 8px;\"> Number of object (evaluated):</h2> <p style=\"margin: 0\">13</p> <h2 style=\"font-size: 14px; font-weight: 600; margin: 24px 0 8px;\"> Number of workflow started successfully:</h2> <p style=\"margin: 0\">0</p> <h2 style=\"font-size: 14px; font-weight: 600; margin: 24px 0 8px;\"> Number of workflow skipped (applicability, locked, already in workflow):</h2> <p style=\"margin: 0\">13</p> <div style=\"display:none\"> <h2 style=\"font-size: 14px; font-weight: 600; margin: 24px 0 8px;\"> Number of workflow failed to start:</h2> <p style=\"margin: 0\">0</p> <h2 style=\"font-size: 14px; font-weight: 600; margin: 24px 0 8px;\"> Failed workflows (first 100 objects):</h2> <ul> </ul> </div> </div> <hr style=\"margin: 0; border-bottom: 1px solid #767676\" /> <div style=\"padding: 32px 24px;\">This email was automatically generated by IBM OpenPages.</div> </body> </html>",
"ibmenmailto": ["<recipient1>", "<recipient2>", ...]
}
Payload properties
The following table describes the properties in the event notification payload:
| Property | Type | Description |
|---|---|---|
specversion |
String | CloudEvents specification version |
id |
String | Unique event identifier: <CRN><jobId.hashCode()> |
source |
String | Event source identifier (always "openpages") |
type |
String | Event type (always "com.ibm.cloud.openpages.event") |
ibmensourceid |
String | IBM Event Notifications source ID (CRN of OpenPages instance) |
ibmendefaultshort |
String | Short notification message (truncated email body) |
ibmendefaultlong |
String | Long notification message (truncated email body) |
message_subject |
String | Email subject line |
message_html_body |
String | Complete HTML-formatted email body |
ibmenmailto |
Array | JSON array of recipient email addresses |
Data size limits
The following table shows the maximum size limits for event payload fields:
| Field | Maximum Size | Truncation Applied |
|---|---|---|
ibmendefaultshort |
1000 characters | Yes - truncated from email body |
ibmendefaultlong |
3000 characters | Yes - truncated from email body |
message_subject |
No explicit limit | No |
message_html_body |
No explicit limit | No |
ibmenmailto |
No explicit limit | No |
specversion |
Fixed: "1.0" | N/A |
source |
Fixed: "openpages" | N/A |
type |
Fixed: "com.ibm.cloud.openpages.event" | N/A |
Enabling notifications
Events that are generated by an instance of the IBM OpenPages service can be forwarded to an Event Notifications service instance that is available in the same account. You can configure only one IBM OpenPages instance to one Event Notifications service instance. However, a single Event Notifications service instance can have many IBM OpenPages instances pointing to it.
The following table shows the IBM OpenPages service instance regions and the Event Notifications service regions that they can forward events to:
| IBM OpenPages service instance region | Supported Event Notifications service region |
|---|---|
| AWS US East ( us-east-1 ) | IBM Cloud Dallas ( us-south ) |
| AWS Europe ( eu-central-1 ) | IBM Cloud Frankfurt ( eu-de ) |
| IBM Cloud Sydney (au-syd) | IBM Cloud Sydney (au-syd) |
Adding an Event Notifications service instance
Before you can enable notifications for IBM OpenPages, add an Event Notifications service instance to the same account as your IBM OpenPages instance.
- Go to the UI where you manage your IBM OpenPages instance. For more information, see Managing your IBM OpenPages instance.
- Click Settings.
- In the Event Notifications section, and click Connect.
- Expand Before you begin.
- Click Create new instance.
- On the Event Notifications Pricing page, select a plan, click the checkbox to agree to the license agreement, and then click Create.
Connecting to Event Notifications
Connect IBM OpenPages to the Event Notifications service instance by using Settings > Event Notifications section in the IBM OpenPages UI to connect the services.
- Go to the UI where you manage your IBM OpenPages instance. For more information, see Managing your IBM OpenPages instance.
- In the IBM OpenPages navigation, click Settings.
- In the Event Notifications section, click Connect.
- In the Event Notification instances section, click Event Notifications service instance and select the Event Notifications that you created.
- To confirm the connection, click Save. The Event Notifications section shows the connection between the IBM OpenPages instance and the Event Notifications instance.
- You can verify that a topic and subscription are created for your IBM OpenPages instance in the Event Notification settings by clicking on the Review link.
Your IBM OpenPages instance is ready to send notifications.
Delivering notifications to select destinations
After you enable notifications for IBM OpenPages, create topics and subscriptions in Event Notifications so that alerts can be forwarded and delivered.
IBM OpenPages notifications are in HTML format and are intended for the email delivery channel.
Email notifications
You can use the IBM Cloud email service as a delivery channel for IBM OpenPages event notifications. Create an Event Notifications subscription between an existing topic and the IBM Cloud email service to forward your alerts to various recipients by email. Recipients are automatically set based on the activity within IBM OpenPages that caused the notification to be created.
These emails originate from no-reply@cloud.ibm.com or event-notifications@cloud.ibm.com, but you can specify your own reply-to address.
The email content is provided in HTML format within the message_html_body field of the event payload. For more information about the payload structure, see Event payload format.