Time Keeping Processing. How does it works?

Modified on Wed, May 29 at 7:22 AM

TABLE OF CONTENTS

What is TK Processing, and when does it start?
Get Work Shift
- Get Clock In and Clock Out
Geo Data Processing. Get Activity Periods for Work Shift.
NO GPS Periods
Stops
Drives
State
Process Clock In/Out
Automatically allocate WOs
Audits, Mileage, Recalculate Time Card Payroll Allocation
Manual Allocation

What is TK Processing, and when does it start?

The Time Keeping Processing is a script that handles of GPS data to create Time Entries, calculates Cost Types and Work Order allocation, launches audits, counts mileage and recalculates Time Cards payroll allocation.

This script runs every day and processes yesterday's data.

Note: all Time Entries that you start manually are created on the same day: Clock In/Out, Check In, Lunch, Hours manually recorded on selected WOs.

Get Work Shift

The TK Processing obtains a Work Shift. The Work Shift is:

A time period between Сlock In and Clock Out.
Or a period of time specified with Check In.

Get Clock In and Clock Out

Clock In and Clock Out Time Entries are created immediately after the corresponding actions on the Wall/Non-GPS/GPS devices.

Get Check In or create it

Salary Employees have the “Salary” mobile role. Check In Time Entry can be created several ways:

Salary Employees check in via the app → this adds a Check In Time Entry and creates a Time Card, if one does not already exist for that day and Employee.
Or the Time Card is automatically created by TK Processing according to the Employee category. It can also add a Check In, again based on the settings in the Employee category.
Or the TK Administrator creates a Time Card manually and adds a Check In TE via the corresponding action in the Time Card.

Geo Data Processing. Get Activity Periods for Work Shift.

Check In Time Entry Process

For the automatically created Check In according to the Employee Category, the TK script fills in hours and Cost Type from the Employee TK Configuration.

Wall/Non-GPS device activity periods

A Non-GPS Employee clocks in/out on the Wall or Non-GPS devices: devices that do not collect GPS data.

Clock In and Clock Out Time Entries are created immediately after the corresponding actions on the Wall/Non-GPS devices.

As the device does not collect the GPS data, the activity period is one Work Shift and one Time Entry: from the Clock In to the nearest Clock Out.

Hence, the TE's event is NA, the Cost Type is Office/Warehouse, the Location is the Asset Location.

GPS device. Process No GPS Periods. Find Stops and Drives. Determine State.

GPS Employee clocks in/out on the GPS devices: devices that collect GPS data.
Clock In/Out and manual Lunch Time Entries are created immediately after the corresponding actions on the GPS devices.

The TK algorithm treats the GPS points, taking into account settings such as a period of NO GPS activity, the average velocity.

Based on the processed data, it determines the periods of stop and driving activity, periods without GPS data and creates Time Entries with the corresponding events. On this step, it sets the default Drive Cost Type for all Time Entries with a Drive event.

NO GPS Periods

NO GPS Entries

No GPS is a period during which there is not a single GPS point.

If there is a point, but the interval before and after it is more than 5 minutes (configurable part), then the algorithm cannot determine where the employee has moved to. Such a period is also NO GPS.

The TK gets the TE with No GPS event and the empty cost type → copies the cost type, Site, Site WO and Location from the next closest entry (first from the next one, otherwise from the previous one).

The script also populates a GPS State from the nearest ones, if both the previous and next Time Entries have the similar GPS State.

Stops

1. The algorithm calculates the average velocity — displacement between points within 5 minutes.

From the result, it determines:

Stops — if v < 1 km/h
Slow Drives — 1 km/h <v < 10 km/h

2. Processing Stops inside polygons.

Once the Stops have been identified, the next step is to define the intersection with Sites, Locations polygons.

Site/Location Boundaries

The boundaries of a Site can take many forms: circle and polygon. This allows you to more clearly mark site lines.

The Site/Location boundary is set on the Site and Location card respectively.

The Default Site boundary is a radius of 300 meters, Location — radius of 100 meters.

A Site/Location with 0 radius is excluded.

We call a Site as Main:

if there is a scheduled "Site" WO (we also call it GPS WO) for that Site.
or there is a Site has a WO for unsheduled visit.

The Main Site may have Related Sites.

