Introduction

The Errand API provides mechanisms to send requests to the Calculation Engine to execute Calculations, Imports and Imported Data Deletes asynchronously.

Errand Resources

Errands

Errands are wrappers around various asynchronous tasks executed by the system at the request of the user. Each of the sub types of Errand create an Errand resource, which is used to track the execution progress.

Once created, use the following endpoints to request further information regarding the execution of an Errand.

GET /errand/v1/errands

Utilise this endpoint to retrieve all Errands. Results are paginated.

Responses are JSON (application/json).

Request

$ curl 'https://gateway-domain.performio.co/gateway/errand/v1/errands?page=0&size=20' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer e9036e38-d67e-11e8-9f8b-f2801f1b9fd1'
Headers
Name Description

Authorization

OAuth 2.0 authentication token
Request Parameters
Parameter Description

page

(Optional) Number representing the page to retrieve. Pages start from 0.

size

(Optional) Number representing the records per page count. Default page size is 20 and the maximum is 2000.

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 421

{
  "results" : [ {
    "id" : 1,
    "name" : "SIP Batch",
    "type" : "Calc",
    "state" : "Complete",
    "startTime" : 1539922402211,
    "endTime" : 1539922945221
  }, {
    "id" : 2,
    "name" : "SIP Batch",
    "type" : "Calc",
    "state" : "Complete",
    "startTime" : 1539922402211,
    "endTime" : 1539922945221
  } ],
  "page" : {
    "totalPages" : 1,
    "totalElements" : 2,
    "hasNext" : false
  }
}
Path Type Description

results

Array

Array of results.

results.[].id

Number

Number representing the ID of the created Errand.

results.[].name

String

String representing he name of the task the Errand encapsulates.

results.[].type

String

String representing the type of the Errand.

results.[].state

String

String representing the current state of the errand. May be one of the following: Running, Complete, Failed, Terminated

results.[].startTime

Number

String representing the timestamp the errand began execution.

results.[].endTime

Number

String representing the timestamp the errand completed execution.

page

Object

Object representing result pagination.

page.totalPages

Number

Number representing the total pages at current page size.

page.totalElements

Number

Number representing the total possible elements for the request.

page.hasNext

Boolean

Boolean representing if there is a next page of results.

GET /errand/v1/errands/{errandId}

Utilise this endpoint to retrieve a specific Errand, used if you wish to poll until the Errand has a "Completed" status. In the event of a "Failed" state, further information can be accessed by requesting logs.

Responses are JSON (application/json).

Request

$ curl 'https://gateway-domain.performio.co/gateway/errand/v1/errands/1' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer e9036e38-d67e-11e8-9f8b-f2801f1b9fd1'
Headers
Name Description

Authorization

OAuth 2.0 authentication token
Parameters
Parameter Description

errandId

Number representing the ID of the Errand to fetch.

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 141

{
  "id" : 1,
  "name" : "SIP Batch",
  "type" : "Calc",
  "state" : "Complete",
  "startTime" : 1539922402211,
  "endTime" : 1539922945221
}
Path Type Description

id

Number

Number representing the ID of the created Errand.

name

String

String representing he name of the task the Errand encapsulates.

type

String

String representing the type of the Errand.

state

String

String representing the current state of the errand. May be one of the following: Running, Complete, Failed, Terminated

startTime

Number

String representing the timestamp the errand began execution.

endTime

Number

String representing the timestamp the errand completed execution.

Error Conditions

Reason

Response

Errand ID provided does not resolve to an Errand.

 
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 163

{
  "timestamp" : 1617843921466,
  "status" : 404,
  "error" : "Not Found",
  "message" : "Could not find an Errand with ID 1",
  "path" : "/errand/v1/errands/1"
}

GET /errand/v1/errands/{errandId}/logs

Utilise this endpoint to retrieve logs for a specific Errand. Results are paginated.

Responses are JSON (application/json).

Request

