====== SAP Cloud ALM ======

This documentation explains how to create a connector for **SAP Cloud ALM** in order to enable Cloud ALM monitoring and data collection.

===== Cloud ALM Monitors =====
  * [[..:monitorsguide:sap_cloud_alm:health_monitoring_monitor|Cloud ALM Health Monitoring Monitor]]

===== Cloud ALM connector =====
Describes how to connect the Redpeaks collector to a SAP Cloud ALM environment.

==== Create Cloud ALM Connector ====
  - + Add Connector → **Web Service**
  - Authentication type → **CLOUD_ALM**
  - **Authentication server** → OAuth token endpoint URL (see section below)
  - **ClientId** → OAuth Client ID (see section below)
  - **ClientSecret** → OAuth Client Secret (see section below)
  - **URL** → Cloud ALM API base URL (see section below)
  - Save and test

==== Where to get Token URL / ClientId / ClientSecret / URL (SAP BTP) ====

All credentials for the SAP Cloud ALM API are obtained from **SAP Business Technology Platform (BTP)** — there is no independent client registration inside Cloud ALM.

**Prerequisites**
  * Your user must have the **Global Account Administrator** role in the SAP Cloud ALM global account.
  * The user must be a member of the subaccount that contains the SAP Cloud ALM subscription.

**Step 1: Configure Entitlements**
  - Open the **SAP BTP Cockpit**.
  - Select the **global account** that contains your SAP Cloud ALM entitlement, then open the **subaccount** that contains your SAP Cloud ALM subscription.
  - In the left menu, go to **Entitlements** → **Edit** → **Add Service Plans**.
  - Select the entitlement **SAP Cloud ALM API**.
  - Under **Available Plans**, check **standard**.
  - Choose **Add 1 Service Plan** → **Save**.

**Step 2: Create or Update the SAP Cloud ALM API Service Instance**
  - In the subaccount, go to **Services** → **Instances and Subscriptions**.
  - If an instance already exists, choose **Actions** (⋯) → **Update**.
  - If no instance exists, choose **Create**.
  - Under **Basic Info**, provide:
     - **Service**: SAP Cloud ALM API
     - **Plan**: standard
     - **Runtime Environment**: Other
     - **Instance Name**: A meaningful name (maximum 32 characters; alphanumeric, periods, hyphens; use underscores instead of spaces)
  - (Recommended) Add the required scopes by inserting the following JSON in the **Parameters** section (see JSON below).
  - Choose **Create** (or **Update**).

**JSON for Parameters section:**

<code>
{
    "xs-security": {
        "xsappname": "<Your Instance Name>",
        "authorities": [
            "$XSMASTERAPPNAME.calm-api.<Required Scope 1>",
            "$XSMASTERAPPNAME.calm-api.<Required Scope 2>"
        ],
        "oauth2-configuration": {
            "credential-types": ["binding-secret"]
        }
    }
}
</code>

Replace //<Your Instance Name>// with your instance name (or the instance GUID when updating).  
Replace the scopes with the ones you need (see [[https://help.sap.com/docs/cloud-alm/apis/api-scopes|API Scopes]]).

**Step 3: Create a Service Binding (recommended) and get the credentials**
  - Next to the instance, choose **Actions** (⋯) → **Create Binding**.
  - Enter a name for the binding → **Create**.
  - Next to the new binding, choose **Actions** (⋯) → **View**.

**Alternative: Create a Service Key**
  - Next to the instance, choose **Actions** (⋯) → **Create Service Key**.
  - Enter a name → **Create**.
  - View or download the JSON.

**Result – Where to find the values in the JSON**

After viewing the **Service Binding** (or **Service Key**), you will see a JSON similar to this:

<code>
{
  "endpoints": {
    "Api": "https://eu15.alm.cloud.sap/api"
  },
  "uaa": {
    ...
    "clientid": "sb-...",
    "clientsecret": "...",
    "url": "https://<your-subaccount>.authentication.eu15.hana.ondemand.com",
    ...
  }
}
</code>


  - **URL** (Cloud ALM API base URL) = value of //endpoints.Api//  **Remove** the trailing **/api** at the end.  Example: https://eu15.alm.cloud.sap (without /api).
  - **ClientId** = value of **clientid** (inside the **uaa** section)
  - **ClientSecret** = value of **clientsecret** (inside the **uaa** section)
  - **Authentication server** (OAuth Token Endpoint) = value of **uaa.url**
    - **Do NOT** add ///oauth/token// at the end. Example: <code>https://<your-subaccount>.authentication.eu10.hana.ondemand.com</code>
  - **URL** (Cloud ALM API base URL) = value of **endpoints.Api**
    - **Remove** the trailing **/api** at the end. Example: <code>https://eu15.alm.cloud.sap</code>

=== Important ===
  * You only need **one service instance / binding** per Cloud ALM tenant.
  * Instance name restrictions: maximum 32 characters. Allowed characters: alphanumeric, periods (.), hyphens (-). Use underscores instead of spaces.
  * The **clientsecret** is only shown once when you create the binding/key. Save it securely.

==== Troubleshooting ====
  * If you cannot see the **SAP Cloud ALM API** service: make sure the **standard** plan entitlement has been added to the subaccount (Global Account → Entitlements → Edit).
  * Ensure your user has the **Global Account Administrator** role and is a member of the subaccount.
  * For scope-related issues or further support, create a case on component **SV-CLM-API**.

This procedure is based on the official SAP documentation: [[https://help.sap.com/docs/cloud-alm/apis/enabling-sap-cloud-alm-apis|Enabling SAP Cloud ALM APIs]].