{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":511,"path":"api-reference/rest-apis/event_management_topic-api.md","title":"Event Management Topic Open API","bundle":null,"doc_type":null,"release":"australia","body":"\n# Event Management Topic Open API\n\nThe 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.\n\nUsing this API you can store topics created through your message broker in the ServiceNow Topic \\[topic\\] table.\n\nThis API runs in the `sn-api-notif-mgmt` namespace and requires the sn\\_api\\_notif\\_mgmt.event\\_mgmt\\_integration role.\n\n**Parent Topic:**[REST API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/api-rest.md)\n\n## Event Management Topic Open - POST /sn\\_api\\_notif\\_mgmt/topic\n\nCreates a new record in the Topic \\[sn\\_api\\_notif\\_mgmt\\_topic\\] table and saves the passed topic information to that record.\n\nUse this endpoint to synchronize topics created in your message-bus middleware with those in your ServiceNow instance.\n\nWhen 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`.\n\n### URL format\n\nVersioned URL: `/api/sn_api_notif_mgmt/{api_version}/topic`\n\nDefault URL: `/api/sn_api_notif_mgmt/topic`\n\n**Note:** Available versions are specified in the [REST API Explorer](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/use-REST-API-Explorer.md). For scripted REST APIs there is additional version information on the [Scripted REST Service form](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_CustomWebServices.md).\n\n### Supported request parameters\n\n\n
\n\nName\n\n\n\nDescription\n\n
\n\napi\\_version\n\n\n\nOptional. 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\n\n
|Name|Description|\n|----|-----------|\n|None| |\n\n\n
\n\nName\n\n\n\nDescription\n\n
\n\ncontentQuery\n\n\n\nFilter 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:\n\n```\n{\n \"eventId\":\"dc2003c2c3bb3550054e20bdc0013136\",\n \"@type\":\"Troubleticket\",\n \"eventType\":\"TroubleTicketCreateEvent\",\n \"event\":{\n \"troubleTicket\":{\n \"short_description\":\"Test payload\",\n \"severity\":3,\n \"ticketType\":\"incident\"\n }\n }\n}\n```\n\nThis parameter supports the following conditions:\n\n- AND: such as`variable1=value1&variable2=value2&variable3=value3`\n- OR: such as `variable1=value1,value2,value3`\n- Hierarchical variables: such as `variable1.variable2.variable3=value1`\n\nFor example: `\"contentQuery\": \"troubleTicket.ticketType=incident&troubleTicket.severity=1\",`\n\nThis field is mapped to the content\\_query field in the associated topic record.\n\nFor additional information, refer to the [TMF688 Event Management API User Guide](https://www.tmforum.org/resources/standard/tmf688-event-management-api-user-guide-v4-0-0/).\n\nData type: String\n\n
\n\nexternalId\n\n\n\nUnique 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\n\n
\n\nheaderQuery\n\n\n\nFilter 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:\n\n- AND: such as`variable1=value1&variable2=value2&variable3=value3`\n- OR: such as `variable1=value1,value2,value3`\n- Hierarchical variables: such as `variable1.variable2.variable3=value1`\n\nFor example: `\"headerQuery\": \"eventType=TroubleTicketStatusChangeEvent,TroubleTicketAttributeChangeEvent\"`\n\nThis field is mapped to the header\\_query field in the associated topic record.\n\nFor additional information, refer to the [TMF688 Event Management API User Guide](https://www.tmforum.org/resources/standard/tmf688-event-management-api-user-guide-v4-0-0/).\n\nData type: String\n\n
\n\nname\n\n\n\nName of the topic.This field is mapped to the topic\\_name field in the associated topic record.\n\nData type: String\n\n
\n\nnamespace\n\n\n\nNamespace for the topic. Empty if there is no associated namespace.This field is mapped to the namespace field in the associated topic record.\n\nData type: String\n\n
### Headers\n\nThe 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](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n|Header|Description|\n|------|-----------|\n|Accept|Data format of the response body. Only supports **application/json**.|\n|Content-Type|Data format of the request body. Only supports **application/json**.|\n\n|Header|Description|\n|------|-----------|\n|None| |\n\n### Status codes\n\nThe 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](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n\n
\n\nStatus code\n\n\n\nDescription\n\n
\n\n201\n\n\n\nSuccessful. The request was successfully processed.\n\n
\n\n400\n\n\n\n`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.\n\n
\n\n500\n\n\n\nInternal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.\n\n
### Response body parameters\n\n\n
\n\nName\n\n\n\nDescription\n\n
\n\ncontentQuery\n\n\n\nValue of the content\\_query field in the created topic record.Data type: String\n\n
\n\nexternalId\n\n\n\nValue of the topic\\_id field in the created topic record.Data type: String\n\n
\n\nheaderQuery\n\n\n\nValue 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\n\n
\n\nid\n\n\n\nSys\\_id of the created topic record.Data type: String\n\n
\n\nname\n\n\n\nName of the topic.Data type: String\n\n
\n\nnamespace\n\n\n\nValue of the namespace field in the created topic record.Data type: String\n\n
### cURL request\n\nThe following code example shows how to call this endpoint.\n\n```\ncurl \"http://instance.servicenow.com/api/sn_api_notif_mgmt/topic\" \\\n--request POST \\\n--header \"Accept:application/json\" \\\n--user 'username':'password'\n--data\n{\n \"name\": \"HighPriorityTroubleTicket\",\n \"headerQuery\": \"eventType=TroubleTicketStatusChangeEvent,TroubleTicketAttributeChangeEvent\",\n \"contentQuery\": \"troubleTicket.ticketType=incident&troubleTicket.severity=1\",\n \"externalId\": \"ext001\",\n \"namespace\": \"telecomEvents\"\n}\n```\n\nResponse:\n\n```\n\n{\n \"externalId\": \"ext001\",\n \"name\": \"HighPriorityTroubleTicket\",\n \"headerQuery\": \"eventType=TroubleTicketStatusChangeEvent,TroubleTicketAttributeChangeEvent\",\n \"contentQuery\": \"troubleTicket.ticketType=incident&troubleTicket.severity=1\",\n \"namespace\": \"telecomEvents\",\n \"id\": \"7ee9850443c3f550461f99612bb8f223\"\n}\n```\n\n"}}