An in-depth guide on how to use our Integration API, and what information can be sent to RotaMaster using this API.
Introduction
The Integration API is a REST API, allowing users to send information to their RotaMaster (RM) database. It accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. The integration API currently allows you to create, update and delete adjustments in RotaMaster.
Endpoints
The endpoints and resource models can be viewed and tried out via Swagger:
https://rotamaster-api.rotamasterweb.co.uk/swagger/index.html
You will need to liaise with your Account Manager to get the access codes.
Authentication
The Integration API will authenticate over an authentication endpoint and will require the RotaMaster Adjustment API key, a customer unique access key and customer ID. This will return a JSON Web Token (JWT) that will be used to authorise requests to the API. The JWT will expire after 5 minutes.
Create/Update Adjustment
This endpoint creates a new adjustment in RotaMaster if there is no existing link between the source adjustment and RotaMaster. If there is an existing link, it will update the existing data with what is provided.
Endpoint
HTTP Method: POST
URL: https://rotamaster-api.rotamasterweb.co.uk/api/integration
Parameters
When creating, if the mandatory fields are not supplied then the adjustment will not be created. When updating, if a parameter is not supplied then that information will not be updated.
|
Field Name |
Mandatory |
Description |
|
Adjustment ID |
Y |
A unique ID that will link the original adjustment with the one created in RotaMaster. Alphanumeric (36 characters) |
|
Person ID |
Y (for creation) |
Must match the payroll ID. Alphanumeric 15 characters |
|
Start Date |
Y |
|
|
End Date |
Y |
|
|
Break |
N |
Break duration in minutes |
|
Paid |
N |
Is the break paid. If blank, will default to no. In minutes |
|
Duration |
N |
If blank, then duration will be worked out by the system |
|
Reason |
Y |
Must match to an adjustment reason in RotaMaster. Will match on the adjustment reason nominal code |
|
Role |
N |
Must match to a role in RotaMaster. Will match on the role nominal code. If not provided, primary role will be used. |
|
Type |
N |
If blank, will default to Planned |
|
Pay Rate Group |
N |
Must match to a pay rate group in RotaMaster. Will match on the pay rate reference field. If blank, will use RM logic to apply a pay rate group (where applicable) |
|
InitialProcessedDate |
Y |
The API will process the adjustments based on this date |
|
DataType |
Y |
Always set to 1 |
Delete Adjustment
This endpoint removes adjustments from RotaMaster.
Endpoint
HTTP Method: DELETE
URL: https://rotamaster-api.rotamasterweb.co.uk/api/integration
Parameters
A list of adjustment IDs to delete.
|
Field Name |
Mandatory |
Description |
|
Adjustment ID |
Y |
This is the unique ID that was originally sent when creating the adjustment. |
Note: Only adjustments created by the API can be deleted via the API
Get Adjustment Status
Retrieve the status of an adjustment ID within RotaMaster.
Endpoint
HTTP Method: GET
URL: https://rotamaster-api.rotamasterweb.co.uk/api/integration
Parameters
A list of adjustments that have been processed since the provided time will be sent in the response.
|
Field Name |
Mandatory |
Description |
|
PreviousRequestTime |
Y |
Note that adding Z to the end of the time will submit the time in GMT not BST |
|
Data Type |
Y |
A value needed on our end to process the data correctly. This value will always be 1. |
Error Codes
On receipt of the data, the Integration API will validate the data for mandatory fields and data formats before creating the records for processing by RotaMaster. If there are any issues with the data at this stage, the invalid records will not be created and there will be an error message in the response for each affected adjustment.
When being processed in RotaMaster, the following validation will be done and an error will be returned from the adjustment status endpoint if any occur:
- Invalid person ID
- Start date before end date
- Break duration less than duration of adjustment
- Invalid adjustment reason
- Adjustment before person start date or after end date
- Invalid role
- Invalid type
- Invalid pay rate group
Processing an adjustment in RotaMaster
Once the data has been received by RotaMaster, the adjustment will be created and the following logic will be applied. For the adjustment to be created, the person ID must match a person who already exists in RotaMaster. If the person ID does not exist then an error will be returned.
Shifts
If the person is in shifts and an adjustment type that is marked in RotaMaster as ‘is leave’ or ‘is sickness’ is created, then that person will be removed from the shifts. If this adjustment is then deleted, that person will not be returned to their shifts. Manual intervention is needed to place them back in the roster.
If the adjustment starts or ends part way through a shift then the shift will be split and the person will be removed from the part of the shift covered by the adjustment.
Pay Rate Group
If no pay rate group reference has been supplied then RM will calculate the pay rate group as follows:
If the person has been removed from a single shift or multiple shifts with the same pay rate group, it will take the assigned pay rate group from the removed shift(s).
If the person has not been removed from a shift or is removed from multiple shifts with differing pay rate groups, no pay rate group will be assigned to the adjustment and the value will remain as 0.
Duration
If no duration is entered then RM will calculate the duration as follows. If a duration is entered then this will always be used.
If the person is in shifts in the time period of the adjustment, and the adjustment reason is marked as a sick or leave type then the duration of the shift will be used.
If the person is not in shifts then their daily working hours will be used.
If no daily working hours then the duration between the start and end time of the adjustment will be used.
Adding New Adjustments
Users will be able to create adjustments within RotaMaster as well. Permissions and end user training will need to be employed to prevent duplication.
Editing Adjustments
Once the adjustment is created in RotaMaster, only the pay rate group can be edited within RotaMaster. If the payrate group is edited and then an update is received for that adjustment with a different pay rate value then this will update the pay rate group.
Adjustments created by the API can only be deleted by the API.