Events API
Introduction
The Events API is typically used by monitoring tools to create new requests in Xurrent.
Note that it is also possible for monitoring tools to use the Mail API to create new Xurrent requests based on an event. The Xurrent Mail API is the next topic in this Training.
Tool to Test Events API: CURL
If you already have your own developer tools you are free to use these during this training.
CURL enables you to send HTTPs requests from the command line. CURL is easy to use and will give you a good understanding of the structure of the API requests. All exercises in the Events API Training can be executed with a CURL statement and the solutions in this training are provided as CURL statements.
To install CURL download the executable for your environment and place it on the PATH. Type curl --version in a command prompt to make sure the installation was successful.
Access Rights
You need to specifiy a personal access token with the correct access rights to create requests in Xurrent. Check this topic in the GraphQL training and create a personal access token for Howard Tanner.
Events API compared to GraphQL or REST API
You can create new requests with the GraphQL requestCreate mutation or the REST API /requests service. But these APIs only accept references (Xurrent node IDs or Xurrent IDs) to link the new request to a team, member, service instance, CI, etc. info not available in the monitoring system. The Events API is a REST API endpoint thas been added to work with the Name or Subject of a record, or with a record’s Source/SourceID combination.
When creating new requests using an integration it is recommended to always specify the Source and SourceID with Source the name of the system that triggered the event and SourceID the unique identifier of the event in that system.
Event Matching
The Xurrent Event API (and Mail API !) provide a build-in event matching mechanism. Monitoring systems can start to ‘spam’ a service management systems with always the same event. With the Xurrent Event Matching you can make sure that when an event is submitted within 24 hours of the creation of an existing open request the existing request is updated and no new requests get generated. Check this section on Event Matching for the details.
Exercises
Can you create an RFI in the ‘wdc’ account for chris.ball@widget.com on the ‘Houston Office Network’ SI?
curl -X POST -i -H "Authorization: Bearer <personal-token>" -H "X-Xurrent-Account: wdc" -d '{"source":"Integrations Workshop", "sourceID":"attempt1", "subject":"Unable to connect", "note":"First time here", "category":"rfi", "requested_for":"chris.ball@widget.com", "service_instance":"Houston Office Network"}' "https://api.4me-demo.com/v1/events"
Can you create an RFC in the ‘wdc’ account for beatrice.baldwin@widget.com based on the ‘Move Widget Data Center desktop PC’ request template when her PC’s label is ‘CMP00023’?
First use the Request Templates API to find the ID of the ‘Move Widget Data Center desktop PC’ template:
curl -X GET -i -H "Authorization: Bearer <personal-token>" -H "X-Xurrent-Account: wdc" "https://api.4me-demo.com/v1/request_templates?subject=Move%20Widget%20Data%20Center%20desktop%20PC&fields=id"
Then use the template ID to create the event:
curl -X POST -i -H "Authorization: Bearer <personal-token>" -H "X-Xurrent-Account: wdc" -d '{"source":"Integrations Workshop", "sourceID":"attempt2", "requested_for":"beatrice.baldwin@widget.com", "ci":"CMP00023", "template_id":"1234"}' "https://api.4me-demo.com/v1/events"
Can you create a ‘down’ event in the ‘wdc’ account for the ‘Expense Reporting Production Database’ CI?
First use the Configuration Items API to find the label of the ‘Expense Reporting Production Database’ CI in the ‘wdc’ account:
curl -X GET -i -H "Authorization: Bearer <personal-token>" -H "X-Xurrent-Account: wdc" "https://api.4me-demo.com/v1/cis?name=Expense%20Reporting%20Production%20Database&fields=label&updated_at=>2010-01-05T23:00:00Z"
Then use the label of the configuration item to create the event in the ‘wdc’ account:
curl -X POST -i -H "Authorization: Bearer <personal-token>" -H "X-Xurrent-Account: wdc" -d '{"source":"Integrations Workshop", "sourceID":"attempt3", "subject":"Server Down", "ci":"ABC1234"}' "https://api.4me-demo.com/v1/events"