Interaction with access control

Function types

When a ZK backend operates in online mode, written data is transmitted and processed directly. Any errors are acknowledged negatively by the system and the logic anchored in the James can react accordingly.

Query status interface

Query system status

Batch processing
In batch processing, usually when processing CSV files (also XML, etc.), a batch of data is stored in a communication directory. James has no knowledge of the time of processing, nor of the success or failure of the process. The average latency until the actual transmission and application of changes can have a negative effect on the security concept and should always be considered!

Querying the status of hardware

Some ZK systems offer the possibility to query the status of hardware components directly via the API. This system status can be used, for example, to chain workflows for critical system parts in the event of a failure.

Time profiles

Time profiles may be of interest to the badge office. The query of the time profiles can be used to determine individual access rights more precisely. The query is read-only in the standard interface. Some CC systems can associate a camera/camera source with a door. This may be of interest to the Global Desk or the WebApp. Query sample / random check metaSEC James offers the sample function as an extension/upgrade of the CC system. However, some ZK systems offer the functionality out of the box. in which case the ZK system side function would be used.


The query of individual doors and their states is an important requirement for the interface. This is accordingly necessary for granting deviating individual authorisations.

List of doors
The listing of doors is optional, but necessary for issuing special authorisations for a cardholder. As far as supported by the ZK backend, a special authorisation can be managed both as a positive and as a negative list.

Door status query
Analogous to the relay control, the query of the status of a door is necessary for possible controls or visualisations. The status of a door can generally have the following states: - Open - Permanently open - Closed - Locked - Timeout / Alarm
The respective states depend on the ZK Backend.

Manual door control
Analogous to relay control, manual interaction with a door can be important. The control of a door is brought about by a corresponding status change.


Events are actions that can be emitted or received by ZK Backend. Depending on the flow direction, the other side can link this event with further actions. A simple example is that an action is executed when someone presents a token to an unauthorised door.

Query event log
Query a list (total or filtered) of the event log. The list may differ from backend to backend.
In the simplest case, the output receives the following fields: Date, Time, Eventtype, Description, Eventsource.

Subscritpion to a singular event
As long as the backend runs in the online module, a so-called subscription to certain event types can be created. This has the advantage that the programme does not have to receive and process all events from the system. The support for event subscriptions is backend dependent.

Relay control

In addition to door controls, some ZK systems also support pure relay / IO modules. These are divided into simple relays or digital input/output contacts.

The contacts can be used either in the Global Desk for manual interaction or in workflows. List of available relays Lists the available contacts. The structure of the list is, Contact type (Relay, Digital IN, Digital Out) Status query Query a single contact or a list / array. This is particularly important for visualisations.

Control of IO states as far as supported, status change for relay contacts, rsp digital Out.
The status of digital input contacts cannot be changed. An event can only be generated here in the event of an external status change - see chapter 'Events'.

List of access areas

The list of all zones/areas created in the ZK system is necessary information for creating a cardholder with the corresponding access profile. The list corresponds to a collection of doors that is created and managed by the ZK system. Access to the access areas is read-only.

Identity Management

Creation of identity/card holder
The creation of a new identity in the ZK backend requires at least the above-mentioned mandatory fields. Depending on the system, additional fields may be required. If this is the case, these requirements are specifically intercepted and completed in the driver. If the interface communicates online (see chapter Function Types), errors can be intercepted directly. With batch processing, e.g. via CSV files, the success of processing cannot always be reliably determined. Most systems return the internal ID of the card object as a return value when the card has been successfully created. This ID is stored internally in the James database.

Modification Identity/Cardholder
Depending on the functionality of the interface (online/stack), a modification of the properties is processed in real time or delayed. The process itself is analogous to a system. With batch processing, there is a system-related latency until the change (e.g. access profile) is processed in the ZK backend and actually takes effect! This must be taken into account in the security concept.

Deletion of identity/card holder
Depending on the functionality of the interface (online/stack), a deletion of an identity is processed in real time or with a delay. Depending on the CC system, other data (e.g. movement types, logbooks, etc.) remain in the system. This may give rise to issues relevant to the GDPR. With batch processing, there is a system-related latency until the change (e.g. access profile) is processed in the ZK backend and actually takes effect! This must be taken into account in the security concept.

Specification metaSEC James ZK Interface

This document describes the general requirements for a connected electronic access control backend (hereafter referred to as the CC system) from the point of view of the James badge centre as well as the visitor management processes.

Not all ZK systems support all function calls. Missing functionalities in the ZK product cannot be compensated for by the badge logic.

An interface or the communication via it is optimally done in real time via a direct data communication (tcp connection, RESTFULL API, SOAP, etc.). Direct communication allows conclusions to be drawn about the success or failure of a system call within the interface.

metaSEC James can manage several ZK backends at the same time and record them with data. A list of currently supported access control products and their respective versions can be obtained from support.

Identity/Cardholder Data Fields

The following fields can be processed by the James interface:
Field Type Mandatory field Description Name Char Yes Name of cardholder First name Char No First name of cardholder Validity Date No Validity of card/start date Card number Char, Array Yes Card number of card/tokens.

IMPORTANT: the same card can return different serial numbers at different readers. There may be a need for card mappings here.

Authorised area Array Yes Authorised areas within the CC system for the cardholder Authorised door Array No Authorisation to a single door(s) Expiry Profile date No Validity of the card/expiry date Photo Blob No Photo of the cardholder Pin Int No PIN code for the card/multi-factor profiles
Attached Files
JAMES_IT Architektur_2022.pdf