Trouble Ticket Notification Open API (TMF621)
ServiceNow implementation of TMF 621Trouble Ticket Open API notification Support includes the following:
- The support of outbound notifications form the Trouble Ticket Open API to 3rd party ticketing systems. In other words, incidents and cases within ServiceNow that are being created or updated may may require notifications to be sent to subscribers, which could include other message buses, consumers, external systems etc.
- Event monitoring architecture using Kafka or Pub/Sub for on prem customers
- Enabling listener registration process by configuring callback endpoints
- Receive timely events and update processes using flows and actions
- ServiceNow aligns with TMForum Standard for sending these event notifications to the subscribers. Standard format is described in TMF 688.
- Supported API Operations include:
- Create Topic
- Trouble Ticket Create Event
- Trouble Ticket Attribute Value Change Event
- Trouble Ticket State change
Event Publication Mechanism
ServiceNow supports two different mechanism to publish messages to customers.
- Sending trouble ticket events in Hermes cluster and then consumed by the customer owned Kafka.
- Providing ability to produce events on any message bus placed in customer’s network.
- System will use TMF 688 payload(TMF621 notifications will be used for trouble tickets wrapped within TMF 688).
Trouble Ticket Event Production using Hermes Kafka – High Level Overview
The following is a high level description of the trouble ticket event journey using Hermes Kafka.
- Out-of-the-box events on the Incident/Case table trigger the system to push these events to the staging table- inbound queu. This process is showcased as part of th the out-of-the-box setup using business rules (BR).
- The scheduler selects the specified number of records at the configured frequency.
- The system converts the Glide snapshot to TMF 688 event.
- The system triggers the ProducerV2 API Stream Connect to publish a message to the topic configured by the customer after customization. (Please refer to the Developer’s Guide for further details)
- The event (Kafka message) is published in the Hermes Kafka cluster.
Trouble Ticket Event Creation with Hermes Kafka
The publishing of events via Hermes is a platform capability and hence the detailed information can be found in the existing documentation detailed below.
|
Stream Connect for Apache Kafka |
|
|
Hermes Messaging Service |
The Topic creation in topic table either manually or via Kafka cluster sync as part of out of the box functionality.
High Level Steps for Producing Events via a Message Bus
- All the message flow to a message bus that happens via the topic concept. Topics can either be created manually in the topic table or they can be created in the message bus and then synchronized to the ServiceNow Topic Table via scripted rest API.
- All the topics created manually are marked as User created=true.
- Topics receive inbound via scripted rest API are marked as “egress”
- A Business rule is created on the incident table which is triggered by the incident creation (trigger conditions can be modifies as per the customer needs).
- These different event types are then sent to the inbound queue wher the scheduler picks the message and then converts it into TMF 688 compatible payload.
- The system then transverses through all the egress topics to match the payload with the topic name. The header query is matched first followed by the content query is matched for that payload.
ServiceNow Implementation of Open API Trouble Ticket Notification Support (TMF 621)
ServiceNow Rest API Explorer
- Navigate to the Rest API Explorer
- Scroll down to Raw Data to create a Topic
- Add a Payload in the RAW tab
- Click on Submit
- A Pop Up will appear asking for confirmation, select “ok”
- Confirm that the the Topic has been successfully created by scrolling down to see the core: 201 Created
- Return to the Topic Table
- Navigate to ALL > Telecom API Notification
- Click on Topics
- A new model “Trouble Ticket Create” has been added
- Navigate to ALL > Telecom API Notification
Creating a New Incident
- Complete the incident as follows:
- Caller: Abel Tuter
- Short Description: Router issue and facing broadband slowness
- Right click and select “Save”
- The new record will be created with State set to “New”
- The scheduler will pick this up and change the state to “in Progress” followed by “Completed”
Flow Designer Verification
- Navigate to ALL > Process Automation > Flow Designer
- Two records are triggered
- Click on the first record
- In the first record, the payload that is being sent out can be verified to be TMF688 compliant
- The Topic can also be verified by clicking on it
- A second ticket was also created which is the Blank Topic where the Header and Content Query are blank
Error Codes and Warnings Descriptions
A list of error codes and warning along with their descriptions are listed below. These error codes and warnings are there to help in troubleshooting efforts.
UI Error while creating topic
The end user may encounter the following error - "Synchronizing topic with message bus failed" when creating topic manually from topic table (sn_api_notif_mgmt_topic) UI. This error indicates that the REST request configured to synchronize the Topic with the Message bus was not successful.
Error Status in Inbound Queue
This indicates that there was a runtime issue encountered while processing the event placed in the inbound queue (sn_tmt_core_inbound_queue). To determine the cause of the error, the "Error message" field of the TABLE may be examined to help determine the cause of error.
API Error Codes
(for 'Create Topic' -/api/sn_api_notif_mgmt/topic)
Topic external id passed already exists. Please pass the unique topic external id
Indicates that external id passed already exist in topic table (a unique index on topic_id already exists)
Please pass the unique combination of topic name, header query ,content query and namespace
Indicates that the combination of topic name, namespace, header query, content query already exists.(there is composite unique index on topic_name,header query,content query and namespace).
Configurations Needed for Feature Implementation
Within this feature, certain configurations need to be configured as part of setup process.
It’s important to note that these configurations will be applied at the Producer Notification Framework level and will therefore affect all events. This applies even if the customer attempts to use this framework to configure other types of events besides trouble tickets.
1. Repeat interval of schedule item entry - "Process events from inbound queue table"
Controls the frequency of the scheduler responsible for selecting the events from the "inbound queue" table and processing them.
Note : In the Washington release, customers are required to modify the repeat interval once, even if they wish to retain the out-of-the-box frequency, in order to "deploy the scheduler.
2. Configure the rest endpoint for synching egress topics from ServiceNow to the Message bus
In the out-of-the-box setup, whenever a new egress topic is created from the UI, the system triggers a business rule named 'Sync topic with external message bus'. By default, this business rule invokes a mock action that provides a mock Rest response. However, partners are expected configure their own REST step to synchronize the Topics with the Message bus.[Applicable with Open Message bus usecase only]
3.Configuring the rest Proxy for topics of message bus
As part of the Out-Of-The-Box setup, a new Request type 'Topic Rest Proxy Outbound Request' with name Spoke-selector has been established. Customers are anticipated to include more entries of request-definition in this request type based on their requirements and the architecture of the Message bus rest proxy. [Applicable with Open Message bus use case only]
4. Configuring the system properties with respect Producer Notification framework
As part of the Producer Notification Framework(utilized for sending Trouble ticket notifications), customers will require to configure certain system properties. Please documentation pertaining to system properties for details.
