Integration API

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.