$ curl 'https://gateway-domain.performio.co/gateway/errand/v1/errands/1/logs?page=0&size=2' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer e9036e38-d67e-11e8-9f8b-f2801f1b9fd1'
Headers
Name Description

Authorization

OAuth 2.0 authentication token
Parameters
Parameter Description

errandId

Number representing the ID of the Errand to fetch logs for.

page

(Optional) Number representing the page to retrieve. Pages start from 0.

size

(Optional) Number representing the records per page count. Default page size is 20 and the maximum is 2000.

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 297

{
  "results" : [ {
    "logMessage" : "first line",
    "status" : "",
    "createTime" : 1539922402211
  }, {
    "logMessage" : "second line",
    "status" : "ended",
    "createTime" : 1539922402222
  } ],
  "page" : {
    "totalPages" : 1,
    "totalElements" : 2,
    "hasNext" : false
  }
}
Path Type Description

results

Array

Array of results.

results[].status

String

String representing the status of the log, indicating if it’s not in a batch or logging has ended

results[].createTime

Number

String representing time since epoch for log creation.

results[].logMessage

String

String representing the the logged message.

page

Object

Object representing result pagination.

page.totalPages

Number

Number representing the total pages at current page size.

page.totalElements

Number

Number representing the total possible elements for the request.

page.hasNext

Boolean

Boolean representing if there is a next page of results.

Error Conditions

Reason

Response

Errand ID provided does not resolve to an Errand.

 
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 168

{
  "timestamp" : 1617843921137,
  "status" : 404,
  "error" : "Not Found",
  "message" : "Could not find an Errand with ID 1",
  "path" : "/errand/v1/errands/1/logs"
}

Batch Errands

Batch Errands are wrappers around Batches that are provided asynchronously to the Calculation Engine where they are actioned. In order for a Batch Errand to be correct it requires a Batch and may require a Period range and a list of Participants (an empty list indicates all) to run for.

Utilise V2 of the endpoint if you intend to provide Participant EIDs instead of IDs.

Once created you can poll for the created Batch Errand to verify that is has been completed by utilising the GET /errand/v1/errands/{errandId} endpoint.

POST /errand/v1/batches

Utilise this endpoint to create a Batch Errand by providing Batch ID along with a Period range and Participant set to run the Batch Errand for.

Requests are JSON (application/json). Responses are JSON (application/json).

Related Resources

Batches

Metadata > Batches

Periods

Metadata > Periods

Participants

Metadata > Participants

Errands

Errand > Errands

Request (Calculation)

$ curl 'https://gateway-domain.performio.co/gateway/errand/v1/batches' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer e9036e38-d67e-11e8-9f8b-f2801f1b9fd1' \
    -d '{ "periodRange": [1, 2, 3], "batchId": 1, "participantIds": [1, 2, 3] }'
Headers
Name Description

Authorization

OAuth 2.0 authentication token
Parameters
Path Type Description

periodRange

Array

Array representing Period numbers to run the Errand for.

batchId

Number

Number representing the the ID of Batch to run.

participantIds

Array

Array representing the IDs of the Participant to run the Calculation for, empty representing run the Calculation for all Participants.

Response

HTTP/1.1 202 Accepted
Content-Type: application/json;charset=UTF-8
Content-Length: 129

{
  "id" : 1,
  "name" : "Batch 1",
  "type" : "Calc",
  "state" : "Running",
  "startTime" : 1539922402211,
  "endTime" : null
}
Path Type Description

id

Number

Number representing the ID of the created Errand.

name

String

String representing he name of the task the Errand encapsulates.

type

String

String representing the type of the Errand.

state

String

String representing the current state of the errand. May be one of the following: Running, Complete, Failed, Terminated

startTime

Number

String representing the timestamp the errand began execution.

endTime

Varies

String representing the timestamp the errand completed execution, Null if not finished.

Error Conditions

Reason

Response

A required parameter is missing from the request.

 
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Content-Length: 153

{
  "timestamp" : 1617843925877,
  "status" : 400,
  "error" : "Bad Request",
  "message" : "Period Range is required",
  "path" : "/errand/v1/batches"
}

