PDQ Connect

PDQ Connect manages Windows computers from the cloud: who's signed in, what's installed, which Windows updates have landed, how full the disk is and which vulnerabilities PDQ has found. Connecting it to schoolOS brings each computer into schoolAssets as the asset it already is, keeps its details current, and puts everything PDQ knows about it on the device's MDM section, so a technician answering a ticket sees it without opening another console.

What the connection does:

• Brings Windows devices in. Every device PDQ reports is matched to an asset you already have (see matching). One that matches nothing waits in the Review queue to start with, so nothing is created until someone approves it. When you're ready to create them, new devices can go to the right school by their PDQ group and get the right device type by their chassis, and Preview shows what a sync will do before it does it.
• Keeps them current. A sync runs every night (or weekly, or only when you select Sync now). Each PDQ field lands in the schoolOS field you map it to.
• Shows the whole PDQ record on each device's MDM section, including the parts no asset field holds.
• Acts on a device. Deploy a package, fix a vulnerability with PDQ's recommended package, update an outdated app, or reboot, from the device's MDM section or from a ticket. schoolOS follows each deployment until it finishes and records how it went.
• Writes back, if you choose. The asset tag, a link to the asset and the owner's email, in PDQ custom fields (see Write back to PDQ).

Reading changes nothing in PDQ. Acting and writing back do, only when someone asks (or you turn write-back on), and only with the scopes the key has.

You need Manage integrations to connect it or change its settings, and your account needs schoolAssets.

Connect#

