How to integrate Cloud ALM with external tickets system

[vitor_wolke1]

Example of how to Configure Integration with ServiceNow Incident Management

The steps that needs to be followed are:

1. ServiceNow Developer program instance request

ServiceNow Developers

Request your new instance and receive your user and password (this will be used as example and will be filled out snow setup process in Cloud ALM)

2. Create ServiceNow in Cloud ALM Landscape Management System. 

1. Log on to your SAP Cloud ALM tenant
2. Navigate to "Administration" > "Landscape Management"
3. Click "Manually add a Cloud Service"
   1. Name: Enter a  name that identifies the ServiceNow instance it connects to (e.g. SERVICE_NOW_PROD)
   2. Description: Enter a description of the ServiceNow instance
   3. System Number: Enter the ServiceNow instance name
      (ServiceNow tenants does not have an unique SAP system number as they are third party. To have a unique ID just use the instance name, which is the same as the domain name without .service-now.com)
   4. Service Type: Choose ServiceNow
   5. Tenant Role: Choose the appropriate role
   6. Root URL: Enter the ServiceNow tenant URL without 'navpage.do' (e.g. https://<instance>.service-now.com/)
   7. The remaining fields are optional
   8. Click the "Save" button

A new cloud service of type "ServiceNow" and endpoint is defined in Landscape Management.

1. Select "Add Endpoint"
   1. Optionally overwrite the EndPoint name and add a description.
   2. Keep proposed Use Case and Root URL.
   3. Select the correct authentication type and maintain credentials.

1. Select "Check Connection"
2. If connection check was successful, save the endpoint

If the needed authentication type is not supported by SAP Cloud ALM landscape management it is also possible to create a destination via the SAP BTP cockpit of the SAP Cloud ALM tenant and select a different authentication type there. In this case follow the generic documentation for 3rd party ticket systems.

3. Create Webhook, mapping file and Subscription

Under Administration > External API Management > Webhook Management > Add new Webhook

The rest of the steps is performed in SAP Cloud ALM.

1. Log on to your SAP Cloud ALM tenant
2. Navigate to "Administration" > "External API Management"
3. Select the view "Webhooks Management"
4. Click the "+" button to add a new webhook
   1. Name: Enter a name for the webhook (e.g. ServiceNow_Prod_Incidents)
   2. Path: Enter the path "/api/now/table/incident"
   3. Destination Source: LMS Endpoint
   4. LMS Service: Select the ServiceNow service created before
   5. LMS End Point: Select the endpoint added to the ServiceNow service before
   6. Destination Type: Select "ServiceNow"
   7. External Resource Type: Select "Incident"
5. Your changes are saved automatically.

You can reuse the same webhook in different subscriptions as long as the target is the same table in the same ServiceNow instance.

4. Adjust mapping to meet specification

The view "Mappings Management" allows you to maintain your own mappings of the fields in the event towards the fields in the incident. SAP ships a standard mapping to map SAP Cloud ALM events to incidents in a ServiceNow with the standard setup. 

If you have customized your ServiceNow instance, it is recommended to create your own mapping and adjust it according to the customizing in your ServiceNow instance. You can copy the SAP-delivered mapping and adjust it.

1. In "External API Management" navigate to the view "Mappings Management"
2. Click the "Duplicate mapping" button in the column "Actions"
3. Click the "Edit mapping" button to open your custom mapping
4. You can adjust the following fields:
   1. Description: The description of the mapping
   2. Version: The version of the mapping
   3. Source: The source system
   4. Target: The target system

1. In the field "Mapping Rules" you find the current mapping in JSON format.
2. Click the "Format rules" button to pretty-print the editor
3. You can upload your own mapping rules using the "Load rules" button

The mapping for ServiceNow incidents consists of the following components:

1. Information: The version information for the mapping
2. Request: Rules for the mapping of the event in SAP Cloud ALM to the incident in ServiceNow. 
3. Response: Rules for the mapping of the fields in the response from ServiceNow to the event status in SAP Cloud ALM.
4. EventTypeMapping: Rules to manage the communication events that happen between SAP Cloud ALM and ServiceNow:
   1. CREATED: Post the incident to ServiceNow
   2. UPDATED: Change incident in ServiceNow
   3. PING: Get incident status from ServiceNow
   4. CLOSED: Close incident in ServiceNow

You can find more information in the fields available in the standard mapping in the SAP Help Portal.

5. Create Subscription

After creating the webhook you now can create the subscription.

1. In "External API Management" navigate to the view "Subscriptions Management"
2. Click the "+" button to create a new subscription
   1. Name: Enter a speaking name, this is the name users will see when they set up the incident creation for the alert.
   2. Description: Enter a description
   3. Type: Select "Built-in"
   4. Resource Type: Select "EVENT-SITUATION"
   5. Webhook: Select the webhook you created in the previous step
   6. Mapping: Select the mapping you want to use (see next section for details)
3. Your changes will be saved automatically.

6. After all completed, you will be able to create tickets in SNOW instance.

Feel free to test the alerts on your tenant and create tickets accordingly:

Reference Article: Integration with External Ticket Systems