The requested Batch exists but is not published.

 
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Content-Length: 185

{
  "timestamp" : 1617843926135,
  "status" : 400,
  "error" : "Bad Request",
  "message" : "Could not create Batch Errand: Batch 1 is not published.",
  "path" : "/errand/v1/batches"
}

The requested Batch exists but is not valid for the selected Period range.

 
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Content-Length: 191

{
  "timestamp" : 1617843926177,
  "status" : 400,
  "error" : "Bad Request",
  "message" : "Could not create Batch Errand: Batch 1 not valid for period 1.",
  "path" : "/errand/v1/batches"
}

The requested Batch does not exist.

 
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 157

{
  "timestamp" : 1617843925730,
  "status" : 404,
  "error" : "Not Found",
  "message" : "Could not find Batch with ID 1",
  "path" : "/errand/v1/batches"
}

Due to an internal issue a Batch Errand could not be created.

 
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 168

{
  "timestamp" : 1617843925809,
  "status" : 500,
  "error" : "Internal Server Error",
  "message" : "Could not create Batch Errand",
  "path" : "/errand/v1/batches"
}

POST /errand/v2/batches

Utilise this endpoint to create a Batch Errand by providing a Batch ID along with a Period range and Participant set to run the Batch Errand for.

If Period Range is omitted, the Batch Errand will default to the current Period based on the date the request is run on.

If Participant EIDs are omitted, the Batch Errand will run for all active Participants.

Requests are JSON (application/json). Responses are JSON (application/json).

Related Resources

Batches

Metadata > Batches

Periods

Metadata > Periods

Participants

Metadata > Participants

Errands

Errand > Errands

Request

$ curl 'https://gateway-domain.performio.co/gateway/errand/v2/batches' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer e9036e38-d67e-11e8-9f8b-f2801f1b9fd1' \
    -d '{
  "periodRange" : [ 1, 2, 3 ],
  "batchId" : 1,
  "participantEids" : [ "test_user_1", "test_user_2", "test_user_3" ]
}'
Headers
Name Description

Authorization

OAuth 2.0 authentication token
Parameters
Path Type Description

periodRange

Varies

(Optional) Array representing Period numbers to run the Errand for, omitted or empty will default to the current Period based on the current date.

batchId

Number

Number representing the the ID of Batch to run.

participantEids

Varies

(Optional) Array representing the EIDs of active Participants to run the Batch for, omitted or empty representing all active Participants.

Response

HTTP/1.1 202 Accepted
Content-Type: application/json;charset=UTF-8
Content-Length: 129

{
  "id" : 1,
  "name" : "Batch 1",
  "type" : "Calc",
  "state" : "Running",
  "startTime" : 1539922402211,
  "endTime" : null
}
Path Type Description

id

Number

Number representing the ID of the created Errand.

name

String

String representing he name of the task the Errand encapsulates.

type

String

String representing the type of the Errand.

state

String

String representing the current state of the errand. May be one of the following: Running, Complete, Failed, Terminated

startTime

Number

String representing the timestamp the errand began execution.

endTime

Varies

String representing the timestamp the errand completed execution, Null if not finished.

Error Conditions

Reason

Response

A required parameter is missing from the request.

 
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Content-Length: 149

{
  "timestamp" : 1617843926356,
  "status" : 400,
  "error" : "Bad Request",
  "message" : "Batch ID is required",
  "path" : "/errand/v2/batches"
}

The requested Batch does not exist.

 
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 157

{
  "timestamp" : 1617843926226,
  "status" : 404,
  "error" : "Not Found",
  "message" : "Could not find Batch with ID 1",
  "path" : "/errand/v2/batches"
}

The requested Batch exists but is not published.

 
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 214

{
  "timestamp" : 1617843926459,
  "status" : 422,
  "error" : "Unprocessable Entity",
  "message" : "Could not create Batch Errand",
  "details" : [ "Batch 1 is not published." ],
  "path" : "/errand/v2/batches"
}

The requested Batch exists but is not valid for the selected Period range.

 
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 220