Related Site – a Site that is listed as related in the Main Site card. A Related Site can also be scheduled, set up as an "unsheduled visit". In this case, it becomes one of the Main Sites.

The cost type will be On Site as usual.

Site WO field in the Stop Time Entry – according to the Sites boundaries and the priority, see next.

On Site Stops

To define a stop as On Site, the script searches for Work Orders linked to a Site based on the following priority.

On Site are Stops within a Site boundary:

that has a scheduled Work Order of the type “Site” (on site work),
it is a related Site to the scheduled WO,
that has a WO of the type “Site” for an unscheduled visit,
it is a related Site to this WO for an unscheduled visit,
it is a Site of a Carrier Group Sites.

A stop may therefore occur within a boundary of several Sites. The script uses this Sites priority to assign a Work Order.

If Sites are equivalent (i.e. both of them have scheduled "Site" WOs), the stop will be assigned to the closest Site.

It fills in the Stop Time Entry: Cost Type = On Site, the Site WO field = the Work Order found. The script also identifies the Stop Time Entry as "Has WOs = true" to further distribute the found WO to the nearest TEs (Drive, No GPS, etc.).

Unscheduled visit to the Site

The script next checks if the Stop is located within the radius of an unscheduled Site → It searches for a Build Plan under that Site that contains a Work Order for an unscheduled visit.

Once confirmed, it sets the following values in the Stop Time Entry:

Cost Type – On Site.
Site Work Order – WO for unscheduled visit.
Unscheduled Visit checkbox – active.

WO for unscheduled visit — a WO specified in the corresponding field of in the BP card. It must be active in order to be populated in the Stop Time Entry during the TK Processing.

It's important to note that the TK script will assign the stop to such WOs if:

There is one WO for unscheduled visit per Site.
There are multiple unscheduled visit WOs per Site.
In this case, the script gets the unsheduled Site
1. Takes BPs under this Site that contain uncheduled visit WOs
2. Takes all WOs under given BPs
3. Check for a unique Financial Account match for the Employee and the Work Order Type among the taken WOs . The Employee's Direct Cost FA = WO Type FA.
4. Assign the stop to the resulted WO

Stops at Office/Warehouse

Stops at Office/Warehouse are

1. Stops within the polygon of the Site that has scheduled "Warehouse" WO.

The script fills in the Site, Site Work Order, Has WOs = true fields in the Time Entry and sets the Cost Type to Office/Warehouse.

2. Stops inside the polygon of the Warehouse location type.

After searching for nearby scheduled Sites, the script will search for close Locations.

If there is a Location within the radius (default 100 meters) of the Stop → it fills in the Location field in the Time Entry. If the Location type found is “Warehouse”, it sets the Cost Type to Office/Warehouse.

Stops at Known Locations

Stops at Known Locations — Stops within the boundary of any other known location (Employee Homes, Material Suppliers, Remote Hotel, etc.).

The Stops and Slow Drives within the polygon of a Site or Location are merged into one Stop. This merged stop is displayed on the map and on the timeline.

The Cost Type is Drive until configured "Unauthorised Time" audits are started.

Unknown Stops

3. Processing Stops outside polygons.

Unknown Stops — Stops outside the Site or Location polygons. For this kind of stops the algorithm will calculate a geometric center (point) of these points within a 100-meter radius.

You can use the map tools to display objects in the area of an unknown stop.

The Cost Type is Drive until configured "Unauthorised Time" audits are started.

Drives

All other periods that are not Stops are considered by the algorithm as Drives.

Short Drives of 1 minute are distributed to adjacent stops.

Intermediate Drive Cost Type

It sets the Cost Type to Intermediate Drive in all the Drive cost type Time Entries that are between the On Site cost type Entries.

State

This step is only performed if using GPS States is enabled in your instance.

As we have the GPS coordinates of the Stop point and know the US state boundaries, the script determines which state the stop is in and fills in the GPS State field in the Stop Time Entry.

The same applies to Drive Time Entries. We know GPS coordinates of the drive time – we can identify a state.

When an employee moves between states, the drive time is split into multiple Drive Time Entries depending on the number of hours spent in each state.

This minimum amount of driving within a state is 5 minutes.

For example.

