PDK Integration — User Manual

This document is the user manual for configuring and operating the PDK (ProdataKey) integration in CLUe.

Revision History

1. About This Document

1.1 Intended Audience

• Place Admin — operators who connect a PDK system to a CLUe Place and run user-credential operations (connect / change / disconnect)

This manual assumes an IT operator who understands HTTPS, OAuth client credentials, and access-control basics (Wiegand card formats, etc.). Make sure you are operating a system on the PDK cloud console (pdk.io) and have its System ID ready in advance.

1.2 Prerequisites

• You must be invited as an admin to the target Place to access the menu.
• You must have obtained the System ID from the PDK cloud (see 2.4).
• A Place may have only one Sync Plugin registered. If another Sync Plugin (e.g., Brivo) is already connected, switching to PDK will remove all existing settings and synchronized user-credential data (see 10.5).

1.3 Glossary

2. Overview of the PDK Integration

2.1 What This Feature Does

The PDK integration binds a CLUe Place to a single System on the PDK cloud, pulling PDK-managed user/credential information into CLUe devices and notifying PDK of access events. It is one type of Sync Plugin.

• Each Place can register only one PDK entry.
• Entering only the System ID is enough — CLUe handles PDK authentication tokens, the Organization ID, and Webhook registration automatically.
• After registration, PDK users are automatically synced into CLUe, and any subsequent change in PDK is propagated automatically through the Webhook PDK calls — CLUe MSA (Lambda) → Device Server.
• Disconnecting PDK cleans up the synchronized card data and Webhook subscription on the CLUe side, with the change reflected on devices immediately.

2.2 Supported Card Formats

So devices interpret the card data registered in PDK identically, the card format must match the PDK system configuration.

Facility Code rule. For 26-bit Wiegand the value must be 0–254; for H10304 37-bit it must be 0–65534. For other formats no input is needed, and any value entered is ignored.

2.3 Face Sync Option

• When checked, CLUe face-authentication credentials are operated together with PDK users.
• When unchecked, only PDK-side credentials such as cards/PIN are used; face credentials are not pulled into CLUe or pushed to devices.

2.4 Preparation — Look Up the System ID in PDK

Before registering PDK in CLUe, sign in to the PDK cloud console (pdk.io) and look up the System ID of the target system. The System ID can be found in the URL of the system detail page or in the system info panel.

Other credentials (Client ID/Secret, ID Token, System Token, Organization ID) are issued / retrieved automatically by the CLUe server using a pre-registered client credential. Operators do not enter these.

2.5 Scope — Per Place

A PDK Sync Plugin is configured per Place only. It is not applied at the Place Group (parent) level, and the same PDK System ID cannot be registered in multiple Places.

3. Major Flows

The PDK integration can be understood as two flows: a registration flow (configured by the admin) and an operational flow (after configuration is complete).

3.1 Registration Flow

[1] Look up the System ID in the PDK console     (external admin work)     | [2] Enable Sync Plugin in Place Settings         The "Sync Plugin" item appears     |                                            in the left-side menu [3] Enter the Sync Plugin menu of the Place     | [4] Select Plugin Type = PDK     |   Enter System ID     |   Select Card Format (and Facility Code if required)     |   Choose Face Sync     | [5] Test Call (mandatory)                        The server attempts a PDK auth.     |                                           ≥1 success enables [6] Apply     | [6] Apply → automatic actions        - CLUe issues PDK auth tokens        - CLUe retrieves and stores the PDK Organization ID        - CLUe auto-generates a Webhook URL and stores it        - The Place's existing user credentials are reset, then a sync job          starts to pull users from PDK

3.2 Operational Flow (Automatic Propagation)

[1] Change to PDK users/cards          Admin adds/edits/deletes in the PDK console     |     ▼ [2] PDK → CLUe MSA (Lambda) Webhook    PDK pushes the change data to the     |  call                            Webhook URL registered at Apply time     ▼ [3] Lambda → Device Server processing  Saved into the Place's credential DB     |                                  (`Last Webhook Received` is updated)     ▼ [4] CLUe → device propagation          Synced card/face credentials reach devices     |     ▼ [5] User attempts access               The device authenticates against PDK creds

No operator action is required for routine operations. Use the manual full sync in 7.2 only when automatic propagation appears to have missed something.

4. Step 1 — Enable Sync Plugin in Place Settings

In the Place screen, go to Settings → Basic and turn on the Sync Plugin option under the Services section. While this option is off, the Sync Plugin item is hidden from the left-side menu, so PDK registration cannot start.

4.1 Initial State

[Screenshot 1: Place Details > Settings > Basic screen with the Sync Plugin toggle in the Services section highlighted, currently OFF.]

• In Settings > Basic, the Sync Plugin toggle in the Services section is OFF.
• In this state, the Sync Plugin item is not visible in the left-side menu.

