Integrations

An integration is one of your own systems (a lab interface, a records sync, a reporting job) calling the Nightingale API directly. It proves who it is with a token, a long secret your system sends with every request. Each integration holds one or more roles, which bound everything it may do.

The Integrations screen lists your organization’s integrations and is where you create, change, suspend and remove them and their tokens.

Integrations need the Integrations add-on on your organization’s licence (see Plans and add-ons). Without it the screen only says so, and the API refuses integration requests. Contact support to add it.

Grant the permissions first

Viewing and managing integrations each need their own permission. New organizations have both in the Administrator role, but organizations created before these permissions existed do not: someone who manages roles must add them (see Roles) before anyone can open the screen. Nightingale support can see your integrations but cannot change them.

How an integration acts

Your system sends these headers with each request:

Header	Value
Authorization	Bearer followed by the token
X-Client-Type	integration
X-On-Behalf-Of	optional: the ID of a staff member it acts for

Acting as itself. Without X-On-Behalf-Of, the integration acts as itself and may do everything its roles allow. What it creates is recorded under the integration’s name. Use this for work no person is behind, such as a nightly records sync.

Acting for a staff member. With X-On-Behalf-Of, it acts for that person, who must hold at least one of the integration’s roles. It then may do only what the roles both hold allow. For example, an integration holding the Doctor role, acting for someone who is both a Doctor and an Administrator, may do what a Doctor may and nothing an Administrator may. What it creates is recorded under that person. Prescriptions, completed laboratory and imaging orders and signed visit documentation also record which integration submitted them.

A request naming someone who holds none of the integration’s roles, or who is not on its list (see below), is refused.

Everything an integration does is recorded in the audit log with the integration it came from.

The list

Each integration shows its name and description, whether it is Active or Suspended, its request limit, its roles, whom it may act for, and its tokens with their expiry.

Creating an integration

Choose New integration and give it:

• a Name you will recognise, such as “Lab interface”. It also shows on the records the integration creates;
• an optional Description;
• its Roles: at least one. Choose the fewest it needs;
• an optional expiry for its first token. Leave it blank for a token that does not expire.

The token is shown once

After the integration is created, its token is shown with a copy button. Copy it into your system straight away. It is never shown again, and no one, including support, can retrieve it later. If it is lost, create a new token and delete the old one.

Changing an integration

On an integration’s card:

• Roles replaces its roles. It always keeps at least one. A role an integration holds cannot be deleted from the Roles screen.
• Staff it may act for narrows whom it may act for (see below).
• The pencil renames it or changes its description.

Changes apply to the integration’s next request.

Who it may act for

• Anyone holding one of its roles: the default.
• Only the staff selected below: limit it to the people you tick. They must still hold one of its roles.

Only active staff can be ticked: if someone on the list has since been deactivated, the dialog says so and removes them when you save.

Tokens

New token issues another token, for example to rotate one without downtime: create the new token, switch your system to it, then delete the old one with the bin icon next to it. Deleting a token stops it at once; the integration’s other tokens keep working. An integration with no tokens left stays, but cannot call the API until it is given a new one.

Suspending and removing

• The pause button suspends the integration: every one of its tokens stops working, and its callback subscriptions are not delivered to. The play button resumes it.
• The bin icon next to the integration deletes it. Its tokens stop working at once and its callback subscriptions are removed. Records it created keep showing its name. This cannot be undone, but the name can be used again.

Request limit

Each integration may make up to 600 requests a minute. Requests beyond that are refused for the rest of the minute, with the time to wait. For bulk synchronization, support can raise an integration’s limit to 6000.

Who sees what

Viewing the screen needs the permission to view integrations. Creating, changing, suspending and deleting integrations and their tokens needs the permission to manage integrations, which also lets you see your organization’s staff and roles.

Managing integrations is powerful

Someone who manages integrations can give an integration any role, Administrator included. Grant that permission only to people you would trust with administrator access. An integration holding the permission to manage integrations may itself manage integrations.

Nightingale support can see your integrations and set their request limit, but does not change anything else.