APP Time Clock

Owned by Halvard Meijer
Last updated: Aug 29, 2023 by Konstantin Gerasimov
17 min read

This article explains everything you need to know about the Time Clock.

Introduction

Adonis Time Clock is an application designed to simplify the hourly registration onboard by using the principle of clocking in/out work hours.
To access the Adonis Time Clock working area, crew members can either enter their current pin and passcode or use a swipe card.

System Architecture

To enable the Time Clock to communicate with Adonis Personnel Manager database, the Time Clock Web Service (AdonisTimeRegSrv) needs to be installed.

  • The Time Clock Web Service is a part of the Adonis Personnel Portal (APP).

In addition, the APP contains the Adonis Administrator Portal that allows an onboard administrator to centralize maintenance of time clocks, including schedule of upgrades and Time Zone changes.

See Configuration of the Adonis Time Clock Client Software section.

Example Service URL: http://server/AdonisWebServices/TimeClockWebService.svc

  • Where server is a server name or a server IP address where Time Clock Web Service is installed.

Minimum System Requirements for Installation/Using TimeClock
The Adonis TimeClock is installed on Panel PC that is located on strategical locations onboard.

  • Strategical location means the location where crew members need to pass when going to and from their work location.

Requirements:
•CPU 1.6 GHz or better recommended.
•512MB of RAM minimum (1GB or more recommended).
•50MB of available hard-disk space.
•Windows XP Service Pack 3, Windows Vista, Windows 7/8/10.
•.Net Framework 4.0 or higher.
•Display resolution (1024x600, 1024x768, 1366x768) with Touch Screen (optional).

Continues Operation when Server is Unavailable
The Time-Clock uses a local cache and will function even if the database or the Time Clock Web Service is offline. 

The timeclock stores approx  18K transactions or swipes per Mb.

The moment the Time Clock Web Service is back online, the Time Clock will upload the cached information back to the server.

Together with a proper UPS on the panel PC, 99% uptime can be reached.

The Adonis Personnel Portal
See separate documentation.

Aspect ratio

This is important for the readability of the time clock application, it not responsive and the following Aspect Ratio are supported. 

  • 4:3

  • 16:9

  • WSVGA

  • 3:2

Most panel pc are delivered with these ratio, if the ratio is not listed let development know we can modify the skin to fit the new ratio

Skins and resolution

Skin

Resolutions/Aspect Ratio







Skin

Resolutions/Aspect Ratio







Modern

1024 x 600 (WSVGA)

1024 x 768 (4:3)

1366 x 768 (~16:9)

1368x923 (3:2) 

Default

1024 x 600 (WSVGA)

1024 x 768  (4:3)





CCI

1024 x 600 (WSVGA)

1024 x 768  (4:3)

1366 x 768  (~16:9)



Adonis

1024 x 600 (WSVGA)

1024 x 768  (4:3)





Classic

Any resolution







Housekeeping

After installation, Time Clock configuration can be done in any of the ways:

  • From panel PC (with admin credentials);

  • Via Time Clock Maintenance tool (in APP).

Configuration parameters are stored in the Settings.xml file in the folder where the application is installed.
See details in below sections.

From Panel PC

To access the Configuration page specifically intended for administrators, log in using the following data:

  • PIN: 0000

  • ACCESS CODE: 1266472012
     

Once accessed, the Config Window then appears on the screen. By switching between the tabs, you can check cache, HTTP communication log, time registration queue and program settings:

Now, let us examine the configuration settings as well as cache and log files in more details.

General Settings

Switch to the General Settings tab to view the settings:

