Skip to content
plugboard.appRequest a demo

Connectors

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.

Three tabs:

TabHolds
ConnectionsConnected, the connections you have, and Add a service, every service you can connect
Sign-in providersLinks to set up sign-in with Microsoft Entra ID, Google Workspace, custom OpenID Connect or another SAML 2.0 provider
Device managementThe 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.

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 buttonWhen
FixThe connection is on, and its last check failed or its credentials need sealing
TestThe connection is on and working
Review & enableThe connection is saved but off
OpenA Microsoft 365 or Google Workspace connection, which holds several features
Run asThe 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.

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.

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.

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.

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.

Those same connectors show one extra setting:

ChoiceWhat 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 siteThe 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.

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.

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:

JSON
{
"<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.

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.

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.

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.

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.

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 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.

Connectors enable features elsewhere. If a screen is empty, the connector behind it is usually not configured.

ConnectAnd you get
An MDMLive device details, MDM actions on the device page, serial autocomplete, loan pools pulled from smart groups
A student systemPeople, year levels, tutor groups, card numbers, term dates
A directoryPeople, and directory account management
EmailEvery notification, tracking link, receipt, alert and scheduled report
SMSText notifications
A ticketing systemExternal tickets raised and kept in step from submissions
WarrantyCoverage lookup on a device, feeding the coverage on a repair
A repair vendorVendor repairs booked out from a submission
PrintersThe printer fleet page
PaperCutBalances and card writing
ThreatLockerThe security approvals queue
A language modelAsk and the AI features

Work through these in order.

CheckHow
Is the URL right, including scheme and no trailing slashPaste it into a browser
Is the credential the value rather than the idA common mistake with Entra client secrets
Has the credential expiredMost vendors expire tokens. Some do it silently
Does the account have the permission the connector needsEach connector page lists the minimum
Can the server reach it at allcurl from the server, not from your laptop
Is it a private addressA 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 placeFor 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 wayOutbound 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.

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.