IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Action and connector APIs Delete connector API »
Elastic Docs ›Kibana Guide [8.5] ›REST API ›Action and connector APIs

Create connector API

edit

Create connector API

edit

Creates a connector.

Request

edit

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

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

Prerequisites

edit

You must have all privileges for the Actions and Connectors feature in the Management section of the Kibana feature privileges.

Path parameters

edit
space_id
(Optional, string) An identifier for the space. If space_id is not provided in the URL, the default space is used.

Request body

edit
config

(Required*, object) The configuration for the connector. Configuration properties vary depending on the connector type. For example:

Config properties
IBM Resilient connectors
apiUrl
(Required, string) The IBM Resilient instance URL.
orgId
(Required, string) The IBM Resilient organization ID.

For more information, refer to IBM Resilient.

Index connectors
executionTimeField
(Optional, string) Specifies a field that will contain the time the alert condition was detected. The default value is null.
index
(Required, string) The Elasticsearch index to be written to.
refresh
(Optional, boolean) The refresh policy for the write request. The default value is false.

For more information, refer to Index.

Jira connectors
apiUrl
(Required, string) The Jira instance URL.
projectKey
(Required, string) The Jira project key.

For more information, refer to Jira.

ServiceNow ITOM, ServiceNow ITSM, and ServiceNow SecOps connectors
apiUrl
(Required, string) The ServiceNow instance URL.
clientId
(Required*, string) The client ID assigned to your OAuth application. This property is required when isOAuth is true.
isOAuth
(Optional, string) The type of authentication to use. The default value is false, which means basic authentication is used instead of open authorization (OAuth).
jwtKeyId
(Required*, string) The key identifier assigned to the JWT verifier map of your OAuth application. This property is required when isOAuth is true.
userIdentifierValue
(Required*, string) The identifier to use for OAuth authentication. This identifier should be the user field you selected when you created an OAuth JWT API endpoint for external clients in your ServiceNow instance. For example, if the selected user field is Email, the user identifier should be the user’s email address. This property is required when isOAuth is true.
usesTableApi

(Optional, string) Determines whether the connector uses the Table API or the Import Set API. This property is supported only for ServiceNow ITSM and ServiceNow SecOps connectors.

If this property is set to false, the Elastic application should be installed in ServiceNow.

Swimlane connectors
apiUrl
(Required, string) The Swimlane instance URL.
appId
(Required, string) The Swimlane application ID.
connectorType
(Required, String) The type of the connector. Valid values are: all, alerts, cases.
mappings

(Optional, object) The field mapping.

Mappings properties
alertIdConfig

(Optional, object) Mapping for the alert ID.

fieldType
(Required, object) The type of the field in Swimlane.
id
(Required, string) The id of the field in Swimlane.
key
(Required, string) The key of the field in Swimlane.
name
(Required, string) The name of the field in Swimlane.
caseIdConfig

(Optional, object) Mapping for the case ID.

fieldType
(Required, object) The type of the field in Swimlane.
id
(Required, string) The id of the field in Swimlane.
key
(Required, string) The key of the field in Swimlane.
name
(Required, string) The name of the field in Swimlane.
caseNameConfig

(Optional, object) Mapping for the case name.

fieldType
(Required, object) The type of the field in Swimlane.
id
(Required, string) The id of the field in Swimlane.
key
(Required, string) The key of the field in Swimlane.
name
(Required, string) The name of the field in Swimlane.
commentsConfig

(Optional, object) Mapping for the case comments.

fieldType
(Required, object) The type of the field in Swimlane.
id
(Required, string) The id of the field in Swimlane.
key
(Required, string) The key of the field in Swimlane.
name
(Required, string) The name of the field in Swimlane.
descriptionConfig

(Optional, object) Mapping for the case description.

fieldType
(Required, object) The type of the field in Swimlane.
id
(Required, string) The id of the field in Swimlane.
key
(Required, string) The key of the field in Swimlane.
name
(Required, string) The name of the field in Swimlane.
ruleNameConfig

(Optional, object) Mapping for the name of the alert’s rule.

fieldType
(Required, Object) The type of the field in Swimlane.
id
(Required, string) The id of the field in Swimlane.
key
(Required, string) The key of the field in Swimlane.
name
(Required, string) The name of the field in Swimlane.
severityConfig

(Optional, object) Mapping for the severity.

