Meta-Data and Tags
The PayRun.io API provides all the data objects you need to enable payroll calculations for a huge range of different employment structures.
However, it is sometimes necessary to extend and catagorise your data. For example you may wish to track a collection of payments that relate to a single project or you may want to have additional properties stored against the employees (ie email or department).
To support extension to the API we provide two features: Meta-Data and Tagging.
What is tagging?
Tags (and tagging) describe the ability to decorate the API objects with a common grouping value. This value is a simple textual string. Tags are controlled using a URL pattern in addition to the decorated entities own URL end point.
The tags URL patterns enable adding and removing tags from a single entity. It is also possible to retrieve entities grouped by a common tag using a single URL.
Using these techniques, it is possible to group and retrieve sets of data objects using a single tag value.
The following data types support tagging:
- CIS Instruction
- CIS Line
- CIS Line Type
- CIS Transaction
- Employee
- Employer
- Holiday Scheme
- Pay Code
- Pay Instruction
- Pay Line
- Pay Run
- Pay Schedule
- RTI Transaction
- Sub Contractor
What is Meta-Data?
In PayRun.io, meta-data describes additional properties set within the data resource. The properties are described using name value pairs. Meta-data Names must be unique within the scope of the owner entity and only contain alpha numeric characters. And meta-data Values, can contain any character.
The follow data types support meta-data:
Tagging URL Patterns
Tags are controlled and retrieved using an extension pattern in addition to the tagged entity URL. Tags allow you to select lists of tag entities using a single request.
Adding Tags
Tags are added using the [PUT] method and the following url pattern.
- Pattern - {Entity Url}/Tag/{Tag Value}
- Example - [PUT] https://api.test.payrun.io/Employer/ER001/Tag/MyTag
- Add the tag value "MyTag" to the employer with unique key "ER001"
Removing Tags
Tags are removed using the [DELETE] method and the following url pattern.
- Pattern - {Entity Url}/Tag/{Tag Value}
- Example - [DELETE] https://api.test.payrun.io/Employer/ER001/Tag/MyTag
- Delete tag "MyTag" from employer with unique key "ER001"
Find all entities in a collection with a specific tag
The following URL pattern is used to return a list of all entities in the collection that have the tag value.
- Pattern - {Parent Entity Url}/{Tagged Entity Type}s/Tag/{Tag Value}
- Example - [GET] https://api.test.payrun.io/Employer/ER001/Employees/Tag/MyTag
- List all employees having tag "MyTag" for employer "ER001"
Find all tags on an entity instance
A list of all entity tags can be retrieved using the following url pattern.
- Pattern - {Entity Url}/Tags
- Example - [GET] https://api.test.payrun.io/Employer/ER001/Employee/EE001/Tags
- List all tags from employee with unique key "EE001"
Find all tags in an entity collection
It is possible to discover all the tags on a collection of entities using the following url pattern.
- Pattern - {Parent Entity Url}/{Tagged Entity Type}s/Tags
- Example - [GET] https://api.test.payrun.io/Employer/ER001/Employees/Tags
- List all employee tags for employer with unique key "ER001"
Entities with Meta-Data
Tagging is excellent for categorising and group your data. But sometimes tagging isn't enough and you need to extend the data model to store additional properties.
Meta-data allows you to store additional name value pair data against the target entity. The extended values are then available when the entity is returned from the API. Meta-data allows you store, edit and delete additional properties on the PayRunIO models that otherwise did not exist.
Name must be Unique
The meta-data name value must be unique within the scope of the extended entity
The extend values are controlled using the standard API communication verbs ([PUT], [POST], [PATCH] and [DELETE]) as part of the decorated entity. This means that there are no additional API end points to consider when dealing with meta-data.
Adding Meta-Data
Meta-data is added to an entity using the MetaData property.
Example
curl -X PUT \
'https://api.test.payrun.io/Employer/ER001' \
-H 'Accept: application/xml' \
-H 'Api-Version: default' \
-H 'Authorization: {OAuthHeader}' \
-H 'Cache-Control: no-cache' \
-H 'Content-type: application/xml' \
-d '<?xml version="1.0"?>
<Employer xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<EffectiveDate>2019-01-01</EffectiveDate>
<MetaData>
<Item Name="Email">Support@company.com</Item>
<Item Name="Departments">Sales,Finance,IT,Shipping</Item>
</MetaData>
</Employer>'
curl -X PUT \
'https://api.test.payrun.io/Employer/ER001' \
-H 'Accept: application/json' \
-H 'Api-Version: default' \
-H 'Authorization: {OAuthHeader}' \
-H 'Cache-Control: no-cache' \
-H 'Content-type: application/json' \
-d '{
"Employer": {
"EffectiveDate": "2019-01-01",
"MetaData": {
"Item": [
{
"@Name": "Email",
"#text": "Support@company.com"
},
{
"@Name": "Departments",
"#text": "Sales,Finance,IT,Shipping"
}
]
}
}
}'
Removing Meta-Data
Meta-data is removed from an entity using the MetaData property. Simply update the object meta data as required and then send ([PUT], [POST] or [PATCH]) it back into the API.
PATCH is absolute!
When updating meta-data using [PATCH], it is important to remember that the entire meta-data property instance will be replaced. Patched meta-data is applied using an override paradigm.
Note: Meta-data is not affected if the [PATCH] does not include a meta-data node.
Example - Delete All
curl -X PATCH \
'https://api.test.payrun.io/Employer/ER001' \
-H 'Accept: application/xml' \
-H 'Api-Version: default' \
-H 'Authorization: {OAuthHeader}' \
-H 'Cache-Control: no-cache' \
-H 'Content-type: application/xml' \
-d '<?xml version="1.0"?>
<Employer xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<EffectiveDate>2019-01-01</EffectiveDate>
<MetaData xsi:nil="true" />
</Employer>'
curl -X PUT \
'https://api.test.payrun.io/Employer/ER001' \
-H 'Accept: application/json' \
-H 'Api-Version: default' \
-H 'Authorization: {OAuthHeader}' \
-H 'Cache-Control: no-cache' \
-H 'Content-type: application/json' \
-d '{
"Employer": {
"EffectiveDate": "2019-01-01",
"MetaData": null
}
}'
Example - Replace All
curl -X PATCH \
'https://api.test.payrun.io/Employer/ER001' \
-H 'Accept: application/xml' \
-H 'Api-Version: default' \
-H 'Authorization: {OAuthHeader}' \
-H 'Cache-Control: no-cache' \
-H 'Content-type: application/xml' \
-d '<?xml version="1.0"?>
<Employer xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<EffectiveDate>2019-01-01</EffectiveDate>
<MetaData>
<Item Name="Email">Info@company.com</Item>
</MetaData>
</Employer>'
curl -X PUT \
'https://api.test.payrun.io/Employer/ER001' \
-H 'Accept: application/json' \
-H 'Api-Version: default' \
-H 'Authorization: {OAuthHeader}' \
-H 'Cache-Control: no-cache' \
-H 'Content-type: application/json' \
-d '{
"Employer": {
"EffectiveDate": "2019-01-01",
"MetaData": {
"Item": [
{
"@Name": "Email",
"#text": "Info@company.com"
}
]
}
}
}'
Meta-Data in Queries
The PayRun.io report query language (RQL) handles meta data as if it was just another property on the entity. By using a dot notation property specification, it is possible to report on the meta data values.
Example Query
The following example query returns the employee email addresses.
curl -X POST \
'https://api.test.payrun.io/Query' \
-H 'Accept: application/xml' \
-H 'Api-Version: default' \
-H 'Authorization: {OAuthHeader}' \
-H 'Cache-Control: no-cache' \
-H 'Content-type: application/xml' \
-d '<?xml version="1.0"?>
<Query xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<RootNodeName>MyQuery</RootNodeName>
<Groups>
<Group ItemName="Employee" Selector="/Employer/ER001/Employees">
<Output xsi:type="RenderProperty" Name="Code" Property="Code" Output="Attribute" />
<Output xsi:type="RenderProperty" Name="Email" Property="MetaData.Email" />
</Group>
</Groups>
</Query>'
curl -X POST \
'https://api.test.payrun.io/Query' \
-H 'Accept: application/json' \
-H 'Api-Version: default' \
-H 'Authorization: {OAuthHeader}' \
-H 'Cache-Control: no-cache' \
-H 'Content-type: application/json' \
-d '{
"Query": {
"RootNodeName": "MyQuery",
"Groups": {
"Group": {
"@ItemName": "Employee",
"@Selector": "/Employer/ER001/Employees",
"Output": [
{
"@xsi:type": "RenderProperty",
"@Output": "Attribute",
"@Name": "Code",
"@Property": "Code"
},
{
"@xsi:type": "RenderProperty",
"@Name": "Email",
"@Property": "MetaData.Email"
}
]
}
}
}
}'
Exmaple Response
<?xml version="1.0"?>
<MyQuery xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" Generated="2019-03-21T11:25:24" Duration="00:00:00.0096165">
<Employee Code="EMP001">
<Email>Employee.A@PayRun.io</Email>
</Employee>
<Employee Code="EMP002">
<Email>Employee.B@PayRun.io</Email>
</Employee>
</MyQuery>
{
"MyQuery": {
"@Generated": "2019-03-21T11:26:32",
"@Duration": "00:00:00.0134497",
"Employee": [
{
"@Code": "EMP001",
"Email": "Employee.A@PayRun.io"
},
{
"@Code": "EMP002",
"Email": "Employee.B@PayRun.io"
}
]
}
}
Common Meta Data Names
There are a set of common meta data "names" that are commonly used across various system reports. If you are writing your own reports or adding meta data it is worth checking this list first to check if a common name has already been defined.
Name | Explanation |
---|---|
AutoEnrolmentOptOutReference | Auto Enrolment opt-out reference; required by some Pension Providers |
CompanyNo | The registered company number. |
CompanyType | The type of company, Limited Liability, Partnership, Sole Trader etc. |
EnrolmentCommunicationsIssuedDate | Date on which enrolment communications were issued to the employee to confirm that enrolment was achieved; used in PAPDIS report. |
GroupNumber | Additional pension identifier. |
JobTitle | The employee's official job title. |
MemberPlanNumber | Employee pension plan number. Legal and General only. |
Nationality | The employee's nationality. |
PrimaryEmailAddress | Employee's primary email address. |
PrimaryTelephone | The employee's primary contact phone number, normally a mobile. |
Employee's secondary email address. | |
SecondaryTelephone | The employee's secondary contact phone number, normally a home landline. |
StatutoryLetterCode | 3-digit unique identifier representing a unique Letter template issued for Auto Enrolment by The Pensions Regulator; used in PAPDIS report. |