Performing Batch Processing

PayRun.io provides the ability to enqueue batches of tasks in a single request. This is accomplished using the Batch Job Instruction. and listing the requred actions.

Batch Job

Batch processing is handled using a background job. You enqueue a batch job then monitor the job progress, waiting until it has completed.

The batched actions are described as a list of batch items. The job can contain any number of batch items, which are executed in the listed order.

Validate Only

Setting the Validate Only value to true, performs a validation only check against the job batch commands. Errors will be reported in the job results, but changes are not commited to the database.

Example Batch Job

curl -X POST \
  'https://api.test.payrun.io/jobs/batch' \
  -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"?>
<BatchJobInstruction xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <HoldingDate xsi:nil="true" />
  <ValidateOnly>false</ValidateOnly>
  <Instructions>
    <PUT Href="/Employer/ER001">
      <Body xsi:type="Employer">
        <EffectiveDate>2018-04-06</EffectiveDate>
        <Name>Batch Employer</Name>
        <Region>NotSet</Region>
        <Territory>UnitedKingdom</Territory>
        <RuleExclusions>None</RuleExclusions>
        <ClaimEmploymentAllowance>false</ClaimEmploymentAllowance>
        <ClaimSmallEmployerRelief>false</ClaimSmallEmployerRelief>
        <ApprenticeshipLevyAllowance>0</ApprenticeshipLevyAllowance>
      </Body>
    </PUT>
    <POST Href="/Employer/ER001/PaySchedules">
      <Body xsi:type="PaySchedule">
        <Name>Test1</Name>
        <PayFrequency>Monthly</PayFrequency>
      </Body>
    </POST>
    <PUT Href="/Employer/ER001/PaySchedule/TEST001">
      <Body xsi:type="PaySchedule">
        <Name>Test2</Name>
        <PayFrequency>Monthly</PayFrequency>
      </Body>
    </PUT>
    <PUT Href="/Employer/ER001/Employee/EE001">
      <Body xsi:type="Employee">
        <EffectiveDate>2018-04-06</EffectiveDate>
        <Code>EMP001</Code>
        <FirstName>John</FirstName>
        <MiddleName xsi:nil="true" />
        <LastName>Smith</LastName>
        <DateOfBirth>0001-01-01</DateOfBirth>
        <Region>England</Region>
        <Territory>UnitedKingdom</Territory>
        <NicLiability>IsFullyLiable</NicLiability>
        <PaySchedule href="/Employer/ER001/PaySchedule/TEST001" />
        <AEAssessmentOverride>None</AEAssessmentOverride>
      </Body>
    </PUT>
    <PATCH Href="/Employer/ER001/Employee/EE001">
      <Body><![CDATA[<Employee><EffectiveDate>2018-04-06</EffectiveDate><Deactivated>true</Deactivated></Employee>]]></Body>
    </PATCH>
    <DELETE Href="/Employer/ER001/PaySchedule/SCH001" />
  </Instructions>
</BatchJobInstruction>'
curl -X POST \
  'https://api.test.payrun.io/jobs/batch' \
  -H 'Accept: application/json' \
  -H 'Api-Version: default' \
  -H 'Authorization: {OAuthHeader}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-type: application/json' \
  -d '{
  "BatchJobInstruction": {
    "HoldingDate": null,
    "ValidateOnly": "false",
    "Instructions": {
      "PUT": [
        {
          "@Href": "/Employer/ER001",
          "Body": {
            "@xsi:type": "Employer",
            "EffectiveDate": "2018-04-06",
            "Name": "Batch Employer",
            "Region": "NotSet",
            "Territory": "UnitedKingdom"
          }
        },
        {
          "@Href": "/Employer/ER001/PaySchedule/TEST001",
          "Body": {
            "@xsi:type": "PaySchedule",
            "Name": "Test2",
            "PayFrequency": "Monthly"
          }
        },
        {
          "@Href": "/Employer/ER001/Employee/EE001",
          "Body": {
            "@xsi:type": "Employee",
            "EffectiveDate": "2018-04-06",
            "Code": "EMP001",
            "FirstName": "John",
            "LastName": "Smith",
            "DateOfBirth": "1980-01-01",
            "Region": "England",
            "Territory": "UnitedKingdom",
            "NicLiability": "IsFullyLiable",
            "PaySchedule": {
              "@href": "/Employer/ER001/PaySchedule/TEST001"
            },
            "StartDate": "2018-01-01",
            "AEAssessmentOverride": "None"
          }
        }
      ],
      "POST": {
        "@Href": "/Employer/ER001/PaySchedules",
        "Body": {
          "@xsi:type": "PaySchedule",
          "Name": "Test1",
          "PayFrequency": "Monthly"
        }
      },
      "PATCH": {
        "@Href": "/Employer/ER001/Employee/EE001",
        "Body": {
          "#cdata-section": "<Employee><EffectiveDate>2018-04-06</EffectiveDate><Deactivated>true</Deactivated></Employee>"
        }
      },
      "DELETE": [
        {
          "@Href": "/Employer/ER001/PaySchedule/SCH001"
        }
      ]
    }
  }
}'

Batch Items

Actions are included using one of the batch item types. Each item type name describes the batch action to perform and includes the resource location to target.

Delete

The delete item only requires the target resource location.

<DELETE Href="/Employer/ER001/PaySchedule/SCH001" />
"DELETE": {
    "@Href": "/Employer/ER001/PaySchedule/SCH001"
}

Patch

Patch items allow you to specify a partial object graph along with the target url. The patch body must describe the patch in XML wrapped inside a CDATA section.

<PATCH Href="/Employer/ER001/Employee/EE001">
    <Body><![CDATA[<Employee><EffectiveDate>2018-04-06</EffectiveDate><Deactivated>true</Deactivated></Employee>]]></Body>
</PATCH>
"PATCH": {
    "@Href": "/Employer/ER001/Employee/EE001",
    "Body": {
        "#cdata-section": "<Employee><EffectiveDate>2018-04-06</EffectiveDate><Deactivated>true</Deactivated></Employee>"
    }
}

NOTE:
When putting or posting you must specify the body data type using the xsi:type attribute.

Post

The post item allows you to insert a new object into a parent collection. It requires both the target collection url and complete object to be posted. Posted objects receive an auto generated unique key.

<POST Href="/Employer/ER001/PaySchedules">
    <Body xsi:type="PaySchedule">
        <Name>Test1</Name>
        <PayFrequency>Monthly</PayFrequency>
    </Body>
</POST>
"POST": {
    "@Href": "/Employer/ER001/PaySchedules",
    "Body": {
        "@xsi:type": "PaySchedule",
        "Name": "Test1",
        "PayFrequency": "Monthly"
    }
}

Put

Performing a put allows you specify the exact resource location to be updated or inserted. Use this option if you do not want to rely on autogenerated unique key identifiers.

<PUT Href="/Employer/ER001">
    <Body xsi:type="Employer">
        <EffectiveDate>2018-04-06</EffectiveDate>
        <Name>Batch Employer</Name>
        <Region>NotSet</Region>
        <Territory>UnitedKingdom</Territory>
    </Body>
</PUT>
"PUT": {
    "@Href": "/Employer/ER001",
    "Body": {
        "@xsi:type": "Employer",
        "EffectiveDate": "2018-04-06",
        "Name": "Batch Employer",
        "Region": "NotSet",
        "Territory": "UnitedKingdom"
    }
}