fieldType
(Required, object) The type of the field in Swimlane.
id
(Required, string) The id of the field in Swimlane.
key
(Required, string) The key of the field in Swimlane.
name
(Required, string) The name of the field in Swimlane.

For more information, refer to Swimlane.

Webhook - Case Management connectors
createCommentJson

(Optional, string) A JSON payload sent to the create comment URL to create a case comment. You can use variables to add Kibana Cases data to the payload. The required variable is case.comment. For example: 

{
  "body": {{{case.comment}}}
}

Due to Mustache template variables (the text enclosed in triple braces, for example, {{{case.title}}}), the JSON is not validated when you create the connector. The JSON is validated once the Mustache variables have been placed when the REST method runs. Manually ensure that the JSON is valid, disregarding the Mustache variables, so the later validation will pass.

createCommentMethod
(Optional, string) The REST API HTTP request method to create a case comment in the third-party system. Valid values are either patch, post, and put. The default value is put.
createCommentUrl

(Optional, string) The REST API URL to create a case comment by ID in the third-party system. You can use a variable to add the external system ID to the URL. If you are using the xpack.actions.allowedHosts setting, make sure the hostname is added to the allowed hosts. For example: 

https://testing-jira.atlassian.net/rest/api/2/issue/{{{external.system.id}}}/comment
createIncidentJson

(Required, string) A JSON payload sent to the create case URL to create a case. You can use variables to add case data to the payload. Required variables are case.title and case.description. For example: 

{
	"fields": {
	  "summary": {{{case.title}}},
	  "description": {{{case.description}}},
	  "labels": {{{case.tags}}}
	}
}

Due to Mustache template variables (which is the text enclosed in triple braces, for example, {{{case.title}}}), the JSON is not validated when you create the connector. The JSON is validated after the Mustache variables have been placed when REST method runs. Manually ensure that the JSON is valid to avoid future validation errors; disregard Mustache variables during your review.

createIncidentMethod
(Optional, string) The REST API HTTP request method to create a case in the third-party system. Valid values are patch, post, and put. The default value is post.
createIncidentResponseKey
(Required, string) The JSON key in the create case response that contains the external case ID.
createIncidentUrl
(Required, string) The REST API URL to create a case in the third-party system. If you are using the xpack.actions.allowedHosts setting, make sure the hostname is added to the allowed hosts.
getIncidentResponseExternalTitleKey
(Required, string) The JSON key in get case response that contains the external case title.
getIncidentUrl

(Required, string) The REST API URL to get the case by ID from the third-party system. If you are using the xpack.actions.allowedHosts setting, make sure the hostname is added to the allowed hosts. You can use a variable to add the external system ID to the URL. For example: 

https://testing-jira.atlassian.net/rest/api/2/issue/{{{external.system.id}}}

Due to Mustache template variables (the text enclosed in triple braces, for example, {{{case.title}}}), the JSON is not validated when you create the connector. The JSON is validated after the Mustache variables have been placed when REST method runs. Manually ensure that the JSON is valid, disregarding the Mustache variables, so the later validation will pass.

hasAuth
(Optional, boolean) If true, a username and password for login type authentication must be provided. The default value is true.
headers
(Optional, string) A set of key-value pairs sent as headers with the request URLs for the create case, update case, get case, and create comment methods.
updateIncidentJson

(Required, string) The JSON payload sent to the update case URL to update the case. You can use variables to add Kibana Cases data to the payload. Required variables are case.title and case.description. For example: 

{
	"fields": {
	  "summary": {{{case.title}}},
	  "description": {{{case.description}}},
	  "labels": {{{case.tags}}}
	}
}

Due to Mustache template variables (which is the text enclosed in triple braces, for example, {{{case.title}}}), the JSON is not validated when you create the connector. The JSON is validated after the Mustache variables have been placed when REST method runs. Manually ensure that the JSON is valid to avoid future validation errors; disregard Mustache variables during your review.

updateIncidentMethod
(Optional, string) The REST API HTTP request method to update the case in the third-party system. Valid values are patch, post, and put. The default value is put.
updateIncidentUrl

(Required, string) The REST API URL to update the case by ID in the third-party system. You can use a variable to add the external system ID to the URL. If you are using the xpack.actions.allowedHosts setting, make sure the hostname is added to the allowed hosts. For example: 

https://testing-jira.atlassian.net/rest/api/2/issue/{{{external.system.ID}}}
viewIncidentUrl

(Required, string) The URL to view the case in the external system. You can use variables to add the external system ID or external system title to the URL.For example: 

