# Step-by-step deployment guide

### 1. Which data is imported from SAP BTP?

The following SAP BTP entities are imported:

* **Shadow Users**: user accounts in SAP BTP (Global Account and Subaccounts)
* **Role Collections**: named bundles of roles assigned to users
* **Roles**: individual role tied to a specific application

The diagram below shows the relationships between them:

```mermaid
graph TD

%% Entities
ShadowUser[Shadow User]
RoleCollection[Role Collection]
Role[Role]

%% Relationships
ShadowUser --> RoleCollection
RoleCollection --> Role
```

#### Shadow User attributes

| Attribute             | Description                                           |
| --------------------- | ----------------------------------------------------- |
| `external_id`         | External identifier from the identity provider        |
| `username`            | SAP BTP username                                      |
| `email`               | Primary email address                                 |
| `firstname`           | Given name                                            |
| `lastname`            | Family name                                           |
| `active`              | Whether the user account is active                    |
| `origin`              | Identity provider origin (e.g. `sap.default`, `ldap`) |
| `lastlogin`           | Timestamp of the user's last login                    |
| `passwordlastchanged` | Timestamp of the last password change                 |
| `account_type`        | Either `globalaccount` or `subaccount`                |
| `account_name`        | Name of the account the user belongs to               |

#### Role Collection attributes

| Attribute      | Description                            |
| -------------- | -------------------------------------- |
| `description`  | Description of the role collection     |
| `account_type` | Either `globalaccount` or `subaccount` |

#### Role attributes

| Attribute            | Description                           |
| -------------------- | ------------------------------------- |
| `application_id`     | The application this role belongs to  |
| `role_template_name` | The role template it was created from |
| `role_name`          | Display name of the role              |
| `description`        | Description of the role               |

### 2. Credentials needed to connect SAP BTP

The integration connect to two different APIs:

* [SCIM API: Users & Groups](https://api.sap.com/api/PlatformAPI/resource/SCIM_groups_role_collections) Also known as Shadow Users and Role Collections in BTP. We use this API to get Shadow Users & Role Collections on both Global Account as well as Subaccount level.
* [Authorization API: Role collections, role templates and roles](https://api.sap.com/api/AuthorizationAPI/resource/Applications) We use this API to get more detailed information on the Roles linked to the Role Collections.

As stated in the documentation for both APIs, they require authentication via the `OAuth 2.0 Client Credentials` flow.

### 3. Prepare the credentials JSON

The connector expects a single file in the following JSON format:

```json
{
  "globalAccountName": "My Global Account",
  "globalAccountClientId": "...",
  "globalAccountClientSecret": "...",
  "globalAccountTokenUrl": "e.g.: https://<subdomain>.authentication.<region>.hana.ondemand.com/oauth/token",
  "globalAccountApiUrl": "e.g: https://<subdomain>.accounts.ondemand.com",
  "subAccounts": [
    {
      "subAccountName": "Production",
      "subAccountClientId": "...",
      "subAccountClientSecret": "...",
      "subAccountTokenUrl": "https://<prod-subdomain>.authentication.<region>.hana.ondemand.com/oauth/token",
      "subAccountApiUrl": "https://<prod-subdomain>.accounts.ondemand.com"
    }
  ]
}
```

### 4. Configure the source in Elimity Insights

1. Go to **Sources** in the left navigation bar and click **Add Source**.
2. Search for **Custom** and click **Set Up**.
3. Click **Set Up** again and give the source a name (e.g. `SAP BTP`).
4. Select **Upload export file**, click **Continue** and upload the data model file: `sap-btp-data-model.json`.

{% file src="/files/FT9iSBMMrFKZX0NswIpN" %}

5. Open the **Config** tab and click **Edit**.
6. Set **Enable automatic imports via custom gateway** to `true` and fill in the Gateway URL: `https://sap-btp-gateway-1027270379075.europe-west1.run.app`
7. Click **Add configuration value** and add the entry below.

| Key           | Type          | Where to find it          |
| ------------- | ------------- | ------------------------- |
| `credentials` | `Secret File` | The JSON file from step 3 |

Click **Save and run** to launch your first import. Monitor progress in the **Logs** tab; the **Imports** tab shows the summary for each run.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.elimity.com/sap-btp/step-by-step-deployment-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.