[alerting]: adds a connector for xMatters (#122357)

* Begin work on building out the backend of an xMatters connector

* Begin work on building out the frontend of an xMatters connector

* Continue attempting to get connector to register properly

* Begin working on the UI for the Edit Connector Test page

* Start working on writing tests for backend component of the xMatters connector

* Remove unneeded test due to not having any fancy escaping

* Write tests for the frontend component of the xMatters connector

* Add documentation for new xMatters connector

* Begin working on functional tests

* Continue work on frontend for xMatters conenctor

* Continue work on backend for xMatters conenctor

* Continue work on the functional tests for the xMatters connector

* Update based on xMatters string reviews

* Remove hidden parameters from ui

* Continue working to get tests running successfully

* Fix my code after rebasing onto latest main

* Fix the xMatters server for the simluator

* Check if listening before listening to the xmatters server in simulator

* Continue work on improving the xMatters connector

* Update strings based on the xMatters team string review

* Remove the headers as an option for the xMatters connector

* Fix alignment of the xmatters logo on the connectors page

* Allow alertId and alertActionGroupName to be null in the xMatters connector for test requests

* Fix the functional tests for the xMatters connector

* Rename alertName to ruleName and remove headers from xMatters connector

* Continue removing headers and renaming alertName to ruleName

* Update the tests so all are passing

* Some clean up for the xMatters connector

* Update the doc images based on changes for the xMatters connector

* Change alert id to use rule id and alert id and be labeled as signal id in the xMatters connector

* Fix failing tests for xMatters connector

* Start addressing comments and failing builds

* Combine if statement

* Update test strings after updating error strings

* Begin making updates after discussions and reviews

* Update failing tests

* Few adjustments after my self review of the xMatters connector

* Fix one failing test

* Fix a few small bugs in the xMatters connector

* Address a few small bugs in the xMatters connector

* Address latest comments and fix a few tests on the xMatters connector

* Adjust naming of secretsUrl and configUrl

* Work on fixing tests for xMatters connector

* Begin updating the xMatters documentation

* Update based on build errors

* Update documentation typo

* Add validation tests for connectors created using the API

* Fix the failing functional tests

* Update docs after review from xMatters team

* Update accidentally duplicated translate id

* Fix small bugs and update based on xMatters team string reviews

* Fix failing tests due to string changes

* [DOCS] Fixes doc build errors

* Update based on comments and feedback

* Update docs based on feedback

* Fix failing functional tests

* Update based on the feedback

* Fix failures in the functional tests

* Remove accidentally added file

Co-authored-by: Kibana Machine <[email protected]>
Co-authored-by: lcawl <[email protected]>

docs/management/connectors/action-types/xmatters.asciidoc

@@ -0,0 +1,119 @@
+[[xmatters-action-type]]
+=== xMatters connector and action
+++++
+<titleabbrev>xMatters</titleabbrev>
+++++
+
+The xMatters connector uses the https://help.xmatters.com/integrations/#cshid=Elastic[xMatters Workflow for Elastic] to send actionable alerts to on-call xMatters resources.
+
+[float]
+[[xmatters-connector-configuration]]
+==== Connector configuration
+
+xMatters connectors have the following configuration properties:
+
+Name:: The name of the connector. The name is used to identify a connector in the management UI connector listing, or in the connector list when configuring an action.
+Authentication Type:: The type of authentication used in the request made to xMatters.
+URL:: The request URL for the Elastic Alerts trigger in xMatters. If you are using the <<action-settings, `xpack.actions.allowedHosts`>> setting, make sure the hostname is added to the allowed hosts.
+Username:: Username for HTTP Basic Authentication.
+Password:: Password for HTTP Basic Authentication.
+
+[float]
+[[xmatters-connector-networking-configuration]]
+==== Connector networking configuration
+
+Use the <<action-settings, Action configuration settings>> to customize connector networking configurations, such as proxies, certificates, or TLS settings. You can set configurations that apply to all your connectors or use `xpack.actions.customHostSettings` to set per-host configurations.
+
+[float]
+[[Preconfigured-xmatters-configuration]]
+==== Preconfigured connector type
+
+Connector using Basic Authentication
+[source,text]
+--
+ my-xmatters:
+   name: preconfigured-xmatters-connector-type
+   actionTypeId: .xmatters
+   config:
+     configUrl: https://test.host
+     usesBasic: true
+   secrets:
+     user: testuser
+     password: passwordkeystorevalue
+--
+
+Connector using URL Authentication
+[source,text]
+--
+ my-xmatters:
+   name: preconfigured-xmatters-connector-type
+   actionTypeId: .xmatters
+   config:
+     usesBasic: false
+   secrets:
+     secretsUrl: https://test.host?apiKey=1234-abcd
+--
+
+Config defines information for the connector type:
+
+`configUrl`:: A URL string that corresponds to *URL*. Only used if `usesBasic` is true.
+
+`usesBasic`:: A boolean that corresponds to *Authentication Type*. If `true`, this connector will require values for `user` and `password` inside the secrets configuration. Defaults to `true`.
+
+Secrets defines sensitive information for the connector type:
+
+`user`:: A string that corresponds to *User*. Required if `usesBasic` is set to `true`.
+
+`password`:: A string that corresponds to *Password*. Should be stored in the <<creating-keystore, {kib} keystore>>. Required if `usesBasic` is set to `true`.
+
+`secretsUrl`:: A URL string that corresponds to *URL*. Only used if `usesBasic` is false, indicating the API key is included in the URL.
+
+[float]
+[[define-xmatters-ui]]
+==== Define connector in Stack Management
+
+Define xMatters connector properties. Choose between basic and URL authentication for the requests:
+
+[role="screenshot"]
+image::management/connectors/images/xmatters-connector-basic.png[xMatters connector with basic authentication]
+
+[role="screenshot"]
+image::management/connectors/images/xmatters-connector-url.png[xMatters connector with url authentication]
+
+Test xMatters rule parameters:
+
+[role="screenshot"]
+image::management/connectors/images/xmatters-params-test.png[xMatters params test]
+
+[float]
+[[xmatters-action-configuration]]
+==== Action configuration
+
+xMatters rules have the following properties:
+
+Severity::                                                     Severity of the rule.
+Tags:: Comma-separated list of tags for the rule as provided by the user in Elastic.
+
+[float]
+[[xmatters-benefits]]
+==== Configure xMatters
+
+By integrating with xMatters, you can:
+
+. Leverage schedules, rotations, escalations, and device preferences to quickly engage the right resources.
+. Allow resolvers to take immediate action with customizable notification responses, including incident creation.
+. Reduce manual tasks so teams can streamline their resources and focus.
+
+[float]
+[[xmatters-connector-prerequisites]]
+==== Prerequisites
+To use the Elastic xMatters connector either install the Elastic workflow template, or add the Elastic Alerts trigger to one of your existing xMatters flows. Once the workflow or trigger is in your xMatters instance, configure Elastic to send alerts to xMatters.
+
+. In xMatters, double-click the Elastic trigger to open the settings menu.
+. Choose the authentication method and set your authenticating user.
+. Copy the initiation URL.
+. In Elastic, open the xMatters connector.
+. Set the authentication method, then paste the initiation URL.
+
+Note: If you use basic authentication, specify the Web / App Login ID in the user credentials for the connector. This value can be found in the Edit Profile modal in xMatters for each user.
+For detailed configuration instructions, see https://help.xmatters.com/ondemand/#cshid=ElasticTrigger[xMatters online help]

docs/management/connectors/index.asciidoc

@@ -11,4 +11,5 @@ include::action-types/servicenow-itom.asciidoc[]
 include::action-types/swimlane.asciidoc[]
 include::action-types/slack.asciidoc[]
 include::action-types/webhook.asciidoc[]
+include::action-types/xmatters.asciidoc[]
 include::pre-configured-connectors.asciidoc[]

docs/settings/alert-action-settings.asciidoc

@@ -126,7 +126,7 @@ into a single string.  This configuration can be used for environments where
 the files cannot be made available.
 
 `xpack.actions.enabledActionTypes` {ess-icon}::
-A list of action types that are enabled. It defaults to `[*]`, enabling all types. The names for built-in {kib} action types are prefixed with a `.` and include: `.email`, `.index`, `.jira`, `.pagerduty`, `.resilient`, `.server-log`, `.servicenow`, .`servicenow-itom`, `.servicenow-sir`, `.slack`, `.swimlane`, `.teams`, and `.webhook`. An empty list `[]` will disable all action types.
+A list of action types that are enabled. It defaults to `[*]`, enabling all types. The names for built-in {kib} action types are prefixed with a `.` and include: `.email`, `.index`, `.jira`, `.pagerduty`, `.resilient`, `.server-log`, `.servicenow`, .`servicenow-itom`, `.servicenow-sir`, `.slack`, `.swimlane`, `.teams`, `.xmatters`, and `.webhook`. An empty list `[]` will disable all action types.
 +
 Disabled action types will not appear as an option when creating new connectors, but existing connectors and actions of that type will remain in {kib} and will not function.
 

x-pack/plugins/actions/server/builtin_action_types/index.test.ts

@@ -24,6 +24,7 @@ const ACTION_TYPE_IDS = [
   '.swimlane',
   '.teams',
   '.webhook',
+  '.xmatters',
 ];
 
 export function createActionTypeRegistry(): {

x-pack/plugins/actions/server/builtin_action_types/index.ts

@@ -16,6 +16,7 @@ import { getActionType as getSwimlaneActionType } from './swimlane';
 import { getActionType as getServerLogActionType } from './server_log';
 import { getActionType as getSlackActionType } from './slack';
 import { getActionType as getWebhookActionType } from './webhook';
+import { getActionType as getXmattersActionType } from './xmatters';
 import {
   getServiceNowITSMActionType,
   getServiceNowSIRActionType,
@@ -36,6 +37,8 @@ export type { ActionParamsType as SlackActionParams } from './slack';
 export { ActionTypeId as SlackActionTypeId } from './slack';
 export type { ActionParamsType as WebhookActionParams } from './webhook';
 export { ActionTypeId as WebhookActionTypeId } from './webhook';
+export type { ActionParamsType as XmattersActionParams } from './xmatters';
+export { ActionTypeId as XmattersActionTypeId } from './xmatters';
 export type { ActionParamsType as ServiceNowActionParams } from './servicenow';
 export {
   ServiceNowITSMActionTypeId,
@@ -69,6 +72,7 @@ export function registerBuiltInActionTypes({
   actionTypeRegistry.register(getServerLogActionType({ logger }));
   actionTypeRegistry.register(getSlackActionType({ logger, configurationUtilities }));
   actionTypeRegistry.register(getWebhookActionType({ logger, configurationUtilities }));
+  actionTypeRegistry.register(getXmattersActionType({ logger, configurationUtilities }));
   actionTypeRegistry.register(getServiceNowITSMActionType({ logger, configurationUtilities }));
   actionTypeRegistry.register(getServiceNowSIRActionType({ logger, configurationUtilities }));
   actionTypeRegistry.register(getServiceNowITOMActionType({ logger, configurationUtilities }));

x-pack/plugins/actions/server/builtin_action_types/lib/post_xmatters.ts

@@ -0,0 +1,50 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+import axios, { AxiosResponse } from 'axios';
+import { Logger } from '../../../../../../src/core/server';
+import { request } from './axios_utils';
+import { ActionsConfigurationUtilities } from '../../actions_config';
+
+interface PostXmattersOptions {
+  url: string;
+  data: {
+    alertActionGroupName?: string;
+    signalId?: string;
+    ruleName?: string;
+    date?: string;
+    severity: string;
+    spaceId?: string;
+    tags?: string;
+  };
+  basicAuth?: {
+    auth: {
+      username: string;
+      password: string;
+    };
+  };
+}
+
+// trigger a flow in xmatters
+export async function postXmatters(
+  options: PostXmattersOptions,
+  logger: Logger,
+  configurationUtilities: ActionsConfigurationUtilities
+): Promise<AxiosResponse> {
+  const { url, data, basicAuth } = options;
+  const axiosInstance = axios.create();
+  return await request({
+    axios: axiosInstance,
+    method: 'post',
+    url,
+    logger,
+    ...basicAuth,
+    data,
+    configurationUtilities,
+    validateStatus: () => true,
+  });
+}