4.2 Turn Sync Plugin On

[Screenshot 2: Same screen with the Sync Plugin toggle now ON; the Sync Plugin item is now visible in the left-side menu.]

• Switch the Sync Plugin toggle in Services to ON and save.
• Once saved, the Sync Plugin item becomes available in the left-side menu.

If you turn this toggle off after a PDK entry has already been registered, only the menu access is blocked — the registration itself remains. To remove the registration, follow the Delete procedure in 8.2.

No PDK details are entered at this step. Continue to chapter 5 to enter the now-enabled menu and start the registration.

5. Step 2 — Enter the Sync Plugin Menu

Open the Sync Plugin item in the left-side menu.

[Screenshot 3: User Sync Plug-In screen with the empty state and an + Add Sync Plugin button at the top right.]

• When no Sync Plugin is registered, an empty state is shown.
• Click the + Add Sync Plugin button at the top right to open the registration panel.

If a Sync Plugin of a different kind (e.g., Brivo) is already registered, delete it first using the procedure in 8.2 before registering PDK. See 10.5 for details on switching plugins. Two kinds of Plugin cannot be operated in the same Place at the same time.

6. Step 3 — Register PDK

6.1 Choose the Plugin Type

[Screenshot 4: Plugin selection grid with cards for Brivo (London ID), Brivo (London Club), PDK, and another plugin; PDK is selected.]

The Plugin Type can be changed after registration, but doing so resets the existing synced card data and starts a fresh sync (see 10.5). Frequent switching is not recommended.

6.2 Enter PDK Settings

[Screenshot 5: PDK registration panel with the System ID input field highlighted.]

Auto-handled values. The following are issued / retrieved / generated automatically by the CLUe server, so operators do not enter them.

These values are not displayed in the UI and cannot be entered or edited directly by operators.

6.3 Choose the Card Format

[Screenshot 6: PDK registration panel with the Card Type dropdown open showing the five Wiegand/CSN options.]

Match this to the PDK system configuration. If the card format or Facility Code differs from PDK's card-issuance policy, sync may succeed but devices will fail to read the cards.

6.4 Face Sync Option

• You can Apply with this unchecked and turn it on/off later.
• After a change, the new Face Sync policy is reflected in the next sync and device propagation following the next Apply.

6.5 Test Call (Mandatory)

[Screenshot 7: PDK registration panel with the Test Call button and a "Plugin test succeeded" toast notification at the top.]

This step verifies that the values you entered actually authenticate against PDK. You must succeed at least once before Apply.

• Press the Test Call button at the bottom of the panel.
• The CLUe server runs a one-shot PDK authentication for the entered System ID (ID Token → System Token → Organization ID retrieval).
• On success the console shows a normal response; on failure it shows the reason (e.g., wrong System ID, PDK-side auth failure, network error).

Mandatory before Apply. The Apply button in 6.6 is only enabled after this test has succeeded at least once. If you change inputs such as System ID or Card Format, you must succeed in the test again before Apply becomes available.

The test call does not save to the DB and does not create a subscription on PDK. It only checks that the entered values authenticate against PDK, so it is safe to run repeatedly even in production.

6.6 Apply

[Screenshot 8: PDK registration panel with the Apply button at the bottom; an "Active Tasks" notification appears showing "Sync Start - PDK".]

The Apply button at the bottom of the panel becomes active only when all required fields are valid and the test call in 6.5 has succeeded at least once. Both new registrations and updates are confirmed with the same Apply button.

• The button stays disabled if there are missing required fields, an invalid System ID, a Facility Code that doesn't match the chosen card format, or a missing or failed test call.
• When you press Apply, the server automatically performs the following:

1. PDK authentication / lookup
   • Client ID/Secret → ID Token issued
   • System ID + ID Token → System Token issued
   • System ID + System Token → Organization ID (ouId) retrieved
2. Duplicate check
   • If the same PDK System ID is already registered to another Place, the apply is rejected.
3. Reset of existing credentials (on new registration)
   • All user credentials previously registered together with synced cards in this Place are removed.
4. Webhook URL creation and subscription
   • CLUe MSA creates a per-Place Webhook URL and registers it as a subscription on PDK.
5. Initial sync + readiness for automatic propagation
   • Right after Apply, the users/credentials already registered in the PDK system are synced into CLUe once (initial sync).
   • From that point on, when PDK users/credentials are added/edited/deleted, PDK pushes change data to the registered Webhook URL; CLUe MSA (Lambda) receives it and writes it to the Device Server DB automatically (see chapter 7 for the full flow).
   • Sync runs asynchronously. Use the registration card's Last Sync At / Last Webhook Received timestamps to verify normal operation.
6. Device propagation
   • The changed credentials and card format are reflected on every device in the Place.

