[Cases][Connectors] ServiceNow ITOM: MVP

docs/management/action-types.asciidoc

@@ -43,6 +43,10 @@ a| <<servicenow-sir-action-type, ServiceNow SecOps>>
 
 | Create a security incident in ServiceNow.
 
+a| <<servicenow-itom-action-type, ServiceNow ITOM>>
+
+| Create an event in ServiceNow.
+
 a| <<slack-action-type, Slack>>
 
 | Send a message to a Slack channel or user.

docs/management/connectors/action-types/servicenow-itom.asciidoc

@@ -0,0 +1,90 @@
+[role="xpack"]
+[[servicenow-itom-action-type]]
+=== ServiceNow connector and action
+++++
+<titleabbrev>ServiceNow ITOM</titleabbrev>
+++++
+
+The ServiceNow ITOM connector uses the https://docs.servicenow.com/bundle/rome-it-operations-management/page/product/event-management/task/send-events-via-web-service.html[Event API] to create ServiceNow events.
+
+[float]
+[[servicenow-itom-connector-configuration]]
+==== Connector configuration
+
+ServiceNow ITOM connectors have the following configuration properties.
+
+Name::      The name of the connector. The name is used to identify a  connector in the **Stack Management** UI connector listing, and in the connector list when configuring an action.
+URL::       ServiceNow instance URL.
+Username::  Username for HTTP Basic authentication.
+Password::  Password for HTTP Basic authentication.
+
+The ServiceNow user requires at minimum read, create, and update access to the Event table and read access to the https://docs.servicenow.com/bundle/paris-platform-administration/page/administer/localization/reference/r_ChoicesTable.html[sys_choice]. If you don't provide access to sys_choice, then the choices will not render.
+
+[float]
+[[servicenow-itom-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-servicenow-itom-configuration]]
+==== Preconfigured connector type
+
+[source,text]
+--
+ my-servicenow-itom:
+   name: preconfigured-servicenow-connector-type
+   actionTypeId: .servicenow-itom
+   config:
+     apiUrl: https://example.service-now.com/
+   secrets:
+     username: testuser
+     password: passwordkeystorevalue
+--
+
+Config defines information for the connector type.
+
+`apiUrl`:: An address that corresponds to *URL*.
+
+Secrets defines sensitive information for the connector type.
+
+`username`:: A string that corresponds to *Username*.
+`password`::  A string that corresponds to *Password*. Should be stored in the <<creating-keystore, {kib} keystore>>.
+
+[float]
+[[define-servicenow-itom-ui]]
+==== Define connector in Stack Management
+
+Define ServiceNow ITOM connector properties.
+
+[role="screenshot"]
+image::management/connectors/images/servicenow-itom-connector.png[ServiceNow ITOM connector]
+
+Test ServiceNow ITOM action parameters.
+
+[role="screenshot"]
+image::management/connectors/images/servicenow-itom-params-test.png[ServiceNow ITOM params test]
+
+[float]
+[[servicenow-itom-action-configuration]]
+==== Action configuration
+
+ServiceNow ITOM actions have the following configuration properties.
+
+Source::       The name of the event source type.
+Node::         The Host that the event was triggered for.
+Type::         The type of event.
+Resource::     The name of the resource.
+Metric name::  Name of the metric.
+Source instance (event_class):: Specific instance of the source.
+Message key::  All actions sharing this key will be associated with the same ServiceNow alert. Default value: `<rule ID>:<alert instance ID>`.
+Severity::     The severity of the event.
+Description::  The details about the event.
+
+Refer to https://docs.servicenow.com/bundle/rome-it-operations-management/page/product/event-management/task/send-events-via-web-service.html[ServiceNow documentation] for more information about the properties.
+
+[float]
+[[configuring-servicenow-itom]]
+==== Configure ServiceNow ITOM
+
+ServiceNow offers free https://developer.servicenow.com/dev.do#!/guides/madrid/now-platform/pdi-guide/obtaining-a-pdi[Personal Developer Instances], which you can use to test incidents.

docs/management/connectors/action-types/servicenow-sir.asciidoc

@@ -36,7 +36,7 @@ Use the <<action-settings, Action configuration settings>> to customize connecto
    name: preconfigured-servicenow-connector-type
    actionTypeId: .servicenow-sir
    config:
-     apiUrl: https://dev94428.service-now.com/
+     apiUrl: https://example.service-now.com/
    secrets:
      username: testuser
      password: passwordkeystorevalue

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

@@ -36,7 +36,7 @@ Use the <<action-settings, Action configuration settings>> to customize connecto
    name: preconfigured-servicenow-connector-type
    actionTypeId: .servicenow
    config:
-     apiUrl: https://dev94428.service-now.com/
+     apiUrl: https://example.service-now.com/
    secrets:
      username: testuser
      password: passwordkeystorevalue

docs/management/connectors/index.asciidoc

@@ -7,6 +7,7 @@ include::action-types/pagerduty.asciidoc[]
 include::action-types/server-log.asciidoc[]
 include::action-types/servicenow.asciidoc[]
 include::action-types/servicenow-sir.asciidoc[]
