Setup Guide

Deployment

Prerequisites

• SAP BTP subaccount with Cloud Foundry environment
• CF CLI with the MultiApps plugin: cf install-plugin multiapps
• The following managed BTP services provisioned in your CF space:

Deploy app package

Use the deployment package provided by ASAPIO and deploy it to your target Cloud Foundry space.

Terminal

# Deploy the provided MTA archive to Cloud Foundry
cf deploy <path-to-your-package>/asapio-spendlens_<version>.mtar

The deploy command creates or updates three CF applications (asapio-spendlens-approuter, asapio-spendlens-srv, asapio-spendlens-db-deployer) and binds them to the services above.

By default, CF generates the module routes automatically. This is the recommended setup for customer deployments because it avoids host-collision and route-mapping drift across spaces/subaccounts. After deployment, get the active app URL via:

cf apps

Generated-route-only is the default and recommended mode. Do not rely on manually mapped fixed alias routes for productive deployments.

First-run checklist

After deployment:

• In BTP Cockpit: assign the SpendLens Admin role collection to at least one user (see Roles and Access below)
• Log in to the app and open Settings (only visible to users with the Admin role)
• Select the S/4HANA BTP destination and click Test Connection
• Set Auth Mode to match your destination type (see Connecting to S/4HANA)
• In User Settings, configure org-unit labels if needed
• Grant the SpendLens User role collection to all other users who need access

After assigning or changing a role collection in BTP Cockpit, users must log out and log back in for the new token (with updated scopes) to take effect. Use the Log out button in the app header.

Roles and access

Spend Lens uses SAP BTP XSUAA for all authentication. There are no local user accounts.

Role collections

Connection settings (which S/4HANA system to connect to, which destination to use) are global and admin-only. A change by one admin takes effect for all users immediately.

Assigning a role in BTP Cockpit

1. Open BTP Cockpit and navigate to your subaccount.
2. Go to Security → Role Collections.
3. Open SpendLens Admin (or SpendLens User).
4. Click Edit, then Users → Add User.
5. Enter the user's email address and select the identity provider the user actually logs in with (see below).
6. Save. The role takes effect on the user's next login (the user must log out and back in).

Assign SpendLens Admin only to users responsible for system configuration. All other users should receive SpendLens User.

Which identity provider?

Role-collection assignments are scoped per identity provider. A role takes effect only when it is assigned under the same identity provider the user signs in with — assigning it under a different one is the most common cause of a "403 — lacking required roles" error even though the role looks assigned.

Which identity provider to choose depends on your subaccount's trust configuration:

• If your subaccount has no custom identity provider, users authenticate via the Default identity provider (SAP Cloud Identity / SAP ID service) — assign roles there.
• If your organisation uses its own SAP Cloud Identity Services (IAS) tenant (optionally federated to a corporate IdP such as Microsoft Entra ID or Okta), users authenticate through that tenant's business-user trust — assign roles there, not under "Default".

To see your subaccount's identity providers, open BTP Cockpit → Security → Trust Configuration (each entry shows its Purpose — pick the one for Business users, not Platform users). The same list is available from the SAP BTP CLI with btp list security/trust.

Troubleshooting "403 — lacking required roles". If a user gets this after the role is assigned: (1) confirm the assignment is under the business-user identity provider the user actually logs in with — not "Platform users" and not a different IdP; (2) have the user log out and log back in (a fresh, e.g. incognito, session) so a new token with the role is issued.

Connecting to S/4HANA

Spend Lens reads from three standard SAP OData APIs — API_PURCHASEORDER_2 (OData v4, purchase orders), API_SUPPLIERINVOICE_PROCESS_SRV (OData V2, supplier invoices), and API_BUSINESS_PARTNER (OData V2, supplier master data). No S/4HANA add-on or custom development is required. The APIs are available on SAP S/4HANA 2022+ (on-premise / private cloud) and S/4HANA Cloud Public Edition, and all three share the same BTP destination.

The connection is configured by an admin in Settings → Connection Settings: select the BTP destination, choose an auth mode, and click Test Connection. Follow the section below that matches your S/4HANA deployment.

S/4HANA On-Premise / Private Cloud

BTP destination

BasicAuthentication: a shared SAP technical user. All Spend Lens users access S/4HANA under the same SAP identity. Simple to set up; set Auth Mode to Technical user in Spend Lens.

PrincipalPropagation: the logged-in BTP user's identity is forwarded to S/4HANA via the Cloud Connector trust configuration. Requires a system trust between BTP and S/4HANA. When the selected destination uses Principal Propagation, Spend Lens shows the Auth Mode as Principal Propagation (read-only) and stores no credentials.

Per-user Basic Auth (auth mode in Spend Lens): only relevant for on-premise BasicAuthentication destinations where Principal Propagation is not configured. Each user signs in with their own SAP credentials. Two storage options: session-only (A) or AES-256-GCM encrypted server-side (B, "Remember me").

Required authorizations

The SAP identity used (technical or propagated user) needs read access to the three APIs. Field-value restrictions (e.g. limiting EKORG to specific purchasing organisations) are respected — Spend Lens shows only data the SAP user is authorized to read.

