Skip to main content

kommuns API

The kommuns API lets an external system work with an organization's data in kommuns: read the inventory, work orders and feedback, open and update work orders, complete them with their form answers, and get webhooks when something happens.

What people build with it​

ScenarioWhat the system does
ERP / maintenance planningCreates work orders from its own plans, reads their status and answers back, keeps its own numbers (external_id).
Building automation, SCADA, sensorsOpens feedback (or a work order) when an alarm fires.
Reporting (Power BI, Excel, a data warehouse)Reads work orders and answers page by page, then only what changed.
A service company's own softwareReads the work orders its customers assign to it, completes them with the answers.
Hotel or call-center softwareOpens feedback for a room or a device and follows it until it is resolved.

How access works​

  1. The plan. The API is a feature of the organization's kommuns plan, with a per-minute call limit and a number of integrations.
  2. An integration. An administrator of the organization creates an integration in Organization › Integrations. It gets a client id, a client secret (shown once) and its scopes — what it may do in the API.
  3. Permissions. The integration is an identity of the organization, like an employee: it is created with an organization permission definition and sees only the inventory it is given permissions on (Assign on a location, system or equipment). Its scopes narrow that further: what the API allows is scopes ∩ permissions.
  4. Tokens. Your system exchanges the client id and secret for an access token (OAuth 2 client credentials) and sends it with every call.

Everything the integration changes is recorded in the organization's Log Records under its name, e.g. "SAP connection (API)", and the people concerned get the usual notifications.

Addresses​

If your organization uses another kommuns installation, use its address.

Next: Getting started.