Working Patterns
In this section:
Overview
Working Patterns are known as Working Calendars in IRIS Cascade and you can edit these in the Working Calendar Administration screen. Working Patterns represent the normal pattern of days an employee works. The Working Pattern is assigned to one or more employees using the Job and Salary screen, setting the Working Calendar.
The Working Pattern and Working Pattern Components endpoints are read-only for now (GET method).
There are several elements which combine to make up a Working Pattern. Below is a brief explanation of Working Patterns and Calendars in IRIS Cascade.
IRIS Cascade UI
IRIS Cascade Working Days
These are essentially the definitions of what each day is, for example, 'Night Shift' starts at 9:00 pm and finishes at 5:00 am, while 'Office', starts at 9:00 am and finishes at 5:30 pm.
Find out more about adding Working Days in the IRIS Cascade UI (Opens in new window or tab).
IRIS Cascade Working Patterns
When you have defined your Working Days, you can use them to create Working Patterns. These are the known as the Sequence in the API model. Use Working Patterns to construct the working week, or a series of weeks.
Take the Working Days and combine them into patterns either fixed (to a day of the week i.e. Monday, Wednesday, Friday) or not fixed i.e. 4 on 4 off starting on the first day of the pattern.
Find out more about adding Working Patterns in the IRIS Cascade UI (user interface). (Opens in new window or tab.)
Fixed
Not-Fixed
IRIS Cascade Working Calendars - Preview
When previewing a Working Calendar in IRIS Cascade, this takes all of the above, combined with a date range you provide, to give you a dataset of the Working Calendar over a date range for a maximum of 366 days.
API
Working Pattern Components API
The endpoint /workingpatterncomponents returns the data required to generate a Working Pattern.
Example response:
{
"@odata.context": "https://api-dev.iris.co.uk/hr/v2/$metadata#WorkingPatternComponents/$entity",
"Id": "ba527344-2d3a-4d9c-a569-a26c697cdd26",
"CreatedOn": "2024-03-07T11:32:31.3517281Z",
"CreatedBy": null,
"LastModifiedOn": "2024-03-07T11:32:31.3518079Z",
"LastModifiedBy": null,
"Description": "4 off 4 on",
"SourceSystemId": null,
"Days": [
{
"DayId": 22,
"SourceSystemId": 22,
"Description": "Blank Day",
"DurationDays": 0,
"DurationMinutes": 0,
"WorkingStartTime": "1900-01-01T00:00:00Z",
"WorkingEndTime": "1900-01-01T00:00:00Z",
"WorkingDayPart": "AllDay"
},
{
"DayId": 36,
"SourceSystemId": 36,
"Description": "Warehouse",
"DurationDays": 1,
"DurationMinutes": 600,
"WorkingStartTime": "1900-01-01T08:00:00Z",
"WorkingEndTime": "1900-01-01T19:00:00Z",
"WorkingDayPart": "AllDay"
}
],
"Periods": [
{
"StartDate": "1990-01-01T00:00:00Z",
"StartOnDayOfSequence": 5,
"FixedDayOfWeek": false,
"InUse": true,
"SourceSystemId": 13,
"Sequence": [
{
"Sequence": 0,
"DayId": 36
},
{
"Sequence": 1,
"DayId": 36
},
{
"Sequence": 2,
"DayId": 36
},
{
"Sequence": 5,
"DayId": 36
},
{
"Sequence": 6,
"DayId": 22
},
{
"Sequence": 8,
"DayId": 22
},
{
"Sequence": 9,
"DayId": 22
},
{
"Sequence": 10,
"DayId": 22
}
]
}
]
}API Definitions of fields
-
Days - This is a unique list of Days used within this pattern. In IRIS Cascade, you can share these between Working Calendars.
-
Periods - Working Patterns are made up of Periods. There can be one or more Periods within a Working Pattern. A Period represents a date range when a Sequence is valid. The StartDate of a Period must be unique and indicates when a Period should take over from a previous one.
-
Sequence - The collection of Days that are applied in Sequence order. The Sequence can have gaps where no Working Day is applied to the Pattern. Once the Pattern generator reaches the highest Sequence value it returns to 0.
-
FixedDayOfWeek - indicates if the Sequence is locked to the day of the week. Starting with Sequence 0, the Day is applied to the Sunday. For Sequence 1, the Day is applied to the Monday, Sequence 2, Tuesday, etc. When the Sequence reaches 7, the Day is applied to the Sunday again. If FixedOnDayOfWeek is false, the Sequence is just applied in order from the StartDate offset by the StartOnDayOfSequence.
-
StartOnDayOfSequence - is used to offset the Sequence. The Start of the Period will start on the Sequence value specified in the StartOnDayOfSequence. If FixedDayOfWeek is true, the StartOnDayOfSequence must leave Sequence 0 on a Sunday but can push the Sequence offset by any number of weeks. e.g 7 equals week 2.
-
InUse - This is manually set through the Working Calendars Administration (UI) area of IRIS Cascade. When set to true, the Working Pattern appears in the Job and Salary screen if the valid period covers today's date. Setting the InUse flag to false does not stop the Working Pattern from working.
Working Patterns API
/workingpatterns?startDate=yyyy-MM-dd&endDate=yyyy-MM-dd
/workingpatterns/{id}?startDate=yyyy-MM-dd&endDate=yyyy-MM-dd
The Working Patterns endpoint require you to specify a start and end date. This is because a Working Pattern has no natural start or end date and can run for years. The start date must be before or on the same day as the end date. The maximum duration between the start and end date is 366 days. This is equivalent to your Working Calendar (Preview) in IRIS Cascade.
{
"@odata.context": "https://iris-hr-api-staging.hrapi.co.uk/$metadata#WorkingPatterns/$entity",
"Id": "4c6a32c3-dd41-441d-8cad-d58e614462d3",
"CreatedOn": "2024-04-05T14:59:46.6949009Z",
"CreatedBy": null,
"LastModifiedOn": "2024-04-05T14:59:46.6949565Z",
"LastModifiedBy": null,
"Description": "4 off 4 on",
"Days": [
{
"Date": "2000-01-01T00:00:00Z",
"DurationDays": 1,
"DurationMinutes": 600,
"WorkingStartTime": "2000-01-01T08:00:00Z",
"WorkingEndTime": "2000-01-01T19:00:00Z",
"WorkingDayPart": "AllDay"
},
{
"Date": "2000-01-02T00:00:00Z",
"DurationDays": 1,
"DurationMinutes": 600,
"WorkingStartTime": "2000-01-02T08:00:00Z",
"WorkingEndTime": "2000-01-02T19:00:00Z",
"WorkingDayPart": "AllDay"
},
{
"Date": "2000-01-08T00:00:00Z",
"DurationDays": 1,
"DurationMinutes": 600,
"WorkingStartTime": "2000-01-08T08:00:00Z",
"WorkingEndTime": "2000-01-08T19:00:00Z",
"WorkingDayPart": "AllDay"
}
]
}The Days which have 0 DurationMinutes and 0 DurationDays are not included as part of the generated Working Pattern. Only actual Working Days are returned. You can assume all gaps are non-working days.
Endpoints
Get All Working Pattern Components
{
"code": "404-000-0001",
"description":"The specified resource cannot be found.",
"log_trace":"rrt-7985358312563982308-a-geu2-22012-294313-1"
}
When to use it?
You could use the Working Pattern Components if you wanted to retrieve all patterns and understand how they are defined. Using these details, you could generate your own pattern or instead use the Working Pattern endpoint.
Get Working Pattern Components by Id
{
"code": "404-000-0001",
"description":"The specified resource cannot be found.",
"log_trace":"rrt-3838139798511848863-b-geu2-21984-18970-1"
}When to use it?
You could use the Working Pattern Components by Id if you wanted to retrieve an individual pattern and understand how it's defined. Using these details, you can generate your own pattern or use the Working Pattern endpoint.
Get All Working Patterns
{
"code": "404-000-0001",
"description":"The specified resource cannot be found.",
"log_trace":"rrt-3838139798511848863-b-geu2-21984-18970-2"
}
When to use it?
You could use this to view all patterns over a date range without needing to calculate the result. For example, if you wanted to view a team calendar. You could also use oData to filter or search on the results.
-
startDate - the date you want to see the Working Pattern from.
-
endDate - the date you want to see the Working Pattern to.
The date range requested should be less than or equal to 366 days.
The endDate must be greater or equal to startDate.
Get Working Pattern by Id
{
"code": "404-000-0001",
"description":"The specified resource cannot be found.",
"log_trace":"rrt-3838139798511848863-b-geu2-21984-18970-3"
}When to use it?
You could use this to view an individual pattern over a date range without having to calculate the result. For example, if you wanted to view an individual employee calendar.
-
id - The Id of the Working Pattern.
-
startDate - the date you want to view the Working Pattern from.
-
endDate - the date you want to view the Working Pattern to.
Id must be a guid and an existing Working Pattern Id.
The date range requested should be less than or equal to 366 days.
The endDate must be greater or equal to startDate.