{
  "timestamp" : 1617843926522,
  "status" : 422,
  "error" : "Unprocessable Entity",
  "message" : "Could not create Batch Errand",
  "details" : [ "Batch 1 not valid for period 1." ],
  "path" : "/errand/v2/batches"
}

One or more of the provided Periods are locked

 
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 224

{
  "timestamp" : 1617843926689,
  "status" : 422,
  "error" : "Unprocessable Entity",
  "message" : "Could not create Batch Errand",
  "details" : [ "The following periods are locked: 1" ],
  "path" : "/errand/v2/batches"
}

One or more of the provided Periods do not exist

 
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 220

{
  "timestamp" : 1617843926581,
  "status" : 422,
  "error" : "Unprocessable Entity",
  "message" : "Could not create Errand",
  "details" : [ "The following periods do not exist: 1" ],
  "path" : "/errand/v2/batches"
}

The provided Participant EIDs do not resolve to any Participants

 
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 259

{
  "timestamp" : 1617843926631,
  "status" : 422,
  "error" : "Unprocessable Entity",
  "message" : "Could not create Errand",
  "details" : [ "Could not resolve any active Participants from the provided Participant EIDs" ],
  "path" : "/errand/v2/batches"
}

Period Range has been omitted and a valid current Period could not be found.

 
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 217

{
  "timestamp" : 1617843926266,
  "status" : 500,
  "error" : "Internal Server Error",
  "message" : "Could not find a Period for the date xxxx-xx-xx, please specify a Period Range",
  "path" : "/errand/v2/batches"
}

Due to an internal issue a Batch Errand could not be created.

 
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 168

{
  "timestamp" : 1617843926312,
  "status" : 500,
  "error" : "Internal Server Error",
  "message" : "Could not create Batch Errand",
  "path" : "/errand/v2/batches"
}

Calculation Errands

Calculation Errands are wrappers around Calculations that are provided asynchronously to the Calculation Engine where they are actioned. In order for a Calculation Errand to be correct it requires a Calculation and may require a Period range and a list of Participants (an empty list indicates all) to run for.

Utilise V2 of the endpoint if you intend to provide Participant EIDs instead of IDs.

Once created you can poll for the created Calculation Errand to verify that is has been completed by utilising the GET /errand/v1/errands/{errandId} endpoint.

POST /errand/v1/calculations

Utilise this endpoint to create a Calculation Errand by providing a Calculation ID along with a Period range and Participant set to run the Calculation Errand for. A Calculation ID can refer to a Plan Template, Leader Board or Script calculation.

Requests are JSON (application/json). Responses are JSON (application/json).

Related Resources

Calculations

Metadata > Calculations

Periods

Metadata > Periods

Participants

Metadata > Participants

Errands

Errand > Errands

Request

$ curl 'https://gateway-domain.performio.co/gateway/errand/v1/calculations' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer e9036e38-d67e-11e8-9f8b-f2801f1b9fd1' \
    -d '{ "periodRange": [1, 2, 3], "calculationId": 1, "participantIds": [1, 2, 3] }'
Headers
Name Description

Authorization

OAuth 2.0 authentication token
Parameters
Path Type Description

periodRange

Array

Array representing Period numbers to run the Errand for.

calculationId

Number

Number representing the the ID of Calculation to run.

participantIds

Array

Array representing the IDs of the Participant to run the Calculation for, empty representing run the Calculation for all Participants.

Response

HTTP/1.1 202 Accepted
Content-Type: application/json;charset=UTF-8
Content-Length: 140

{
  "id" : 1,
  "name" : "SIP Calc: Period 1",
  "type" : "Calc",
  "state" : "Running",
  "startTime" : 1539922402211,
  "endTime" : null
}
Path Type Description

id

Number

Number representing the ID of the created Errand.

name

String

String representing he name of the task the Errand encapsulates.

type

String

String representing the type of the Errand.

state

String

String representing the current state of the errand. May be one of the following: Running, Complete, Failed, Terminated

