Revisible Objects

One core design principle of the PayRun.io API is to allow rewind and replay. To enable this, special revisible data structures have been created.

Revisible objects allow you to capture the changing state and examine the history of an entity.

Recorded as a stacked sequence of instances ordered by the day when the revision becomes effective.

Revisible Data Types

Special Properties

All revisible objects include two special properties: Effective Date and Revision.

Effective Date

The effective date describes the day when the change became effective. Revisions can be made on a per day basis. If there are multiple revisions on a single day, the revision with the highest revision number is considered effective.

Revision Number

Every time a revision is added, the revision number is incremented. Revision numbers are system generated and cannot be set externally. Inserting or updating the revision number will have no effect.

Data Integrity

All revisible objects confirm to a set to data integrity rules to ensure that changes never invalidate existing entities. These rules prevent you from making amendments that contradict previous calculations and ensure that history is created in a chronological sequence.

Dependant Calculation
If the revision information has been used in a pay run calculation, it is considered to have a "dependent calculation". See below for more information on dependant calculations.

1. New revisions cannot supersede existing revisions

Revisions must always be added in chronological order. You cannot insert a revision with an effective date before an existing effective date. However, you can insert a revision with the same effective date, as long as doing so does not conflict with the other data integrity rules.

2. New revisions cannot be before dependent calculation dates

It is not possible to insert a revision with an effective date on or before a dependent calculation payment date. Doing so would invalidate the calculation because the values used to perform the calculation have changed. A calculation is considered dependent if it was generated using the revisible object.

3. Revisions with dependent calculations cannot be deleted

The existence of dependent calculated data prevents the deletion of a revision.

4. Revisions cannot be deleted out of sequence

Only the most recent revision can be deleted. Revisions are treated like a stack, only the top if the stack can be added to or removed.

Dependant calculation

Dependant calculation example:

Effective Date Pay Run Pay Day
Revision 1 2017-04-06 Run A 2017-04-30
Revision 2 2017-05-06 Run B 2017-05-31
Revision 3 2017-06-06

The the above example, the entity has 3 revisions and has been included in 2 pay run calculations.

Run A was completed using Revision 1 and Run B used Revision 2. This means that revisions 1 and 2 have dependent calculations.

Revision 3 is after the most recent pay day, so has no dependent calculation.

Working with Revisions in the API

Revisible objects are handled through the API just like other API resources, using [PUT], [POST], [PATCH], [GET] and [DELETE].

Specify the effective date

In addition to the regular URL pattern, an effective date can also be supplied. This allows you to target a specific history point in the revisible objects life time. If no effective date is specified, the most recent revision is returned.

URL Revision Effective Date
/Employer/ER001/Employee/EE001 Revision 1 2017-04-01
/Employer/ER001/Employee/EE001 Revision 2 2017-05-01
/Employer/ER001/Employee/EE001 Revision 3 2017-05-01
/Employer/ER001/Employee/EE001 Revision 4 2017-05-02

Example URLs

  • /Employer/ER001/Employee/EE001/2017-03-31 - 404 (no revision exists for specified date)
  • /Employer/ER001/Employee/EE001/2017-04-30 - Revision 1
  • /Employer/ER001/Employee/EE001/2017-05-01 - Revision 3
  • /Employer/ER001/Employee/EE001/2017-12-31 - Revision 4
  • /Employer/ER001/Employee/EE001 - Revision 4

Note:
Revision 2 is hidden because Revision 3 uses the same effective date.
When multiple revisions exist on the same day, the highest number revision is used.

Inserting

Revisions can be added using [POST] or [PUT].

Note:
The effective date should not be included in the URL when adding or amending revisions.

Updating

In addition to the standard [PUT], revisible objects can be updated using [PATCH] and a minimal data payload.

Note:
When [PATCH]ing revisions you must include the effective date.

Retrieving

Revisions can be retrieved using [GET]. You can also optionally specify the effective date of the required revision. Omitting the effective date returns the most recent revision.

See Specify the effective date above for more details.

Deleting

Revisible objects can be deleted entirely, or revision by revision. Issuing a [DELETE] without an effective date deletes all revisions. A [DELETE] request including an effective date deletes the revision for the specified date. If multiple revisions exist on the specified date, the highest number revision is deleted.

Note:
Individual revisions can only be deleted in descending revision order. The most recent revision must be deleted first.