Events API

The Events API is typically used by monitoring tools to create new requests in ITRP based on events. It is also possible for monitoring tools to use the Mail API to register new requests.

Submit Event

POST /events?subject=Server%20Down&source=MyMonitoringTool&sourceID=882395&note=Not%20reachable

When posting an event these parameters are available. For most of the required request fields the Events API uses default values in case a value is not specified.

Response Request created

If a new request is created based for a given event, the following response is returned.

Status: 201 Created
{
  "service_instance": {
    "name": "Data Center Rack Space",
    "id": 29
  },
  "organization": {
    "id": 44,
    "name": "Widget Data Center, External IT"
  },
  "completion_reason": "solved",
  "completed_at": "2014-03-04T02:14:00-06:00",
  "desired_completion_at": "2014-03-04T03:00:00-06:00",
  "requested_by": {
    "name": "Patrick Spratt",
    "id": 56
  },
  "created_by": {
    "name": "Patrick Spratt",
    "id": 56
  },
  "created_at": "2009-02-02T12:18:00-06:00",
  "category": "rfc",
  "sourceID": null,
  "downtime_start_at": null,
  "updated_at": "2016-03-14T03:14:13-06:00",
  "supplier": null,
  "resolution_target_at": null,
  "requester_resolution_target_at": null,
  "new_assignment": false,
  "grouping": "none",
  "grouped_into": null,
  "member": {
    "name": "Carla Cluster",
    "id": 54
  },
  "supplier_requestID": null,
  "subject": "Add new rack in data center",
  "response_target_at": null,
  "id": 68673,
  "requested_for": {
    "name": "Patrick Spratt",
    "id": 56
  },
  "problem": null,
  "change": {
    "id": 238,
    "subject": "Install new rack"
  },
  "project": null,
  "ci": null,
  "downtime_end_at": null,
  "impact": null,
  "team": {
    "name": "Unix Servers",
    "id": 13
  },
  "status": "completed",
  "source": "self service",
  "next_target_at": "no_target",
  "template": null,
  "custom_data": null,
  "waiting_until": null,
  "reviewed": true,
  "satisfaction": "satisfied",
  "knowledge_article": null,
  "urgent": false,
  "addressed": false
}

Default values

To simplify request creation by system management or monitoring tools, default values are used when values have not been provided for request fields that are required.

category
Set to incident if a service instance is to be related to the request. Otherwise, set to other.
created_by
Set to the current user
impact
Set to top if category is incident. Otherwise the Impact field of the request is left empty.
member
Set to the current user if a valid member is not provided and a status is specified that causes the Member field of the request to be required. When the template_id parameter is used and the request template is linked to a change template, then the Member field of the request is set to the manager of the change.
requested_by
Set to the current user
requested_for
Set to the current user
service_instance
Set to the first service instance of the configuration item when a configuration item is specified for the request.
source
Set to event.
status
Set to assigned. When the template_id parameter is used and the request template is linked to a change template, then set to change_pending.
team
The team to which the person specified as the member belongs. Otherwise, if a service instance is to be related to the request, the First Line Team of this service instance or, if a First Line Team is not specified or the current user is a member of the First Line Team or the Support Team, the Support Team of this service instance. Else, set to the Service Desk Team of the first line support agreement that covers the account of the person selected in the Requested for field.
Note: if an invalid team was specified in the API call, the default team is selected in the request.

Relying on all default values makes it possible to create a request by providing only the subject field. It is recommended, though, to always specify the source, note and configuration item when possible.

Source

When creating a new request using the Events API, the source of the new request is set to event by default. It is best practice, however, to always specify the name of the monitoring tool that passed the event to ITRP as the source.

This also improves the matching of events in case multiple system management tools monitor the same Configuration Items.

Parameters

The following parameters can be used in an Events API call to set the field values of the request:

category
Used to specify an option in the Category field of the request. The available field options can be found in the Fields section of the Requests API page.
change_id
Used to specify the change that is to be related to the request. The change needs to be identified by its ITRP ID.
ci
Used to specify the configuration item that is to be related to the request. The configuration item needs to be identified by its label or, in case of a software CI, its Name field value.
ci_id
Used to specify the configuration item that is to be related to the request. The configuration item needs to be identified by its ITRP ID.
ci_source
Used together with the ci_sourceID parameter to specify the configuration item that is to be related to the request. This parameter should be used to specify the configuration item’s Source field value.
ci_sourceID
Used together with the optional ci_source parameter to specify the configuration item that is to be related to the request. The configuration item needs to be defined using its Source ID field value.
completion_reason
Used to specify an option in the Completion reason field of the request when its Status field is set to ‘completed’. The available field options can be found in the Fields section of the Requests API page.
desired_completion_at
Used to specify the date and time that has been agreed on for the completion of the request. The desired completion overwrites the automatically calculated resolution target of any affected SLA that is related to the request when the desired completion is later than the affected SLA’s resolution target. By default, the requested_by receives a notification based on the ‘Desired Completion Set for Request’ email template whenever the desired_completion_at is set, updated or removed.
downtime_end_at
Used to specify the end date and time of a service outage. Be sure to use the correct datetime format.
downtime_start_at
Used to specify the start date and time of a service outage. Be sure to use the correct datetime format.
impact
Used to specify an option in the Impact field of the request. The available field options can be found in the Fields section of the Requests API page.
internal_note
Used to provide the text that needs to be added as an Internal Note to the request. Be sure to apply URL encoding for a valid URI syntax when, for example, spaces are included in the text.
member
Used to specify the person to which the request is to be assigned. This person needs to be identified by the Person record’s Primary email field value.
member_id
Used to specify the person to which the request is to be assigned. This person needs to be identified by the Person record’s ITRP ID.
note
Used to provide the text that needs to be added as a Note to the request. Be sure to apply URL encoding for a valid URI syntax when, for example, spaces are included in the text.
problem_id
Used to specify the problem that is to be related to the request. The problem needs to be identified by its ITRP ID.
requested_for
Used to specify the person who is to be selected in the Requested for field of the request. This person needs to be identified by the Person record’s Primary email field value.
requested_for_id
Used to specify the person who is to be selected in the Requested for field of the request. This person needs to be identified by the Person record’s ITRP ID.
service_instance
Used to specify the service instance that is to be related to the request. The service instance needs to be identified by its Name field value.
service_instance_id
Used to specify the service instance that is to be related to the request. The service instance needs to be identified by its ITRP ID.
source
Used to specify the name of the monitoring tool, see source. After the request has been created, this value is visible in its Audit Trail.
source_id
Used to specify the unique ID of the event for which the request is to be registered, see source. After the request has been created, this value is visible in its Audit Trail.
status
Used to specify an option in the Status field of the request. The available field options can be found in the Fields section of the Requests API page.
subject
Used to specify the Subject of the request. Be sure to apply URL encoding for a valid URI syntax when, for example, spaces are included in the text.
supplier
Used to specify the Organization to which the request has been submitted. The Organization needs to be identified by its Name field value.
supplier_id
Used to specify the Organization to which the request has been submitted. The Organization needs to be identified by its ITRP ID.
supplier_requestID
Used to specify the identifier under which the request has been registered at the supplier organization.
support_domain
Used to specify the support domain account ID in which the request is to be registered. This parameter needs to be specified when the current user’s Person record is registered in a directory account. The ID of an ITRP account can be found in the ‘Account Overview’ section of the Settings console.
team
Used to specify the team to which the request is to be assigned. The team needs to be identified by its Name field value.
team_id
Used to specify the team to which the request is to be assigned. The team needs to be identified by its ITRP ID.
template_id
Used to specify the request template that is to be applied to the request. This request template needs to be identified by its ITRP ID. It is important to note that the field values specified in the API call overwrite the values specified in the request template.
waiting_until
Used to specify the date and time at which the status of the request is to be updated from waiting_for to assigned. Be sure to use the correct datetime format.

Configuration Item

When creating new requests, the ci_id parameter defines the reference to a configuration item. In most cases, however, monitoring tools will not know the ID of the configuration item by which it is known in ITRP. So a separate call to the ITRP API would be needed to fetch the ci_id based on the source and sourceID of the configuration item.

To simplify the CI selection, the Events API accepts the ci parameter so that that the value in the CI’s Label field can be used to find the CI in ITRP.

The combination of the ci_source (optional) and ci_sourceID parameters can also be used to identify the CI that is to be related to the request. This can be useful, for instance, when a discovery tool registered the CI in ITRP and entered a value in its source and sourceID fields. Example:

POST /events?subject=Server%20Down&source=MyMonitoringTool&sourceID=12345&ci_source=MyDiscoveryTool&ci_sourceID=56789

Event matching

If an event is submitted within 24 hours of the creation of an existing open request that has the same source, service_instance, and ci parameters, then a new request does not get generated. Instead the note parameter is used to add a new note to the existing request. To avoid duplicate notes, however, the note is only added when its text is different from a previous note of the existing request. If the note parameter is the same as a previous note, or if the note parameter is not provided, then no changes are made to the existing request.

If an existing request is updated for a given event, the following response is returned.

Status: 200 OK
{
  "category": "...",
  "...": "..."
}

The response contains all fields of the updated request and is similar to the response in Response Request created

When the service_instance parameter is not included in the event, it is found by looking up the service instance to which the configuration item is linked. Once the service instance is known, the event matching starts.

When the ci parameter is not included in the event, event matching will not prevent the generation of a new request unless the subject and note parameters, as well as the account, source, and requested_for parameters are the same as those of an existing open request that was generated within the past 24 hours.