startTime

Number

String representing the timestamp the errand began execution.

endTime

Varies

String representing the timestamp the errand completed execution, Null if not finished.

Error Conditions

Reason

Response

A required parameter is missing from the request.

 
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Content-Length: 158

{
  "timestamp" : 1617843924288,
  "status" : 400,
  "error" : "Bad Request",
  "message" : "Period Range is required",
  "path" : "/errand/v1/calculations"
}

The requested Calculation exists but is not published.

 
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Content-Length: 202

{
  "timestamp" : 1617843924399,
  "status" : 400,
  "error" : "Bad Request",
  "message" : "Could not create Calculation Errand: Calculation 1 is not published.",
  "path" : "/errand/v1/calculations"
}

The requested Calculation exists but is not active.

 
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Content-Length: 199

{
  "timestamp" : 1617843924513,
  "status" : 400,
  "error" : "Bad Request",
  "message" : "Could not create Calculation Errand: Calculation 1 is not active.",
  "path" : "/errand/v1/calculations"
}

The requested Calculation exists but is not valid for the selected Period range.

 
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Content-Length: 208

{
  "timestamp" : 1617843924214,
  "status" : 400,
  "error" : "Bad Request",
  "message" : "Could not create Calculation Errand: Calculation 1 not valid for period 1.",
  "path" : "/errand/v1/calculations"
}

The requested Calculation does not exist.

 
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 168

{
  "timestamp" : 1617843924345,
  "status" : 404,
  "error" : "Not Found",
  "message" : "Could not find Calculation with ID 1",
  "path" : "/errand/v1/calculations"
}

Due to an internal issue a Calculation Errand could not be created.

 
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 179

{
  "timestamp" : 1617843924578,
  "status" : 500,
  "error" : "Internal Server Error",
  "message" : "Could not create Calculation Errand",
  "path" : "/errand/v1/calculations"
}

POST /errand/v2/calculations

Utilise this endpoint to create a Calculation Errand by providing a Calculation ID along with a Period range and Participant set to run the Calculation Errand for. A Calculation ID can refer to a Plan Template, Leader Board or Script calculation.

If Period Range is omitted, the Calculation Errand will default to the current Period based on the date the request is run on.

If Participant EIDs are omitted, the Calculation Errand will run for all active Participants.

Requests are JSON (application/json). Responses are JSON (application/json).

Related Resources

Calculations

Metadata > Calculations

Periods

Metadata > Periods

Participants

Metadata > Participants

Errands

Errand > Errands

Request

$ curl 'https://gateway-domain.performio.co/gateway/errand/v2/calculations' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer e9036e38-d67e-11e8-9f8b-f2801f1b9fd1' \
    -d '{
  "periodRange" : [ 1, 2, 3 ],
  "calculationId" : 1,
  "participantEids" : [ "test_user_1", "test_user_2", "test_user_3" ]
}'
Headers
Name Description

Authorization

OAuth 2.0 authentication token
Parameters
Path Type Description

periodRange

Varies

(Optional) Array representing Period numbers to run the Errand for, omitted or empty will default to the current Period based on the current date.

calculationId

Number

Number representing the the ID of Calculation to run.

participantEids

Varies

(Optional) Array representing the EIDs of active Participants to run the Calculation for, omitted or empty representing all active Participants.

Response

HTTP/1.1 202 Accepted
Content-Type: application/json;charset=UTF-8
Content-Length: 140

{
  "id" : 1,
  "name" : "SIP Calc: Period 1",
  "type" : "Calc",
  "state" : "Running",
  "startTime" : 1539922402211,
  "endTime" : null
}
Path Type Description

id

Number

Number representing the ID of the created Errand.

name

String

String representing he name of the task the Errand encapsulates.

type

String

String representing the type of the Errand.

state

String

String representing the current state of the errand. May be one of the following: Running, Complete, Failed, Terminated

startTime

Number

String representing the timestamp the errand began execution.

endTime

Varies

String representing the timestamp the errand completed execution, Null if not finished.

