Create connector API
editCreate connector API
editCreates a connector.
Request
editPOST <kibana host>:<port>/api/actions/connector
POST <kibana host>:<port>/s/<space_id>/api/actions/connector
Prerequisites
editYou 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:
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.
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
, andput
. The default value isput
. -
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
andcase.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
, andput
. The default value ispost
. -
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
andcase.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
, andput
. The default value isput
. -
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
, or.server-log
. -
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.
Jira connectors
-
apiToken
- (Required, string) The Jira API authentication token for HTTP basic authentication.
-
email
- (Required, string) The account email for HTTP Basic authentication.
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
editPOST 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 }