You have worked in South Carolina, and now drive to North Carolina → spend less than 5 minutes there → drive back to SC. For the FCX system, this is driving activity within one state — SC.

Conversely, you spent more than 5 minutes in North Carolina. →  Driving time is split between driving in SC and driving in NC.

The script will copy a GPS state from the previous Time Entry to the Manual Lunch TE, if that TE has a state

Process Clock In/Out

Clock In/Out TEs can have their own GPS coordinates. The script fills the Site and Location fields in these TEs in the same way as for Stop TEs: first searches for Site within the Clock In/Out coordinates → otherwise tries to find a Location.

This is then be used to calculate the mileage.

For adjusted Clock Out, the script records the coordinates where an employee was at the given adjusted time.

Automatically allocate WOs

Now that the TK script has defined the Site and Warehouse stops, it will try to automatically allocate time in the next cases.

Distribute a Site WO to other Time Entries (Drives, NO GPS)

The TK script gets all the Time Entries with cost type On Site and the specified Site WO (it is filled during Stop TEs processing) and distributes this Site WO:

to the previous/next Time Entries up to the one with the assigned WO (different from the distributed one) within a work shift.

WO for Unscheduled Visit

The Stop cannot be assigned to the scheduled WO, it is bound to the Site for unscheduled WO. All of these hours will be assigned to an unscheduled visit work order, if this Site has such a Build Plan with the appropriate WO.

If there are multiple unscheduled visit WOs per Site.

It compares the current employee's Direct Cost FA with the FA of the WO type among all WOs given by BPs that have unscheduled visit WOs. If there's a unique match, it assigns the stop to the calculated WO. Otherwise, no assignment is made.

Warehouse hours and “Warehouse” WO

Search for a single scheduled “Warehouse” type WO and allocate all Warehouse hours to it.

If it exists, allocate all the hours of the Office/Warehouse cost type TEs to this single WO and:

fill in the Site WO field, if the TEs are assigned to the Site (a warehouse presented as a Site object in system)
fill in the WO allocation table in the Time Entry, if these TEs are assigned to WH Location.

Warehouse WO = Non-GPS WO. This type of WO has the work type “Warehouse”. It is defined in the WO Type card.

Distribute Warehouse WOs

The scheduled “Warehouse” (Non-GPS) WO is distributed to:

all the Office/Warehouse cost type Time Entries
all Time Entries without assigned GPS WO.

If there is more than one scheduled “Warehouse” (Non-GPS) WO, the TK Processing will distribute the TE hours proportionally between these WOs.

Default WO

The system uses the Default WO from the Employee TK Configuration and checks the setting "Overwrite GPS WO".

The system assigns the Default WO to all unallocated Check In hours (auto-created Check In hrs) → fills in the GPS WO field in the Check In Time entry.

If "Overwrite GPS WO" = No → the system assigns the Default WO to all unallocated hours (search for Time Entries or TC Adjustment).

This works when an Employee isn't prompted to manually allocate time — doesn't have the "Requires WO Allocation" role.
Plus, a TC doesn't have Time Entries of the On Site cost type .

When "Overwrite GPS WO" = Yes → it takes the approved time from Time Entries allocated to a Site Work Order (the same name field is filled in during TK processing) and assigns it to the Default WO.

The Default WO hours are added directly to the Time Card Payroll Allocation table.

Audits, Mileage, Recalculate Time Card Payroll Allocation

Finally, once the Time Keeping Processing has created Time Entries, filled Cost Type and assigned Work Orders, it's time to run audits to catch any unauthorized activity: stops in unknown locations, exceeding the allowed time in a warehouse, missed allocations and so on.

Depending on the audit rules, approved Time Entries can be reset to 0, and the cost type can be changed to Unauthorized Stop. Time Cards can be marked as pending manual allocation.

One of the last steps is to calculate the mileage using the coordinates of Clock In/Out, stops at Sites and Locations. See the separate article.

At the end it is necessary to recalculate a Time Card Payroll Allocation table: pull all data from Time Entries, a Reason (add nonwork hours), etc.

The Cost Type can be changed depending on the allocated Work Order. See Cost Type Priority.

Manual Allocation

Read about manual allocation here:

Manual Work Order Allocation Rules

Mobile App. Manually allocate time between WOs