IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Actions API (for pushing cases to external systems) Update connector »
Elastic Docs ›Elastic Security Solution [7.10] ›Elastic Security APIs ›Actions API (for pushing cases to external systems)

Create connector

edit
IMPORTANT: This documentation is no longer updated. Refer to Elastic's version policy and the latest documentation.

Create connector

edit

Creates a connector, which can then be used to open and update cases in external systems.

Request URL

edit

POST <kibana host>:<port>/api/actions/action

Request body

edit

A JSON object with these fields:

Name Type Description Required

actionTypeId

String

Must be one of these:

  • .servicenow: Send cases to ServiceNow
  • .jira: Send cases to Jira
  • .resilient Send cases to IBM Resilient

Yes

config

config

Object containing the action’s configuration.

Yes

secrets

Object

Object containing the third-party account information used to create and update incidents.

For ServiceNow connectors:

  • username (string): The account username.
  • password (string): The account password.

For Jira connectors:

  • email (string): The account email.
  • apiToken (string): Jira API authentication token.

For IBM Resilient connectors:

  • apiKeyId (string): The authentication key ID.
  • apiKeySecret (string): The authentication key secret.

Yes

name

String

The connector’s name.

Yes

config schema

Name Type Description Required

casesConfiguration

incidentConfiguration

Object

Use casesConfiguration for all connectors apart from ServiceNow. For ServiceNow, use incidentConfiguration. Contains a mapping array, which determines how Elastic Security case fields are mapped to external system fields:

  • source (string): The name of the Elastic Security case field, which can be title, description, or comments.
  • target (string): The name of the mapped external field. For example: short_description (ServiceNow), title (Jira), name (IBM Resilient), description, and comments.
  • actionType (string): Determines whether Elastic Security case updates overwrite or append to the mapped incident fields. Valid values are overwrite and append.

Yes

apiUrl

String

URL of the third-party instance.

Yes

projectKey

String

Jira project key.

For Jira connectors, yes. For other connectors, no.

orgId

String

IBM Resilient organization ID.

For IBM Resilient connectors, yes. For other connectors, no.

isCaseOwned

Boolean

Indicates a ServiceNow connector is used for Elastic Security cases. Must be true.

For ServiceNow connecters only, yes. For other connectors, no.

Example requests

edit

Creates a ServiceNow connector:

POST api/actions/action
{
  "actionTypeId": ".servicenow",
  "config": {
    "incidentConfiguration": {
      "mapping": [
        {
          "source": "title", 
          "target": "short_description",
          "actionType": "overwrite"
        },
        {
          "source": "description", 
          "target": "description",
          "actionType": "overwrite"
        },
        {
          "source": "comments", 
          "target": "comments",
          "actionType": "append"
        }
      ]
    },
    "apiUrl": "https://dev87359.service-now.com",
    "isCaseOwned": true
  },
  "secrets": {
    "username": "admin",
    "password": "securePassword123!"
  },
  "name": "ServiceNow"
}

Elastic Security case title fields are mapped to ServiceNow short_description fields. When a Elastic Security title field is updated and sent to ServiceNow, the ServiceNow short_description field is overwritten.

Elastic Security case description fields are mapped to ServiceNow description fields. When a Elastic Security description field is updated and sent to ServiceNow, the ServiceNow description field is overwritten.

Elastic Security case comments fields are mapped to ServiceNow comments fields. When a Elastic Security comments field is updated and sent to ServiceNow, the updated text is appended to the ServiceNow comments field.

Creates a Jira connector:

POST api/actions/action
{
  "actionTypeId": ".jira",
  "config": {
    "casesConfiguration": {
      "mapping": [
        {
          "source": "title",
          "target": "summary",
          "actionType": "overwrite"
        },
        {
          "source": "description",
          "target": "description",
          "actionType": "overwrite"
        },
        {
          "source": "comments",
          "target": "comments",
          "actionType": "append"
        }
      ]
    },
    "apiUrl": "https://hms.atlassian.net",
    "projectKey": "HMS"
  },
  "secrets": {
    "email": "[email protected]",
    "apiToken": "my-api-token"
  },
  "name": "Jira"
}

Creates an IBM Resilient connector:

POST api/actions/action
{
  "actionTypeId": ".resilient",
  "config": {
    "casesConfiguration": {
      "mapping": [
        {
          "source": "title",
          "target": "name",
          "actionType": "overwrite"
        },
        {
          "source": "description",
          "target": "description",
          "actionType": "overwrite"
        },
        {
          "source": "comments",
          "target": "comments",
          "actionType": "append"
        }
      ]
    },
    "apiUrl": "https://ibm-resilient.siem.estc.dev",
    "orgId": "201"
  },
  "secrets": {
    "apiKeyId": "2ad2bbd3-7cd2-3096-9619-de13c5ab70ca",
    "apiKeySecret": "Hzol67ZoeATAR-8pQxSp3q_NPTDtWU6_QNBoCSCA-ic"
  },
  "name": "IBM"
}

Response code

edit
200
Indicates a successful call.

Response payload

edit

A JSON object with a connector id that is required to push cases to ServiceNow.

Example response

edit

ServiceNow connector:

{
  "id": "f07a60c7-a340-4cb1-93b8-1f5e35dc56b1",
  "actionTypeId": ".servicenow",
  "name": "SN API 2",
  "config": {
    "apiUrl": "https://dev185413.service-now.com",
    "incidentConfiguration": {
      "mapping": [
        {
          "actionType": "overwrite",
          "source": "title",
          "target": "short_description"
        },
        {
          "actionType": "overwrite",
          "source": "description",
          "target": "description"
        },
        {
          "actionType": "append",
          "source": "comments",
          "target": "comments"
        }
      ]
    },
    "isCaseOwned": true
  },
  "isPreconfigured": false
}
« Actions API (for pushing cases to external systems) Update connector »