diff --git a/docs/management/connectors/action-types/servicenow-itom.asciidoc b/docs/management/connectors/action-types/servicenow-itom.asciidoc index 70ee48ccccd7b..ea21cb72248f7 100644 --- a/docs/management/connectors/action-types/servicenow-itom.asciidoc +++ b/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:: diff --git a/docs/management/connectors/action-types/servicenow.asciidoc b/docs/management/connectors/action-types/servicenow.asciidoc index f3c636df29b6b..db0b9b3183a6f 100644 --- a/docs/management/connectors/action-types/servicenow.asciidoc +++ b/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 <> 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 <> 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,56 @@ 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. +. <>. . <>. . <>. . If you use open authorization (OAuth), you must also: .. <>. .. <>. +[float] +[[servicenow-itsm-connector-privileges]] +==== Assign cross-scope privileges + +The Elastic for ITSM app requires specific cross-scope privilege records to run successfully. +In particular, you must have a privilege record for the `Elastic for ITSM` application and source scope with a `global` target scope for each of the following targets: + +|=== +|Target name, type|Operation|Status + +|GlideRecord.insert, Scriptable +|Execute API +|Allowed + +|GlideRecord.setValue, Scriptable +|Execute API +|Allowed + +|GlideRecordSecure.getValue, Scriptable +|Execute API +|Allowed + +|Incident, Table +|Read +|Allowed + +|ScriptableServiceResultBuilder.setBody, Scriptable +|Execute API +|Allowed + +|ScopedGlideElement, Scriptable +|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 +316,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 <>. +.. Install https://store.servicenow.com/sn_appstore_store.do#!/store/application/7148dbc91bf1f450ced060a7234bcb88[Elastic for ITSM] and complete the <>. .. 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 <> 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 <> 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. diff --git a/docs/management/connectors/images/servicenow-connector-basic.png b/docs/management/connectors/images/servicenow-connector-basic.png index e2bf73ad14594..4cf1f19fe8173 100644 Binary files a/docs/management/connectors/images/servicenow-connector-basic.png and b/docs/management/connectors/images/servicenow-connector-basic.png differ diff --git a/docs/management/connectors/images/servicenow-connector-oauth.png b/docs/management/connectors/images/servicenow-connector-oauth.png index f0124d39cfde9..8f818185f686b 100644 Binary files a/docs/management/connectors/images/servicenow-connector-oauth.png and b/docs/management/connectors/images/servicenow-connector-oauth.png differ diff --git a/x-pack/plugins/stack_connectors/public/connector_types/lib/servicenow/translations.ts b/x-pack/plugins/stack_connectors/public/connector_types/lib/servicenow/translations.ts index b0db38a93b69c..998f4540cfd47 100644 --- a/x-pack/plugins/stack_connectors/public/connector_types/lib/servicenow/translations.ts +++ b/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', } ); diff --git a/x-pack/plugins/stack_connectors/public/connector_types/servicenow_itsm/servicenow_itsm_params.tsx b/x-pack/plugins/stack_connectors/public/connector_types/servicenow_itsm/servicenow_itsm_params.tsx index 7c0c72db2b502..283e0c0fb9c8f 100644 --- a/x-pack/plugins/stack_connectors/public/connector_types/servicenow_itsm/servicenow_itsm_params.tsx +++ b/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< /> } + labelAppend={ + + {i18n.OPTIONAL_LABEL} + + } > - + + {i18n.OPTIONAL_LABEL} + + } + > + {i18n.REQUIRED_LABEL} + + } > { + 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'); + }); + }); +}