Overview

A Working pattern in Bob is the number of hours an employee is expected to work each day of the week. For example, a full-time employee could be expected to work 9 hours a day, Monday to Friday. Working patterns are defined in the central library, and are used when you assign employees to working patterns as part of their employment details.

When using the Public API, you can fetch the employee’s employment details and their working patterns. The JSON response will contain the actual working pattern the employee uses, together with the calculated ‘FTE %’ (Full-Time Equivalent) from Bob.

Note: The FTE % is a calculated ratio that demonstrates how many days or hours an employee works compared to a regular full-time employee’s working days or hours. When the employee works in a standard working pattern the FTE is always 100%. When the employee has an adjusted working pattern, the FTE will be calculated by Bob. To learn more, see Calculate and view FTE %.

Working patterns library

The Working pattern library in Bob is a central hub where working patterns are created and managed. Bob Admins can use these working patterns as the site’s default or assign employees to specific working patterns.

Library working patterns types

Weekly: Allows you to define the working days and working hours per day in a week.
Bi-Weekly: You can define working days and working hours per day for two weeks.

Note: it is not possible to assign a bi-weekly working pattern to a Site default.

Working patterns in the Employment table

An employee's employment table can hold multiple entries (employment entries), allowing you to track changes in the employment history over time.

Each employment entry includes the working pattern assigned to this employee, which can be standard or adjusted.

The employee's working pattern varies based on the following options:

Standard:
- Site default: The employee uses the default weekly working pattern for this site.
- From library: The employee uses a weekly/bi-weekly working pattern selected from the library.
Adjusted (for part-time or different hours):
- From library: The employee uses a specific weekly/bi-weekly working pattern selected from the library.
- Custom: The employee uses a customized weekly pattern with specific hours per day for this employee.
- Flexible: The employee uses a special weekly pattern where only the work percentage is defined. The percentage is based on the Standard working pattern selected for this user (site/library).

Note: Because bi-weekly patters cannot be defined as the site default (only weekly patterns can), they always need to be selected from the library when you want to assign such a working pattern for an employee.

Working patterns JSON structure

When using the Public API to read the working pattern from the employment table, the response is returned in JSON format, and the working pattern that was actually selected for the employee is returned in the actualWorkingPattern section.

The JSON format varies based on the working pattern type as follows.

Weekly working pattern

The weekly working pattern’s type is internally called ‘hourly’.

"actualWorkingPattern": 			  
{		
    "workingPatternType": "hourly"
    "days": {
      "sunday": 0,
      "tuesday": 9,
      "wednesday": 9,
      "monday": 9,
      "friday": 9,
      "thursday": 9,
      "saturday": 0
    },
    "hoursPerDay": 9, 
    "workingPatternId": 280653 // id in library if 'from library'
  },

Bi-Weekly working pattern

The bi-weekly working pattern’s type is internally called ‘fortnightly’.

"actualWorkingPattern": 			  
{		
    "workingPatternType": "fortnightly",
    "firstWeek": {
        "sunday": 0,
        "tuesday": 8,
        "wednesday": 8,
        "monday": 8,
        "friday": 8,
        "thursday": 8,
        "saturday": 0
    },
    "secondWeek": {
        "sunday": 0,
        "tuesday": 8,
        "wednesday": 8,
        "monday": 8,
        "friday": 0,
        "thursday": 8,
        "saturday": 0
    },
    "	anchorDate": "2024-07-22", // the date the working pattern will go into effect (must be a Monday)
    "hoursPerDay": 7,
    "workingPatternId": 7613058 // id in library 
  },

Flexible working pattern

A flexible working pattern is a special case of an adjusted working pattern in which the only relevant data is the work percentage.

"actualWorkingPattern": 			  
{		
   "workingPatternType": "flexible",
   "weeklyWorkPercentage": 80
},

Note: A flexible working pattern is always based on a ‘Weekly’ pattern.

Additional working pattern fields

The employment table endpoint also returns additional working pattern sections and fields:

