Create connector

edit

Creates a connector, which can then be used to open and update cases in external systems. Note that data from mapped case fields can be pushed to external systems but cannot be pulled in.

Request URL

edit

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

Request body

edit

A JSON object with these fields:

Name Type Description Required

connector_type_id

String

Must be one of these:

  • .servicenow: Send cases to ServiceNow ITSM
  • .servicenow-sir: Send cases to ServiceNow SecOps
  • .jira: Send cases to Jira
  • .resilient Send cases to IBM Resilient
  • .swimlane Send cases to Swimlane

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 ITSM and ServiceNow SecOps 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.

For Swimlane connectors:

  • apiToken (string): Swimlane API authentication token.

Yes

name

String

The connector’s name.

Yes

config schema

Name Type Description Required

apiUrl

String

URL of the third-party instance.

Yes

appId

String

Swimlane application ID.

For Swimlane connectors, yes. or other connectors, no.

connectorType

String

The type of the connector.

Must be one of these:

  • all
  • alerts
  • cases

For Swimlane connectors, yes. For other connectors, no.

mappings

Object

The field mapping.

Must be:

  • alertIdConfig (Object): Mapping for the alert ID.
  • caseIdConfig (Object): Mapping for the case ID.
  • caseNameConfig (Object): Mapping for the case name.
  • commentsConfig (Object): Mapping for the case comments.
  • ruleNameConfig (Object): Mapping for the name of the alert’s rule.
  • severityConfig (Object): Mapping for the severity.
  • descriptionConfig (Object): Mapping for the case description.

The object of each attribute in the mappings must be:

  • id (string): The id of the field in Swimlane.
  • key (string): The key of the field in Swimlane.
  • name (string): The name of the field in Swimlane.
  • fieldType (Object): The type of the field in Swimlane.

For Swimlane connectors, yes. or other connectors, no.

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.

Example requests

edit

Creates a ServiceNow ITSM connector:

POST api/actions/connector
{
  "connector_type_id": ".servicenow",
  "config": {
    "apiUrl": "https://dev87359.service-now.com",
  },
  "secrets": {
    "username": "admin",
    "password": "securePassword123!"
  },
  "name": "ServiceNow ITSM"
}

Creates a ServiceNow SecOps connector:

POST api/actions/connector
{
  "connector_type_id": ".servicenow-sir",
  "config": {
    "apiUrl": "https://dev87359.service-now.com",
  },
  "secrets": {
    "username": "admin",
    "password": "securePassword123!"
  },
  "name": "ServiceNow SecOps"
}

Creates a Jira connector:

POST api/actions/connector
{
  "connector_type_id": ".jira",
  "config": {
    "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/connector
{
  "connector_type_id": ".resilient",
  "config": {
    "apiUrl": "https://ibm-resilient.siem.estc.dev",
    "orgId": "201"
  },
  "secrets": {
    "apiKeyId": "2ad2bbd3-7cd2-3096-9619-de13c5ab70ca",
    "apiKeySecret": "Hzol67ZoeATAR-8pQxSp3q_NPTDtWU6_QNBoCSCA-ic"
  },
  "name": "IBM"
}

Creates a Swimlane connector:

POST api/actions/connector
{
   "name":"Swimlane",
   "config":{
      "connectorType":"all",
      "mappings":{
         "ruleNameConfig":{
            "id":"b6fst",
            "name":"Alert Name",
            "key":"alert-name",
            "fieldType":"text"
         },
         "alertIdConfig":{
            "id":"bpvow",
            "name":"Alert ID",
            "key":"alert-id",
            "fieldType":"text"
         },
         "caseIdConfig":{
            "id":"be1mi",
            "name":"Case ID",
            "key":"case-id",
            "fieldType":"text"
         },
         "caseNameConfig":{
            "id":"bnxnr",
            "name":"Case Name",
            "key":"case-name",
            "fieldType":"text"
         },
         "commentsConfig":{
            "id":"bu18d",
            "name":"Comments",
            "key":"comments",
            "fieldType":"comments"
         },
         "severityConfig":{
            "id":"b71ik",
            "name":"severity",
            "key":"severity",
            "fieldType":"text"
         },
         "descriptionConfig":{
            "id":"b5zrn",
            "name":"Description",
            "key":"description",
            "fieldType":"text"
         }
      },
      "appId":"myAppID",
      "apiUrl":"https://myswimlaneinstance.com"
   },
   "secrets":{
      "apiToken":"secureToken"
   }
}

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",
  "connector_type_id": ".servicenow",
  "name": "SN API 2",
  "config": {
    "apiUrl": "https://dev185413.service-now.com",
  },
  "isPreconfigured": false
}