Integration with External Ticket Systems

SAP Cloud ALM can forward events to external ticket systems to create incidents or cases. This page describes the setup and the mapping definition of the integration. The integration to ticket systems is always bi-directional and requires status updates from the ticket system back to SAP Cloud ALM.

Integration Types

Any ticket system can be connected to SAP Cloud ALM using the provided External API Integration capabilities. Depending on the environment the following integration types have to be distinguished.

Integration with Service Now

SAP Cloud ALM provides an ready-to-use integration with ServiceNow Incident Management including a pre-defined API mapping. Only the maintenance of a destination to Service Now with authentication information is required. In case of advanced needs the mapping file can be adjusted.

Simple Integration with Other Ticket Systems

The ticket system must:

Expose REST APIs for incident manipulation

  • Support a compatible payload for REST operations
    • Only one payload per REST operation
    • Mapping of Cloud ALM event situation payload to target payload must be achievable with attribute matching, placeholder expressions and switch expressions
    • The return value of the REST API for creating a ticket must contain the ticket number and/or ticket guid to enable updates of existing tickets from SAP Cloud ALM
  • The target system API endpoint must be accessible from the SAP Cloud ALM BTP account with a BTP destination type which is supported by SAP Cloud ALM (Restrictions and Limitations are documented in Creating SAP BTP Destinations in SAP Help).


Complex Integration with Other Ticket Systems

If the ticket system does not match the requirements for a simple integration, an integration can still be achieved by using SAP Integration Suite or 3rd party API Integration HUB platform.

Kindly note that each integration of type ticket needs a 1:1 mapping of event situation and ticket number and that it is mandatory to store the ticket number in SAP Cloud ALM to ensure proper functionality of the integration. The only way to store the ticket number in SAP Cloud ALM is at the time of the create ticket API call. The API called must therefore return the ticket ID synchronously in this call.

It is recommended to include SAP Cloud ALM partners in such projects to accelerate the implementation and to ensure long-term support of the solution.

Configuration Flow to Connect Ticket Systems with SAP Cloud ALM

Prerequisites

  • Timestamps returned by the ticket system API must be formatted in “YYYY-MM-DDTHH:mm:ssZ” format and must be returned in UTC time.
     

Establish Connectivity from SAP Cloud ALM to the external ticket system

Case 1: The external ticket system is not ServiceNow Incident Management

To connect from SAP Cloud ALM to the external ticket system, a destination must be configured in the BTP subaccount, where SAP Cloud ALM is deployed.

  1. Log on to BTP Cockpit and enter your SAP Cloud ALM subaccount
  2. Navigate to "Connectivity" > "Destinations"
  3. Click "New Destination"
    1. Name: Enter a destination name that identifies the API endpoint of your ticket system or the API middleware provider
    2. Type: HTTP
    3. Description: A description of the destination
    4. URL: URL of the API endpoint of your ticket system or the used API middleware
    5. Proxy Type: Internet
    6. Authentication: use the authentication method of the target API. Authentication method “NoAuthentication” is not supported by SAP Cloud ALM integrations
    7. Enter the required authentication information depending on the authentication method
  4. Click the "Save" button

Case 2: The external ticket system is ServiceNow Incident Management

To establish connectivity to ServiceNow Incident Management you can ignore the steps above and configure the connectivity in Landscape Management in SAP Cloud ALM. Refer to "Example: Configure Integration with ServiceNow Incident Management" below for details.


Create Mapping

To map and convert the available values of the event situation outbound integration with the API definition of the target system a field or value mapping is necessary in most cases. This mapping can be achieved for simple integrations by providing a mapping file in SAP Cloud ALM directly. The possible options for mappings are described in the SAP Cloud ALM documentation. The format of the event situation API is also documented there.

The return values of the integration must return an externalId and externalNumber of the created ticket. During runtime these values are stored in SAP Cloud ALM to map the event situation in SAP Cloud ALM to the ticket in the ticket system.

If the provided mapping capabilities are not sufficient or if a single API call a single API call from SAP Cloud ALM to the ticket system is not sufficient to create or update a ticket, additional integration logic must be defined in an integration system.


Maintain External API

With the destination and the mapping file the definition of the external API endpoint in Cloud ALM can be completed by creating a webhook and the subscription. To make the integration available as for creation of tickets, the “External Ressource Type” must be “Incident”. As “Destination Type” the name of the ticket system can be used (free text field). The “Ressource Type” in the subscription definition must be set to “CALM Event Situation”.


Configure External API as Event Action

After the subscription is fully maintained as explained above the available subscriptions of type incident are then available in the event configuration for “Create Ticket” event action. To enable ticket creation the switch create ticket needs to be turned on and the subscription with the mapping and webhook for this event type can be selected.