siteWorkingPattern: the site default working pattern details.
standardWorkingPattern: the details of the working pattern that was selected from the library. If there is no working pattern selected from the library (e.g., when using the site default), this section will be null.
fte: the calculated FTE % when there is a personalized working pattern. Otherwise, it will always be 100%.
hoursInDayNotWorked: the same as defined in the `actual working pattern.'
weeklyHours: the average number of hours the employee is expected to work each week or two weeks.

Adjustments fields JSON

The working pattern that is selected for the employee will always appear in the ‘actualWorkingPattern’ section. However, if you also need to know whether there were adjustments and what they were, you should process other parameters in the JSON response:

Weekly / Bi-weekly
As indicated by the workingPatternType JSON parameter:
- Weekly: workingPatternType = “hourly” or “flexible”
- Bi-weekly: workingPatternType = “fortnightly”
Has Adjustments
As indicated by the personalWorkingPatternType JSON parameter:
- Standard: personalWorkingPatternType = null
  - Site default: standardWorkingPatternId = null
  - From library: standardWorkingPatternId ≠ null
Adjusted: personalWorkingPatternType ≠ null
- From library: personalWorkingPatternType = “library”
- Custom: personalWorkingPatternType = "custom"
- Flexible: personalWorkingPatternType = "flexible"

Public API endpoints

You can read the working pattern of an employee with the following Public API endpoints.

Using ‘Employment table history’ endpoints

When using employment table history endpoints, you read the employment table entries with the history over time.

You can use the following endpoints:
List employment history for a list of employees - for a list of employees
List employee's employment history - for a specific employee

The field "isCurrent": true determines the active working pattern entry that is currently effective.

Example employment table working pattern response JSON:

      "values": [
        {
            "personalWorkingPatternType": "library",
            "hoursInDayNotWorked": 8,
            "actualWorkingPattern": {		// the actual working pattern
                "workingPatternType": "hourly",
                "days": {
                    "sunday": 0,
                    "tuesday": 8,
                    "wednesday": 8,
                    "monday": 8,
                    "friday": 8,
                    "thursday": 8,
                    "saturday": 0
                },
                "hoursPerDay": 8,
                "workingPatternId": 4719563
            },
            "workingPattern": {		// the adjusted (personal) pattern
                "workingPatternType": "hourly",
                "days": {
                    "sunday": 0,
                    "saturday": 0,
                    "tuesday": 8,
                    "wednesday": 8,
                    "friday": 8,
                    "thursday": 8,
                    "monday": 8
                },
                "hoursPerDay": 8,
                "workingPatternId": 4719563
            },
            "fte": 100,					// the FTE %
            "id": 1000020240724,
            "activeEffectiveDate": "2024-07-24",
            "canBeDeleted": true,
            "weeklyHours": 40,
            "standardWorkingPatternId": null,
            "change": {
                "reason": null,
                "changedBy": null,
                "changedById": "3332883804594373380"
            },
            "isCurrent": true,	
            "siteWorkingPattern": {			// site default
                "workingPatternType": "hourly",
                "days": {
                    "sunday": 0,
                    "tuesday": 8,
                    "wednesday": 8,
                    "monday": 8,
                    "friday": 8,
                    "thursday": 8,
                    "saturday": 0
                },
                "hoursPerDay": 8,
                "workingPatternId": 4719563
            },
            "standardWorkingPattern": null,
        },

Using ‘Search for employees’

When using the Search for employees endpoint, you should request each of the fields separately. For the actual working pattern, you need to request for the payroll.employment.actualWorkingPattern field in the endpointfields parameter.

POST /v1/people/search 
{
    "fields": [
    	"payroll.employment.actualWorkingPattern"
    ],
}

Getting additional fields
The search endpoint will return only the fields you request for. If you want additional details like the FTE % or details about adjustments, you should specify these fields explicitly (e.g. "payroll.employment.fte". To learn more about the fields you can request for, see Working patterns JSON schema. Alternatively, you can read the employment table entry, which returns all the employment entry fields.

Example working pattern response JSON from search:

"payroll": {
"employment": {
     		"actuaWorkingPattern": {
           "workingPatternType": "hourly",
           "days": {
           	"sunday": 9,
                "tuesday": 9,
                "wednesday": 9,
                "monday": 9,
                "friday": 0,
                "thursday": 8,
                "saturday": 0
                },
            "hoursPerDay": 9,
            "workingPatternId": 4719564
            }
           }
          }
}

Reading the ‘human readable’ format

When using the Search for employees endpoint you can request the working pattern in a ‘human readable' format, which is a string representing the working pattern, similar to how it would appear in the employment table in the UI.

For example, if you request for the ‘actual working pattern’ field and set the human readable flag to ‘APPEND’, it will return in the following format:

Human readable for weekly: "Monday:8.00,Tuesday:8.00,Wednesday:8.00,Thursday:8.00,Friday:8.00,Saturday:0.00,Sunday:0.00"
Human readable for bi-weekly:
"Week1-Monday:8.00,Tuesday:8.00,Wednesday:8.00,Thursday:8.00,Friday:8.00,Saturday:0.00,Sunday:0.00_Week2-Monday:8.00,Tuesday:8.00,Wednesday:8.00,Thursday:8.00,Friday:8.00,Saturday:0.00,Sunday:0.00"
📘
HumanReadable flag
To learn more about the human readable flag, see Using the ‘humanReadable’ flag.

Example:

POST /v1/people/search 
{
    "filters": [
    {
      "fieldPath": "/root/id",
      "operator": "equals",
      "values": [
        "3332883862928753000"
      ]
    }
    ],
    "fields": [
    "payroll.employment.actualWorkingPattern"
    ],
    "showInactive": false,
    "humanReadable": "APPEND"

}

Response with human readable section:

{
    "employees": [
        {
            "payroll": {
                "employment": {
                    "actualWorkingPattern": {
                        "workingPatternType": "hourly",
                        "days": {
                            "sunday": 0,
                            "tuesday": 8,
                            "wednesday": 8,
                            "monday": 8,
                            "friday": 8,
                            "thursday": 8,
                            "saturday": 0
                        },
                        "hoursPerDay": 8,
                        "workingPatternId": 4719563
                    }
                }
            },
            "humanReadable": {
                "payroll": {
                    "employment": {
                        "actualWorkingPattern": "Monday:8.00,Tuesday:8.00,Wednesday:8.00,Thursday:8.00,Friday:8.00,Saturday:0.00,Sunday:0.00"
                    }
                }
            },
        }
    ]
}

Examples and use-cases

Standard based on site default with no personal working pattern

{
  "personalWorkingPatternType": null	  // No personal pattern
  "hoursInDayNotWorked": 9,
  "actualWorkingPattern": {			  // the actual pattern
    "workingPatternType": "hourly",
    "days": {
      "sunday": 0,
      "tuesday": 9,
      "wednesday": 9,
      "monday": 9,
      "friday": 9,
      "thursday": 9,
      "saturday": 0
    },
    "hoursPerDay": 9, 		// same as hoursInDayNotWorked
    "workingPatternId": 280653	
  },
  "workingPattern": null		// null because no personalized
  "fte": 100,	
  "weeklyHours": 45,
  "standardWorkingPatternId": null, // null because not using lib
  "siteWorkingPattern": {		   // same as the actual
    "workingPatternType": "hourly",
    "days": {
      "sunday": 0,
      "tuesday": 9,
      "wednesday": 9,
      "monday": 9,
      "friday": 9,
      "thursday": 9,
      "saturday": 0
    },
    "hoursPerDay": 9,
    "workingPatternId": 280653
  },
  "standardWorkingPattern": null
}

Standard 'from library' with an adjusted working pattern (weekly)

{
  "personalWorkingPatternType": "library" //from library
  "hoursInDayNotWorked": 9,
  "actualWorkingPattern": { 	// the actual pattern selected
    "workingPatternType": "hourly",
    "days": {
      "sunday": 0,
      "tuesday": 9,
      "wednesday": 9,
      "monday": 9,
      "friday": 0,
      "thursday": 9,
      "saturday": 0
    },
    "hoursPerDay": 9,
    "workingPatternId": 280651
  },
  "workingPattern": {			// the personalized pattern (same as actual)
       "workingPatternType": "hourly",
       "days": {
         "sunday": 0,
         "tuesday": 9,
         "wednesday": 9,
         "monday": 9,
         "friday": 0,
         "thursday": 9,
         "saturday": 0
       },
       "hoursPerDay": 9,
       "workingPatternId": 280651
   },
  "fte": 80,						// fte
  "weeklyHours": 36,
  "standardWorkingPatternId": 280654,
  "siteWorkingPattern": {		// site default always appears
    "workingPatternType": "hourly",
    "days": {
      "sunday": 0,
      "tuesday": 9,
      "wednesday": 9,
      "monday": 9,
      "friday": 9,
      "thursday": 9,
      "saturday": 0
    },
    "hoursPerDay": 9,
    "workingPatternId": 280653
  },
  "standardWorkingPattern": {		// pattern from library 
    "workingPatternType": "hourly",
    "days": {
      "sunday": 9,
      "tuesday": 9,
      "wednesday": 9,
      "monday": 9,
      "friday": 0,
      "thursday": 9,
      "saturday": 0
    },
    "hoursPerDay": 9,
    "workingPatternId": 280654
  },
}

Site default with an adjusted working pattern (flexible)

{
  "personalWorkingPatternType": "flexible" // flexible
  "hoursInDayNotWorked": 9,
  "actualWorkingPattern": {
    "workingPatternType": "flexible",
    "weeklyWorkPercentage": 80		// only using percentage
  },
  "workingPattern": {				
     "workingPatternType": "flexible", // flexible = weekly
     "weeklyWorkPercentage": 80
  },
  "fte": 80,
  "weeklyHours": 36,
  "standardWorkingPatternId": null,
  "siteWorkingPattern": {			// site default
    "workingPatternType": "hourly",
    "days": {
      "sunday": 0,
      "tuesday": 9,
      "wednesday": 9,
      "monday": 9,
      "friday": 9,
      "thursday": 9,
      "saturday": 0
    },
    "hoursPerDay": 9,
    "workingPatternId": 280653
  },
  "standardWorkingPattern": null
}

Site default with a custom working pattern (weekly)

{
            "personalWorkingPatternType": "custom",
            "hoursInDayNotWorked": 8,
            "actualWorkingPattern": {
                "workingPatternType": "hourly",
                "days": {
                    "sunday": 4,
                    "tuesday": 4,
                    "wednesday": 4,
                    "monday": 4,
                    "friday": 4,
                    "thursday": 4,
                    "saturday": 4
                },
                "hoursPerDay": 8,
                "workingPatternId": null
            },
            "workingPattern": {
                "workingPatternType": "hourly",
                "days": {
                    "sunday": 4,
                    "saturday": 4,
                    "tuesday": 4,
                    "wednesday": 4,
                    "friday": 4,
                    "thursday": 4,
                    "monday": 4
                },
                "hoursPerDay": 8,
                "workingPatternId": null
            },
}

Bi-weekly with an adjusted bi-weekly from library working pattern

{
  "personalWorkingPatternType": "library" // from library
  "hoursInDayNotWorked": 9,
  "actualWorkingPattern": {			// actual working pattern
    "workingPatternType": "fortnightly", 
    "firstWeek": {
        "sunday": 0,
        "tuesday": 8,
        "wednesday": 8,
        "monday": 8,
        "friday": 8,
        "thursday": 8,
        "saturday": 0
    },
    "secondWeek": {
        "sunday": 0,
        "tuesday": 8,
        "wednesday": 8,
        "monday": 8,
        "friday": 0,
        "thursday": 8,
        "saturday": 0
    },
    "anchorDate": "2024-07-01",
    "hoursPerDay": 8,
    "workingPatternId": 7486938
  },
  "workingPattern": {			// personalized working pattern
      "workingPatternType": "fortnightly",
      "firstWeek": {
          "sunday": 0,
          "tuesday": 8,
          "wednesday": 8,
          "monday": 8,
          "friday": 8,
          "thursday": 8,
          "saturday": 0
      },
      "secondWeek": {
          "sunday": 0,
          "tuesday": 8,
          "wednesday": 8,
          "monday": 8,
          "friday": 0,
          "thursday": 8,
          "saturday": 0
      },
      "anchorDate": "2024-07-01",
      "hoursPerDay": 8,
      "workingPatternId": 7486938
  }
  "fte": 90,
  "weeklyHours": 36,
  "standardWorkingPatternId": 7486939,
  "siteWorkingPattern": {		// site default (weekly)
    "workingPatternType": "hourly",
    "days": {
      "sunday": 0,
      "tuesday": 9,
      "wednesday": 9,
      "monday": 9,
      "friday": 9,
      "thursday": 9,
      "saturday": 0
    },
    "hoursPerDay": 9,
    "workingPatternId": 7486938
  },
  "standardWorkingPattern": {	// from library
    "workingPatternType": "fortnightly",
    "firstWeek": {
        "sunday": 0,
        "tuesday": 8,
        "wednesday": 8,
        "monday": 8,
        "friday": 8,
        "thursday": 8,
        "saturday": 0
    },
    "secondWeek": {
        "sunday": 0,
        "tuesday": 8,
        "wednesday": 8,
        "monday": 8,
        "friday": 8,
        "thursday": 8,
        "saturday": 0
    },
    "anchorDate": "2024-07-01",
    "hoursPerDay": 8,
    "workingPatternId": 7486939
  }
}