+include::action-types/servicenow-itom.asciidoc[]
 include::action-types/swimlane.asciidoc[]
 include::action-types/slack.asciidoc[]
 include::action-types/webhook.asciidoc[]

x-pack/plugins/actions/README.md

@@ -45,9 +45,12 @@ Table of Contents
       - [`subActionParams (getFields)`](#subactionparams-getfields-1)
       - [`subActionParams (getIncident)`](#subactionparams-getincident-1)
       - [`subActionParams (getChoices)`](#subactionparams-getchoices-1)
-  - [| fields   | An array of fields. Example: `[priority, category]`. | string[] |](#-fields----an-array-of-fields-example-priority-category--string-)
-  - [Jira](#jira)
+  - [ServiceNow ITOM](#servicenow-itom)
     - [`params`](#params-2)
+      - [`subActionParams (addEvent)`](#subactionparams-addevent)
+      - [`subActionParams (getChoices)`](#subactionparams-getchoices-2)
+  - [Jira](#jira)
+    - [`params`](#params-3)
       - [`subActionParams (pushToService)`](#subactionparams-pushtoservice-2)
       - [`subActionParams (getIncident)`](#subactionparams-getincident-2)
       - [`subActionParams (issueTypes)`](#subactionparams-issuetypes)
@@ -56,13 +59,13 @@ Table of Contents
       - [`subActionParams (issue)`](#subactionparams-issue)
       - [`subActionParams (getFields)`](#subactionparams-getfields-2)
   - [IBM Resilient](#ibm-resilient)
-    - [`params`](#params-3)
+    - [`params`](#params-4)
       - [`subActionParams (pushToService)`](#subactionparams-pushtoservice-3)
       - [`subActionParams (getFields)`](#subactionparams-getfields-3)
       - [`subActionParams (incidentTypes)`](#subactionparams-incidenttypes)
       - [`subActionParams (severity)`](#subactionparams-severity)
   - [Swimlane](#swimlane)
-    - [`params`](#params-4)
+    - [`params`](#params-5)
   - [| severity    | The severity of the incident.    | string _(optional)_ |](#-severity-----the-severity-of-the-incident-----string-optional-)
 - [Command Line Utility](#command-line-utility)
 - [Developing New Action Types](#developing-new-action-types)
@@ -355,6 +358,43 @@ No parameters for the `getFields` subaction. Provide an empty object `{}`.
 | Property | Description                                          | Type     |
 | -------- | ---------------------------------------------------- | -------- |
 | fields   | An array of fields. Example: `[priority, category]`. | string[] |
+
+---
+## ServiceNow ITOM
+
+The [ServiceNow ITOM user documentation `params`](https://www.elastic.co/guide/en/kibana/master/servicenow-itom-action-type.html) lists configuration properties for the `addEvent` subaction. In addition, several other subaction types are available.
+### `params`
+
+| Property        | Description                                                       | Type   |
+| --------------- | ----------------------------------------------------------------- | ------ |
+| subAction       | The subaction to perform. It can be `addEvent`, and `getChoices`. | string |
+| subActionParams | The parameters of the subaction.                                  | object |
+
+#### `subActionParams (addEvent)`
+
+
+| Property        | Description                                                                                                                      | Type                |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
+| source          | The name of the event source type.                                                                                               | string _(optional)_ |
+| event_class     | Specific instance of the source.                                                                                                 | string _(optional)_ |
+| resource        | The name of the resource.                                                                                                        | string _(optional)_ |
+| node            | The Host that the event was triggered for.                                                                                       | string _(optional)_ |
+| metric_name     | Name of the metric.                                                                                                              | string _(optional)_ |
+| type            | The type of event.                                                                                                               | string _(optional)_ |
+| severity        | The category in ServiceNow.                                                                                                      | string _(optional)_ |
+| description     | The subcategory in ServiceNow.                                                                                                   | string _(optional)_ |
+| additional_info | Any additional information about the event.                                                                                      | string _(optional)_ |
+| message_key     | This value is used for de-duplication of events. All actions sharing this key will be associated with the same ServiceNow alert. | string _(optional)_ |
+| time_of_event   | The time of the event.                                                                                                           | string _(optional)_ |
+
+Refer to [ServiceNow documentation](https://docs.servicenow.com/bundle/rome-it-operations-management/page/product/event-management/task/send-events-via-web-service.html) for more information about the properties.
+
+#### `subActionParams (getChoices)`
+
+| Property | Description                                | Type     |
+| -------- | ------------------------------------------ | -------- |
+| fields   | An array of fields. Example: `[severity]`. | string[] |
+
 ---
 ## Jira
 
@@ -418,6 +458,7 @@ No parameters for the `issueTypes` subaction. Provide an empty object `{}`.
 No parameters for the `getFields` subaction. Provide an empty object `{}`.
 
 ---
+
 ## IBM Resilient
 
 The [IBM Resilient user documentation `params`](https://www.elastic.co/guide/en/kibana/master/resilient-action-type.html) lists configuration properties for the `pushToService` subaction. In addition, several other subaction types are available.
@@ -545,4 +586,4 @@ Instead of `schema.maybe()`, use `schema.nullable()`, which is the same as `sche
 
 ## user interface
 
-To make this action usable in the Kibana UI, you will need to provide all the UI editing aspects of the action. The existing action type user interfaces are defined in [`x-pack/plugins/triggers_actions_ui/public/application/components/builtin_action_types`](../triggers_actions_ui/public/application/components/builtin_action_types). For more information, see the [UI documentation](../triggers_actions_ui/README.md#create-and-register-new-action-type-ui).
+To make this action usable in the Kibana UI, you will need to provide all the UI editing aspects of the action. The existing action type user interfaces are defined in [`x-pack/plugins/triggers_actions_ui/public/application/components/builtin_action_types`](../triggers_actions_ui/public/application/components/builtin_action_types). For more information, see the [UI documentation](../triggers_actions_ui/README.md#create-and-register-new-action-type-ui).

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

@@ -16,10 +16,15 @@ 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 { getServiceNowITSMActionType, getServiceNowSIRActionType } from './servicenow';
+import {
+  getServiceNowITSMActionType,
+  getServiceNowSIRActionType,
+  getServiceNowITOMActionType,
+} from './servicenow';
 import { getActionType as getJiraActionType } from './jira';
 import { getActionType as getResilientActionType } from './resilient';
 import { getActionType as getTeamsActionType } from './teams';
+import { ENABLE_ITOM } from '../constants/connectors';
 export { ActionParamsType as EmailActionParams, ActionTypeId as EmailActionTypeId } from './email';
 export {
   ActionParamsType as IndexActionParams,
@@ -42,6 +47,7 @@ export {
   ActionParamsType as ServiceNowActionParams,
   ServiceNowITSMActionTypeId,
   ServiceNowSIRActionTypeId,
+  ServiceNowITOMActionTypeId,
 } from './servicenow';
 export { ActionParamsType as JiraActionParams, ActionTypeId as JiraActionTypeId } from './jira';
 export {
@@ -75,4 +81,9 @@ export function registerBuiltInActionTypes({
   actionTypeRegistry.register(getJiraActionType({ logger, configurationUtilities }));
   actionTypeRegistry.register(getResilientActionType({ logger, configurationUtilities }));
   actionTypeRegistry.register(getTeamsActionType({ logger, configurationUtilities }));
+
+  // TODO: Remove when ITOM is ready
+  if (ENABLE_ITOM) {
+    actionTypeRegistry.register(getServiceNowITOMActionType({ logger, configurationUtilities }));
+  }
 }

x-pack/plugins/actions/server/builtin_action_types/servicenow/api.test.ts

@@ -361,6 +361,7 @@ describe('api', () => {
       const res = await api.getFields({
         externalService,
         params: {},
+        logger: mockedLogger,
       });
       expect(res).toEqual(serviceNowCommonFields);
     });
@@ -371,6 +372,7 @@ describe('api', () => {
       const res = await api.getChoices({
         externalService,
         params: { fields: ['priority'] },
+        logger: mockedLogger,
       });
       expect(res).toEqual(serviceNowChoices);
     });
@@ -383,6 +385,7 @@ describe('api', () => {
         params: {
           externalId: 'incident-1',
         },
+        logger: mockedLogger,
       });
       expect(res).toEqual({
         description: 'description from servicenow',

x-pack/plugins/actions/server/builtin_action_types/servicenow/api_itom.test.ts

@@ -0,0 +1,53 @@
+/*
+ * 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 { Logger } from '../../../../../../src/core/server';
+import { externalServiceITOMMock, itomEventParams } from './mocks';
+import { ExternalServiceITOM } from './types';
+import { apiITOM, prepareParams } from './api_itom';
+let mockedLogger: jest.Mocked<Logger>;
+
+describe('api_itom', () => {
+  let externalService: jest.Mocked<ExternalServiceITOM>;
+  const eventParamsWithFormattedDate = {
+    ...itomEventParams,
+    time_of_event: '2021-10-13, 10:51:44',
+  };
+
+  beforeEach(() => {
+    externalService = externalServiceITOMMock.create();
+    jest.clearAllMocks();
+  });
+
+  describe('prepareParams', () => {
+    test('it prepares the params correctly', async () => {
+      expect(prepareParams(itomEventParams)).toEqual(eventParamsWithFormattedDate);
+    });
+
+    test('it removes null values', async () => {
+      const { time_of_event: timeOfEvent, ...rest } = itomEventParams;
+      expect(prepareParams({ ...rest, time_of_event: null })).toEqual(rest);
+    });
+
+    test('it set the time to null if it is not a proper date', async () => {
+      const { time_of_event: timeOfEvent, ...rest } = itomEventParams;
+      expect(prepareParams({ ...rest, time_of_event: 'not a proper date' })).toEqual(rest);
+    });
+  });
+
+  describe('addEvent', () => {
+    test('it adds an event correctly', async () => {
+      await apiITOM.addEvent({
+        externalService,
+        params: itomEventParams,
+        logger: mockedLogger,
+      });
+
+      expect(externalService.addEvent).toHaveBeenCalledWith(eventParamsWithFormattedDate);
+    });
+  });
+});