1. Yomly
  2. Tutorials
  3. Integrating Yomly with external apps

Programming the Timesheet API

Padmini Krishna
Updated

Introduction

Yomly provides you with the Timesheet API to enable you to submit clocking data (clock in and clock out records) from external time-tracking applications to the platform.

The Timesheet API runs on Kubernetes.

When Yomly receives records from the external application, for each transaction (clocking record), the platform tries to match the employee code (internal to Yomly) with the employee identifier in the time-tracking application. If there are no matches, the received transactions are discarded.

Objective

In this tutorial, you will learn how to program the Yomly Timesheet API to receive transactions from the external time-tracking application.

Procedure

To program the Timesheet API, do the following:

  1. Generate the Yomly API key

  2. Authenticate and obtain the JWT token

  3. Send a transaction to the API

Step 1: Generate the Yomly API key

To authorize integration with the Yomly API, an API key is required.

You must generate the key using an account that has the HRADMIN role. If you generate it using a user account with any other role, when the records are synchronized, all of them will be attributed to only the user.

  1. Log in to Yomly as an HR Admin user.

  2. In the sidebar, in the Business section, click Settings.

    blobid1.png

  3. Go to General > API Keys.

    integration-t-and-a-with-biotime-1.png

  4. Click + Add API Key.

  5. Enter an Issue Date and Valid for date, which are the start and end dates of validity of the API key, respectively.

    blobid3.png

  6. (Optional) In IPcdr, enter an IP address range during which the key will be used.

  7. (Optional) In Comments, enter a comment to document why you have generated the key. For example, enter "BioTime integration".

  8. Click Generate API Key.

    blobid4.png

  9. Click Copy API Key to copy the Generated API Key and paste it in a text file or note. Also copy and paste the associated API key ID.

    You can copy the Generated API Key only at this time (immediately after creating it).

    The API key ID is the number displayed in the new expandable section. For example, in the previous image, it is the number that starts with "15872...".

Step 2: Authenticate and obtain the JWT token

Send a POST request to the API to authenticate and obtain the JWT token based on the following sample:

Request path:

POST https://k8.emirateshr.com/ehr-integrations/public/authentication

Request headers:

Content-Type: application/json

Request body:

{
  “api_key”: “{{generated-api-key}}”,
  “api_key_id”: “{{generated-api-key-id}}”
}

cURL:

curl --location --request POST 'https://k8.emirateshr.com/ehr-integrations/public/authentication' \
--header 'Content-Type: application/json' \
--data-raw '{
    "api_key": "API_KEY",
    "api_key_id": "API_KEY_ID"
}'

The following response is received for a successful request:

{
  "success": true,
  "state": "TOKEN_SUCCESS",
  "accessToken": accessTOKEN,
  "authorizationToken": authTOKEN
}

Step 3: Send a transaction to the API

Send a transaction as a POST request to the API based on the following sample:

Request path:

POST https://k8.emirateshr.com/telemetry/transaction

Request headers:

Authorization: Bearer {{authTOKEN}}

cURL:

curl --location --request POST 'https://k8.emirateshr.com/telemetry/transaction' \
--header 'Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJidXNpbmVzc0lkIjoxMTM2LCJlbXBsb3llZUlkIjoyLCJhY2Nlc3MiOlsiTUFOQUdFUiIsIkVWRVJZQk9EWSIsIkVNUExPWUVFIiwiSFJNQU5BR0VSIiwiSFJBRE1JTiJdLCJpc0FkbWluIjpmYWxzZSwiaWF0IjoxNjU4MzkwOTUyMjAxLCJleHAiOjE2NTg0NzczNTIyMDEsImF1ZCI6Imh0dHBzOi8vbG9naW4uZW1pcmF0ZXNoci5jb20iLCJpc3MiOiJodHRwOi8vYXBpLmVtaXJhdGVzaHIuY29tIiwic3ViIjoiMDZjZjg2NTAtNWRjOC00NWQ4LWEwNDktYTFlOTI3ODZlMjVhIiwiZW1haWwiOiJuaWNramR0ZXN0MDdAZ21haWwuY29tIn0.Ehg6k3Gfk5_ocXeeIqSFHrqKDgxDLR8t-23k12ggP4k' \
--data-raw '{
    "emp_code": "30175",
    "punch_time": "2022-07-01 05:55:15",
    "punch_state": "1",
    "punch_state_display": "Check Out",
    "terminal_sn": "AEH2190760068",
    "terminal_alias": "Auto add",
    "gps_location": "",
    "timeZoneOffset": 240.0
}'

The following response is received for a successful request:

{
  "success": true, 
  "message": "Transaction Added"
}

Transaction details

The transaction needs to be in the following format:

{
  "emp_code": "30175",
  "punch_time": "2022-07-01 05:55:15",
  "punch_state": "1",
  "punch_state_display": "Check Out",
  "terminal_sn": "AEH2190760068",
  "terminal_alias": "Auto add",
  "gps_location": "",
  "timeZoneOffset": 240.0
}

The following table describes the different fields of the transaction in detail:

Field Description Mandatory?
emp_code

Employee identifier in the time-tracking application (that needs to be the same as the employee code in Yomly)

  
punch_time Time of clocking action  
punch_state

ID of punch_state_display. This field can have one of the following values: 0, 1, 2, or 3.

  
punch_state_display

Depending on the punch_state, this could be one of the following values:

0 = Clock In
1 = Clock Out
2 = Check In
3 = Check Out

An employee can clock in at the beginning of their shift and clock out at the end of their shift. During their shift, they can check out and back in during breaks.

  
terminal_sn

The terminal serial number, which is a unique identifier of the hardware that the employee uses

  
terminal_alias The name associated with the serial number. For example, this could be the location of the terminal, such as Dubai Mall.  
gps_location The GPS location of the terminal  
timeZoneOffset The number of minutes by which the current timezone is offset  
Was this article helpful?
1 out of 1 found this helpful

Comments

0 comments

Please sign in to leave a comment.

Articles in this section