[Security Solution] Doc pre-reqs for using the SN ITSM, SecOps, and ITOM connectors (#117122)

Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com>

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

@@ -1,25 +1,31 @@
 [role="xpack"]
 [[servicenow-itom-action-type]]
-=== ServiceNow connector and action
+=== ServiceNow ITOM 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.
+The {sn} 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 {sn} events.
+
+[float]
+[[servicenow-itom-connector-prerequisites]]
+==== Prerequisites
+Create an integration user in {sn} and assign it the following roles.
+
+* `personalize_choices`: Allows the user to retrieve Choice element options, such as Severity.
+* `evt_mgmt_integration`: Enables integration with external event sources by allowing the user to create events.
 
 [float]
 [[servicenow-itom-connector-configuration]]
 ==== Connector configuration
 
-ServiceNow ITOM connectors have the following configuration properties.
+{sn} 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.
+Name::      The name of the connector. The name is used to identify a  connector in the **Stack Management** connector listing, and in the connector list when configuring an action.
+URL::       {sn} 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
@@ -55,12 +61,12 @@ Secrets defines sensitive information for the connector type.
 [[define-servicenow-itom-ui]]
 ==== Define connector in Stack Management
 
-Define ServiceNow ITOM connector properties.
+Define {sn} ITOM connector properties.
 
 [role="screenshot"]
 image::management/connectors/images/servicenow-itom-connector.png[ServiceNow ITOM connector]
 
-Test ServiceNow ITOM action parameters.
+Test {sn} ITOM action parameters.
 
 [role="screenshot"]
 image::management/connectors/images/servicenow-itom-params-test.png[ServiceNow ITOM params test]
@@ -69,7 +75,7 @@ image::management/connectors/images/servicenow-itom-params-test.png[ServiceNow I
 [[servicenow-itom-action-configuration]]
 ==== Action configuration
 
-ServiceNow ITOM actions have the following configuration properties.
+{sn} ITOM actions have the following configuration properties.
 
 Source::       The name of the event source type.
 Node::         The Host that the event was triggered for.
@@ -77,7 +83,7 @@ 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>`.
+Message key::  All actions sharing this key will be associated with the same {sn} alert. Default value: `<rule ID>:<alert instance ID>`.
 Severity::     The severity of the event.
 Description::  The details about the event.
 
@@ -85,6 +91,6 @@ Refer to https://docs.servicenow.com/bundle/rome-it-operations-management/page/p
 
 [float]
 [[configuring-servicenow-itom]]
-==== Configure ServiceNow ITOM
+==== Configure {sn} 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.
+{sn} 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

@@ -1,25 +1,83 @@
 [role="xpack"]
 [[servicenow-sir-action-type]]
-=== ServiceNow connector and action
+=== ServiceNow SecOps connector and action
 ++++
 <titleabbrev>ServiceNow SecOps</titleabbrev>
 ++++
 
-The ServiceNow SecOps connector uses the https://docs.servicenow.com/bundle/orlando-application-development/page/integrate/inbound-rest/concept/c_TableAPI.html[V2 Table API] to create ServiceNow security incidents.
+The {sn} SecOps connector uses the https://docs.servicenow.com/bundle/orlando-application-development/page/integrate/inbound-rest/concept/c_TableAPI.html[V2 Table API] to create {sn} security incidents.
+
+[float]
+[[servicenow-sir-connector-prerequisites]]
+==== Prerequisites
+After upgrading from {stack} version 7.15.0 or earlier to version 7.16.0 or later, you must complete the following within your {sn} instance before creating a new {sn} SecOps connector or <<servicenow-sir-connector-update, updating an existing one>>:
+
+* Install https://store.servicenow.com/sn_appstore_store.do#!/store/application/2f0746801baeb01019ae54e4604bcb0f[Elastic for Security Operations (SecOps)] from the {sn} Store.
+* Create a {sn} integration user and assign it the appropriate roles.
+* Create a Cross-Origin Resource Sharing (CORS) rule.
+
+*Create a {sn} integration user*
+
+To ensure authenticated communication between Elastic and {sn}, create a {sn} integration user and assign it the appropriate roles. 
+
+. In your {sn} instance, go to *System Security -> Users and Groups -> Users*.
+. Click *New*.
+. Complete the form, then right-click on the menu bar and click *Save*.
+. Go to the *Roles* tab and click *Edit*.
+. Assign the integration user the following roles: 
+* `import_set_loader`
+* `import_transformer`
+* `personalize_choices`
+* `sn_si.basic`
+* `x_elas2_sir_int.integration_user`
+. Click *Save*.
+
+*Create a CORS rule*
+
+A CORS rule is required for communication between Elastic and {sn}. To create a CORS rule:
+
+. In your {sn} instance, go to *System Web Services -> REST -> CORS Rules*.
+. Click *New*.
+. Configure the rule as follows:
+* *Name*: Name the rule.
+* *REST API*: Set the rule to use the Elastic SecOps API by choosing `Elastic SIR API [x_elas2_sir_int/elastic_api]`.
+* *Domain*: Enter the Kibana URL.
+. Go to the *HTTP methods* tab and select *GET*.
+. Click *Submit* to create the rule.
+
+[float]
+[[servicenow-sir-connector-update]]
+==== Update a deprecated {sn} SecOps connector
+
+{sn} SecOps connectors created in {stack} version 7.15.0 or earlier are marked as deprecated after you upgrade to version 7.16.0 or later. Deprecated connectors have a yellow icon after their name and display a warning message when selected.
+
+[role="screenshot"]
+image::management/connectors/images/servicenow-sir-update-connector.png[Shows deprecated ServiceNow connectors]
+
+IMPORTANT: Deprecated connectors will continue to function with the rules they were added to and can be assigned to new rules. However, it is strongly recommended to update deprecated connectors or <<creating-new-connector, create new ones>> to ensure you have access to connector enhancements, such as updating incidents.
+
+To update a deprecated connector:
+
+. Open the main menu and go to *Stack Management -> Rules and connectors -> Connectors*.
+. Select the deprecated connector to open the *Edit connector* flyout.
+. In the warning message, click *Update this connector*.
+. Complete the guided steps in the *Edit connector* flyout.
+.. Install https://store.servicenow.com/sn_appstore_store.do#!/store/application/2f0746801baeb01019ae54e4604bcb0f[Elastic for Security Operations (SecOps)] from the {sn} Store and complete the <<servicenow-sir-connector-prerequisites, required prerequisites>>.
+.. Enter the URL of your {sn} instance.
+.. Enter the username and password of your {sn} instance.
+. Click *Update*.
 
 [float]
 [[servicenow-sir-connector-configuration]]
 ==== Connector configuration
 
-ServiceNow SecOps connectors have the following configuration properties.
+{sn} SecOps 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.
+URL::       {sn} 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 Security Incident 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-sir-connector-networking-configuration]]
 ==== Connector networking configuration
@@ -48,7 +106,7 @@ Config defines information for the connector type.
 `apiUrl`:: An address that corresponds to *URL*.
 `usesTableApi`:: A boolean that indicates if the connector uses the Table API or the Import Set API.
 
-Note: If `usesTableApi` is set to false the Elastic application should be installed in ServiceNow.
+NOTE: If `usesTableApi` is set to false, the Elastic application should be installed in {sn}.
 
 Secrets defines sensitive information for the connector type.
 
@@ -59,12 +117,12 @@ Secrets defines sensitive information for the connector type.
 [[define-servicenow-sir-ui]]
 ==== Define connector in Stack Management
 
-Define ServiceNow SecOps connector properties.
+Define {sn} SecOps connector properties.
 
 [role="screenshot"]
 image::management/connectors/images/servicenow-sir-connector.png[ServiceNow SecOps connector]
 
-Test ServiceNow SecOps action parameters.
+Test {sn} SecOps action parameters.
 
 [role="screenshot"]
 image::management/connectors/images/servicenow-sir-params-test.png[ServiceNow SecOps params test]
@@ -79,13 +137,16 @@ Short description::    A short description for the incident, used for searching
 Priority::             The priority of the incident.
 Category::             The category of the incident.
 Subcategory::          The subcategory of the incident.
-Correlation ID::       All actions sharing this ID will be associated with the same ServiceNow security incident. If an incident exists in ServiceNow with the same correlation ID the security incident will be updated. Default value: `<rule ID>:<alert instance ID>`.
-Correlation Display::  A descriptive label of the alert for correlation purposes in ServiceNow.
+Correlation ID::       Connectors using the same Correlation ID will be associated with the same {sn} incident. This value determines whether a new {sn} incident will be created or an existing one is updated. Modifying this value is optional; if not modified, the rule ID and alert ID are combined as `{{ruleID}}:{{alert ID}}` to form the Correlation ID value in {sn}. The maximum character length for this value is 100 characters.
+
+NOTE: Using the default configuration of `{{ruleID}}:{{alert ID}}` ensures that {sn} will create a separate incident record for every generated alert that uses a unique alert ID. If the rule generates multiple alerts that use the same alert IDs, {sn} creates and continually updates a single incident record for the alert.
+
+Correlation Display::  A descriptive label of the alert for correlation purposes in {sn}.
 Description::          The details about the incident.
 Additional comments::  Additional information for the client, such as how to troubleshoot the issue.
 
 [float]
 [[configuring-servicenow-sir]]
-==== Configure ServiceNow SecOps
+==== Configure {sn} SecOps
 
-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.
+{sn} 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.asciidoc

@@ -1,25 +1,82 @@
 [role="xpack"]
 [[servicenow-action-type]]
-=== ServiceNow connector and action
+=== ServiceNow ITSM connector and action
 ++++
 <titleabbrev>ServiceNow ITSM</titleabbrev>
 ++++
 
-The ServiceNow ITSM connector uses the https://docs.servicenow.com/bundle/orlando-application-development/page/integrate/inbound-rest/concept/c_TableAPI.html[V2 Table API] to create ServiceNow incidents.
+The {sn} ITSM connector uses the https://docs.servicenow.com/bundle/orlando-application-development/page/integrate/inbound-rest/concept/c_TableAPI.html[V2 Table API] to create {sn} incidents.
+
+[float]
+[[servicenow-itsm-connector-prerequisites]]
+==== Prerequisites
+After upgrading from {stack} version 7.15.0 or earlier to version 7.16.0 or later, you must complete the following within your {sn} instance before creating a new {sn} ITSM connector or <<servicenow-itsm-connector-update, updating an existing one>>:
+
+* Install https://store.servicenow.com/sn_appstore_store.do#!/store/application/7148dbc91bf1f450ced060a7234bcb88[Elastic for ITSM] from the {sn} Store.
+* Create a {sn} integration user and assign it the appropriate roles.
+* Create a Cross-Origin Resource Sharing (CORS) rule.
+
+*Create a {sn} integration user*
+
+To ensure authenticated communication between Elastic and {sn}, create a {sn} integration user and assign it the appropriate roles.
+
+. In your {sn} instance, go to *System Security -> Users and Groups -> Users*.
+. Click *New*.
+. Complete the form, then right-click on the menu bar and click *Save*.
+. Go to the *Roles* tab and click *Edit*.
+. Assign the integration user the following roles: 
+* `import_set_loader`
+* `import_transformer`
+* `personalize_choices`
+* `x_elas2_inc_int.integration_user`
+. Click *Save*.
+
+*Create a CORS rule*
+
+A CORS rule is required for communication between Elastic and {sn}. To create a CORS rule:
+
+. In your {sn} instance, go to *System Web Services -> REST -> CORS Rules*.
+. Click *New*.
+. Configure the rule as follows:
+* *Name*: Name the rule.
+* *REST API*: Set the rule to use the Elastic ITSM API by choosing `Elastic ITSM API [x_elas2_inc_int/elastic_api]`.
+* *Domain*: Enter the Kibana URL.
+. Go to the *HTTP methods* tab and select *GET*.
+. Click *Submit* to create the rule.
+
+[float]
+[[servicenow-itsm-connector-update]]
+==== Update a deprecated {sn} ITSM connector
+
+{sn} ITSM connectors created in {stack} version 7.15.0 or earlier are marked as deprecated after you upgrade to version 7.16.0 or later. Deprecated connectors have a yellow icon after their name and display a warning message when selected.
+
+[role="screenshot"]
+image::management/connectors/images/servicenow-sir-update-connector.png[Shows deprecated ServiceNow connectors]
+
+IMPORTANT: Deprecated connectors will continue to function with the rules they were added to and can be assigned to new rules. However, it is strongly recommended to update deprecated connectors or <<creating-new-connector, create new ones>> to ensure you have access to connector enhancements, such as updating incidents.
+
+To update a deprecated connector:
+
+. Open the main menu and go to *Stack Management -> Rules and connectors -> Connectors*.
+. Select the deprecated connector to open the *Edit connector* flyout.
+. In the warning message, click *Update this connector*.
+. Complete the guided steps in the *Edit connector* flyout.
+.. Install https://store.servicenow.com/sn_appstore_store.do#!/store/application/7148dbc91bf1f450ced060a7234bcb88[Elastic for ITSM] and complete the <<servicenow-itsm-connector-prerequisites, required prerequisites>>.
+.. Enter the URL of your {sn} instance.
+.. Enter the username and password of your {sn} instance.
+. Click *Update*.
 
 [float]
 [[servicenow-connector-configuration]]
 ==== Connector configuration
 
-ServiceNow ITSM connectors have the following configuration properties.
+{sn} ITSM 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.
+URL::       {sn} 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 Incident 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-connector-networking-configuration]]
 ==== Connector networking configuration
@@ -48,7 +105,7 @@ Config defines information for the connector type.
 `apiUrl`:: An address that corresponds to *URL*.
 `usesTableApi`:: A boolean that indicates if the connector uses the Table API or the Import Set API.
 
-Note: If `usesTableApi` is set to false the Elastic application should be installed in ServiceNow.
+NOTE: If `usesTableApi` is set to false, the Elastic application should be installed in {sn}.
 
 Secrets defines sensitive information for the connector type.
 
@@ -59,12 +116,12 @@ Secrets defines sensitive information for the connector type.
 [[define-servicenow-ui]]
 ==== Define connector in Stack Management
 
-Define ServiceNow ITSM connector properties.
+Define {sn} ITSM connector properties.
 
 [role="screenshot"]
 image::management/connectors/images/servicenow-connector.png[ServiceNow connector]
 
-Test ServiceNow ITSM action parameters.
+Test {sn} ITSM action parameters.
 
 [role="screenshot"]
 image::management/connectors/images/servicenow-params-test.png[ServiceNow params test]
@@ -73,21 +130,24 @@ image::management/connectors/images/servicenow-params-test.png[ServiceNow params
 [[servicenow-action-configuration]]
 ==== Action configuration
 
-ServiceNow ITSM actions have the following configuration properties.
+{sn} ITSM actions have the following configuration properties.
 
 Urgency::              The extent to which the incident resolution can delay.
 Severity::             The severity of the incident.
 Impact::               The effect an incident has on business. Can be measured by the number of affected users or by how critical it is to the business in question.
 Category::             The category of the incident.
 Subcategory::          The category of the incident.
-Correlation ID::       All actions sharing this ID will be associated with the same ServiceNow incident. If an incident exists in ServiceNow with the same correlation ID the incident will be updated. Default value: `<rule ID>:<alert instance ID>`.
-Correlation Display::  A descriptive label of the alert for correlation purposes in ServiceNow.
+Correlation ID::            Connectors using the same Correlation ID will be associated with the same {sn} incident. This value determines whether a new {sn} incident will be created or an existing one is updated. Modifying this value is optional; if not modified, the rule ID and alert ID are combined as `{{ruleID}}:{{alert ID}}` to form the Correlation ID value in {sn}. The maximum character length for this value is 100 characters.
+
+NOTE: Using the default configuration of `{{ruleID}}:{{alert ID}}` ensures that {sn} will create a separate incident record for every generated alert that uses a unique alert ID. If the rule generates multiple alerts that use the same alert IDs, {sn} creates and continually updates a single incident record for the alert.
+
+Correlation Display::  A descriptive label of the alert for correlation purposes in {sn}.
 Short description::    A short description for the incident, used for searching the contents of the knowledge base.
 Description::          The details about the incident.
 Additional comments::  Additional information for the client, such as how to troubleshoot the issue.
 
 [float]
 [[configuring-servicenow]]
-==== Configure ServiceNow
+==== Configure {sn}
 
-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.
+{sn} 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.