People First logo

Integrations - Work reference

Introduction

A Work Reference Code allows users to apply relatable, pre-configured tags to their time records, helping to categorize the type of shift they have completed and provide clear context for their working hours.

In the People First system, recording a Work Reference against a time record enables the time record to be linked to an activity held in another system. For example, an engineerinng system generates a list of tasks/activities that need to be done to build or maintain the facilities on a site. Each activity has a reference or key. Each time an employee spends time on a specific activity or task, they record time against that key or work reference. The subsequent time record can then be used to identify how long it has taken to perform the task - for costing and planning future activity. This field is not passed to payroll.

 

Work Reference in PeopleFirst

In PeopleFirst we allow configuration of the Work References from the Administration App, 

Workforce Management > Work Fields > Work reference.

Here you can activate the functionality, providing a label and helptext for employees logging their time.

 

Managing work reference codes

You can create or delete Work Reference codes externally using our API. Please note that existing codes cannot be updated or edited. To change your codes, the best practice is to delete the current list and recreate it in its entirety.

There are two ways to manage these codes:

  • Option 1: Direct API integration

    Use your WFM Integration Token to send a direct POST request to the API endpoint. This method is best for customers with custom-built integrations who want to send data automatically.

  • Option 2: Data import API (CSV method)

    This option uses a guided import process. Using your WFM integration token and the Import API documentation, follow the guide below to safely upload your data.

     

Direct API integration

This guide explains how to connect your system directly to our API to retrieve and use Work reference data.

While the CSV import method is excellent for bulk updates, Direct API integration allows your system to "talk" to ours in real-time. This ensures that whenever a Work Reference is updated in the administration area, your integrated system sees that change instantly without a manual file upload.

The "Digital Breadcrumb" Principle

Unlike traditional systems where you have to memorize every secret web address, our API follows the HATEOAS (Hypertext as the Engine of Application State) principle.

Think of this as a digital trail of breadcrumbs. Each time you ask the system for information, the response includes "links" that tell your system where to go next. This makes your integration "break-proof"—even if we move a folder or rename a path, your system will simply follow the new link.

Necessary Request Headers

To communicate with the API, every request must include these credentials:

  • Method: GET
  • Authorisation: Bearer Token (Your unique digital key)
  • Accept: application/json

The Discovery Process at a Glance

To find the options for a Work Reference, your system follows a four-step path to "discover" the data it needs. 

Step 1: Access the main directory

First, you need to see all the different types of lists available in the administration area.

  • Request: GET /ta/configurablelists
  • What happens: The API returns a master list of configuration categories.
  • Your goal: Look through the list for the item named "Work fields" and grab the link (URL) provided next to it.

Step 2: Open the "Work Fields" folder

Now that you have the specific link for Work Fields, you use it to see what’s inside.

  • Request: GET /ta/fieldconfiguration/workfields
  • What happens: You receive a list of all individual fields within that category.
  • Your goal: Locate "Work Reference" and find its unique ID (a long string of numbers and letters called a UUID).

Step 3: Retrieve the field metadata

Using the Unique ID, you ask the system for the "Identity Card" of that specific field.

  • Request: GET /ta/fieldconfiguration/{Unique_ID}
  • What happens: The API provides the "Human" details, such as the Label (e.g., "Helping Hand") and the Help text.
  • Your goal: Look for a specific link in the response labeled singleChoiceFieldItems. This is the direct path to the actual choices.

Step 4: Fetch the menu options

This is the final step where you get the actual data to show your users. Included in this response are the links for actions that can be enacted on the resource collection.

  • Request: GET /ta/fieldconfiguration/{Unique_ID}/singlechoiceitems
  • What happens: The API gives you the full menu of choices.
  • The result: You will receive a list containing:
    • Code: The shorthand name the computer uses (e.g., STEPPING_UP).
    • Value: The name the human sees (e.g., Stepping Up).
    • Active: A True/False status showing if it should be visible.

 

