Purpose of the integration and division of responsibilities
The plant has an access control system with readers and cards, and a working time records system. InnerWeb is an independent complementary system: it receives tap events, links them with qualifications, permits, attendance and working time records, and does not replace the KD, the RCP or HR.
InnerWeb does not manufacture or replace readers. The integration specification is intended for the KD supplier, because it is the supplier who configures the sending of events. The plant's task is to make sure the supplier receives the specification and access to a test environment.
Event fields: what the KD supplier should send
A card tap event contains, among other things, the time, the place, the first and last name, the company, the number of the active card, the phone number, the e-mail address and the language of the person. Not all fields may be available in the KD system, so the specification is agreed at the level of mandatory and optional fields.
The practical minimum is the time of the tap, the place (gate or reader) and the identifier of the person: the number of the active card. The remaining fields make it easier to match the person to an account, but personal data should be passed only to the extent necessary and in line with the plant's legal basis.
- time of the tap with a time zone designation
- place: identifier of the gate or reader
- number of the active card
- first and last name, and company, if the KD system stores them
- language of the person, if it is to be used for messages
Sample schedule for the webhook integration (assumption)
Authentication: a token with a limited validity period
InnerWeb receives the card tap event through a webhook authenticated with a token that is valid for a limited time: 12 hours. The KD supplier must therefore plan the renewal of the token before it expires, not only after an event has been rejected.
The specification should state who renews the token and how, what happens to events sent after expiry, and how the supplier learns about an error. Good practice is a queue on the KD side that retries sending when delivery has not been confirmed.
The token must not be stored in a plain configuration file or in the text of a service request. It is passed through a channel agreed by the IT departments of both sides.
Sequence of work: from test to production
Stage one: the KD supplier receives the specification and the data of the test environment. Stage two: sending test events from one gate, and checking the fields and the time. Stage three: sending from all gates of one hall. Stage four: switching on the whole plant and comparing the number of taps on both sides.
Comparing the number of taps is the key test: the number of events sent by the KD and received by InnerWeb in the same time window should be the same. Differences are analysed by gate and by hour, because they often point to a specific reader or to the moment a token expired.
Pitfalls: time, duplicates and taps without a person
The first pitfall is the time zone: a tap time recorded in local time without a time zone designation gives an error of one hour during the change of clocks, which in working time records looks like an overtime hour. The time should be passed with its time zone designation.
The second pitfall is duplicates: the same card tapped twice within a few seconds, because the reader read it both on entry and on exit. The filtering rules are set with security, not in the integration code.
The third pitfall is taps without a person: a card number that has no assigned account, or is assigned to a duplicated account. Such an event goes to the list of exceptions, and the check of duplicate account pairs after importing cards reduces their number.
Acceptance and maintenance
Acceptance ends with a protocol: the list of gates, the result of the comparison of tap counts, the test of token expiry and renewal, and the test of a communication link failure. Maintenance means an alarm for the absence of events from a gate during the hours when taps normally occur, because silence from one gate is often the first sign of a fault.
The plant should name the person who receives the alarms, and the KD supplier who resolves them on the side of its system. Without this the integration works until the first problem occurs.
When the plant is extended with a new hall or gate, the KD supplier adds the new readers to the sending configuration, and the plant updates the list of places so that events from the new gate do not arrive as taps without a location. Changing the list of gates should be a step in the change procedure, as mandatory as ordering a reader.
Video
Frequently asked questions
Does InnerWeb replace readers?
No. InnerWeb integrates with the plant's existing KD system, and the specification is intended for its supplier.
How long is the webhook token valid?
12 hours, so the KD supplier must plan its renewal.
What data does a tap event contain?
Among other things the time, the place, the first and last name, the company, the number of the active card, the phone number, the e-mail address and the language of the person, within the scope agreed with the plant.
How do you check that the integration works?
Compare the number of taps sent by the KD and received by InnerWeb in the same time window, by gate.
Sources
Pass the specification to the KD supplier
We will prepare the specification of fields and authentication for your KD supplier and a test plan for a single gate.
Let's talk