Schedule Group Assignments - Aggregated
Schedule groups organize employees who share characteristics such as schedules into groups that make their schedules easier to manage. When you create schedule groups, you can assign schedules and schedule entities to all members of the group.
There are two types of groups, groups with inheritance and groups without inheritance.
- Groups with no inheritance simply make it easier to view a certain set of employees separately from other employees. The only impact is in the sequence of the list of employees and the ability to collapse the list.
- Groups With Inheritance make it easier to create and modify employee schedules in unison. When you apply a pattern, a shift, a paycode, or an availability status to a group with inheritance, that entity appears in the schedule of all the employees in the group. That entity can be modified or removed from the schedule of all employees with a single command. Individual shifts, paycodes, and availability can also be defined for specific employees at specific times. These entities are not inherited and must be managed at the employee level.
If you modify the schedule of individual employees in a group, the modified entity is un-linked from the group and will no longer be affected by any modification of the original group-based entity.
Prerequisites
A person ID is the same identifier as personKey and employee ID, and is not the same as a person number.
Example
In this example, we assign, verify, delete, and pass a request that makes no change to multiple people's schedule group assignments.
Create or update assignments
The create or update request:
- uses
personIdentityto identify the person using their person number - uses
scheduleGroupinsidepersonAssignmentsto define the schedule groups to assign
Example request
Call POST /v1/commons/persons/assignments/multi_upsert with the following request payload.
[
{
"personIdentity": {
"personNumber": "90107"
},
"personAssignments": {
"scheduleGroup": {
"assignments": [
{
"scheduleGroup": {
"qualifier": "Team A"
},
"effectiveDate": "2020-04-20",
"expirationDate": "2022-01-01"
},
{
"scheduleGroup": {
"qualifier": "Team B"
},
"effectiveDate": "2020-04-20",
"expirationDate": "2022-01-01"
}
]
}
}
}
]
Example response
A success response returns HTTP status code 200 and a response body similar to the following example.
[
{
"personIdentity": {
"personNumber": "90107"
},
"personAssignments": {
"scheduleGroup": {
"assignments": [
{
"scheduleGroup": {
"id": 101,
"qualifier": "Team A"
},
"effectiveDate": "2020-04-20",
"expirationDate": "2022-01-01"
},
{
"scheduleGroup": {
"id": 102,
"qualifier": "Team B"
},
"effectiveDate": "2020-04-20",
"expirationDate": "2022-01-01"
}
]
}
}
}
]
Verify assignments
You can use the bulk multi-read operation to verify assignments for multiple people at once.
Example request
To verify, call POST /v1/commons/persons/assignments/multi_read with the following request payload.
{
"where": {
"employees": {
"key": "personNumber",
"values": [
"90107"
]
},
"personAssignments": [
"scheduleGroup"
]
}
}
Example response
A success response returns HTTP status code 200 and a response body similar to the following example.
[
{
"personIdentity": {
"personNumber": "90107",
"personKey": 254
},
"personAssignments": {
"scheduleGroup": {
"assignments": [
{
"scheduleGroup": {
"id": 101,
"qualifier": "Team A"
},
"effectiveDate": "2020-04-20",
"expirationDate": "2022-01-01"
},
{
"scheduleGroup": {
"id": 102,
"qualifier": "Team B"
},
"effectiveDate": "2020-04-20",
"expirationDate": "2022-01-01"
}
]
}
}
}
]
Make no change to assignments
When working with large numbers of people, you may wish to pass a request payload that makes no changes to a person's schedule group assignments.
In the following example, the system makes no changes. Setting a null assignmentProfile and passing the unAssignExisting Boolean as false both result in no changes to a person's assignments.
Example request
Call POST /v1/commons/persons/assignments/multi_upsert with the following request payload.
[
{
"personIdentity": {
"personNumber": "10020"
},
"personAssignments": {
"scheduleGroup": {
"assignments":null
}
}
},
{
"personIdentity": {
"personNumber": "10030"
},
"personAssignments": {
"scheduleGroup": {
"unAssignExisting":false
}
}
}
]
Example response
A success response returns HTTP status code 200 and a response body similar to the following example.
[
{
"personIdentity": {
"personNumber": "10020"
},
"personAssignments": {
"scheduleGroup": {}
}
},
{
"personIdentity": {
"personNumber": "10030"
},
"personAssignments": {
"scheduleGroup": {}
}
}
]
Delete assignments
You can delete, or unassign, schedule group assignments. To delete our example's schedule group assignments, call POST /v1/commons/persons/assignments/multi_upsert using the unAssignExisting property.
Example request
Call POST /v1/commons/persons/assignments/multi_upsert with the following request payload.
[
{
"personIdentity": {
"personNumber": "10020"
},
"personAssignments": {
"scheduleGroup": {
"unAssignExisting":true
}
}
},
{
"personIdentity": {
"personNumber": "10030"
},
"personAssignments": {
"scheduleGroup": {
"unAssignExisting":true
}
}
}
]
Example response
A success response returns HTTP status code 200 and a response body similar to the following example.
[
{
"personIdentity": {
"personNumber": "10020"
},
"personAssignments": {
"scheduleGroup": {
"assignments": []
}
}
},
{
"personIdentity": {
"personNumber": "10030"
},
"personAssignments": {
"scheduleGroup": {
"assignments": []
}
}
}
]
Note: You can verify that the assignments were deleted by calling POST /v1/commons/persons/assignments/multi_read with a request payload specifying all of the affected person identities.
Updated over 1 year ago