Configuring a connector
Settings, 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.
The Connectors page
Section titled “The Connectors page”Three tabs:
| Tab | Holds |
|---|---|
| Connections | Connected, the connections you have, and Add a service, every service you can connect |
| Sign-in providers | Links to set up sign-in with Microsoft Entra ID, Google Workspace, custom OpenID Connect or another SAML 2.0 provider |
| Device management | The fleet settings of your connected MDM |
Add connector, at the top of the page, takes you to Add a service and puts the cursor in its search.
Connected
Section titled “Connected”A bar across the top counts connections by state: needing attention, passed a check today, not checked in 24 hours, unavailable. Below it, search by name, service or campus, filter by State (Needs attention, Connected, Disabled, Not checked) and Group by family. Each row shows the connection’s name, its service and family, Status and Last check.
Each row has one button for what its state calls for, and the rest in its menu:
| Row button | When |
|---|---|
| Fix | The connection is on, and its last check failed or its credentials need sealing |
| Test | The connection is on and working |
| Review & enable | The connection is saved but off |
| Open | A Microsoft 365 or Google Workspace connection, which holds several features |
| Run as | The connector can act as a technician as well as Plugboard. See Run as |
The row menu adds Reconfigure, Test, Add instance, Provider details, Disable, Copy connection ID and Remove, plus Match people on an enabled student system and Collect Wonde token on a Wonde connection. Right-click a row for the same menu.
Connector agents at the top right opens the agents page, with a count beside it when some are not reporting. Read operational data at the foot reads what some connectors hold, such as monitoring checks, on demand.
Add a service
Section titled “Add a service”Services are grouped by family, in setup priority: identity and directory, device management and enrolment, student information, then ticketing and the supporting integrations. AV and room systems have their own family. A chip marked Connected already has a connection. Search by name or by what it does.
The connector guide
Section titled “The connector guide”Settings, Connectors, Guide (/admin/connectors/guide) is what each
connector can do and the access it needs, from the same reference as the
capability reference. Capability reference
links on the page open it, and /help/connectors opens it too.
Sign-in providers
Section titled “Sign-in providers”The Sign-in providers tab offers Microsoft Entra ID, Google Workspace, Custom OpenID Connect (OIDC) and Other SAML 2.0 provider. They open Sign-in & SSO. Sign-in configuration is separate from directory connections: adding several Entra or Google connections does not configure several sign-in issuers.
The steps
Section titled “The steps”- Choose the service under Add a service. Its page lists what it needs before any credentials (Before you continue), its supported scope and limits, and every setup field. Continue to setup opens setup; nothing is saved or turned on until you finish.
- Choose where this connection works: an Instance name, and Coverage, the whole school or selected campuses. Coverage is independent of where the connection runs. Where offered, tick Use by default for new outbound work for sending email or SMS, raising external tickets or lodging repairs. Continue to access.
- 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 connection details. Non-secret fields such as a URL sit in one section; credentials sit under Secure credentials and are write-only once saved. Save disabled & test.
- Validate the connection. Plugboard has saved the settings with the connection off, and reports whether the test passed, with how long the service took to respond, or the error. Edit access settings and Run test again until it passes, or Finish disabled to come back later.
- Review and enable. A table shows each setting before and as saved. Enable connection turns it on; a demo connection reads Enable demo connection.
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:
| Choice | What it means |
|---|---|
| Plugboard itself (must be on that network) | 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 |
A service that always needs an agent, such as Active Directory, asks you to Choose a campus connector agent instead, on self-hosted installs too.
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 a campus does not install or check an agent.
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 setup 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
Settings, Campuses, or that your role does not include the
site.manage permission. Ask somebody whose does.
A failed test leaves the settings saved and the connection off, with your entries still in the form, so the wrong field can be corrected without retyping the rest.
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.
So 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 are two exceptions.
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 each connection’s ID: Copy connection ID in
its row menu, or the 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.
Plugboard never receives that file and never asks for it. Setup does not offer the credential fields once a site is chosen, and the API refuses them if they arrive anyway. A hosted service has no use for a domain bind password, so it does not hold one.
A Wonde school token is collected, not typed. Plugboard support stores it, and Collect Wonde token puts it straight into the connection’s sealed settings. See Wonde.
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.
Run as
Section titled “Run as”Some connectors can act either as Plugboard or as the technician doing the work. Run as on the row opens, for each thing the connector does, who the provider sees:
- Acts as Plugboard
- Acts as the technician when they have signed in
- Acts as the technician; refuses otherwise
A technician signs in once under Account, Connected accounts. Signed in as themselves lists who has, with Disconnect. Where the directory cannot match a person to their provider account, set the provider address for them here.
Match people
Section titled “Match people”A student system’s first sync waits when the school’s active people already
came from another student system or a CSV import, so it does not add everyone
a second time. Match people, in an enabled student system’s row menu,
previews who matches and applies it, or adds everyone as new. It needs
user.manage over every campus. See the first sync of a student
system.
Demo mode
Section titled “Demo mode”Most connectors have a demo mode, Use demo data in setup (demoMode). With
it on, the connector returns realistic fictional data and makes no calls to the
real system. Nothing on the Connectors list marks it: a demo connector’s check
reads Passed like any other, so open its setup to see whether Use demo
data is on.
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”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 how long the service took to respond. A slow test usually means a slow feature. A test does not prove every operation works: a passing read says nothing about write permissions.
More than one instance
Section titled “More than one instance”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. Add instance in a connection’s row menu starts another. 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 school 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 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.
Disabling against removing
Section titled “Disabling against removing”Disabling a connection 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.
Removing deletes the configuration and the encrypted secrets. The credentials are not recoverable afterwards. Removing does not revoke anything at the provider: delete the app, key or token there too.
For a connector run by an agent there are no stored credentials to remove; removing 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 enable features elsewhere. If a screen is empty, the connector behind it is usually not configured.
| Connect | And you get |
|---|---|
| An MDM | Live device details, MDM actions on the device page, serial autocomplete, loan pools pulled from smart groups |
| A student system | 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 tickets raised and kept in step 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 |
| A language model | Ask and the AI features |
When the test fails
Section titled “When the test fails”Work through these in order.
| 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 | A 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 message on the test result comes from the connector. Some quote the vendor’s reply, which is usually literal; others give a fixed message naming what to check, so a vendor’s error text never reaches the page.
Auditing
Section titled “Auditing”Configuring, reconfiguring, enabling, disabling and removing a connector are all written to the audit log, with who did it and when. Secret values are never written to the log.