diff --git a/docs/cases/cases-ui-integrations.asciidoc b/docs/cases/cases-ui-integrations.asciidoc index 962ada2c82..05c65c4e8b 100644 --- a/docs/cases/cases-ui-integrations.asciidoc +++ b/docs/cases/cases-ui-integrations.asciidoc @@ -4,23 +4,19 @@ You can push {es-sec} cases to these third-party systems: -* {sn} ITSM -* {sn} SecOps +* {sn-itsm} +* {sn-sir} * {jira} (including Jira Service Desk) * {ibm-r} * {swimlane} -To push cases, you need to create a connector, which stores the information -required to interact with an external system. +To push cases, you need to create a connector, which stores the information required to interact with an external system. After you have created a connector, you can set {es-sec} cases to automatically close when they are sent to external systems. -After you have created a connector, you can set {es-sec} cases to -automatically close when they are sent to external systems. +IMPORTANT: To create connectors and send cases to external systems, you need the +https://www.elastic.co/subscriptions[appropriate license], and your role needs *All* privileges for the *Action and Connectors* feature. For more information, refer to <>. -NOTE: To create connectors and send cases to external systems, you need the -https://www.elastic.co/subscriptions[appropriate license] and your role needs *All* privileges for the *Action and Connectors* feature. For more information, refer to <>. - -[[create-new-connector]] [float] +[[create-new-connector]] === Create a new connector . Go to *Investigate* -> *Cases* -> *Edit external connection*. @@ -28,90 +24,144 @@ https://www.elastic.co/subscriptions[appropriate license] and your role needs *A [role="screenshot"] image::images/cases-ui-connector.png[Shows the page for creating connectors] . From the *Incident management system* list, select *Add new connector*. -. Select one of these: -* *{sn}*: To send cases to {sn} +. Select the system to send cases to: *{sn}*, *{jira}*, *{ibm-r}*, or *{swimlane}*. + ++ +IMPORTANT: If you've upgraded from {stack} version 7.15.0 or earlier to 7.16.0 or later, you must complete several prerequisites before creating a new {sn-itsm} or {sn-sir} connector. For more information, refer to prerequisites for {kibana-ref}/servicenow-action-type.html#servicenow-itsm-connector-prerequisites[{sn-itsm}] and {kibana-ref}/servicenow-sir-action-type.html#servicenow-sir-connector-prerequisites[{sn-sir}]. + +. Enter your required settings. ++ +|=== + +| *Connector name* | Name for the connector. + +| *URL* | ({ibm-r} and {jira} only) The URL of the external system to which you want to send cases. + +| *{sn} instance URL* | ({sn} only) The URL of the {sn} instance to which you want to send cases. + +| *Use OAuth authentication* | ({sn} only) Enable this to use open authorization (OAuth) to authenticate a connection between Elastic and {sn}. + +To use open authorization (OAuth), you must {kibana-ref}/servicenow-action-type.html#servicenow-itsm-connector-prerequisites-rsa-key[create an RSA keypair and add an X.509 Certificate] and also {kibana-ref}/servicenow-action-type.html#servicenow-itsm-connector-prerequisites-endpoint[create an OAuth JWT API endpoint for external clients with a JWT Verifiers Map.] + +| *API URL* | ({swimlane} only) The URL of the {swimlane} instance to which you want to send cases. + +| *Organization ID* | ({ibm-r} only) Your organization’s {ibm-r} ID number. + +| *Application ID* | ({swimlane} only) The application ID of your {swimlane} application. From {swimlane}, you can find the application +ID by checking your application’s settings or at the end of your application’s URL after you’ve opened it. + +| *Username* | ({sn} only and displays if *Use OAuth authentication* is turned off) The username of the {sn} account used to access the {sn} instance. +| *Password* | ({sn} only and displays if *Use OAuth authentication* is turned off) The password of the {sn} account used to access the {sn} instance. + +| *Client ID* | ({sn} only and displays if *Use OAuth authentication* is turned on) The client ID assigned to your OAuth application. + +| *User Identifier* | ({sn} only and displays if *Use OAuth authentication* is turned on) Identifier to use for OAuth type authentication. Use the value you entered into the *User field* when you created an OAuth JWT API endpoint for external clients. + +| *JWT Verifier Key ID* | ({sn} only and displays if *Use OAuth authentication* is turned on) The key ID assigned to the JWT Verifier Map of your OAuth application. + +| *Client Secret* | ({sn} only and displays if *Use OAuth authentication* is turned on) The client secret assigned to your OAuth application. + +| *Private Key* | ({sn} only and displays if *Use OAuth authentication* is turned on) The RSA private key generated when you created an RSA keypair. + +| *Private Key Password* | ({sn} only and displays only if *Use OAuth authentication* is turned on) The The password for the RSA private key generated during setup, if set. + +| *Project key* | ({jira} only) The key of the {jira} project to which you are sending cases. + +| *Email address* | ({jira} only) The {jira} account username or email. + +| *API token* | ({jira} only) The API token or password is used to authenticate {jira} updates. + +| *API key ID* | ({ibm-r} only) The API key is used to authenticate {ibm-r} updates. + +| *API key secret* | ({ibm-r} only) The API key secret is used to authenticate {ibm-r} updates. + +| *API token* | ({swimlane} only) The {swimlane} API authentication token is used for HTTP Basic authentication. +This is the personal access token for your user role. + +|=== ++ +. Choose the connector type ({swimlane} only): + -IMPORTANT: If you've upgraded from {stack} version 7.15.0 or earlier to version 7.16.0 or later, you must install https://store.servicenow.com/sn_appstore_store.do#!/store/application/7148dbc91bf1f450ced060a7234bcb88[Elastic for ITSM] or https://store.servicenow.com/sn_appstore_store.do#!/store/application/2f0746801baeb01019ae54e4604bcb0f[Elastic for Security Operations (SecOps)] on your {sn} instance and complete additional configuration steps before creating a new {sn} ITSM or SecOps connector. If you don't, an error message displays and you cannot create the new connector. For more information, refer to {kibana-ref}/servicenow-sir-action-type.html[{sn} SecOps] and {kibana-ref}/servicenow-action-type.html[{sn} ITSM]. - -* *{jira}*: To send cases to {jira} or {jira} Service Desk -* *{ibm-r}*: To send cases to {ibm-r} -* *{swimlane}*: To send cases to {swimlane} - -. Fill in the following: -* *Connector name*: A name for the connector. -* *URL*: The URL of the external system to which you want to send cases. -* *{sn} instance URL* (for {sn} connectors only): The URL of the {sn} to which you want to send cases. -* *API Url* ({swimlane} connectors only): The URL of the {swimlane} instance to which you want to send cases. -* *Organization ID* ({ibm-r} connectors only): Your organization's {ibm-r} ID -number. -* *Application ID* ({swimlane} connectors only): The application ID of your {swimlane} application. From {swimlane}, you can find the application ID by checking your application's settings or at the end of your application's URL after you've opened it. -* *Username* ({sn} connectors only): The username of the {sn} account used to -access the {sn} instance. -* *Password* ({sn} connectors only): The password of the {sn} account used to access the {sn} instance. -* *Project key* ({jira} connectors only): The key of the {jira} project to which -you are sending cases. -* *Email address* ({jira} connectors only): The {jira} account's username or email address. -* *API token* ({jira} connectors only): The API token or password used -to authenticate {jira} updates. -* *API key ID* ({ibm-r} connectors only): The API key used to authenticate -{ibm-r} updates. -* *API key secret* ({ibm-r} connectors only): The API key secret used to -authenticate {ibm-r} updates. -* *API token* ({swimlane} connectors only): The {swimlane} API authentication token used for HTTP Basic authentication. This is the personal access token for your user role. - -. Choose the connector type (for {swimlane} connectors only): -** *All*: You can choose to set all or no field mappings when creating your new {swimlane} connector. However, note that if you don't set field mappings now, you'll be prompted to do so if you want to use the connector for a case or a rule. The prompts no longer display once you set up the required mappings. -** *Alerts*: Provide an alert ID and rule name. -** *Cases*: Provide a case ID, a case name, comments, and a description. +|=== + +| *All* | You can choose to set all or no field mappings when creating your new {swimlane} connector. However, note that if +you don’t set field mappings now, you’ll be prompted to do so if you want to use the connector for a case or a rule. + +| *Alerts* | Provide an alert ID and rule name. +| *Cases* | Provide a case ID, a case name, comments, and a description. + +|=== ++ . Save the connector. TIP: To learn how to connect {elastic-sec} to {jira}, check out the <> at the end of this topic. +[float] +[[mapped-case-fields]] +=== Mapped case fields + To represent an {es-sec} case in an external system, {es-sec} case fields are mapped as follows: NOTE: Data from mapped case fields can be pushed to external systems but cannot be pulled in. * For {sn} incidents: -** *Title*: Mapped to the {sn} `Short description` field. When an update to a -Security case title is sent to {sn}, the existing {sn} `Short description` -field is overwritten. -** *Description*: Mapped to the {sn} `Description` field. When an update to a -Security case description is sent to {sn}, the existing {sn} `Description` -field is overwritten. -** *Comments*: Mapped to the {sn} `Work Notes` field. When a comment is updated -in a Security case, a new comment is added to the {sn} incident. ++ +|=== + +| *Title* | Mapped to the {sn} `Short description` field. When an update to a case title is sent to {sn}, the existing {sn} `Short description` field is overwritten. + +| *Description* | Mapped to the {sn} `Description` field. When an update to a case description is sent to {sn}, the existing {sn} `Description` field is overwritten. + +| *Comments* | Mapped to the {sn} `Work Notes` field. When a comment is updated in a case, a new comment is added to the {sn} incident. + +|=== ++ + * For {jira} issues: -** *Title*: Mapped to the {jira} `Summary` field. When an update to a -Security case title is sent to {jira}, the existing {jira} `Summary` field is -overwritten. -** *Description*: Mapped to the {jira} `Description` field. When an update to a -Security case description is sent to {jira}, the existing {jira} `Description` -field is overwritten. -** *Comments*: Mapped to the {jira} `Comments` field. When a comment is updated -in a Security case, a new comment is added to the {jira} incident. ++ +|=== + +| *Title* | Mapped to the {jira} `Summary` field. When an update to a case title is sent to {jira}, the existing {jira} `Summary` field is overwritten. + +| *Description* | Mapped to the {jira} `Description` field. When an update to a case description is sent to {jira}, the existing {jira} `Description` field is overwritten. + +| *Comments* | Mapped to the {jira} `Comments` field. When a comment is updated in a case, a new comment is added to the {jira} incident. + +|=== ++ + * For {ibm-r} issues: -** *Title*: Mapped to the {ibm-r} `Name` field. When an update to a -Security case title is sent to {ibm-r}, the existing {ibm-r} `Name` field is -overwritten. -** *Description*: Mapped to the {ibm-r} `Description` field. When an update to a -Security case description is sent to {ibm-r}, the existing {ibm-r} `Description` -field is overwritten. -** *Comments*: Mapped to the {ibm-r} `Comments` field. When a comment is updated -in a Security case, a new comment is added to the {ibm-r} incident. ++ +|=== + +| *Title* | Mapped to the {ibm-r} `Name` field. When an update to a case title is sent to {ibm-r}, the existing {ibm-r} `Name` field is overwritten. + +| *Description* | Mapped to the {ibm-r} `Description` field. When an update to a case description is sent to {ibm-r}, the existing {ibm-r} `Description` field is overwritten. + +| *Comments* | Mapped to the {ibm-r} `Comments` field. When a comment is updated in a case, a new comment is added to the {ibm-r} incident. + +|=== ++ + * For {swimlane} records: -** *Title*: Mapped to the {swimlane} `caseName` field. When an update to a -Security case title is sent to {swimlane}, the field that is mapped to the {swimlane} `caseName` field is ++ +|=== + +| *Title* | Mapped to the {swimlane} `caseName` field. When an update to a case title is sent to {swimlane}, the field that is mapped to the {swimlane} `caseName` field is overwritten. -** *Description*: Mapped to the {swimlane} `Description` field. When an update to a -Security case description is sent to {swimlane}, the field that is mapped to the {swimlane} `Description` -field is overwritten. -** *Comments*: Mapped to the {swimlane} `Comments` field. When a new comment is added to a Security case, or an existing one is updated, the field that is mapped to the {swimlane} `Comment` field is appended. Comments are posted to the {swimlane} incident record individually. + +| *Description* | Mapped to the {swimlane} `Description` field. When an update to a case description is sent to {swimlane}, the field that is mapped to the {swimlane} `Description` field is overwritten. + +| *Comments* | Mapped to the {swimlane} `Comments` field. When a new comment is added to a case, or an existing one is updated, the field that is mapped to the {swimlane} `Comment` field is appended. Comments are posted to the {swimlane} incident record individually. + +|=== [[close-connector]] [float] +[[close-sent-cases]] === Close sent cases automatically To close cases when they are sent to an external system, select @@ -119,6 +169,7 @@ To close cases when they are sent to an external system, select [[default-connector]] [float] +[[change-default-connector]] === Change the default connector To change the default connector used to send cases to external systems, go to *Cases* -> *Edit external connection* and select the required connector from the Incident management system list. @@ -138,6 +189,7 @@ image::images/add-connectors.png[width=60%][height=60%][Shows how to add connect [[modify-connector]] [float] +[[modify-connector-settings]] === Modify connector settings To change the settings of an existing connector: