SAP Cloud ALM Integration with External Chat Systems

SAP Cloud ALM can forward events to external chat tools to create messages in chat channels. This page describes the setup and the mapping definition of the integration.

Integration Types

Any chat tool 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 Microsoft Teams

SAP Cloud ALM provides a ready-to-use integration with Microsoft Teams including a pre-defined API mapping.  Only the maintenance of an SAP BTP destination to Teams with authentication information is required. In case of advanced needs, new mapping file can be created by the user.


Simple Integration with Other Chat Tools

The chat tool must:

  • Expose REST APIs for creating chat messages
  • Support a compatible payload for REST operations
    • Only one payload per REST operation
    • Mapping of SAP Cloud ALM event situation payload to target payload must be achievable with attribute matching, placeholder expressions and switch expressions
  • The target system API endpoint must be accessible from the SAP Cloud ALM BTP account with a BTP destination type which is supported by Cloud ALM (e.g. SAP Cloud ALM does not support authentication via http header variables)


Complex Integration with Other Chat Tools

If the chat tools do 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 Chat Tools with SAP Cloud ALM

Establish Connectivity

To connect from SAP Cloud ALM to the chat tool 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 chat tool or the API middleware provider
    2. Type: HTTP
    3. Description: A description of the destination
    4. URL: URL of the API endpoint of your chat tool or the used API middleware
    5. Proxy Type: Internet
    6. Authentication: use the authentication method of the target API.
    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 Cloud ALM directly. The possible options for mappings are described in the Cloud ALM documentation. The format of the event situation API is also documented there.

As there is no update expected from the chat tool and updates will always create a new message in the chat channel. There is no expected return value from the chat tool. Accordingly, there is also no mapping between the chat message and the even situation maintained in SAP Cloud ALM.

If the provided mapping capabilities are not sufficient or if a single API call a single API call from SAP Cloud ALM to the chat tool is not sufficient to create a message, 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 sending of chat messages, the “External Resource Type” must be “Chat”. As “Destination Type” the name of the chat tool can be used (free text field). The “Resource Type” in the subscription definition must be set to “Event Situation”.


Configure External API as Event Action

After the subscription is fully maintained as explained above the available subscriptions of type chat are then available in the event configuration for “Send Chat message” event action. To enable chat message creation the switch send chat message needs to be turned on and the subscription with the mapping and webhook for this event type can be selected.

Example: Configure Integration with Microsoft Teams Chat Channels

Prerequisites

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 Microsoft Teams channel it connects to (e.g. MSTEAMS_CLOUDALM)
    2. Type: HTTP
    3. Description: A description of the destination
    4. URL: The URL of the workflow shown in MS Teams.
    5. Proxy Type: Internet
    6. Authentication: NoAuthentication
  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. MSTeams_CloudALM)
    2. Path: keep empty
    3. Destination Source: BTP Destination
    4. Destination Id: Select the destination you created in the BTP Cockpit
    5. External Resource Type: Select "Chat"
    6. Destination Type: Select „Microsoft Teams"
  5. Your changes are saved automatically.


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 chat message 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: “Event Situation to MS Teams Chat”
  3. Your changes will be saved automatically.

Configure Event Reaction

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

  1. Navigate to the configuration for the application for which you want to configure the automatic creation of chat messages for the event
  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" > "Send Chat Message"
    2. Click the "+" button to add the correct subscription
    3. Select the subscription that you created in the previous step
    4. Save your changes