https://testing-jira.atlassian.net/browse/{{{external.system.title}}}

For more information, refer to Webhook - Case Management.

This object is not required for server log connectors.

For more configuration properties, refer to Connectors.

connector_type_id
(Required, string) The connector type ID for the connector. For example, .cases-webhook, .index, .jira, .server-log, or .servicenow-itom.
name
(Required, string) The display name for the connector.
secrets

(Required*, object) The secrets configuration for the connector. Secrets configuration properties vary depending on the connector type. For information about the secrets configuration properties, refer to Connectors.

Remember these values. You must provide them each time you call the update API.

Secrets properties
IBM Resilient connectors
apiKeyId
(Required, string) The authentication key ID for HTTP Basic authentication.
apiKeySecret
(Required, string) The authentication key secret for HTTP Basic authentication.
Jira connectors
apiToken
(Required, string) The Jira API authentication token for HTTP basic authentication.
email
(Required, string) The account email for HTTP Basic authentication.
ServiceNow ITOM, ServiceNow ITSM, and ServiceNow SecOps connectors
clientSecret
(Required*, string) The client secret assigned to your OAuth application. This property is required when isOAuth is true.
password
(Required*, string) The password for HTTP basic authentication. This property is required when isOAuth is false.
privateKey
(Required*, string) The RSA private key that you created for use in ServiceNow. This property is required when isOAuth is true.
privateKeyPassword
(Required*, string) The password for the RSA private key. This property is required when isOAuth is true and you set a password on your private key.
username
(Required*, string) The username for HTTP basic authentication. This property is required when isOAuth is false.
Swimlane connectors
apiToken
(string) Swimlane API authentication token.
Webhook - Case Management connectors
password
(Optional, string) The password for HTTP basic authentication.
user
(Optional, string) The username for HTTP basic authentication.

This object is not required for index or server log connectors.

Response codes

edit
200
Indicates a successful call.

Examples

edit

Create an index connector:

POST api/actions/connector
{
  "name": "my-connector",
  "connector_type_id": ".index",
  "config": {
    "index": "test-index"
  }
}

The API returns the following:

{
  "id": "c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad",
  "connector_type_id": ".index",
  "name": "my-connector",
  "config": {
    "index": "test-index",
    "refresh": false,
    "executionTimeField": null
  },
  "is_preconfigured": false,
  "is_deprecated": false,
  "is_missing_secrets": false
}

Create a Jira connector:

POST api/actions/connector
{
  "name": "my-jira-connector",
  "connector_type_id": ".jira",
  "config": {
    "apiUrl": "https://elastic.atlassian.net",
    "projectKey": "ES"
  },
  "secrets": {
    "email": "myEmail",
    "apiToken": "myToken"
  }
}

Create an IBM Resilient connector:

POST api/actions/connector
{
  "name": "my-resilient-connector",
  "connector_type_id": ".resilient",
  "config": {
    "apiUrl": "https://elastic.resilient.net",
    "orgId": "201"
  },
  "secrets": {
    "apiKeyId": "myKey",
    "apiKeySecret": "myToken"
  }
}

Create an ServiceNow ITOM connector that uses open authorization:

POST api/actions/connector
{
  "name": "my-itom-connector",
  "connector_type_id": ".servicenow-itom",
  "config": {
    "apiUrl": "https://exmaple.service-now.com/",
    "clientId": "abcdefghijklmnopqrstuvwxyzabcdef",
    "isOAuth": "true",
    "jwtKeyId": "fedcbazyxwvutsrqponmlkjihgfedcba",
    "userIdentifierValue": "testuser@email.com"
  },
  "secrets": {
    "clientSecret": "secretsecret",
    "privateKey": "-----BEGIN RSA PRIVATE KEY-----\nprivatekeyhere\n-----END RSA PRIVATE KEY-----"
  }
}

Create a Swimlane connector:

POST api/actions/connector
{
   "name":"my-swimlane-connector",
   "connector_type_id": ".swimlane",
   "config":{
      "connectorType":"all",
      "mappings":{
         "ruleNameConfig":{
            "id":"b6fst",
            "name":"Alert Name",
            "key":"alert-name",
            "fieldType":"text"
         }
      },
      "appId":"myAppID",
      "apiUrl":"https://myswimlaneinstance.com"
   },
   "secrets":{
      "apiToken":"myToken"
   }
}
« Action and connector APIs Delete connector API »