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:

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 fisrt 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.