Events API
Integrations Events and Mail API Events API

Events API

Introduction

The Events API is typically used by monitoring tools to create new requests in 4me.

Note that it is also possible for monitoring tools to use the Mail API to create new 4me requests based on an event. The 4me 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 4me. 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 (4me node IDs or 4me 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 4me 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 4me 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

curl -X POST -i -H "Authorization: Bearer <personal-token>" -H "X-4me-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"

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-4me-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-4me-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"

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-4me-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-4me-Account: wdc" -d '{"source":"Integrations Workshop", "sourceID":"attempt3", "subject":"Server Down", "ci":"ABC1234"}' "https://api.4me-demo.com/v1/events"

Next Topic