The Event Management Topic Open API provides an endpoint that enables you to send a topic through your message broker and store it on a ServiceNow instance.

Using this API you can store topics created through your message broker in the ServiceNow Topic [topic] table.

This API runs in the sn-api-notif-mgmt namespace and requires the sn_api_notif_mgmt.event_mgmt_integration role.

Event Management Topic Open - POST /sn_api_notif_mgmt/topic

Creates a new record in the Topic [sn_api_notif_mgmt_topic] table and saves the passed topic information to that record.

Use this endpoint to synchronize topics created in your message-bus middleware with those in your ServiceNow instance.

When topics are created using this endpoint, the user_created field in the associated topic record is set to false and the type field is set to egress.

URL format

Versioned URL: /api/sn_api_notif_mgmt/v1/topic

Default URL: /api/sn_api_notif_mgmt/topic

Supported request parameters

Table 1. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
Table 2. Query parameters
Name Description
None
Table 3. Request body parameters
Name Description
contentQuery Filter to apply to the payload of the event. This query is a deeper event filter that is used to find information such as event severity or ticket type. You can pass this parameter as a nested query.
For example, for the following trouble ticket event payload, this query applies to the attributes that are in the "event" object of the payload:
{
  "eventId":"dc2003c2c3bb3550054e20bdc0013136",
  "@type":"Troubleticket",
  "eventType":"TroubleTicketCreateEvent",
  "event":{
    "troubleTicket":{
      "short_description":"Test payload",
      "severity":3,
      "ticketType":"incident"
    }
  }
}
This parameter supports the following conditions:
  • AND: such as variable1=value1&variable2=value2&variable3=value3
  • OR: such as variable1=value1,value2,value3
  • Hierarchical variables: such as variable1.variable2.variable3=value1

For example: "contentQuery": "troubleTicket.ticketType=incident&troubleTicket.severity=1",

This field is mapped to the content_query field in the associated topic record.

For additional information, refer to the TMF688 Event Management API User Guide.

Data type: String
externalId Unique external identifier for the topic, such as a GUID. This field is mapped to the topic_id field in the associated Topic record.

Data type: String
headerQuery Filter to apply to the event header properties. This query defines the type of events to listen to for the associated topic. You can pass this parameter as a nested query.
This parameter supports the following conditions:
  • AND: such as variable1=value1&variable2=value2&variable3=value3
  • OR: such as variable1=value1,value2,value3
  • Hierarchical variables: such as variable1.variable2.variable3=value1

For example: "headerQuery": "eventType=TroubleTicketStatusChangeEvent,TroubleTicketAttributeChangeEvent"

This field is mapped to the header_query field in the associated topic record.

For additional information, refer to the TMF688 Event Management API User Guide.

Data type: String
name Name of the topic.

This field is mapped to the topic_name field in the associated topic record.

Data type: String
namespace Namespace for the topic. Empty if there is no associated namespace.

This field is mapped to the namespace field in the associated topic record.

Data type: String

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 4. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Content-Type Data format of the request body. Only supports application/json.
Table 5. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Table 6. Status codes
Status code Description
201 Successful. The request was successfully processed.
400 Topic external id passed already exists. Please pass the unique topic external id: Indicates that passed external ID already exists in the Topic table.

Please pass the unique combination of topic name, header query, content query and namespace : Indicates that the combination of topic name, namespace, header query, and content query already exists.
500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters

Name Description
contentQuery Value of the content_query field in the created topic record.

Data type: String
externalId Value of the topic_id field in the created topic record.

Data type: String
headerQuery Value of the header_query field in the created Topic record. This field is used by the topic picker framework to determine what event messages should be sent to a topic.

Data type: String
id Sys_id of the created topic record.

Data type: String
name Name of the topic.

Data type: String
namespace Value of the namespace field in the created topic record.

Data type: String

Example: cURL request

The following code example shows how to call this endpoint.

curl "http://instance.servicenow.com/api/sn_api_notif_mgmt/topic" \
--request POST \
--header "Accept:application/json" \
--user 'username':'password'
--data
{
  "name": "HighPriorityTroubleTicket",
  "headerQuery": "eventType=TroubleTicketStatusChangeEvent,TroubleTicketAttributeChangeEvent",
  "contentQuery": "troubleTicket.ticketType=incident&troubleTicket.severity=1",
  "externalId": "ext001",
  "namespace": "telecomEvents"
}

Response:


{
  "externalId": "ext001",
  "name": "HighPriorityTroubleTicket",
  "headerQuery": "eventType=TroubleTicketStatusChangeEvent,TroubleTicketAttributeChangeEvent",
  "contentQuery": "troubleTicket.ticketType=incident&troubleTicket.severity=1",
  "namespace": "telecomEvents",
  "id": "7ee9850443c3f550461f99612bb8f223"
}