[Connectors][ServiceNow ITSM] Edit labels, automate screenshots, add cross-scope privileges

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

@@ -31,16 +31,14 @@ image::management/connectors/images/servicenow-itom-connector-oauth.png[{sn-itom
 [[servicenow-itom-connector-configuration]]
 ==== Connector configuration
 
-{sn-itom} connectors have the following configuration properties:
+{sn-itom} connectors have a name and the following configuration properties:
 
 Client ID::
 The client identifier assigned to your OAuth application.
 Client secret:: 
 The client secret assigned to your OAuth application.
-JWT key ID::
+JWT verifier key ID::
 The key identifier assigned to the JWT verifier map of your OAuth application.
-Connector name::
-The name is used to identify a connector in the management UI connector listing or in the connector list when configuring an action.
 Password::
 The password for HTTP basic authentication.
 Private key::

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

@@ -12,9 +12,108 @@ The {sn-itsm} connector uses the
 https://developer.servicenow.com/dev.do#!/reference/api/sandiego/rest/c_ImportSetAPI[import set API]
 to create {sn} incidents. You can use the connector for rule actions and cases.
 
+[float]
+[[define-servicenow-ui]]
+=== Create connectors in {kib}
+
+You can create connectors in *{stack-manage-app} > {connectors-ui}*
+or as needed when you're creating a rule. You must choose whether to use OAuth for authentication.
+
+[role="screenshot"]
+image::management/connectors/images/servicenow-connector-basic.png[ServiceNow connector using basic auth]
+// NOTE: This is an autogenerated screenshot. Do not edit it directly.
+
+
+[role="screenshot"]
+image::management/connectors/images/servicenow-connector-oauth.png[ServiceNow connector using OAuth]
+// NOTE: This is an autogenerated screenshot. Do not edit it directly.
+
+[float]
+[[servicenow-connector-configuration]]
+==== Connector configuration
+
+{sn-itsm} connectors have a name and the following configuration properties:
+
+Client ID::
+The client identifier assigned to your OAuth application.
+Client secret::
+The client secret assigned to your OAuth application.
+JWT verifier key ID::
+The key identifier assigned to the JWT verifier map of your OAuth application.
+Password::
+The password for HTTP basic authentication.
+Private key::
+The RSA private key that you created for use in {sn}.
+Private key password::
+The password for the RSA private key.
+This values is required if you set a password for your private key.
+{sn} instance URL::
+The full URL for the {sn} instance.
+Use OAuth authentication:: 
+By default, basic authentication is used instead of open authorization (OAuth).
+User identifier::
+The identifier to use for OAuth type authentication.
+This identifier should be the user field you selected during setup. For example, if the selected user field is `Email`, the user identifier should be the user's email address.
+Username::
+The username for HTTP basic authentication.
+
+[float]
+[[servicenow-action-configuration]]
+=== Test connectors
+
+You can test connectors with the <<execute-connector-api,run connector API>> or
+as you're creating or editing the connector in {kib}. For example:
+
+[role="screenshot"]
+image::management/connectors/images/servicenow-params-test.png[ServiceNow params test]
+
+{sn-itsm} actions have the following configuration properties.
+
+Additional comments::
+Additional information for the client, such as how to troubleshoot the issue.
+Category::
+The category of the incident.
+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.
+Impact::
+The effect an incident has on business.
+It can be measured by the number of affected users or by how critical it is to the business in question.
+Severity::
+The severity of the incident.
+Short description::
+A short description for the incident, used for searching the contents of the knowledge base.
+Subcategory::
+The category of the incident.
+Urgency::
+The extent to which the incident resolution can delay.
+
+[float]
+[[servicenow-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]
+[[configuring-servicenow]]
+=== Configure {sn}
+
+{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.
+
 [float]
 [[servicenow-itsm-connector-prerequisites]]
-=== Prerequisites
+==== Prerequisites
 
 After upgrading from {stack} version 7.15.0 or earlier to version 7.16.0 or
 later, you must complete the following steps within your {sn} instance before
@@ -23,13 +122,57 @@ creating a new {sn-itsm} connector or
 
 . Install
 https://store.servicenow.com/sn_appstore_store.do#!/store/application/7148dbc91bf1f450ced060a7234bcb88[Elastic for ITSM]
-from the {sn} Store.
+from the {sn} store.
+. <<servicenow-itsm-connector-privileges,Assign cross-scope privileges for the Elastic for ITSM app>>.
 . <<servicenow-itsm-connector-prerequisites-integration-user,Create a {sn} integration user and assign it the appropriate roles>>.
 . <<servicenow-itsm-connector-prerequisites-cors-rule,Create a Cross-Origin Resource Sharing (CORS) rule>>.
 . If you use open authorization (OAuth), you must also:
 .. <<servicenow-itsm-connector-prerequisites-rsa-key,Create an RSA keypair and add an X.509 Certificate>>.
 .. <<servicenow-itsm-connector-prerequisites-endpoint,Create an OAuth JWT API endpoint for external clients with a JWT Verifiers Map>>.
 
+[float]
+[[servicenow-itsm-connector-privileges]]
+==== Assign cross-scope privileges
+
+The Elastic for ITSM app requires specific cross-scope privilege records to run successfully:
+
+|===
+|Source scope|Target scope|Target name|Operation|Status
+
+.6+|Elastic for ITSM
+.6+|Global
+|GlideRecord.insert
+|Execute API
+|Allowed
+
+|GlideRecord.setValue
+|Execute API
+|Allowed
+
+|GlideRecordSecure.getValue
+|Execute API
+|Allowed
+
+|Incident
+|Read
+|Allowed
+
+|ScriptableServiceResultBuilder.setBody
+|Execute API
+|Allowed
+
+|ScopedGlideElement
+|Execute API
+|Allowed
+|===
+
+To access the cross scope privileges table:
+
+1. Log into {sn} and set your application scope to Elastic for ITSM.
+2. Click *All* and search for `sys_scope_privilege`.
+
+For more details, refer to the https://docs.servicenow.com/[{sn} product documentation].
+
 [float]
 [[servicenow-itsm-connector-prerequisites-integration-user]]
 ==== Create a {sn} integration user
@@ -174,77 +317,7 @@ To update a deprecated connector:
 . 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>>.
+.. 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]
-[[define-servicenow-ui]]
-=== Create connectors in {kib}
-
-You can create connectors in *{stack-manage-app} > {connectors-ui}*
-or as needed when you're creating a rule. You must choose whether to use OAuth for authentication.
-
-[role="screenshot"]
-image::management/connectors/images/servicenow-connector-basic.png[ServiceNow connector using basic auth]
-
-[role="screenshot"]
-image::management/connectors/images/servicenow-connector-oauth.png[ServiceNow connector using OAuth]
-
-[float]
-[[servicenow-connector-configuration]]
-==== Connector configuration
-
-{sn-itsm} connectors have the following configuration properties:
-
-Name::      The name of the connector.
-Is OAuth::  The type of authentication to use.
-URL::       {sn} instance URL.
-Username::  Username for HTTP Basic authentication.
-Password::  Password for HTTP Basic authentication.
-User Identifier:: Identifier to use for OAuth type authentication. This identifier should be the *User field* you selected during setup. For example, if the selected *User field* is *Email*, the user identifier should be the user's email address.
-Client ID:: The client ID assigned to your OAuth application.
-Client Secret:: The client secret assigned to your OAuth application.
-JWT Key ID:: The key ID assigned to the JWT Verifier Map of your OAuth application.
-Private Key:: The RSA private key generated during setup.
-Private Key Password:: The password for the RSA private key generated during setup, if set.
-
-[float]
-[[servicenow-action-configuration]]
-=== Test connectors
-
-You can test connectors with the <<execute-connector-api,run connector API>> or
-as you're creating or editing the connector in {kib}. For example:
-
-[role="screenshot"]
-image::management/connectors/images/servicenow-params-test.png[ServiceNow params test]
-
-
-{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::            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]
-[[servicenow-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]
-[[configuring-servicenow]]
-=== Configure {sn}
-
-{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.

x-pack/plugins/stack_connectors/public/connector_types/lib/servicenow/translations.ts

@@ -77,7 +77,7 @@ export const SECURITY_INCIDENT = i18n.translate(
 export const SHORT_DESCRIPTION_LABEL = i18n.translate(
   'xpack.stackConnectors.components.serviceNow.titleFieldLabel',
   {
-    defaultMessage: 'Short description (required)',
+    defaultMessage: 'Short description',
   }
 );
 
@@ -209,14 +209,14 @@ export const UNKNOWN = i18n.translate('xpack.stackConnectors.components.serviceN
 export const CORRELATION_ID = i18n.translate(
   'xpack.stackConnectors.components.serviceNow.correlationID',
   {
-    defaultMessage: 'Correlation ID (optional)',
+    defaultMessage: 'Correlation ID',
   }
 );
 
 export const CORRELATION_DISPLAY = i18n.translate(
   'xpack.stackConnectors.components.serviceNow.correlationDisplay',
   {
-    defaultMessage: 'Correlation display (optional)',
+    defaultMessage: 'Correlation display',
   }
 );
 

x-pack/plugins/stack_connectors/public/connector_types/servicenow_itsm/servicenow_itsm_params.tsx

@@ -12,6 +12,7 @@ import {
   EuiFlexGroup,
   EuiFlexItem,
   EuiSpacer,
+  EuiText,
   EuiTitle,
   EuiLink,
 } from '@elastic/eui';
@@ -62,6 +63,11 @@ const CorrelationIdField: React.FunctionComponent<
           />
         </EuiLink>
       }
+      labelAppend={
+        <EuiText size="xs" color="subdued">
+          {i18n.OPTIONAL_LABEL}
+        </EuiText>
+      }
     >
       <TextFieldWithMessageVariables
         index={index}
@@ -294,7 +300,15 @@ const ServiceNowParamsFields: React.FunctionComponent<
                   />
                 </EuiFlexItem>
                 <EuiFlexItem>
-                  <EuiFormRow fullWidth label={i18n.CORRELATION_DISPLAY}>
+                  <EuiFormRow
+                    fullWidth
+                    label={i18n.CORRELATION_DISPLAY}
+                    labelAppend={
+                      <EuiText size="xs" color="subdued">
+                        {i18n.OPTIONAL_LABEL}
+                      </EuiText>
+                    }
+                  >
                     <TextFieldWithMessageVariables
                       index={index}
                       editAction={editSubActionProperty}
@@ -319,6 +333,11 @@ const ServiceNowParamsFields: React.FunctionComponent<
                   incident.short_description !== undefined
                 }
                 label={i18n.SHORT_DESCRIPTION_LABEL}
+                labelAppend={
+                  <EuiText size="xs" color="subdued">
+                    {i18n.REQUIRED_LABEL}
+                  </EuiText>
+                }
               >
                 <TextFieldWithMessageVariables
                   index={index}

x-pack/test/screenshot_creation/apps/response_ops_docs/stack_connectors/index.ts

@@ -63,6 +63,7 @@ export default function ({ loadTestFile, getService }: FtrProviderContext) {
     loadTestFile(require.resolve('./pagerduty_connector'));
     loadTestFile(require.resolve('./server_log_connector'));
     loadTestFile(require.resolve('./servicenow_itom_connector'));
+    loadTestFile(require.resolve('./servicenow_itsm_connector'));
     loadTestFile(require.resolve('./slack_connector'));
     loadTestFile(require.resolve('./webhook_connector'));
     loadTestFile(require.resolve('./xmatters_connector'));

x-pack/test/screenshot_creation/apps/response_ops_docs/stack_connectors/servicenow_itsm_connector.ts

@@ -0,0 +1,48 @@
+/*
+ * 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 { FtrProviderContext } from '../../../ftr_provider_context';
+
+export default function ({ getService, getPageObjects }: FtrProviderContext) {
+  const commonScreenshots = getService('commonScreenshots');
+  const screenshotDirectories = ['response_ops_docs', 'stack_connectors'];
+  const pageObjects = getPageObjects(['common', 'header']);
+  const actions = getService('actions');
+  const testSubjects = getService('testSubjects');
+
+  describe('servicenow itsm connector', function () {
+    beforeEach(async () => {
+      await pageObjects.common.navigateToApp('connectors');
+      await pageObjects.header.waitUntilLoadingHasFinished();
+    });
+
+    it('servicenow itsm connector screenshots', async () => {
+      await pageObjects.common.navigateToApp('connectors');
+      await pageObjects.header.waitUntilLoadingHasFinished();
+      await actions.common.openNewConnectorForm('servicenow');
+      await testSubjects.setValue('nameInput', 'ServiceNow ITSM test connector');
+      await testSubjects.setValue('credentialsApiUrlFromInput', 'https://dev123.service-now.com');
+      await testSubjects.click('input');
+      await commonScreenshots.takeScreenshot(
+        'servicenow-connector-oauth',
+        screenshotDirectories,
+        1920,
+        1600
+      );
+      await testSubjects.click('input');
+      await testSubjects.setValue('connector-servicenow-username-form-input', 'testuser');
+      await testSubjects.setValue('connector-servicenow-password-form-input', 'testpassword');
+      await commonScreenshots.takeScreenshot(
+        'servicenow-connector-basic',
+        screenshotDirectories,
+        1920,
+        1400
+      );
+      await testSubjects.click('euiFlyoutCloseButton');
+    });
+  });
+}