Introduction

Query incidents for a given period of time based on properties of the incident or properties of the events correlated to the incidents. By default, incidents created in the last 7 days will be retrieved and filtered. A start time and end time can be provided to define the time range, but the range is limited to a 30 day period. The query also has a limit of 500 incidents being returned for any query.

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response always indicates success. A 400 type response is some sort of failure, and a 500 type response usually indicates an internal system error.

Methods

Query incidents by incident properties and properties of the correlated events

Query incidents for a given period of time based on properties of the incident or properties of the events correlated to the incidents. By default, incidents created in the last 7 days will be retrieved and filtered. A start time and end time can be provided to define the time range, but the range is limited to a 30 day period. The query also has a limit of 500 incidents being returned for any query. Incidents can be requested by incident properties, like incident priority and incident state. You can also set 1 or more event filters that set conditions on events that must be correlated to an incident for it to be included in the query results. You can filter only on incident properties, only on properties of the correlated events, or a combination of the two. Restrictions on incident/event filter expressions:

  • Attribute names are case sensitive

  • Expressions must include an attribute name, operator, and value (no value is allowed for operators "is empty" "is not empty")

  • There must be at least one space between the attribute name and operator and the operator and value.

  • Operators and logical operators are case insensitive 'or' == 'OR' == 'Or'

  • Only "or's" or "and's" are allowed in an expression, not a mixture of both

  • No parentheses are allowed for grouping expressions

Use the URLs provided to see the specifications for the incident attributes and event attributes, including valid operators and and constraints on the value.

Example expressions for incident filter:

  • lastChanged > "2017-08-01"
  • priority == 5 OR priority == 4
  • priority == 1 and state != 'closed' and assignedBy == 'POLICY'

Example expressions for event filter (up to 5 filters supported):

  • severity >= "minor"
  • summary starts with "Failure" and resource.application == "payroll"
  • type.eventType == 'a1' or type.eventType == 'a2' or type.eventType == 'a3'

For best performance, filter the incidents as much as possible using the incident properties. This will reduce the number of incidents that must be further processed against their events if event filter properties are specified.

GET /incidentquery/v1
Request

Query Parameters

  • Beginning UTC timestamp (YYYY-MM-DDTHH:mm:SS.sssZ) for range of incidents to query - will default to system configured value of 7 days ago. This time is compared to the "created" time of an incident to determine if the incident should be included. Example values: 2017-09-12T08:00:00.000Z, 2017-09-12T08:00, 2017-09-12

  • Ending UTC timestamp (YYYY-MM-DDTHH:mm:SS.sssZ) for range of incidents to query - - will default to current time. This time is compared to the "created" time of an incident to determine if the incident should be included. Example values: 2017-09-14T17:00:00.000Z, 2017-09-14T17:00, 2017-09-14

  • A condition filter that specifies expression matches for incident properties

  • Set to "and" or "or" to indicate how the event filters should be combined when filtering by event content. The default is to combine the event filters using the "and" operator, meaning all event filters must be satisfied by any returned incident. Use "or" if only one of the event filters must be satisfied.

    Allowable values: [and,or]

    Default: and

  • A condition filter that specifies expression matches for the properties of a single event on the incident

  • A condition filter that specifies expression matches for the properties of a single event on the incident

  • A condition filter that specifies expression matches for the properties of a single event on the incident

  • A condition filter that specifies expression matches for the properties of a single event on the incident

  • A condition filter that specifies expression matches for the properties of a single event on the incident

Response

A single incident defined in the Cloud Event Management data store

Status Code

  • Array of incidents retrieved

  • Bad request

  • Internal server error

No Sample Response

This method does not specify any sample responses.

Query the specifications for incident attributes allowed in incident filter conditions.

Query information that describes the attributes of an incident that can be used for creating filters for querying incidents. This will list valid attribute names, descriptions, valid operators, and any restrictions on the value.

GET /incidentquery/v1/incidentattributes
Request

No Request Parameters

This method does not accept any request parameters.

Response

Status Code

  • Array of attribute specs that constrain filter conditions for incident queries

  • Bad request

  • Internal server error

No Sample Response

This method does not specify any sample responses.

Query the specifications for event attributes allowed in event filter conditions.

Query information that describes the attributes of events in an incident that can be used for creating filters for querying incidents. This will list valid attribute names, descriptions, valid operators, and any restrictions on the value.

GET /incidentquery/v1/eventattributes
Request

No Request Parameters

This method does not accept any request parameters.

Response

Status Code

  • Array of attribute specs that constrain filter conditions for incident queries

  • Bad request

  • Internal server error

No Sample Response

This method does not specify any sample responses.

Query the properties of a specific incident.

Query the properties for a specific incident. The incident UUID must be specified in the requesting URL. This URL is returned in the response for each incident found when using the main incident query endpoint /incidentquery/v1.

GET /incidentquery/v1/{id}
Request

Path Parameters

  • UUID of incident to retrieve

    Constraints: Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-1[0-9a-f]{3}-[0-9a-f]{4}-[0-9a-f]{12}$

Response

A single incident defined in the Cloud Event Management data store

Status Code

  • Single incident

  • Bad request

  • Requested object was not found

  • Internal server error

No Sample Response

This method does not specify any sample responses.

Query the events for a specific incident.

Query the events for a specific incident. The incident UUID must be specified in the requesting URL. This URL is returned in the response for each incident found when using the main incident query endpoint /incidentquery/v1.

GET /incidentquery/v1/{id}/events
Request

Path Parameters

  • UUID of incident to retrieve

    Constraints: Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-1[0-9a-f]{3}-[0-9a-f]{4}-[0-9a-f]{12}$

Response

Status Code

  • Array of incident events retrieved

  • Bad request

  • Internal server error

No Sample Response

This method does not specify any sample responses.

Query the timeline for a specific incident.

Query the timeline entries for a specific incident. The incident UUID must be specified in the requesting URL. This URL is returned in the response for each incident found when using the main incident query endpoint /incidentquery/v1.

GET /incidentquery/v1/{id}/timeline
Request

Path Parameters

  • UUID of incident to retrieve

    Constraints: Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-1[0-9a-f]{3}-[0-9a-f]{4}-[0-9a-f]{12}$

Response

Description of a change to an incident

Status Code

  • Array of incident timeline entries retrieved

  • Bad request

  • Internal server error

No Sample Response

This method does not specify any sample responses.