Error Conditions

Reason

Response

A required parameter is missing from the request.

 
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Content-Length: 160

{
  "timestamp" : 1617843923691,
  "status" : 400,
  "error" : "Bad Request",
  "message" : "Calculation ID is required",
  "path" : "/errand/v2/calculations"
}

The requested Calculation does not exist.

 
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 168

{
  "timestamp" : 1617843923758,
  "status" : 404,
  "error" : "Not Found",
  "message" : "Could not find Calculation with ID 1",
  "path" : "/errand/v2/calculations"
}

The requested Calculation exists but is not published.

 
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 231

{
  "timestamp" : 1617843923873,
  "status" : 422,
  "error" : "Unprocessable Entity",
  "message" : "Could not create Calculation Errand",
  "details" : [ "Calculation 1 is not published." ],
  "path" : "/errand/v2/calculations"
}

The requested Calculation exists but is not active.

 
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 228

{
  "timestamp" : 1617843924048,
  "status" : 422,
  "error" : "Unprocessable Entity",
  "message" : "Could not create Calculation Errand",
  "details" : [ "Calculation 1 is not active." ],
  "path" : "/errand/v2/calculations"
}

The requested Calculation exists but is not valid for the selected Period range.

 
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 237

{
  "timestamp" : 1617843923605,
  "status" : 422,
  "error" : "Unprocessable Entity",
  "message" : "Could not create Calculation Errand",
  "details" : [ "Calculation 1 not valid for period 1." ],
  "path" : "/errand/v2/calculations"
}

One or more of the provided Periods are locked

 
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 223

{
  "timestamp" : 1617843923927,
  "status" : 422,
  "error" : "Unprocessable Entity",
  "message" : "Could not create Errand",
  "details" : [ "The following periods are locked: 1" ],
  "path" : "/errand/v2/calculations"
}

One or more of the provided Periods do not exist

 
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 225

{
  "timestamp" : 1617843923816,
  "status" : 422,
  "error" : "Unprocessable Entity",
  "message" : "Could not create Errand",
  "details" : [ "The following periods do not exist: 1" ],
  "path" : "/errand/v2/calculations"
}

The provided Participant EIDs do not resolve to any Participants

 
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 264

{
  "timestamp" : 1617843923543,
  "status" : 422,
  "error" : "Unprocessable Entity",
  "message" : "Could not create Errand",
  "details" : [ "Could not resolve any active Participants from the provided Participant EIDs" ],
  "path" : "/errand/v2/calculations"
}

Period Range has been omitted and a valid current Period could not be found.

 
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 222

{
  "timestamp" : 1617843924102,
  "status" : 500,
  "error" : "Internal Server Error",
  "message" : "Could not find a Period for the date xxxx-xx-xx, please specify a Period Range",
  "path" : "/errand/v2/calculations"
}

Due to an internal issue a Calculation Errand could not be created.

 
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 179

{
  "timestamp" : 1617843924154,
  "status" : 500,
  "error" : "Internal Server Error",
  "message" : "Could not create Calculation Errand",
  "path" : "/errand/v2/calculations"
}

Imported Data Delete Errands

Imported Data Delete Errands are wrappers around deletions for data previously imported via Import File that are asynchronously passed to the Calculation Engine where they are actioned. In order to be successful, Delete Data Errands must reference an Import File.

Once created you can poll for the created Imported Data Delete Errand to verify that is has been completed by utilising the GET /errand/v1/errands/{errandId} endpoint.

POST /errand/v1/imported-data-deletes

This endpoint allows you to request that an Errand wrapping a request to delete previously imported file data to be created and sent to the Calculation Engine to be actioned. The response is an object describing the current state of the Errand.

Requests are JSON (application/json). Responses are JSON (application/json).

Related Resources

Import Files

Document > Import Files

Errands

Errand > Errands

Request

$ curl 'https://gateway-domain.performio.co/gateway/errand/v1/imported-data-deletes' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer e9036e38-d67e-11e8-9f8b-f2801f1b9fd1' \
    -d '{
  "importFileId": 1
}'
Headers
Name Description