Below you can find the description of the settings:

  • Remove border from main screen. Select the checkbox to remove the standard windows border. It is recommended to use this option when displaying the application on a panel PC in the Kiosk Mode.

  • Stay "Debug" window on top of main window. Select the checkbox to display the Config Window on top of other windows.

  • Hide mouse cursor (for touch screens). Select the checkbox to hide a mouse cursor. The option is intended for touch screens of a panel PC.
    It is recommended to clear the checkbox when running the application on a laptop.

  • Disable display dim, turn off and sleep mode while application is running. Select the checkbox to prevent the panel PC from disabling the screen or going into sleep mode.

  • Data folder. The field contains the path to the directory where the application data is to be saved. The data folder is used to store the local cache. When the server is unavailable, the Time Clock registrations are stored locally and transferred to the server once it is running again.

     

    Make sure the application has the read/write folder permissions.

  • Use Time Zone table. The setting is used to determine the time zone. When selected, the application checks the time zone on the server. If the option is not selected, the panel PC is to be manually reset. Adonis Time Clock then uses local time onboard when registering the time clock transactions.

  • Enable Gangway. Select the checkbox to enable the Gangway registrations (sign on/off or offshore visit). For more information on the Gangway functionality, switch to Gangway.

  • SignOff button visible only on Estimated End Date. Select the checkbox to make the Sign Off button available on the panel only on the estimated end date. If the checkbox remains unselected, the Sign Off button is available if a crew member is onboard.

  • Location. Enter the location of Adonis Time Clock.

  • Main window skin. From the drop-down menu, select the skin you want to be displayed to the main page.

  • Confirmation screen visible time. Set the number of seconds after which the Confirmation dialog will autoclose.

  • Admin pin. The default pin number that allows accessing the Config Window is set to 0000.

    We do not recommend changing the pin number. In case you do, make sure that:

    the pin does not intersect with APM pin numbers  or the pin starts with 0

  • Admin password. The default access code that allows accessing the Config Window is set to 1266472012. To change the password, clear the fields with the current password and enter a new password twice. Once done, select the Show Password checkbox and verify that the entered passwords match. To reset the password to the default value, click the Default button.

  • Exit Application. Click the button to exit Adonis Time Clock when running it on a panel PC.

  • Help. Click the button to get redirected to the Adonis Time Clock user guide.

Network Settings

Switch to the Network Settings tab to view the settings:

Below you can find the description of the settings:

  • Web Service URL is the path to the TimeClock web service. It is used to communicate with the Adonis Database

     

    To activate the web service, make sure you have Adonis Personnel Portal installed.

  • Allow untrusted certificate. Select the checkbox to allow connecting to the Web Service with an untrusted certificate. For example, self-signed certificate.

  • Offline cache timeout (ms). Specify a time interval (in milliseconds) the application waits for the server to reply before it starts using offline cache to update user interface. The default value is1000.

  • Cache refresh interval (sec). Define the time period in seconds for refreshing cache. The default value is 900.

  • If cache refresh time fails, retry in. Enter the time period (in seconds) in which the application makes an attempt to refresh cache in case the update fails. The default value is 30.

  • Try to send queued item every. Enter the interval (in seconds) between the attempts of queued requests to be sent in case the previous attempt has failed. The default value is 30.

  • SyncSettings interval (sec). Specify the number of seconds Adonis Time Clock checks the server for any configuration settings. The default value is 60.

  • Remove Registration from queue in. Enter the number of days after which the failed registrations will be removed from the queue. The default value is 15.

Card Reader Settings

Switch to the Card Reader Settings tab to view the settings enabling you to define:

  • how to communicate with a card reader

  • where the information is stored on the magnetic strip

Below you can find the description of the settings.

Card Reader Settings:

  • Enable card reader debug mode. Select the checkbox to display all the card data on the main screen. The debug mode allows you to see an input string coming from the magnetic strip.

  • Require password if card used. Select the checkbox to ask for an access code after a card is used. Otherwise, the next screen will be shown without checking an access code.

  • Log card reader events to log. Select the checkbox to store all card reader events in the log file.

  • Pin extraction params:
    Line number is a line on a card where the pin number is located. Define the magnetic strip row that contains the pin number.
    Start Position is a character number from which the pin number begins on a card. Use the start position and length to determine the location  of the pin number in a line or a row. The default value is 4. 
    Length is the length of a pin number on a card. The default value is 3.

Serial port input settings. Select the Enable Card Reader input from Serial Port checkbox to configure a com port in case a card reader is connected to the panel PC via the com port. Check with the card reader supplier about the com port settings to be used.

Keyboard input settings:

  • Enable Card Reader input from Keyboard. Select the checkbox if the magnetic input is sent via the keyboard buffer.

  • "End of input" card key time out (ms). Specify the time in milliseconds after which the application clears an input buffer and starts processing the received card data if no key has been received within the specified time interval. The default value is 200.