1. In PDQ Connect, open Settings › API keys and select Create API key. Name it schoolOS and give it the scopes in Which scopes to grant. Copy the key: PDQ shows it once.
2. Copy your Organization URL from your browser's address bar while PDQ Connect is open, for example https://app.pdq.com/lincoln-usd/devices. An API key doesn't say which organization it belongs to, so this is how Open in PDQ finds each device.
3. Open Admin › Account › Integrations and select PDQ Connect, then Add PDQ organization.
4. Give it a Name (what you call it in schoolOS; left blank, it's named after the organization), paste the Organization URL and the API key, and select Add and check key.

schoolOS checks the key with PDQ before it saves anything. PDQ has to accept it and it has to read devices; if not, nothing is saved and the dialog says what to fix. Once it's saved, the dialog and What each key can do show what the key can do.

More than one PDQ organization. A district that runs a PDQ organization per region, or one for staff and one for labs, adds each with Add PDQ organization: each has its own name, Organization URL and key, and syncs on its own. An account can connect up to 20. The settings below apply to all of them.

For example, a district with 3,200 Windows laptops in one PDQ organization creates a "schoolOS" key with devices:read, groups:read, custom_fields:read and vulnerabilities:read, adds it as "Lincoln Unified", and sees 3,200 devices available to sync.

Which scopes to grant#

A PDQ key carries scopes per resource, and PDQ needs every scope of every resource a request names. A write scope doesn't include read. Grant only what you use:

| Grant | schoolOS can | Without it | | --- | --- | --- | | devices:read | Sync devices into schoolAssets, with the details you choose to pull. | Nothing works; schoolOS won't save the key. | | groups:read | Show each device's PDQ groups. | The PDQ groups section says to grant it. | | vulnerabilities:read (with devices:read) | Show each device's open vulnerabilities. Also needs PDQ's vulnerability management on the organization. | The Vulnerabilities section says to grant it. | | custom_fields:read | Pick a PDQ custom field for matching owners from a list. | Type the field's name instead. | | devices:write | Reboot a device. | Reboot is off, saying which scope to grant. | | packages:read, deployments:write | Deploy a package, Fix and Update. | Deploy package, Fix and Update are off, saying which scope to grant. | | deployments:read | Follow a deployment to the end and note how it went. | schoolOS starts deployments but can't say how they finished; each shows Still running in PDQ after a day. | | custom_fields:write (with devices:write) | Write back the asset tag, link and owner's email. With custom_fields:read too, it finds fields you already made. | Write-back says which scope to grant. |

PDQ keys can't be edited. To add a scope, create a new key with it and paste it on the organization's Edit: the new key is checked and replaces the old one. Keys made before August 10, 2026 have every scope.

How schoolOS knows what a key can do#

PDQ has no way to ask a key for its scopes, so schoolOS asks for one item of each kind (devices, groups, packages, deployments, custom fields, and one device's vulnerabilities) when the key is saved and when you select Test connection. To learn about the write scopes without changing anything, it asks PDQ to deploy nothing and to set a custom field on a device that can't exist: PDQ refuses those on the missing details, which only happens after it has checked the scopes. That's about eight requests and changes nothing in PDQ.

If PDQ later refuses something the key could do before (someone replaced the key in PDQ, say), schoolOS marks it lost, shows Lost access on the organization's row and the scope in What each key can do, and stops asking. Test connection checks again.

The setup page#

• PDQ organizations. Each connection with whether it syncs, how many devices its key saw, Last sync and what it said, This key can (how many of schoolOS's features it reaches) and the API key's last four characters. Selecting a row opens Edit. Its … menu: Edit, Test connection, Sync now, Open in PDQ, Pause sync or Resume sync (both can be undone from the message that follows), and Remove, which asks first. Removing stops its sync and hides its devices' PDQ details; assets keep what was already synced onto them and nothing changes in PDQ. Undo brings it back within ten minutes; after that its key is cleared. Disconnect on the PDQ Connect row of Admin › Account › Integrations removes every PDQ organization at once and clears their keys, with no Undo; use Remove here to take out one.
• What each key can do. For each organization, a line per feature: what it can do, and the exact scopes to add for what it can't.
• Sync. When to sync and what to pull with each device (see below).
• Matching devices to people, with Preview the match (see below).
• MDM tab fields. Which fields the device's Details section lists, grouped Identity, Networking, Health, OS and Hardware.
• Write back to PDQ. Off to start. See Write back to PDQ.
• Field mapping. Where each PDQ field lands on the asset. Device name fills Name, Manufacturer and Model fill theirs, OS and OS version fill OS Name and OS Version, Last user fills Last Signed-in User, MAC address fills MAC Address and Public IP address fills Last WAN IP. Change any of them, or map more.
• New devices from PDQ, with Preview, and the Review queue. New PDQ connections start on Add to review queue. See New devices from PDQ.

New devices from PDQ#

When PDQ has a device schoolOS doesn't chooses what a device that matches no asset does: Do nothing (log only), Add to review queue (the default for PDQ) or Auto-create. See Integrations for when to choose each. With Add to review queue or Auto-create, the section also sets where new devices go and what they are:

• Default device type and Default location: what a new asset gets when nothing below says otherwise. Leave the location blank to use your account's default location.
• School by PDQ group. Pick a PDQ group and the location its devices go to; Add a group for each. A device in more than one mapped group goes to the first one listed, so put the most specific groups first (a "Lincoln Library" group above "Lincoln Elementary"); the arrows change the order. A device in none of them goes to the default location. Groups appear once a sync has read them, which needs groups:read; with several PDQ organizations, each group shows which organization it's in.
• Device type by chassis. PDQ reports each computer's chassis. Choose a device type for Laptop (laptops, notebooks, convertibles and detachables), Desktop (towers, mini PCs and the like), All-in-one, Tablet, Server and Virtual machine. A chassis left on Use the default device type, or one PDQ reports that isn't listed, gets the default device type.

A mapping can fill in what the defaults leave out: a device in a mapped group, with a mapped chassis, can be created even with no default set. A device nothing places waits in review instead of being guessed. These settings apply to every PDQ organization in your account, and to the next sync. Approve in the review queue (one device, selected ones or Approve all) places a device the same way: its group's location and its chassis' type, else the defaults. The approved asset gets its mapped fields (OS, MAC address and the rest) straight away, not at the next sync.

For example, a district maps its "Lincoln Labs" group to Lincoln Lab and its "Lincoln Elementary" group to Lincoln Elementary, in that order, and Laptop to Windows Laptop. A lab laptop in both groups is created as a Windows Laptop at Lincoln Lab; a desktop in the front office, in no mapped group, gets the default type at the default location.

Assign devices to their user#

Off to start. Turned on, a device a sync creates as an asset, or matches to an asset that has no owner, is assigned to the person signed in on it: who's signed in now, else who signed in last, matched to a person in schoolOS the way matching people does, by the part of their email before the @. The asset's timeline says "Assigned to Jo Smith", the audit log records it under PDQ Connect, and the sync's summary counts how many were assigned.

It's careful by design:

• An owner is never replaced, nor a room the asset is assigned to. Only an asset with no owner gets one.
• Only one person. A sign-in that matches no one in schoolOS, or more than one person ([email protected] and [email protected]), is left alone.
• Only someone who may own it there. The person must be one who could be assigned the device from its page: in the device's district, and at its school unless their role reaches the whole district (or account). A teacher at West Middle signed in to a District Office laptop isn't assigned it. When where the device is isn't known, it's left alone.
• Shared devices are skipped. Under Skip shared devices, add the PDQ groups (labs, libraries, carts) and the hostname patterns (LAB-*, *-LIB-*: commas between them, * for any characters, any case) whose devices are never assigned, whoever signs in.

It applies at the next sync, to every device once, and then as devices change.

Preview the import#

Preview, on this section and on the PDQ Connect card of Admin › Account › Import Data, shows what the next sync would do with the devices each PDQ organization last synced, using your saved settings, before anything is created:

• Will match existing assets, will create, will send to review and will skip, each with how many and why (for example "38 its serial number is on other assets").
• Open one to see its devices: each with its name and serial number, and the asset it matches (select it to open it), or the type and location a new asset would get and whether that came from its group or chassis. Skipped and reviewed devices say why.
• New catalog entries: the manufacturers and models that creating these assets would add to your catalog.
• With Assign devices to their user on, who each device would be assigned to, or why it wouldn't be (for example "The person isn't at this device's school or district").

The preview decides with the sync's own rules and changes nothing, in schoolOS or PDQ. It reads each device on its own, so two new devices with the same serial both read as Will create; the sync creates the first and sends the second to review. Before the first sync there's nothing to preview: select Sync now first (with Add to review queue, nothing is created).

Manufacturer names are cleaned up as devices come in: "Dell Inc.", "LENOVO" and "HP Inc." become Dell, Lenovo and HP (see Manufacturer names).

What syncs and when#

| Sync | What happens | Choose it when | | --- | --- | --- | | Every night (default) | The nightly run syncs each organization. | Almost always. | | Once a week | The nightly run skips an organization synced in the last week. A failed sync is tried again the next night. | Your PDQ limit is busy with other tools, or the devices rarely change. | | Only when I select Sync now | Nothing runs on its own. | You're trying PDQ out, or sync on your own timetable. |

The nightly run asks PDQ only for the devices it updated since the last successful sync; once a week, after a failed sync, and on Sync now, it reads everything again. A device whose record hasn't changed is skipped. A sync reads 100 devices per request, so 3,200 devices are 32 requests.

Pull with each device chooses what comes with each device: Software, Windows updates, Disks, Processors, Networking, Active Directory, Active Directory groups and Custom fields start on; Drivers and Windows features start off, since the MDM section doesn't show them. Each makes the sync larger, not slower.

After the devices, a sync reads each PDQ group's members (with groups:read, up to 100 groups) and, with vulnerabilities:read, vulnerabilities for up to 400 devices, oldest first, so a large district's vulnerabilities fill in over a few nights and then stay within a day. When a group is mapped to a school, or skipped for owner assignment, the members are read before the devices are matched instead, so a device new to PDQ goes to its school on its first sync; they're still read once a sync.

Several organizations. Each syncs on its own. Sync now on the PDQ Connect card of Admin › Account › Import Data syncs every active organization, and one that's already syncing is left to finish while the others start; Sync now in an organization's … menu syncs just that one.

Rate limits. PDQ allows each organization 300 requests every 2 minutes, shared with every other tool your district connects to it. schoolOS keeps to at most 180 of them, and the app and the sync share that budget. When PDQ asks it to slow down, it waits as long as PDQ says. A sync that's cut short keeps what it read and picks up where it stopped on the next run.

Matching devices to assets and people#

To assets. A PDQ device is matched to an existing asset by its PDQ device ID once it's linked. Before that, by its Serial Number; then, only when the serial finds nothing, its BIOS asset tag against Asset Tag, its MAC address against MAC Address (any separators), and its hostname against the asset's Name. Each links only when it points at exactly one asset that no other device still in PDQ holds; anything less certain is left unmatched rather than guessed. Placeholder serials and asset tags like "To be filled by O.E.M." or "No Asset Tag" never match. A device in two of your PDQ organizations, or in PDQ and Intune, is one asset with a link to each.

To people (for the devices on a person's tickets). In order, each device listed once under the first that finds it:

1. The ticket's asset, when it has a PDQ device.
2. Assigned to them in schoolAssets: assets assigned to the person, by their linked device, else by serial number or BIOS asset tag.
3. Signed in now or Signed in last: who Windows says is signed in, compared with the part of their email before the @. DISTRICT\jsmith, [email protected] and JSmith all match [email protected].
4. PDQ custom field: a PDQ custom field that holds the owner's email, compared without case.

Which signed-in user should count?#

| Option | What it does | Choose it when | | --- | --- | --- | | Auto (recommended) | Who's signed in now, or else who signed in last. | Most districts: staff laptops with one main user. | | Current user | Only who's signed in right now. | Shared carts, where the last user is rarely the owner. | | Last user | Only who signed in last. | Devices that are often off or asleep when a ticket arrives. | | Don't match on signed-in users | Uses the other ways only. | Labs and kiosks, where anyone signs in. |

PDQ custom field with the owner's email: for districts that record each device's owner in PDQ. With custom_fields:read you pick it from a list; without, type its name.

Preview the match: type an email and select Preview the match to see the person (when they're in schoolOS) and each device that would count as theirs, with Matched on, its PDQ organization, when it was last seen, and Open in PDQ. It reads what's synced and the saved settings; nothing is sent to PDQ.

For example, a teacher's ticket comes in from [email protected]. Her laptop is assigned to her in schoolAssets, so it's listed first under Assigned to them in schoolAssets; the library PC she's signed in to right now follows under Signed in now.

On a device's MDM section#

A device synced from PDQ shows PDQ's own layout on its MDM section:

• At the top: its name and hostname, Online or Offline and when it was last seen, which organization it came from and when it synced, Reboot needed when Windows is waiting for one, Open in PDQ, and who's Signed in now and Signed in last, with their picture when they're in schoolOS.
• Health: Disk free (in amber under 15%), Memory, OS and build, Last boot and how long it's been up, and Windows updates installed with the latest one's date.
• Vulnerabilities: open ones counted by PDQ's risk (critical, high, medium, low), how many are exploitable or weaponized, and the riskiest ten with their CVE, CVSS score, the software they're in and PDQ's recommended fix. It opens on its own when there's a critical or weaponized one.
• Software (search it; titles with a newer version show it in amber, and come first), Windows updates, Hardware (processors, disks with free space and BitLocker), Networking, Active Directory and its groups, PDQ groups, Custom fields, and Details (the fields chosen under MDM tab fields).

Each section folds and says what's inside while closed. A section the key can't read says which scope to grant instead, and a section whose details aren't pulled doesn't show. Until a device's first sync with these details, its MDM section shows the general record instead.

Act on a device#

The top of a PDQ device's MDM section has Deploy package, Reboot, Remote and Refresh beside Open in PDQ, and each vulnerability has Fix. Below the sections, PDQ actions has Check for updates and the deployments started from schoolOS on this device, with who started each and how it went.

• Deploy package. Search PDQ's packages (yours and PDQ's library) by name or publisher, pick one, and choose a Version (Latest to start). Select Deploy package to start it in PDQ. It can't be undone from schoolOS: PDQ is already installing.
• Fix. Deploys the package PDQ recommends for that vulnerability, after you confirm it. When PDQ recommends none, Fix is off and says so.
• Update. Check for updates looks up a PDQ package for each app PDQ calls outdated. Update appears only when exactly one package has the app's name (and publisher, when both say): "Google Chrome" by Google matches PDQ's Google Chrome, never "Chrome Remote Desktop". Anything less certain offers nothing, so a deployment never installs the wrong app.
• Reboot. Restarts the device now, after you confirm. The dialog says who is signed in, since they lose anything unsaved. During school hours it asks you to confirm that too.
• Remote. Opens the device's page in PDQ Connect, where you start a remote session.
• Refresh. Reads this device from PDQ again, for what changed since the sync (who's signed in, whether it's online).

Reading the device's fixes and refreshing cost requests from PDQ's shared limit, so they happen when you ask, not when the page opens.

School hours#

A reboot interrupts whoever is using the device, so school hours (7:30 AM to 3:30 PM, Monday to Friday, in the time zone in Admin › Account › Account Settings) are quiet hours for reboots. One device can still be rebooted then: check Reboot during school hours in the dialog. Several devices at once, or a workflow, wait until after school hours.

Several devices at once#

One action reaches at most 50 devices for a deployment and 25 for a reboot; for more, use a PDQ group in PDQ. Deploying to more than 5 devices, or rebooting more than one, asks you to type how many first.

When PDQ is busy#

When PDQ says the organization is at its request limit, a deployment or reboot to a device in schoolAssets is queued and sent as soon as PDQ allows, and its message says Queued. One to a device schoolOS doesn't have as an asset asks you to try again shortly.

Who can act#

Deploying, fixing, updating and rebooting need Update assets, the same permission as every other device command (lock, erase, remote session), and the device in your scope. On a ticket, you also need to work tickets. Changing Write back to PDQ needs Manage integrations. Everyone who can see the device sees its deployments.

On a ticket#

On a ticket, each linked device PDQ knows has PDQ Connect in its card, under Apps, with how PDQ last saw it ("Online · 2 min ago"). Open the card to see Status (online or offline), Last seen, OS, Reboot needed, Disk free and Vulnerabilities, from the last sync, with Refresh to read it again. To act on a requester's computer from their ticket, link it to the ticket first: a computer that isn't linked doesn't show there.

Its actions are the device's: Deploy package (search PDQ's packages), Check fixes and updates (each vulnerability with Fix, each outdated app with Update), Reboot, Open in PDQ, Remote and Refresh, followed by the deployments already started on it. Each one you take goes on the ticket's timeline under your name ("Deployed Google Chrome 129 to LIB-204 with PDQ Connect"), and the message that confirms it says it was logged on the ticket. Deploy package on a ticket also offers Solve the ticket when it succeeds.

Following a deployment#

PDQ doesn't tell anyone when a deployment finishes, so schoolOS asks: soon after it starts, then less often (every 30 seconds at first, up to every 15 minutes), within PDQ's limit. When nothing is left queued or running, it settles as Succeeded, Failed, Partly succeeded or Canceled; one still running after a day shows Still running in PDQ, and schoolOS stops asking.

When it finishes:

• The device's asset timeline says how it went.
• A deployment started from a ticket gets an internal note from Otto: "Google Chrome 129 deployed to LIB-204: succeeded". Several devices read "succeeded on 2 of 3".
• With Solve the ticket when it succeeds, a deployment that succeeded on every device solves the ticket, the same as you would. A ticket with open child tickets or blocking tasks stays open, and one already solved is left alone.

PDQ's own history names only the API key, so this is the record of who started what: Admin › Account › Logs lists each deployment and reboot under PDQ Connect.

Write back to PDQ#

Write back to PDQ on the setup page puts three schoolOS details into PDQ custom fields on each device that's an asset, so whoever is in PDQ sees which asset it is and whose:

| Field | What it holds | | --- | --- | | schoolOS Asset Tag | The asset tag. | | schoolOS Asset Link | A link to the asset in schoolOS. | | schoolOS Owner Email | The email of the person it's assigned to, or empty when it's unassigned. |

Rename any field, or leave one blank to not write it. Turning it on finds each field in PDQ by name (any case), or creates it as a text field. A field of that name that holds dates or numbers is refused, so pick another name. Then every device is written, and after that only a device whose values changed: after a sync links it to an asset, and after its asset changes. Writes go a few at a time within PDQ's limit, so a large district fills in over the first hour. It needs custom_fields:write and devices:write; custom_fields:read lets it find fields that already exist. Turning it off stops writing and leaves what's in PDQ.

The owner's email is the field matching people can use: point PDQ custom field with the owner's email at schoolOS Owner Email.

Your key and your data#

• The API key is stored encrypted and never shown again, in the app or its logs. The setup page shows only its last four characters; to change it, type a new one. It's sent to PDQ and nowhere else.
• Checking a key changes nothing (see How schoolOS knows). PDQ changes only when someone deploys, reboots or turns on write-back.
• What a sync brings in is kept for your account only, and the copy of a device PDQ deleted goes on the next full sync.

Workflows#

With PDQ Connect connected, workflows can run when PDQ finds a computer for the first time, loses one, hasn't seen one for a while, or finds one that has needed a restart, is low on disk, has an app that's behind or has a new critical or exploited vulnerability, and when a deployment schoolOS started finishes or fails. They can deploy a package (including a vulnerability's recommended fix or an app's update), restart a computer after school hours, write a PDQ custom field, wait for a deployment's result, and open a ticket per vulnerability. Four ready-made templates start you off. These triggers are checked at each sync, so they follow your sync schedule, and vulnerability triggers about once a day. See Automate PDQ Connect with workflows.

On tickets, Otto suggests a restart, an update or a fix for the ticket's computer when PDQ's data points to one.

Troubleshooting#

• "PDQ Connect didn't accept this API key." It was mistyped, or deleted in PDQ. Create a new one and paste it on Edit.
• "This key can't read devices." Create a key with devices:read.
• "PDQ Connect says this organization's subscription isn't active." PDQ refused because of the organization's PDQ plan. Check it in PDQ.
• "PDQ Connect is busy." Your district's PDQ tools used up the organization's requests for the moment. Try again in the time it says; a sync waits on its own.
• Open in PDQ goes to the wrong place. Check the Organization URL on Edit.
• A device's vulnerabilities say "Not read yet." They're read a few hundred devices a night; the rest follow over the next nights.
• Lost access on a row: PDQ refused a scope the key had. See How schoolOS knows what a key can do.
• "The PDQ API key can't do this." The key lacks the scope named. Create a key with it and paste it on Edit.
• "Reboots wait until after school hours." Several devices, or a workflow, during school hours. Reboot one at a time, or after school.
• A deployment says "Still running in PDQ." PDQ kept it going for more than a day, or the key lacks deployments:read. Check it in PDQ.
• Write back says a field holds dates or numbers. A PDQ field of that name already exists with another type. Pick another name.
• Every sync, deployment and reboot is in Logs.