Authorization

OAuth 2.0 authentication token
Parameters
Path Type Description

importFileId

Number

Number representing the ID of the Import File to delete data for.

Response

HTTP/1.1 202 Accepted
Content-Type: application/json;charset=UTF-8
Content-Length: 146

{
  "id" : 1,
  "name" : "file.csv",
  "type" : "Delete Imported Data",
  "state" : "Running",
  "startTime" : 1539922402211,
  "endTime" : null
}
Path Type Description

id

Number

Number representing the ID of the created Errand.

name

String

String representing he name of the task the Errand encapsulates.

type

String

String representing the type of the Errand.

state

String

String representing the current state of the errand. May be one of the following: Running, Complete, Failed, Terminated

startTime

Number

String representing the timestamp the errand began execution.

endTime

Varies

String representing the timestamp the errand completed execution, Null if not finished.

Error Conditions

Reason

Response

A required parameter is missing from the request.

 
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Content-Length: 169

{
  "timestamp" : 1617843922007,
  "status" : 400,
  "error" : "Bad Request",
  "message" : "Import File ID is required",
  "path" : "/errand/v1/imported-data-deletes"
}

The request Import File does not exist.

 
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 176

{
  "timestamp" : 1617843921827,
  "status" : 404,
  "error" : "Not Found",
  "message" : "Could not find ImportFile with ID 1",
  "path" : "/errand/v1/imported-data-deletes"
}

Due to an internal issue an Imported Data Delete Errand could not be created.

 
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 199

{
  "timestamp" : 1617843921887,
  "status" : 500,
  "error" : "Internal Server Error",
  "message" : "Could not generate Imported Data Delete Errand",
  "path" : "/errand/v1/imported-data-deletes"
}

Import Errands

Import Errands are wrappers around Import File / Import File Type combinations that are provided asynchronously to the Calculation Engine to be imported. In order to be successful, an Import Errand must contain a reference to an Import File and an Import File Type. Depending on the Import File Type, a Period range may be required too.

Once created you can poll for the created Import Errand to verify that is has been completed by utilising the GET /errand/v1/errands/{errandId} endpoint.

POST /errand/v1/imports/file

Utilise this endpoint to create an Import Errand to import a pre-created Import File.

Requests are JSON (application/json). Responses are JSON (application/json).

Related Resources

Import Files

Document > Import Files

Import File Types

Metadata > Import File Types

Periods

Metadata > Periods

Errands

Errand > Errands

Request

$ curl 'https://gateway-domain.performio.co/gateway/errand/v1/imports/file' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer e9036e38-d67e-11e8-9f8b-f2801f1b9fd1' \
    -d '{
  "importFileId": 1,   "periodRange": [1, 2, 3],
  "importFileTypeId": "standard-3"
}'
Headers
Name Description

Authorization

OAuth 2.0 authentication token
Parameters
Path Type Description

importFileId

Number

Number representing the ID of the File to be imported.

periodRange

Array

(Optional) Array representing the Period range to run the Errand for. May be omitted if the Import File Type selected does not require a Period. Full range will be derived from the lowest to highest value provided.

importFileTypeId

String

String representing the the ID of the Import File Type to import the provided records as.

Response

HTTP/1.1 202 Accepted
Content-Type: application/json;charset=UTF-8
Content-Length: 154

{
  "id" : 1,
  "name" : "Import Test: Period 1",
  "type" : "Import",
  "state" : "Running",
  "startTime" : 1539922402211,
  "endTime" : 1539922945221
}
Path Type Description

id

Number

Number representing the ID of the created Errand.

name

String

String representing he name of the task the Errand encapsulates.

type

String

String representing the type of the Errand.

state

String

String representing the current state of the errand. May be one of the following: Running, Complete, Failed, Terminated

startTime

Number

String representing the timestamp the errand began execution.

endTime

Varies

String representing the timestamp the errand completed execution, Null if not finished.

Error Conditions

Reason

Response

