The SIEM app is now a part of the Elastic Security solution. Click here to view the current documentation.
IMPORTANT: No additional bug fixes or documentation updates will be released for this version.
« Actions API (for pushing cases to external systems) Update connector »
Elastic Docs ›SIEM Guide [7.8] ›SIEM APIs ›Actions API (for pushing cases to external systems)

Create connector

edit

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/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

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.

Yes

name

String

The registered ServiceNow connector.

Yes

config schema

Name Type Description Required

casesConfiguration

Object

Contains a mapping array, which determines how SIEM case fields are mapped to external system fields:

  • source (string): The name of the SIEM case field, which can be title, description, or comments.
  • target (string): The name of the mapped exterals field. For example: short_description (ServiceNow), title (Jira), description, and comments.
  • actionType (string): Determines whether SIEM 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 ServiceNow connectors, no.

Example requests

edit

Creates a ServiceNow connector:

POST api/action
{
  "actionTypeId": ".servicenow",
  "config": {
    "casesConfiguration": {
      "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"
  },
  "secrets": {
    "username": "admin",
    "password": "securePassword123!"
  },
  "name": "ServiceNow"
}

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

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

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

Creates a Jira connector:

POST api/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": "admin@hms.gov.co.uk",
    "apiToken": "my-api-token"
  },
  "name": "Jira"
}

SIEM case title fields are mapped to Jira summary fields.

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 responses

edit

ServiceNow connector:

{
  "id": "61787f53-4eee-4741-8df6-8fe84fa616f7",
  "actionTypeId": ".servicenow",
  "name": "ServiceNow",
  "config": {
    "casesConfiguration": {
      "mapping": [
        {
          "source": "title",
          "target": "short_description",
          "actionType": "overwrite"
        },
        {
          "source": "description",
          "target": "description",
          "actionType": "overwrite"
        },
        {
          "source": "comments",
          "target": "comments",
          "actionType": "append"
        }
      ]
    },
    "apiUrl": "https://dev78437.service-now.com"
  },
  "isPreconfigured": false
}

Jira connector:

{
  "id": "05da469f-1fde-4058-99a3-91e4807e2de8",
  "actionTypeId": ".jira",
  "name": "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"
  },
  "isPreconfigured": false
}
« Actions API (for pushing cases to external systems) Update connector »