> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SAP LeanIX

> Connect Serval to SAP LeanIX so workflows can read and update the enterprise architecture inventory — fact sheets, relations, the meta model, and GraphQL.

## About SAP LeanIX

SAP LeanIX is an enterprise architecture management platform. Its inventory of
**fact sheets** — applications, IT components, business capabilities, providers,
projects and their relations — is often the system of record for what software
an organization runs and who owns it.

The Serval SAP LeanIX integration connects to your workspace through the
**Pathfinder** API. Workflows can read and update fact sheets, traverse
relations, inspect the workspace data model, and run arbitrary GraphQL queries.
The integration is marked **Beta** in Serval's connect UI.

**Authentication:** OAuth 2.0 client credentials. Serval exchanges your API token
for a short-lived bearer token at
`https://{instance}.leanix.net/services/mtm/v1/oauth2/token` and attaches it to
API requests at `https://{instance}.leanix.net/services/pathfinder/v1`.

**Data sync:** On demand only. There is no background inventory sync.

## What the SAP LeanIX integration enables

| Capability                 | Description                                                                                                                                                                               |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SAP LeanIX API request     | Typed access to the full Pathfinder v1 surface — fact sheets, relations, bookmarks, exports, the meta model, and workspace settings.                                                      |
| SAP LeanIX GraphQL request | Runs GraphQL queries and mutations, the only LeanIX surface that filters, sorts and pages fact sheets on arbitrary fields. GraphQL-level errors are raised rather than silently returned. |
| Pathfinder API discovery   | The full Pathfinder endpoint catalog is indexed for workflow authoring.                                                                                                                   |

<Note>
  LeanIX answers a failed GraphQL operation with HTTP 200 and an `errors` array.
  The GraphQL action raises those as errors so a broken query fails the workflow
  step instead of returning an empty result.
</Note>

## Get your credentials

You need your **instance host**, your **workspace name**, and an **API token**
for a technical user in that workspace.

<Steps>
  <Step title="Note your instance host and workspace">
    Sign in to LeanIX and read both out of the browser URL. In
    `https://us-2.leanix.net/acme/dashboard` the host is `us-2.leanix.net` and
    the workspace is `acme`. The host is region-specific (`us-2`, `eu-1`, `app`,
    `demo-eu-1`, …) and determines both the API endpoint and the token endpoint.
  </Step>

  <Step title="Create a technical user">
    Go to **Administration → Technical Users** and create a technical user for
    Serval, scoped to the workspace you want to connect.
  </Step>

  <Step title="Choose its permission role">
    Grant at least **MEMBER** to read fact sheets. Writing fact sheets needs a
    role with write permission; reading the meta model and workspace settings
    needs **ADMIN**.
  </Step>

  <Step title="Copy the API token">
    Copy the generated API token. LeanIX shows it once — store it before closing
    the dialog.
  </Step>
</Steps>

<Warning>
  An API token inherits its technical user's permission role for the whole
  workspace. Give the Serval technical user the lowest role that covers your
  workflows, and use a separate technical user per environment rather than sharing
  one token.
</Warning>

## Connect in Serval

<Steps>
  <Step title="Open the SAP LeanIX connect form">
    In Serval, add the SAP LeanIX integration. It is labeled **Beta**.
  </Step>

  <Step title="Instance host (required)">
    Enter the host, such as `us-2.leanix.net`. Pasting the full workspace URL is
    fine — the scheme and path are stripped.
  </Step>

  <Step title="Workspace (required)">
    Enter the workspace name, such as `acme`. Several workspaces can share one
    regional host, so this is what identifies the workspace this connection
    points at.
  </Step>

  <Step title="API token (required)">
    Paste the technical user's API token in the password field.
  </Step>

  <Step title="Save and verify">
    Submit the form. Serval runs four health checks (below).
  </Step>
</Steps>

<Note>
  When editing an existing connection, a blank or obfuscated API token keeps the
  stored value. Paste a new token to rotate credentials without re-entering the
  instance host.
</Note>

## Verifying the connection

Four health checks run after you connect:

1. **Test SAP LeanIX Connection** — exchanges the API token and reads the
   workspace data model. Success reports how many fact sheet types the workspace
   defines.
2. **List SAP LeanIX Fact Sheets** — reads one fact sheet and reports the
   workspace total. Confirms inventory read access.
3. **Run SAP LeanIX GraphQL Query** — runs `{ allFactSheets(first: 1) { totalCount } }`.
   Confirms the GraphQL endpoint accepts queries from this integration.
4. **Read SAP LeanIX Workspace Settings** — confirms the elevated permissions
   that workspace-level reads require.

<Tip>
  If the first three checks pass but workspace settings fails, the technical user
  authenticates and can read the inventory but is below **ADMIN**. That is a valid
  setup for read-only inventory workflows.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="One token, one workspace">
    LeanIX API tokens are scoped to a single workspace. To reach several
    workspaces, connect SAP LeanIX once per workspace — each connection carries
    its own host, workspace and token. Two connections on the same host must
    name different workspaces; Serval identifies a connection by host and
    workspace together.
  </Accordion>

  <Accordion title="The instance host is region-specific">
    A token issued on `eu-1.leanix.net` will not authenticate against
    `us-2.leanix.net`. A 401 immediately after connecting usually means the host
    and the token belong to different regions.
  </Accordion>

  <Accordion title="Prefer GraphQL for anything but a straight lookup">
    `GET /factSheets` only narrows by fact sheet type. Filtering by name, tag,
    subscription, lifecycle or any custom field — and sorting or paging on
    them — is only available through GraphQL.
  </Accordion>

  <Accordion title="Fact sheet writes are governed by the meta model">
    Creating or updating a fact sheet must satisfy the workspace's data model,
    including required fields and permitted relation types. LeanIX rejects
    violations with HTTP 422 and a validation payload rather than partially
    applying the change.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your SAP LeanIX integration.