Using the Bpanda API

Bpanda's REST interface for integrations: which license and which API client (a technical user with a Client ID and Client Secret) you need, how to obtain a token — and which information from your CMDB, ERP, GRC or project tools you can link to your processes.

Through the Public API, your IT creates information from other systems as architecture elements in Bpanda and links it to processes. It also reads process information, organizational structure, users and groups. Each operation has its own page in the API Reference — with parameters, response format, code examples and a Try it section. This article explains what to do beforehand, how authentication works and what the API is useful for.

Prerequisites

• API license. Your account needs the license for the API. It is activated by the Customer Success team: wecare@mid.de.
• API client. You create it yourself in the Account Management: in the Account Users section via ⋮ Add New API User, see Managing Account Users. It consists of a Client ID and a Client Secret and acts in Bpanda as a technical user — the API user. You only see the secret when creating the client — keep it as safe as a password.
• A Bpanda license for the API user. In addition to the API license, the API user is assigned a regular Bpanda license in the Account Management, just like any other user. This gives the API user read access to the Process Space.
• A Bpanda role, if the API user needs to do more. Only BPM Managers and Designers may create, import and publish architecture elements. The role an operation requires is listed on its page in the reference under Security. You assign the role as you would for any other user, see Assigning Users and Bpanda Roles and Defining Designers and BPM Managers.
• Account ID. It appears in the path of the Account Management as soon as you have opened your account.

How to Authenticate

Authentication is a single call without a prior token: apiUserInfo. You pass the Account ID, Client ID and Client Secret and receive everything the subsequent calls need. The base address of your environment is shown in every code example in the reference.

curl -X POST https://<api-adresse>/bpm/api/v1/apiUserInfo -H "Content-Type: application/json" -d "{\"accountId\":\"<Account-ID>\",\"clientId\":\"<Client-ID>\",\"clientSecret\":\"<Client-Secret>\"}"

$body = @{ accountId = "<Account-ID>"; clientId = "<Client-ID>"; clientSecret = "<Client-Secret>" } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "https://<api-adresse>/bpm/api/v1/apiUserInfo" -ContentType "application/json" -Body $body

The response contains five fields:

A first call that reads all users of the Process Space looks like this:

curl https://<api-adresse>/bpm/api/v1/warehouses/<processSpaceId>/users -H "Authorization: Bearer <token>" -H "BpmLicense: <licenseToken>"

Invoke-RestMethod -Uri "https://<api-adresse>/bpm/api/v1/warehouses/<processSpaceId>/users" -Headers @{ Authorization = "Bearer <token>"; BpmLicense = "<licenseToken>" }

If authentication responds with 404 “No license token found”, the account lacks the API license. With 429 you have made too many calls in a short time — wait briefly and repeat the call. If the access token expires, simply call the authentication again — there is no separate refresh mechanism.

Linking Information from Other Systems to Processes

The API is most valuable when you link information from other systems to your processes. You then see, for example, which applications a process uses, which requirements it implements or which project changes it. You create this information in Bpanda as architecture elements: Bpanda knows the element types of all layers of ArchiMate® 3.2, and each element can be linked to processes. You evaluate the links in Bpanda afterwards, see Available Reports.

The following overview is organized by tool category. For each category, it shows what the system holds, which element types in Bpanda this data corresponds to, and which questions you can answer once you link it to processes.

You define which element types are active in your Process Space under Defining Architecture Settings; Linked Architecture Elements and Relationship Types explains what each relationship stands for.

Embedding Processes in the Architecture

For every process revision, the architecture automatically contains a Business Process element. This is how you embed a process in the architecture: you create a relationship between your element from the external system and this Business Process element.

1. Create or update the element: createArchitectureElement, editArchitectureElement. You transfer an entire inventory with importArchimateXml.
2. Retrieve the Business Process element for the process revision: getArchitectureElementsByRepresentation.
3. Query which relationship types are permitted between the two elements: findValidReferenceTypesWithDirections. Only what ArchiMate® allows between the two types is offered.
4. Create the relationship: addArchitectureElementRelation. If it already exists, the API returns the existing one instead of creating a second.
5. Publish the elements: publishArchitectureElements. Until then they are drafts, just as when created in the user interface.

You can read the result back with findExternalUses: all relationships of an element or a process revision, for example every process that uses a particular application.

Note: The procedure above links elements from other systems to a process. The reverse also works: if you create an element of type Business Process, a process is implicitly created in Bpanda — without a diagram and without content. You cannot publish this process via the API, because the API does not currently cover the release workflow. A process is released and published as usual in Bpanda, see Releasing and Publishing Processes.

Bpanda as a Source for Other Tools

In the opposite direction, the API reads whatever other tools need to know about your processes: process information, versions, the diagram as SVG, the organizational structure, users and groups, and the architecture reports. This lets you embed diagrams in your intranet, show in a portal which applications a process uses, or determine responsible persons automatically.

Context

The reference under API describes every operation in full and is generated from the API description — so it always reflects the current state of the system. How architecture elements and their relationships work in Bpanda is described in the Architecture section; who may do what in Bpanda is described in Roles and Authorizations.