API_PURCHASEORDER_2

API_SUPPLIERINVOICE_PROCESS_SRV

API_BUSINESS_PARTNER (Supplier Profiles — optional)

Powers the supplier fact sheet (master data, addresses, contacts) on the Suppliers page. Optional: if unavailable, the rest of the Suppliers page still works — only the fact-sheet panel stays empty.

S/4HANA Cloud Public Edition

BTP destination

OAuth2ClientCredentials: a shared service account. All Spend Lens users access S/4HANA under the same service identity. Set Auth Mode to Technical user in Spend Lens.

OAuth2SAMLBearerAssertion: the BTP user's identity is asserted to S/4HANA via a SAML bearer token exchange. Requires a communication arrangement in S/4HANA that trusts your BTP subaccount as an identity provider. Set Auth Mode to Technical user in Spend Lens (the Cloud SDK performs the SAML assertion exchange automatically).

Basic Auth is not used with S/4HANA Cloud Public Edition.

Communication scenarios

Create a Communication Arrangement for each scenario below (Communication Management → Communication Arrangements). All three can be assigned to the same inbound communication user and the same communication system.

No separate BTP destination is needed per API — the existing purchase-order destination is reused for all three. API_BUSINESS_PARTNER / SAP_COM_0009 is optional (only the supplier fact sheet uses it).

Features

All analytics are read-only. Spend Lens does not write any procurement data back to S/4HANA.

Currency conversion

Procurement documents often span several currencies. By default Spend Lens keeps each amount in its document currency and flags any mixed total; optionally you can enable Global Display Currency to report everything in one currency. Both behaviours are described below. Configure currency on the Settings → Currency tab (admin only).

Default: native currency with a mixed-currency safeguard

When Global Display Currency is off, each KPI tile shows the dominant currency and its share of the result set (e.g. "EUR 62%"). If the dominant currency covers less than 80% of the total, the tile shows "Mixed (top: EUR 62%)" to flag that the number bundles more than one currency and should not be read as a single-currency total. Table amounts are shown as plain numbers (e.g. 1.2M) with a separate CCY column for the document currency code — no currency symbol is embedded in the amount cell, so a USD figure can never be mislabelled with a € sign.

Global Display Currency

Enable Global Display Currency to report all amounts in a single currency, so the Dashboard, charts, Top Suppliers, Purchase Orders, and Invoices all show one currency with no "Mixed" warning.

Exchange rates from the ECB. Rates for the 29 ECB reference currencies (USD, GBP, CHF, JPY, SEK, DKK, NOK, PLN, CZK, HUF, RON, ISK, TRY, AUD, CAD, CNY, HKD, INR, MXN, ZAR, and more) are fetched from the ECB Data Portal, with EUR as the base.

Setup is two steps:

1. Click "Pull from ECB" to fetch live rates for the 29 ECB reference currencies.
2. Turn on the toggle and choose the display currency. The display-currency dropdown only lists currencies that have a stored rate, so you can never select a currency the app cannot convert to.

Rates must exist for every document currency in your data; rows in a currency with no rate are excluded from converted totals and a "missing rates" banner appears on the Dashboard.

Custom currencies & manual rates. The Exchange Rates table's Add / Update row has a currency-code field — type any code (up to 5 characters) and its rate (1 EUR = X). Codes the ECB does not publish show a warning that "Pull from ECB" will not refresh them, so you maintain their rate manually. Edit any existing rate inline and click Save, or remove one with the ✕ button. "Pull from ECB" refreshes every ECB-covered currency already in the table and leaves manual ones untouched.

Applying a change

After enabling Global Currency or switching the display currency, a banner offers a Sync Now button — no need to leave Settings. Totals are correct immediately, including for data synced before the feature was switched on.

Reading the tables. With Global Currency on, tables add a Converted column in the display currency alongside the document-currency amount and its CCY code, so you always see both the original and the converted figure.

Data caching

Spend Lens does not query S/4HANA on every interaction. It reads the relevant procurement documents from the standard OData APIs, caches them, and serves the dashboard from that cache. This limits how often Spend Lens calls your S/4HANA system. All metrics are derived from the cached source documents, so they match what you would compute directly in S/4HANA. Spend Lens is read-only and never writes back.

Refresh and time-to-live

Cached data is refreshed automatically after a time-to-live (TTL) expires, and on demand whenever you press Refresh. Purchase Orders and Supplier Invoices share a single lookback window so combined views and the spend trend never mix mismatched time spans. Both the TTL and the lookback window are configurable per deployment:

The lookback window vs. your date filter. The cache holds documents inside the lookback window (e.g. the last 25 months). The date filter on the dashboard narrows what you see within the cached data — it is applied to the cache and makes no S/4HANA call. If you set the filter to reach earlier than the cache covers, the older documents are not loaded yet and the dashboard shows an information banner inviting you to Refresh, which re-pulls from S/4HANA back to your filter's start date. Setting a date within the window never shrinks the cache.

When Global Display Currency is enabled, amounts are converted to your chosen currency for every KPI, chart, and table — see Currency conversion.