RFID Card Settings

Before getting started, make sure the following information is provided to you by the card supplier:

  • Key A

  • Key B

  • MAD Application Identifier

  • TimeClock Sector

Below you can find the description of the settings.

MIFARE reader settings

Select one of the card reader models:

  • Enable MIFARE Card Reader. Select the option to specify the card reader model in use and select the correct card reader in the Card reader field.

  • Enable MD150 MIFARE Card Reader. Select the option to specify the card reader model in use and and select the correct port name in the Port name drop-down list.

  • Enable ZCS100 MIFARE Card Reader. Select the option to specify the card reader model in use. If you use this card reader, please note that when crew is swiping, it's required that the TimeClock window will be in focus/active (it works like 'keyboard'; what window is active, where the data from card is inputted).

All 3 models can read and initialize the pin codes.

MIFARE Application Directory (MAD) vs TimeClock Sector

The application directory on Sector 0 contains the overview of the sectors used by the various applications that can program the card.

The application identifier is used to find the sector used by Adonis TimeClock.

There is the card supplier, for example: LabelCraft, that needs to provide a customer with the application id that can be used by Adonis TimeClock.

It is not required to use MAD/sector 0, in this case the Adonis TimeClock needs to know the sector to write and read the pin number from.

Again, it is the third party supplier that needs to supply the free sector.

So, If the MAD is used, then enable the Look for TimeClock sector in MAD option and enter the MAD identifier in the respective MAD Application identifier field in hexadecimal. The identifier is required to find the sector where the pin number is located.

  • Read Key is a security key required to access the sector where the PIN is stored (read the data). The key must be specified in the hex format.

  • Data prefix is used to ensure that a pin number is read (not a random number that can be interpreted as a pin number). Data prefix prevents from reading unprogrammed or wrongly programmed cards.

  • How to store the pin number on RFID card:
    2bytes that is the prefix that is placed in front of the pin number.
    It uses 2 bytes. The remaining 4 bytes are used for the PIN number.

  • If this prefix is not used (it is only pin on the card) please input '0' 

  • If the MAD is not used, then select Specify TimeClock sector and identify the sector that will be used (a value from 1 to 16). 

  • Pin is in ASCII format. Select the option if pin is needed to be read in text format or clear it if in decimals.

MIFARE program settings

Set the Program Time Clock Sector check-box and enter 2 keys:

  • Key A allows reading information from the sector where the pin is stored. 

  • Key B is provided by the third party supplier.

Select the Format TimeClock Sector checkbox. Use the option only if the cards are not used by any other supplier. The keys in the Before Format Key A and Before Format Key B fields are used to write the sector for the first time. Then it encodes the sector with the keys found in TimeClock Sector Key A and TimeClock Sector Key B. Each sector has 2 keys to be read (A, B). You can change these access keys.

From Release 2018.2.1, it has become possible to program the RFID card directly from Adonis TimeClock, without any need to address the third party suppliers.
For more information, see Working with RFID Card.

Working with RFID Card

From Release 2018.2.1, it has become possible to program the RFID card directly from Adonis TimeClock, without any need to address the third party suppliers.
When the Time Clock cannot detect the crew members pin number when scanning the RFID card, it will prompt the end user to initialize the card.
The system will then guide the crew member through the process to program the card:

Click Yes. On the next screens, enter your PIN number and use PIN+Year Of Birth as passcode:

Follow instruction:

Press OK

Initialization is finished.

Cache, Log Files

The following tabs list the contents of the cache, local log files and registrations:

Pin Cache

All crew members that are currently onboard (employees with an onboard activity) are cached:

Here we can find Pin and Name.
Access Denied:

  • If True – a crew member failed to log in

  • If Fasle - a crew member suceesfully logged in 

Crew Portal User:

  • If True – a crew member has an account in APP (record is in WEB_CP_ACCOUNT table);

  • If Fasle - a crewmember has an account in APP.

You can search by pin/name.

We can see that now there are 410 pins (in Total) in the list with 4 wokrtypes; last/next cache update date/time.

Click Update Cache Now button to perform refresh immediately.


Work Type Cache

The work types an employee can select during registration:

Work types can be added in the Adonis Administrator Porta

Action Cache

Is used for Gangway functionality:

Is visible only if Enable Gangway option is ON at General Settings tab.

Time Zones

Here we store the various time zones and local onboard time changes:

The active/in use Time zone is highlighted green.

Time zones can be added/managed in the Adonis Administrator Portal.

Operation Log

All communication between the server and the TimeClock is logged, as well the communication with the com port or card reader:

Here you can check Date/Time, Action description, Status, Duration (in sec.) and actual Result of any operation.

Time Reg Request Queue

Contains all the cached time entries made in the Time Clock/panel PC during the time the server was unavailable.
It means that even if Panel PC is off-line, crew members can continue swiping and making registrations.
We can call them 'pending registrations'.

The queue contains Work Start Time, Pin, selected Work type, Status, number of Attempts and detailed information why the request was not uploaded to the server (with waiting Status) or if the registration succeeded after server became online (Sent status).

  • This queue is empty when the server is available (no current pending registrations).

  • From here you can remove unneeded registration by right-clicking the record:


Centralized Maintenance (APP)

From the Administrator Portal, you can maintain various Time Clock installations onboard.

  • You must have admin rights.

Start the Administrator Portal and go to tool:

  1. Displays the overview screen (TimeClock Status).
    From this screen, you can then modify the various configuration settings for one or more panel PCs.

    See TimeClock Overview section.

  2. Upload update files. This gives you the possibility to upgrade time clock(s) remotely.

    See TimeClock Update section.

TimeClock Overview

Displays the overview screen listing all installed Time Clocks onboard.
From this screen, you can modify various configuration settings for one or more panel PCs, set notifications and schedule automatic upgrades:

  1. The list of Time Clocks installed onboard with Location, Status (online or offline), Version, IP address and Notification Status data.
    Here you can tag needed one(s) to work with.

  2. Refreshes the overview screen.

  3. Here we can enable notifications to inform if any of the Time Clock is offline:


    For this, Notification Service needs to be previously installed.
    If we set the checkbox, the following Notification Task Form appears: 




    Please define:
    Notification Interval (in min.) – Notification Service checks if any panel PC is offline for the set period, if so - sends the list of offline PCs. 
    Recipient email (s); 
    Email Subject and Body (instead of {OFFLINE_TIMECLOCK_TABLE} will be the list of PCs with Offline status). 

    Click Save.

  4. Displays the settings screen for one or more timeclocks (depends which you tagged in the list).
    The following tabs are available: General Settings, Network Settings, Card Reader Settings and RFID Card Settings:



     For all details: see From the Panel PC section. 

  5. Update screen
    This allows you to schedule the upgrade.


    Enter the date and time you want to upgrade the TimeClock and select the update file.
    File needs to be previously uploaded to appear in the drop-down list.
    See TimeClock Update section below.

  6. Here we can disable offline notifications for one/several tagged PCs:



    For example, this can be useful if the administrator knows about a breakdown/problem with some panel PC, and while it is being fixed, he does not want to receive offline notifications.
    For this, set the checkbox and define the Date/Time from or choose from Now. 
    Also set duration period Disable for (in min.). 
    Offline TimeOut – if during this period the system does not receive SyncSettings request from the TimeClock(s), the TimeClock state/status becomes offline in the Timeclock Maintain Tool – TimeClock Overview screen. 
    Please pay attention: Offline TimeOut value must be set more or equal to Sync Settings interval (the number of seconds the Time Clock checks the server for any configuration settings) set on Network Settings tab. 
    Default value: 2 minutes.
    When you're done, click Save.

  7. Click to restart tagged panel PC record(s) in the TimeClock overview list.

  8. If you want to remove unneeded records (panel PCs that are not used any more), tag records in the list and click Delete
    If you deleted some real/online record by chance, the system returns it in the list after refreshing (TimeClock is run on this panel PC).| 

TimeClock Update

You have a possibility to schedule the upgrade of time clock(s) remotely via APP.
You need:

  1. Save update file locally;

  2. Upload it into APP;

  3. Schedule an upgrade.


Step 1: Save the file
Go to FTP > UpdateViaMaintainTool folder, save the special update file like:

  • It differs from common exe. file by absence of 'install' part of the name:



Step 2: Upload the file
To upload an update file, please go to screen:

Click Browse to upload needed files (exe.), previously saved in your local folder.
Click Upload button.
This file will appear in the list.


Step 3: Schedule
The upgrade is scheduled using the Update function under Timeclock Overview > Update tab:


Update screen:

Enter the Date and time you want the TimeClock (selected on overview screen) to be upgraded.
Select the update file.

Special update file needs to be previously saved/uploaded to appear in the drop-down list.
Click Update to save your settings.

This day/time selected timeclock(s) will be silently upgraded.

Only if timeclock is on-line.

If it's offline for some reason, upgrade will be performed immideately after it backs on-line

Installation

To start the installation, go to the download area of our web site or to your ftp area and download the latest version of Adonis Time Clock.
Once the download is complete, go to the downloaded path and double-click the installation file to launch a setup wizard.

The administrator rights are required when installing Adonis Time Clock.


Step 1

The Welcome dialog appears on the screen:

Click Next to continue.


Step 2

Define the network settings.

Fill in the fields as described below:

  • Please enter Web Service URL. Enter the web service URL with the correct server address that looks like:

    http://server/AdonisWebServices/TimeClockWebService.svc
    In the URL, server is a name of the server or an IP address of the computer on which the Adonis Time Registration Service is installed.

  • Select Data Folder. Set the folder where the application stores the saved data (cache, logs, etc.).

    A user must have write access to this folder.

  • Please enter PanelPC location. Enter the location of the target panel PC.

On completing, click Next.


Step 3

Select the mode which you want to run the application in:

Normal mode. Select the option to run the application in a standard mode (recommended to be used):

  • Run TimeClock on Windows start up. Select the checkbox if you want to open the Adonis TimeClock application on Windows start up. 


Kiosk mode. Select the mode if you want to prevent crew members from accidently starting a different application. Let us consider the mode in details:

  • On setting Kiosk mode, enter the password of the current windows user.

  • The mode allows Windows to make auto logon on startup and will not ask user for a password.

  • If the current user has no password, leave it empty.

 

Step 4

Choose the folder where you want to install the Adonis TimeClock application.
To do this, click Browse… and indicate the path to the destination folder. 

Click Install to continue.


Step 5

The Adonis TimeClock application has been successfully installed on your PC. 

Click Next to finish the installation.

 

Step 6

Click Finish to close the setup wizard:

You can choose to select the Run Adonis TimeClock checkbox to open the application immediately after the installation.

Upgrade


There are two ways you can use to upgrade your current version of Adonis TimeClock to a higher version:

  • By manual run of an executable file. To do this, follow the instructions provided below.

  • Upload an update file and schedule an automatic upgrade in APP. For more information, see TimeClock Update.

To start the manual upgrade, go to the download area of our web site or to your ftp area and download the latest version of Adonis Time Clock. Once the download is complete, go to the downloaded path and double-click the installation file to launch a setup wizard.


Step 1

 The Welcome dialog appears on the screen:

Click Next to continue.


Step 2 

Within the dialog, select the Update TimeClock option:


Click Update to proceed.


Step 3

The update of Adonis TimeClock is successfully completed:

Click Finish to close the setup wizard.

Uninstallation

There are two ways you can use to uninstall the Adonis TimeClock application:

  1. Click Start on the Windows task bar and go to All Programs > Adonis TimeClock > Uninstall.

  2. Click Start on the Windows task bar and go to Control Panel > Programs and Features. In the list of applications, select Adonis TimeClock.

To disable the Kiosk mode, uninstall the Adonis TimeClock application.

Now, proceed with the following instructions.

Step 1

The Welcome dialog appears on the screen:

Make sure the Adonis TimeClock application is not running and click Next.


Step 2

Indicate the directory where the Adonis TimeClock application is installed:

Click Uninstall to initiate the installation process.

Now, you can see the uninstallation in progress:

When completed, click Next.

Step 3

The uninstallation is successfully completed:

Click Finish to close the setup wizard.


See also

https://adonishr.atlassian.net/wiki/spaces/KB/pages/2639103794

https://adonishr.atlassian.net/wiki/spaces/KB/pages/4703027201