Create or update an external incident

edit

Creates a new or updates an existing external incident from a Elastic Security case.

Console supports only Elasticsearch APIs. Console doesn’t allow interactions with Kibana APIs. You must use curl or another HTTP tool instead. For more information, refer to Run Elasticsearch API requests.

You can only send cases to external systems after you have created a connector.

Request URL

edit

POST <kibana host>:<port>/api/actions/connector/<connector ID>/_execute

URL parts

edit

The URL must include the connector ID. Call Get current connector to retrieve the currently used connector ID, or Find connectors to retrieve all connectors IDs.

Request body

edit

A JSON object with these fields:

Name Type Description Required

params

params

Contains the Elastic Security case details for which you are opening or updating an external incident.

Yes

params schema

Name Type Description Required

subAction

String

The action to be performed. When opening or updating cases in external systems, must be: pushToService.

Yes

subActionParams

subActionParams

Case details to send to external systems.

Yes

subActionParams schema

Name

Type

Description

Required

incident

incident

The incident.

Yes

comments

Object[]

Array containing case comments:

  • commentId (string, required): The comment ID.
  • comment (string, required): The comment text.

No

incident schema

Name

Type

Description

Required

alertId

String

The alert ID.

No. Valid only for Swimlane connectors.

caseId

String

The case ID.

No. Valid only for Swimlane connectors.

caseName

String

The case name.

No. Valid only for Swimlane connectors.

dest_ip

String

A comma separated list of destination IPs.

No. Valid only for ServiceNow SecOps connectors.

description

String

The case description.

No

externalId

String

The external incident/issue ID.

No, only required when updating an existing issue.

impact

String

ServiceNow ITSM incident impact.

No. Valid only for ServiceNow ITSM connectors.

incidentTypes

String

IBM Resilient incident types.

No. Valid only for IBM Resilient connectors.

issueType

String

Jira issue type.

No. Valid only for Jira connectors.

labels

String

Jira issue labels.

No. Valid only for Jira connectors.

malware_hash

String

A comma separated list of malware hashes.

No. Valid only for ServiceNow SecOps connectors.

malware_url

String

A comma separated list of malware URLs.

No. Valid only for ServiceNow SecOps connectors.

name

String

IBM Resilient organization incident name.

Yes. Valid only for IBM Resilient connectors.

parent

String

Jira issue parent.

No. Valid only for Jira connectors.

priority

String

Jira issue priority.

No. Valid only for Jira and ServiceNow SecOps connectors.

ruleName

String

The name of the alert’s rule.

No. Valid only for Swimlane connectors.

severity

String

ServiceNow ITSM incident severity.

No. Valid only for ServiceNow ITSM and Swimlane connectors.

severityCode

String

IBM Resilient incident severity code.

No. Valid only for IBM Resilient connectors.

short_description

String

ServiceNow incident name.

Yes. Valid only for ServiceNow connectors.

source_ip

String

A comma separated list of source IPs.

No. Valid only for ServiceNow SecOps connectors.

summary

String

Jira issue title.

Yes. Valid only for Jira connectors.

urgency

String

ServiceNow ITSM incident urgency.

No. Valid only for ServiceNow ITSM connectors.

When updating an existing case, call Get case or Find cases to retrieve the externalId. In the case JSON object, the externalId value is stored in the external_service field.

Example requests

edit

Creates a new ServiceNow incident:

POST api/actions/connector/7349772f-421a-4de3-b8bb-2d9b22ccee30/_execute
{
  "params": {
    "subAction": "pushToService",
    "subActionParams": {
      "comments": [
        {
          "commentId": "dda30310-732a-11ea-a0b2-c51ea50a58e2",
          "comment": "Comment about the incident",
        }
      ],
      "incident": {
        "description": "Description of the incident",
        "short_description": "Incident name"
      }
    }
  }
}

Updates an existing ServiceNow incident:

POST api/actions/connector/7349772f-421a-4de3-b8bb-2d9b22ccee30/_execute
{
  "params": {
    "subAction": "pushToService",
    "subActionParams": {
      "comments": [
        {
          "commentId": "8ef6d660-732f-11ea-a0b2-c51ea50a58e2",
          "comment": "Comment about the incident",
        }
      ],
      "incident": {
        "externalId": "cc6ef44bdb7300106ba884da0b9619cf",
        "short_description": "Incident name"
      }
    }
  }
}

Response code

edit
200
Indicates a successful call.

Response payload

edit

A JSON object with the ID and the URL of the external incident.

Example response

edit
{
  "status": "ok",
  "actionId": "61787f53-4eee-4741-8df6-8fe84fa616f7",
  "data": {
    "title": "INC0010012",
    "id": "62dc3c8bdb7300106ba884da0b9619ea",
    "pushedDate": "2020-03-31T09:01:33.000Z",
    "url": "https://dev78437.service-now.com/nav_to.do?uri=incident.do?sys_id=62dc3c8bdb7300106ba884da0b9619ea",
    "comments": [
      {
        "commentId": "dda30310-732a-11ea-a0b2-c51ea50a58e2",
        "pushedDate": "2020-03-31T09:01:34.000Z"
      }
    ]
  }
}