Reference17:Concept App Service Connector for Datafox

From innovaphone wiki
Jump to navigation Jump to search
FIXME: This article is still work in progress
FIXME: This product is in the alpha phase and is not yet finished

Applies To

  • innovaphone System (PBX/AP) from version 16r1 upwards

Requirements

  • innovaphone PBX
  • innovaphone AppPlatform
  • innovaphone myApps
  • innovaphone Working App from Version 16r1 SR6 upwards
  • Datafox time recording / access terminal with HTTP(S) communication enabled (configured with Datafox Studio)

Licensing

The Connector for Datafox itself does not require a license. However, every user who tracks their working time with a Datafox terminal needs the following license for the Working app.

  • ID: App(innovaphone-working)

Concept

The Connector for Datafox connects Datafox time recording terminals to the innovaphone Working app. Employees clock in and out at the terminal with their badge (transponder) or a function key, and the bookings are transferred to the Working app as working times of the assigned PBX user. In addition, the terminal can show the current overtime balance of the user.

How it works

The Datafox terminal sends every booking as an HTTP(S) request (webhook) to the Connector for Datafox. The connector identifies the user by the badge ID, looks up the assigned PBX user (SIP name) and starts or stops the working time of this user in the Working app. The terminal then shows a short confirmation on its display.

The following function keys are supported:

  • 1 - Clock in (start working time). The terminal shows "Willkommen".
  • 2 - Clock out (stop working time). The terminal shows "Auf Wiedersehen".
  • 3 - Show overtime balance (read only, e.g. "Saldo: +3.2h"). Nothing is booked.

The time recorded by the terminal is transferred to the Working app, so bookings that were stored offline on the terminal and sent later are booked with their original time. If the Working app is not reachable, the bookings are stored by the connector and transferred automatically in the correct order as soon as the connection is available again.

Bookings of badges that are not yet assigned to a PBX user are not lost. They are shown in the list of unknown IDs in the app and can be assigned to a user there.

The connector also keeps a list of all terminals that are in contact with it (serial number, IP address, last contact). From this list, a remote reset can be sent to a single terminal.

Apps

App (innovaphone-working-datafox)

The Settings plugin enables the following parameters:

Websocket
Connection between the PBX and the App Platform.
Services
API which is used to get access to APIs provided by other App Services. The Connector for Datafox needs it to find and connect to the Working app service.

The app itself is used by administrators to manage the assignment of badges to users, to check the bookings and to manage the terminals:

Users & Access Tokens
List of the assignments between PBX users (SIP name) and badge IDs. Assignments can be added, edited, deleted and filtered by SIP name or badge ID.
Auto-confirm
If enabled for an assignment, the working times booked at the terminal are marked as confirmed in the Working app.
Import CSV
Imports a list of assignments. Format: sip;mac;autoConfirm, one assignment per line, separated by semicolons. A header line sip;mac is skipped. The column autoConfirm is optional (default: enabled). Existing badge IDs are updated.
4-byte conversion
Converts decimal badge numbers into the 4-byte value that is reported by the terminal, e.g. if the number printed on the badge differs from the ID sent by the terminal.
Bookings
History of all bookings with their status (pending, succeeded, failed, overlap). Overlap means that the Working app rejected the booking because it overlaps with an existing working time.
Unknown IDs
Badge IDs used at a terminal that are not assigned to a user yet. An ID can be assigned to a SIP name or dismissed.
Show devices
List of all known terminals with serial number, IP address and time of the last contact. With the switch Maintenance, a remote reset is sent to the terminal the next time it contacts the connector.

Install

  • Install the Connector for Datafox via the App Installer Settings plugin.
  • Create a new PBX Object for the Connector for Datafox with the Settings Plugin of the Connector for Datafox.
    • Configure a name and SIP name
    • Select the templates (config objects) of the users who should get access to the app.

Set up

Datafox terminal

The terminal has to be configured with Datafox Studio to send its data records via HTTP(S) to the connector. Please refer to the Datafox documentation "Data protocol HTTP(S) communication" for details.

URL
https://<AppPlatform>/<domain>/<instance>/datafox (URL of the app instance followed by /datafox)
Method
GET (recommended) or POST
Authentication
HTTP Basic authentication, if enabled in the configuration of the connector (see below)

The data record of a booking has to contain the following fields:

action
Function key: 1 = clock in, 2 = clock out, 3 = overtime balance
mac
Badge (transponder) ID
df_serial
Serial number of the terminal
Timestamp field
Date and time of the booking, e.g. Datum (name configurable, see below)
Label field
Optional label that is transferred together with the booking (name configurable, see below)

It is recommended to enable the system variable http.record_state on the terminal, so the connector can recognize records that were stored offline or sent again. The terminal should also send the Alive table regularly, so it appears in the list of known devices and can receive a maintenance reset.

Configuration

The configuration is done in the Settings plugin of the Connector for Datafox with the button Configuration.

Timestamp field name
Name of the column in the Datafox data record that contains the time of the booking (default: Datum).
Label field name
Name of the column in the Datafox data record that contains an optional label for the booking (default: Label).
Require Basic Auth
If enabled, the terminal has to authenticate with HTTP Basic authentication.
Basic Auth user
User name the terminal has to use.
Basic Auth password
Password the terminal has to use.

The time of the terminal is expected in the time zone Europe/Berlin. If the time of the terminal differs by more than 10 seconds, the connector sends the current time to the terminal.

Troubleshooting

If problems occur, please send us a log of the app service. Before reproducing the issue, delete the current contents of the log. The following trace flags should be enabled:

  • App
  • App Websocket
  • Webserver traffic (only in case of communication problems with the terminal)
  • Bookings are not transferred: Check the list Unknown IDs. If the badge ID is listed there, it is not assigned to a user yet.
  • The terminal sends the same booking again and again: Check the URL and, if enabled, the Basic Auth credentials on the terminal. The terminal only removes a record if the connector confirmed it.
  • Bookings have the status overlap: The Working app rejected the booking because it overlaps with an existing working time of the user. Correct the working times in the Working app.

Known issues

  • The overtime balance is only shown on request (key 3), not automatically when clocking out.
  • Texts on the terminal display are currently German only.

Related Articles