Contact Us
×
How you can contact us:

  • Technical Assistance

    Request product support from SAP

  • Non-Technical Assistance

    Request non-product support or provide feedback on SAP Support Portal site

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.

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 (e.g. SAP Cloud ALM does not support the usage of unauthenticated destinations or authentication via http header variables)

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.

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

Establish Connectivity

To connect from SAP Cloud ALM to the external ticket system a destination must be configured in the BTP subaccount, where 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


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.

Example: Configure Integration with ServiceNow Incident Management

Prerequisites

  • You need a technical user in ServiceNow that has the authorization to create incidents and/or cases.
  • You need access to the SAP Cloud ALM subaccount in BTP Cockpit.
  • Your user needs the role "Connectivity and Destination Administrator" in the SAP Cloud ALM subaccount.

Create Destination in BTP Cockpit

The destination is created in SAP BTP Cockpit.

  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 ServiceNow tenant it connects to (e.g. SERVICE_NOW_PROD)
    2. Type: HTTP
    3. Description: A description of the destination
    4. URL: The ServiceNow tenant URL without 'navpage.do' (e.g. https://instance.service-now.com/)
    5. Proxy Type: Internet
    6. Authentication: Supported are BasicAuthentication, ClientCertificateAuthentication, or OAuth2ClientCredentials.
    7. Enter the required authentication information depending on the authentication method
  4. Click the "Save" button

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 Id: Select the destination you created in the BTP Cockpit
    4. Destination Type: Select "SNOW"
    5. 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 Reaction

After configuring the integration between SAP Cloud ALM and ServiceNow you can now use this configuration to create incidents from events.

  1. Navigate to the configuration for the 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