A required parameter is missing from the request

 
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Content-Length: 165

{
  "timestamp" : 1617843922584,
  "status" : 400,
  "error" : "Bad Request",
  "message" : "Import File Type ID is required",
  "path" : "/errand/v1/imports/file"
}

The requested Import File does not exist.

 
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 168

{
  "timestamp" : 1617843922818,
  "status" : 404,
  "error" : "Not Found",
  "message" : "Could not find Import File with ID 1",
  "path" : "/errand/v1/imports/file"
}

The requested Import File Type does not exist.

 
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 184

{
  "timestamp" : 1617843922695,
  "status" : 404,
  "error" : "Not Found",
  "message" : "Could not find Import File Type with ID standard-300",
  "path" : "/errand/v1/imports/file"
}

Due to an internal issue an Import Errand could not be created.

 
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 174

{
  "timestamp" : 1617843922640,
  "status" : 500,
  "error" : "Internal Server Error",
  "message" : "Could not create Import Errand",
  "path" : "/errand/v1/imports/file"
}

POST /errand/v1/imports/records

Utilise this endpoint to perform an Import Errand for up to 50 records as provided in the request.

Requests are JSON (application/json). Responses are JSON (application/json).

Related Resources

Import File Types

Metadata > Import File Types

Periods

Metadata > Periods

Errands

Errand > Errands

Request

$ curl 'https://gateway-domain.performio.co/gateway/errand/v1/imports/records' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer e9036e38-d67e-11e8-9f8b-f2801f1b9fd1' \
    -d '{
  "records": [
    { "field1": "value1" },    { "field1": "value2" },    { "field1": "value3" },    { "field1": "value4" }  ],
  "periodRange": [1],
  "importFileTypeId": "standard-1"
}'
Headers
Name Description

Authorization

OAuth 2.0 authentication token
Parameters
Path Type Description

periodRange

Array

(Optional) Array representing the Period range to run the Errand for. May be omitted if the Import File Type selected does not require a Period. Full range will be derived from the lowest to highest value provided.

importFileTypeId

String

String representing the the ID of the Import File Type to import the provided records as.

records

Array

Array representing records to import as JSON objects.

Response

HTTP/1.1 202 Accepted
Content-Type: application/json;charset=UTF-8
Content-Length: 141

{
  "id" : 1,
  "name" : "Account: Period 1",
  "type" : "Import",
  "state" : "Running",
  "startTime" : 1539922402211,
  "endTime" : null
}
Path Type Description

id

Number

Number representing the ID of the created Errand.

name

String

String representing he name of the task the Errand encapsulates.

type

String

String representing the type of the Errand.

state

String

String representing the current state of the errand. May be one of the following: Running, Complete, Failed, Terminated

startTime

Number

String representing the timestamp the errand began execution.

endTime

Varies

String representing the timestamp the errand completed execution, Null if not finished.

Error Conditions

Reason

Response

A required parameter is missing from the request.

 
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Content-Length: 157

{
  "timestamp" : 1617843922529,
  "status" : 400,
  "error" : "Bad Request",
  "message" : "Records are required",
  "path" : "/errand/v1/imports/records"
}

Record count in the request exceeds the maximum allowed.

 
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 242

{
  "timestamp" : 1617843922415,
  "status" : 422,
  "error" : "Unprocessable Entity",
  "message" : "Could not create Import Errand.",
  "details" : [ "Restrict request to a maximum of 50 records" ],
  "path" : "/errand/v1/imports/records"
}

The requested Import File Type does not exist.

 
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 187

{
  "timestamp" : 1617843922757,
  "status" : 404,
  "error" : "Not Found",
  "message" : "Could not find Import File Type with ID standard-100",
  "path" : "/errand/v1/imports/records"
}

Due to an internal issue an Import Errand could not be created.

 
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 178

{
  "timestamp" : 1617843922472,
  "status" : 500,
  "error" : "Internal Server Error",
  "message" : "Could not create Import Errand.",
  "path" : "/errand/v1/imports/records"
}