Import attendance punches into Bob via public API

If your employees clock in and out using a physical time clock device, the device can be integrated with Bob's time and attendance system. 

This includes devices such as clocks, fingerprint readers and swipe cards.

Note: This article is intended for IT professionals responsible for implementing the solution.

Get the most out of Bob

Integrating a time clock device benefits employees, managers and admins.

  • Employees are able to manage and submit their timesheets within Bob because attendance data will be moved seamlessly to Bob.
  • Managers are able to manage approval flow.
  • Admins can export attendance data to the payroll system, as all data is kept in the same place. 
  • Secure and private solution which via a public API using a generic JSON file.

Before you begin

In order to use Bob’s Public API to import attendance records into Bob, you will need to prepare the following

  • Filter out clock punches that will be uploaded to Bob - for example, if you only want to include the first in and last out punches.
  • Compose/manage a script that will run on the relevant clock punches output and will translate them into the JSON format.
  • Create a service user to run the public API query. For more information about creating a service user, see API service users. For more details, see Import attendance public API. 

    Note: The service user needs to have the following permission: Other employees > Time attendance > Manage time attendance sheets.

  • Determine whether the method of pushing records via the API is Aggregate or Immediate:
    • Aggregate: This is the common attendance record processing in the API. In this mode, the user pushes data (clock punches) in the JSON format and only in the following early morning (01:30 AM site local time) will a job in bob run and keep the previous 24 hours punches. The entries will be added to a temporary location and the aggregation job will process the data asynchronously.
    • Immediate: This option will push the information into Bob immediately during runtime. Frequency is up to the customer.

Aggregate vs Immediate comparison

  Aggregate Immediate

Which method should I use?

When the clock can generate multiple punches and not all punches should show in Bob. 

E.g. When employee punches several time throughout the day for break intervals.

If all punches should be registered e.g. if you want to see punches closer to real time.

This can be used to import historical data, as long as there is no existing newer data and the attendance cycle (timesheet) exists.

When will punches be shown in Bob?

The following day (after 01:30).

When an API call is conducted.

Troubleshoot

Any data submitted beyond the 24-hour window will not appear in Bob. Retrospective punches will require submitting an Engineering task.

 

Will process data as long as there are no newer punches.

Error handling / Logs

Employee ID errors will be returned immediately.

Data in incorrect form: error will be returned immediately.

Data processing will be asynchronous. 

Employee ID errors will be returned immediately.

Data in incorrect form: error will be returned immediately.

Check API error codes.

Solution flow

mceclip0.png

Data details

ImportAttendanceData

About query fields:

  • dateTimeFormat - set the attendance record date to be processed. Default format: yyyy-MM-ddThh:mm.
  • idType: - the employee’s identifier. It can be one of the following:
    • BobID - This is the 19 digit system identifier that appears in the URL when viewing the employee's Bob profile: mceclip1.png
      You can also pull the BobID using the People API.
    • Email - the employee’s bob email address.
    • Employee ID - taken from the Work category in the employee's profile in Bob.
  • Requests: the list of attendance events (clock punches) to be pushed via the API.

ImportAttendanceEvent

  • ClockIn - Can be any date format.
  • ClockOut - Can be any date format.
  • Id: the employee’s identifier (as detailed in ImportAttendanceData above).

ImportAttendanceResponse

Imported Attendance Records report

The Imported Attendance Records report shows the details of every employee attendance punch sent to Bob from a physical time clock via public API.

How to generate the report

  1. From the left menu, select Analytics > Reports.
  2. Click + Add new > Report > Use a template.
  3. In the Reports templates popup, from the left menu select Time & Attendance, then select Imported Attendance Records and click Generate.

Report details

image__1_.png

The report includes the following information by default:

  • Entry date: the date the record was sent to Bob.
  • Punch in: the time the employee clocked in.
  • Punch out: the time the employee clocked out.
  • Status: whether the entry was Created, manually Updated or Failed.

    Note: Updated means that either the punch in or punch out time was entered manually in Bob.