CDS - Custom Procare Extra - ZKTeco Door Controller

We are requesting an enhancement to develop a Procare Extra that integrates with the ZKTeco ZKBio CVSecurity 3rd-Party API, enabling Procare users to manually (or optionally automatically) synchronize keyless entry codes with supported ZKTeco access control devices (e.g., QR502V).

This integration will support:

• Syncing personnel and KES codes from Procare to ZKTeco

• Assigning access permissions based on school-level access/exposure settings

• Removing personnel from ZKTeco when access is no longer valid (based on account status)

🛠️ Functional Requirements

1. Trigger Mechanism

• A manual button to initiate the sync will be provided in the Procare Extra interface.

• An optional checkbox ("Run every 15 minutes") will allow scheduling a recurring job, disabled by default.

2. Data Collection

When triggered, a stored procedure will execute and perform the following for each row in [Procare].[dbo].[G_KESPerson]:

• Fetch PersonID

• Join with G_Person to retrieve:

  • Name

  • Gender

  • Date of Birth

  • Photo (optional)

  • Contact Info (optional)

• Determine KES Code (KESCode)

• Check active school association by identifying all SchoolIDs the person is associated with via:

  • The Visible Accounts logic

  • Join with AR_Account to verify account is active

The data is then mapped to ZKTeco's required format for syncing.

🔁 Integration Logic

✅ For active users:

For every user with valid access:

• Call POST /person/addPersonnelBasicInfo

  • pin: PersonID

  • name: From G_Person

  • cardNo: KESCode

  • accessGroupIdList: Mapped from list of SchoolIDs

  • Optional fields: gender, birthday, phone, email

• If the user already exists in ZKTeco, the API will update their info.

❌ For users no longer associated with an active account:

• Call DELETE /person/delete/{pin}

  • Removes the person from ZKTeco

  • Further review of the API is necessary, but transmitting someone with no active school associations may also revoke access, removing the need for an additional delete check.

This ensures that access is revoked when a user no longer has a valid, active association.

🔐 API Endpoints Used

🔄 Access Group Mapping

Each SchoolID in Procare will map to a ZKTeco Access Group ID. A simple internal mapping table will be created (or hardcoded) for lookups:

sqlCopyEditSchoolID | AccessGroupID
---------|---------------
1001     | 3001
1002     | 3002

⚙️ Proposed Architecture

1. Stored Procedure pulls:

   • PersonID

   • KESCode

   • SchoolIDs

   • Active status from AR_Account

   • Person info from G_Person

2. .NET Core microservice or Procare Extra runner:

   • Authenticates to ZKTeco API

   • Iterates through the results:

     • Calls addPersonnelBasicInfo or delete as needed

   • Logs results and errors to local directory

   • Optionally logs results and errors to BAM..ProcareErrors

🧪 Edge Cases

• PersonID exists in ZKTeco but is no longer in G_KESPerson → Delete

• PersonID has no valid SchoolID or account → Delete

• PersonID is present but with modified KESCode or school list → Update

📈 MVP Scope

This enhancement focuses on:

• One-way push sync only

• No UI management inside ZKTeco (CDS will manage the ZKTeco side)

• No inbound transaction/event sync

✅ Benefits

• Securely extends Procare’s KES infrastructure to external devices

• Reduces need for double data entry

• Enforces centralized access management using existing Procare logic

• Flexible and scalable: future automation and bi-directional support can be added later

• Allows CDS to fully transition to Procare as an all-in-one solution