Events API

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

Events API

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
  },
  "resolution_duration": null,
  "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,
  "workflow": {
    "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": "R-Service Self Service",
  "next_target_at": "no_target",
  "template": null,
  "custom_fields": null,
  "waiting_until": null,
  "reviewed": true,
  "satisfaction": "satisfied",
  "knowledge_article": null,
  "urgent": false,
  "addressed": false,
  "feedback": {
    "requested_by": {
      "satisfied_url": "https://pro-product.r-service.tech/requests/68673/2sii015q/149/yes",
      "dissatisfied_url": "https://pro-product.r-service.tech/requests/68673/2sii015q/149/no"
    }
  }
}

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.

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 R-Service 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:

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 R-Service. So a separate call to the R-Service 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 R-Service.

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 R-Service 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 parameters can be used to make changes to the existing request:

completion_reason desired_completion_at downtime_start_at downtime_end_at status waiting_until team team_id member member_id

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.