You can configure the event actions for monitoring events from the configuration page in the relevant monitoring application (Business Process Monitoring, Integration & Exception Monitoring, Job & Automation Monitoring, Health Monitoring).

You can configure the event actions for status events (Disruptions, Degradations , Maintenance, Customer Communication events from Business Service Management or SAP for Me Notifications) as described here.


Setup Event Situation Confirmation if Ticket is Solved

For monitoring events  it is required to  update the status of event situations whenever a ticket is solved. Doing so will ensure, that the corresponding event situation for the ticket is also completed in Cloud ALM and new occurrences of the same issue will no longer try to update the already solved ticket, but creates a new ticket instead.

To achieve this the ticket system processing rules must be updated to trigger a callback into Cloud ALM using the Event Situation API. With the API two different calls are possible – either by the event situation id as generated in Cloud ALM (this requires the event situation id to be transferred and persisted in the ticket system) or by the external id of the ticket in the ticket system, which is stored in Cloud ALM during the ticket creation. The details about the API to be called are available here.

For status events (Disruptions, Degradations, Maintenances), the event situation will be closed automatically some time after the event is completed. A call back from the ticket system is therefore not required and also not supported. 

 

Example: Configure Integration with ServiceNow Incident Management

Scope

The provided example solution for integrating ServiceNow Incident Management and SAP Cloud ALM for Operations is intended to enable a rapid prototyping and as baseline for customer specific implementations. This solution does not consider the back communication from ServiceNow to SAP Cloud ALM as well as specific customer ITSM process definitions or grouping of multiple event situations into single tickets.

SAP recommends to use the provided mapping as starting point and create a productive integration together with an integration expert (SAP service delivery or SAP partner) to ensure a smooth integration into customer service processes.

Prerequisites

  • You need a technical user in ServiceNow that has the authorization to create incidents and/or cases. The personalization settings for this user must set the user time zone to “GMT” and the date format to “MM-dd-yyyy”.
  • Your user needs the role "Connectivity and Destination Administrator" in the SAP Cloud ALM subaccount.

Establish Connectivity

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

  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
  4. Select the new cloud service of type ServiceNow
  5. 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.
    4. Select "Check Connection"
    5. If connection check was successful, save the endpoint
  6. 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.

Create 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.

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.

Example ServiceNow: Mapping

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
  5. In the field "Mapping Rules" you find the current mapping in JSON format.
  6. Click the "Format rules" button to pretty-print the editor
  7. 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.

Example ServiceNow: Configure Event Action

After configuring the integration between SAP Cloud ALM and ServiceNow you need to create an event action to trigger incidents from events

For events triggered from monitoring applications:

  1. Navigate to the configuration for the monitoring application for which you want to create the event and incident
  2. Select the service for which you want to create the event
  3. In the configuration UI, select the tab "Events"
  4. Create an event (The available events differ for different use cases and different service/system types)
    1. Scroll down to "Event Actions" > "Create ServiceNow Ticket"
    2. Click the "+" button to add the correct subscription
    3. Select the subscription that you want to use to create the incident
    4. Save your changes

Activate event actions for status events (Disruptions, Degradations, Maintenances, Customer Communications) triggered from Business Service Management or SAP For Me as described here.

Troubleshooting

For analysis of missing or incomplete integrations the following tools and steps are provided by SAP Cloud ALM to investigate the issue:
 

Intelligent Event Processing Logbook

Using the Intelligent Event Processing Logbook provides the capability to search for event situations which happened in SAP Cloud ALM. Especially to verify if an event was raised as expected this functionality is the first entry point into each analysis. The analytical steps are as follows:

  1. Set scope to the cloud service or system you expect the event to happen.
  2. Check the result list if the expected event situation is available – in case it is not available, the configuration of the event must be checked in the corresponding monitoring application inside of SAP Cloud ALM and if the event is correctly setup, it is also required, that the defined threshold criteria's matched to raise a corresponding event situation.
  3. If you have identified a matching event situation it is possible to further drill-down to the action log for this event. Here it is possible to see each action which was triggered for the event situation with a short success or error message. In case there is an error raised for the create ticket action, the error text from the target API is directly shown. Further details are available in the console of the External API Management application.
     

External API Management

Within the External API Management application the subscriptions and mappings for external APIs are managed. Also available there is a console application, which shows all calls from Cloud ALM to the external APIs. Using this a missing or failed call can be easily identified. Based on the timestamp of the event action as seen in the Intelligent Event Processing Logbook it is possible to search to the API call in the console and to identify for each call:

  • Call status
  • Detailed error message
  • Detailed response payload from the API and the result of the mapping

Also available in this screen is the correlation id, which is necessary in case of tickets to the SAP Cloud ALM team. Please raise issues to component SV-CLM-OP-IEP.