Build your own integration
A custom integration is a PowerShell script that connects Overseer to a tool it has no built-in integration for. This page explains what one can supply, how it is put together and how you know it is working.
What a custom integration is
Overseer has integrations for the usual kinds of tool an MSP runs: a remote management tool, a PSA, security software, an identity provider. When you run something Overseer has no integration for, you can write one.
A custom integration is a PowerShell script that you write in the Script Editor. It is kept in Overseer and usually does its work by calling the other tool's API. Once it exists, it behaves like any other integration: it has settings, it is checked for health, and deployments can use it.
There are two directions a connection can run in, and this page is about the first.
- Overseer reaching out. A custom integration asks another tool for its clients, its computers or its tokens.
- Another system reaching in. An outside system asks Overseer to start a maintenance session, install software or hand back information. That is done through Overseer's API and is covered in the API documentation.
What an integration can supply
An integration is built from capabilities. Each capability is one kind of thing the integration can do, and you add only the ones the other tool supports.
| Capability | What Overseer does with it |
|---|---|
| A list of clients | Lets you match each client in the other tool to a tenant. |
| A list of computers | Shows the computers, or agents, the other tool knows about for the clients you have matched. |
| A way to recognise the tool's agent | Identifies that tool's agent on a computer. |
| An installation token for a client | Hands the right token to the script that installs the tool's agent. |
| An uninstallation token for a client | Hands the right token to the script that removes it. |
| A handler for incoming web requests | Lets the other tool call your integration, and lets your script decide how to answer. |
When you add a capability, Overseer adds the matching part of the screen for you. An integration that supplies a list of clients gets a place to map those clients, with no extra work from you.
An integration can also act on the other tool, for example by switching that tool's maintenance or learning mode on and off.
How an integration is written
Every integration has two required parts. Capabilities are added on top of them.
- A start-up part. This runs when the integration is created or updated. It checks the settings, makes the connection and reports whether that succeeded.
- A health check. This runs periodically and reports whether the integration is still working.
Settings
Most integrations need a few values before they can connect, such as the address of a service and an API key. Your script declares the values it needs, and Overseer builds the settings form from that declaration. You do not design a form. A value you declare as secret is stored securely.
The private store
Each integration has a private store that lasts between its parts. The start-up part puts the connection details there, and the health check and the capabilities read them back. Only the integration's own script can reach the store. It cannot be read from outside the integration, even while a script is being debugged.
Shared code
A larger integration is easier to maintain when the calls to the other tool sit in a PowerShell module of their own, which the integration then uses. Give each function a name that says which tool it talks to and what it does.
How deployments use an integration
Because the private store is closed, an install script never sees an API key. It asks Overseer for the one thing it needs, such as an installation token, and Overseer fetches it from the integration. Setting that up follows a sequence.
- 1Write the integration, with the token capability, and map its clients to your tenants.
- 2Add the other tool's agent to the Library as software.
- 3Link that software to your kind of integration.
- 4Create a deployment for the software and choose which integration it uses.
- 5In the install script, ask for the installation token.
When the script runs, Overseer works out which integration the deployment uses, finds the computer's client in the mapping, asks the integration for that client's token and passes it to the script. The script supplies no details of its own.
Testing and health checks
Build an integration in small steps and prove each one.
- Start small. Write the start-up part, the health check and one capability. Get those working before you add more.
- Test with real data. Run the integration against the real tool. Check that the clients and computers it returns are the ones you expect.
- Add one capability at a time. A fault is then easy to place.
- Make the health check mean something. Have it confirm that the other tool still answers. A check that reports healthy without looking tells you nothing.