When Apply finishes, the panel closes and the registration appears in the list with information such as Plugin Type, Card Type, Face Sync flag, last sync time, and last Webhook received time.

7. User Sync

When PDK users/credentials are added, edited, or deleted, the change is propagated to CLUe automatically without any operator action — that is the normal mode. As a safety net for transient Webhook delivery problems, an explicit manual full-sync trigger is also provided.

7.1 Automatic Propagation (Routine Operation)

PDK change ──Webhook──▶ CLUe MSA (Lambda) ──▶ Device Server DB ──▶ devices

1. At the time of Apply in 6.6, the CLUe MSA (Lambda) Webhook URL is registered as a subscription on the PDK system.
2. Whenever a user/credential change occurs in PDK afterward, PDK pushes the change to the registered Webhook URL.
3. CLUe MSA (Lambda) receives the push and forwards it to CLUe Device Server, which updates the Place's credential information.
4. The updated credentials are propagated to every device in the Place automatically.
5. The Last Webhook Received timestamp on the registration card is updated, which serves as the indicator of normal operation.

Operators do not need to act for routine operation. Changes made in the PDK console are reflected automatically in CLUe and on devices a short while later.

7.2 Manual Full Sync (Troubleshooting)

This is a re-sync command to use when automatic propagation (7.1) is not working as expected. It is not needed in routine operation.

[Screenshot 9: User list screen with a Manual Sync button highlighted at the top right.]

• Pressing the Sync button on the registration card pulls every user/credential registered in PDK into CLUe again, rebuilding the Place's credentials from scratch (full sync).
• A manual sync runs asynchronously like automatic propagation; once finished, the Last Sync At timestamp on the registration card is updated.

Try a manual sync when you see any of the following symptoms (see 10.3 / 10.6 for detailed checks):

• Users added/edited in PDK are not reflected in CLUe / on devices even after some time
• The Last Webhook Received timestamp is not updated for a long time
• You suspect a transient network outage between PDK and CLUe

8. Change / Delete

8.1 Change

Click the registered PDK card to open the change panel. You can re-enter System ID, Card Format, Facility Code, and Face Sync and apply with Apply (the same Apply button used for new registration).

• If you change the System ID to another value, authentication and subscription against the new system run again, and an initial sync runs automatically right after Apply. Subsequent changes are picked up by the new Webhook automatically.
• A change of card format propagates to all devices immediately. Make sure it matches PDK's card-issuance policy.

8.2 Delete

Use the Delete button on the registration card to disconnect PDK. On delete, the following happens automatically:

1. Bulk deletion of CLUe-side synced card data (cards registered in PDK are kept as is.)
2. Subscription cancellation on PDK — the Webhook subscription is removed from PDK (silently ignored if it is already gone).
3. Sync Plugin connection cleared — the Place's registration entry is emptied.
4. Device propagation — the card-data change is reflected on every device in the Place immediately.

PDK console users/cards are kept after deletion. If you register PDK in the same Place again with Apply, the initial sync runs again and brings the PDK credentials back.

9. Input Rules — At a Glance

10. Troubleshooting

10.1 The Sync Plugin Item Is Missing in the Left-Side Menu

• Confirm the Sync Plugin toggle under Settings > Basic > Services is ON (see chapter 4)
• If you changed the toggle but did not save, save the change and refresh the screen
• Confirm you have Place Admin permission — the menu itself is hidden without permission

10.2 Apply Fails

10.3 PDK Changes Are Not Reflected in CLUe

• First, run a Test Call in 6.5 to confirm PDK authentication works
• Check whether the registration card's Last Webhook Received timestamp is updating — that is the key signal of automatic propagation 7.1 (see 10.6)
• Run a Manual Full Sync in 7.2 once to force the data to be pulled in again
• If it still does not reflect, contact the operations team

10.4 Access Works but Cards Are Not Recognized

• Whether the Card Type / Facility Code matches PDK's card-issuance policy
• Whether device propagation has completed after a card-format change (a short delay is possible right after a change)
• Whether the card data on the PDK console is actually issued to that user

10.5 Switching from Another Plugin → PDK

• A Place can host only one kind of Plugin. Delete the existing Plugin via 8.2 first, then register PDK fresh.
• At the moment of switching, the Place's existing synced credentials are all removed and resynced from scratch against PDK. Plan the switch with operational downtime in mind.

10.6 PDK Webhooks Are Not Received (Last Webhook Received Not Updating)

This is the most common cause of automatic propagation (7.1) not working.

• Confirm in the PDK console that the System's subscription is active
• Availability of the CLUe MSA Webhook endpoint — repeated call failures on the PDK side can disable the subscription. In that case, refresh the subscription by re-applying via 8.1.
• As a first action, recover any missed changes with the Manual Full Sync in 7.2, then perform the checks above.