Troubleshooting & validation

Because this method relies on following links, errors usually happen if the "trail" is broken or your key expires.

Authorisation failures (401 Error)

  • Trigger: Your Bearer Token has expired or is incorrect.
  • How to fix: Refresh your authentication token and ensure it is included in the header of your request.

Resource not found (404 Error)

  • Trigger: You are trying to use an ID or a link that no longer exists (perhaps the field was deleted in the admin area).
  • How to fix: Start back at Step 1. By re-running the discovery process from the beginning, your system will find the new, correct links automatically.

Empty data sets

  • Trigger: You successfully reached Step 4, but no choices are listed.
  • How to fix: Check the PeopleFirst administration area. Ensure that there are "Items" added to the Work Reference field and that they are toggled to Active.

     

Work References API import guide

This guide will walk you through the process of adding new Work References to your system using our API. Work References allow employees to categorize their time when recording clock-ins.

To perform this import, you will use the import session code: WorkReference.

The import process at a glance

The import process follows a three-stage "handshake" to ensure the import content is valid before it is officially saved to the system.

Necessary request headers:

  • Method: GET, POST
  • Authorization: Bearer Token
  • Accept: application/JSON, text/plain, /

Step 1: Download the template

Before you upload data, you need the correct format.

  • Request: Make a GET request to the 'Work Reference' resource template API endpoint: /ta/importsessions/importtemplates/WorkReference/resourceTemplate
  • Response: The API will provide a file named WorkReference.csv.
  • Data Fields: Your file must contain these three columns:
    • Work reference - The name of the reference.
    • Description - A brief explanation of the work.
    • Active - Use Yes or No to determine if it's currently available for use.

Step 2: Prepare and upload your data

Once your CSV file is filled out, you need to prepare it for the API. APIs prefer a text-based format called Base64.

  • Populate: Fill in your CSV with your new work references.
  • Encode: Convert the contents of your CSV into a Base64 string (think of this as "packaging" your file for transport).
  • Request: Send a POST request to the API containing this encoded string. This initiates an Import Session.
  • Response: A new importsession resource with a unique ID.

Payload structure:

Provide this as a JSON object in the data response for the template endpoint:

{
  "importsessions": {
    "fileData": "V29yayByZWZlcmVuY2UJRGVzY3JpcHRpb24JQWN0aXZlClRlc3RXb3JrUmVmZXJlbmNlCVRlc3RpbmcgaW1wb3J0IHdpdGggZXhwbGljaXQgQVBJIGNhbGxzCXllcwo=",
    "documentName": "WorkReference.csv"
  }
}

 

Step 3: Begin the import

If your data passes the initial check, the API will return a Session ID. The data is not saved yet! You must give the final "OK."

  • Request: Send a POST request to the /importing endpoint.
  • Payload: Include the Session ID you received in Step 2.
  • Response: The system processes the session and adds the references to your database.


Troubleshooting & validation

The API acts as a gatekeeper to prevent "bad data" from entering your system.

Validation failures (Fails at Step 2)

  • Trigger: Your data is formatted incorrectly or missing required fields.
  • Response: The response will contain a link to the validationFailures endpoint. Call this with the GET method to return a collection of validation failures and error codes.
  • How to Fix: Review the error codes against your CSV file. Common issues include typos in the Active column or missing Work reference names.
  • Retry: Once you’ve corrected the CSV, repeat Step 2 to start a new session.

Import failures (Fails at Step 3)

  • Trigger: The data being imported fails to save to the database because of conflicts with existing records or because it fails to meet specific data constraints.
  • Response: The response will provide a link to the importFailures endpoint. Call this with the GET method to return a collection of failures to help identify the issue.
  • How to Fix: Review the data to ensure that it does not conflict with existing Work References.

Technical note: All requests should be directed to the base URL provided in your API documentation. Ensure your authentication headers are included in every call.

Looking for something specific?