Configuring a connector
Admin, Connectors (/admin/connectors), gated by the connector.manage
permission.
The steps are identical for every connector. The vendor-specific part is getting the credentials, and that is on each connector’s own page.
From 0.14.2, the catalogue follows setup priority: identity and directory, device management and enrolment, student systems, then ticketing and supporting integrations. AV and room systems have their own section. Adding a new provider does not move it above the school’s core systems.
Sign-in providers
Section titled “Sign-in providers”The sign-in setup links above the catalogue offer Microsoft Entra ID, Google Workspace, custom OIDC and SAML, alongside LDAP/AD sign-in. They open the authentication settings or provider-specific setup instructions. Sign-in configuration is separate from directory connections: adding several Entra or Google instances does not configure several sign-in issuers. See Single sign-on for setup and limitations.
The steps
Section titled “The steps”- Find the connector under its category and click Add instance, or Reconfigure on the named instance you want to change.
- Name the instance and choose its coverage: the whole organisation or selected campuses. Coverage is independent of where the connection runs.
- Choose where it runs, if the connector reaches something inside your own network. See Runs on below. Most connectors talk to a vendor API over the internet and do not ask.
- Fill in the settings. Non-secret fields such as a URL sit in one section; credentials sit in another and are write-only once saved.
- Click Save & test. Plugboard saves the settings and immediately verifies the connection, reporting success with a latency, or the error the system returned.
On a managed deployment, a connector that reaches something inside your own network — Active Directory, Synergetic, PaperCut, Web Help Desk, printers over SNMP — is tested through your connector agent, not from the platform. Without an agent serving that connector’s site the test is refused, saying so, instead of attempting a connection the platform cannot make. A self-hosted install on the same network tests directly and needs none of this.
Runs on
Section titled “Runs on”Those same connectors show one extra setting, above everything else in the dialog:
| Choice | What it means |
|---|---|
| Plugboard itself | Plugboard makes the connection directly. Correct for a self-hosted install sitting on the same network as the system. This is the default. |
| The connector agent at site | The agent at that site makes the connection from inside your network. This is what a managed deployment needs. |
One entry appears per site that you have created, so a school with a junior and a senior campus on separate networks points each connector at the campus its system actually lives on.
Choosing an agent changes where the credentials go. The agent holds them itself, in its own secrets file on your server, and Plugboard does not take them — see Where the credentials live below. The credential fields disappear from the dialog when you choose a site, and are refused if something sends them anyway.
Changing this later is safe: reconfigure the connector and choose differently.
Seeing no sites in the list means either that none have been created, under
Admin, Campuses, or that your role does not include the site.manage permission. Ask
somebody whose does.
The dialog stays open on a failure, with your credentials still in it, so the wrong field can be corrected without retyping the rest. A drawn tick means saved and connected; a shake and a red edge means it is not. A failed connection test is reported as a failure, but the settings have been saved. Correct the settings and retry in the same dialog; this updates the saved instance.
During first-run setup a connector opens in place, so setting three of them up does not end the wizard three times.
Settings against secrets
Section titled “Settings against secrets”Every connector separates them.
Settings are things like a base URL, a tenant id, a mailbox address, a customer id. They are stored as ordinary configuration and shown back to you.
Secrets are tokens, passwords and private keys. They are encrypted with envelope encryption before they touch the database and never displayed again. The form shows them as set, and leaving a secret field blank when re-saving keeps the existing value.
That last behaviour matters: you can change a base URL without re-entering a token you no longer have a copy of.
Where the credentials live
Section titled “Where the credentials live”There is one exception to all of the above, and it is the important one.
A connector you have pointed at a connector agent does
not give its credentials to Plugboard at all. The agent is what connects to
your domain controller, your SQL Server or your print server, so the agent is
what holds the password — in its own secrets file, on your server, named by the
AGENT_SECRETS line in its agent.env, keyed by connector instance ID:
{ "<north-campus-ldap-instance-id>": { "bindPassword": "..." }, "<south-campus-ldap-instance-id>": { "bindPassword": "..." }}Replace the example keys with the instance id values returned by the authorised
GET /connectors/instances API (under the /api prefix). A provider key such as
ldap remains compatible only for the original default instance. Additional
instances require the 0.14.0 agent protocol and their own credential entries.
Plugboard never receives that file and never asks for it. The settings dialog does not offer the credential fields once a site is chosen, and the API refuses them if they arrive anyway — a domain bind password is not something a hosted service should hold a copy of when it has no use for one.
Everything else on this page — encryption, blank-means-unchanged, deletion — applies to connectors Plugboard runs itself, which is every cloud connector and every connector at all on a self-hosted install.
Demo mode
Section titled “Demo mode”Most connectors have a demoMode switch. With it on, the connector returns
realistic fictional data and makes no calls to the real system.
Use it to:
- See a feature work before the credentials arrive.
- Demonstrate the product without wiring up a school’s real systems.
- Set up training environments.
Then turn it off. A connector left in demo mode in production looks like it is working and is not, which costs more to find than one that fails outright.
The compliance page lists connectors still in demo mode, for this reason.
Testing
Section titled “Testing”Save and test runs the connector’s own health check. Each connector defines what “working” means for it, which is usually the cheapest authenticated call the vendor offers:
- Jamf authenticates and pings.
- Intune requests a Graph token.
- LDAP performs a bind.
- SMTP opens a connection and authenticates.
- Kandji lists one device.
The result includes latency. A test that succeeds in 3 seconds is telling you something about how the feature depending on it will feel.
More than one instance
Section titled “More than one instance”Starting with 0.14.0, a district can configure several Jamf instances, separate Entra directories or multiple Google Workspace connections inside one organisation. Each has its own name, settings, credentials and enabled state. For example, use District directory, North school Jamf and South school Jamf. Names and campus assignments do not change an instance’s identity.
Choose Whole organisation for a shared connection or Selected campuses for one or more schools. A campus administrator can manage an instance only when they administer every campus it covers. Coverage does not automatically assign imported people or devices to schools, and does not replace the organisation’s licensing or access boundaries.
The directory and person identity pane let you select the source explicitly. Campus-scoped account access also requires a district administrator to confirm the provider account against a local person. Device actions retain their recorded MDM source. SIS sync processes each enabled source separately and reports partial failures; matching external IDs in different sources do not merge people.
For new outbound email, SMS, external tickets and repair lodgements, choose an explicit default where offered. With campus context, a matching campus default precedes the organisation default. Conflicting defaults are refused. Workflows without a source picker refuse ambiguous connections, including when another configured source is disabled; disabling a source does not transfer its records.
Multiple sign-in issuers and SCIM tenancy are separate features. Adding another directory connector does not configure either. Existing provider live/demo boundaries still apply. See Directory accounts and 0.14.0 upgrade notes.
Disabling against deleting
Section titled “Disabling against deleting”Disabling an instance stops it being used but keeps the configuration and credentials. Use this to test what happens without a connector, or to pause an integration during a vendor outage.
Deleting removes the configuration and the encrypted secrets. The credentials are not recoverable afterwards.
For a connector run by an agent there are no stored credentials to remove; deleting it stops the work being queued, and the entry in the agent’s own secrets file stays until you remove it there.
What connecting something changes
Section titled “What connecting something changes”Connectors light up features elsewhere. Configuring one is usually the answer to “why is this screen empty”.
| Connect | And you get |
|---|---|
| An MDM | Live device details, MDM actions on the device page, serial autocomplete, loan pools pulled from smart groups |
| An SIS | People, year levels, tutor groups, card numbers, term dates |
| A directory | People, and directory account management |
| Every notification, tracking link, receipt, alert and scheduled report | |
| SMS | Text notifications |
| A ticketing system | External ticket sync from submissions |
| Warranty | Coverage lookup on a device, feeding the coverage on a repair |
| A repair vendor | Vendor repairs booked out from a submission |
| Printers | The printer fleet page |
| PaperCut | Balances and card writing |
| ThreatLocker | The security approvals queue |
| Ollama | A smarter assistant |
When the test fails
Section titled “When the test fails”Work through these in order. They cover most of it.
| Check | How |
|---|---|
| Is the URL right, including scheme and no trailing slash | Paste it into a browser |
| Is the credential the value rather than the id | The single most common mistake with Entra client secrets |
| Has the credential expired | Most vendors expire tokens. Some do it silently |
| Does the account have the permission the connector needs | Each connector page lists the minimum |
| Can the server reach it at all | curl from the server, not from your laptop |
| Is it a private address | A managed deployment needs an agent and the connector set to run on that site; a self-hosted one may need ALLOW_PRIVATE_EGRESS=1 |
| Is the credential in the right place | For an agent-run connector it belongs in the agent’s secrets file, not in Plugboard. A healthy agent with the wrong file in it fails as an authentication error from the far end |
| Is a proxy or firewall in the way | Outbound filtering on school networks is common and usually silent |
The error message on the test result is the vendor’s own, not ours. It is usually literal.
Auditing
Section titled “Auditing”Configuring, reconfiguring, enabling, disabling and deleting a connector are all written to the audit log, with who did it and when. Secret values are never written to the log.