REST Tasks API

The Tasks API provides a REST service for creating and updating tasks in Journey Manager in a secure and efficient manner.

Security

To access the Tasks REST endpoint the caller needs to be authenticated using HTTP Basic Authentication. The authenticated user will need an user account on the Journey Manager server and this account will need to be active and have access to the Management Console module.

To be authorized to call the service the user account will also need the Management Console permission 'REST Tasks API'. You will also need to be either an administrator with global access or be associated with an organization to access its transaction records.

URL Endpoint

The REST Tasks API URL endpoint is as follows:

``` https:///manager/secure/rest/tasks/v1/ ```

Service API

This section provides a description all the REST Tasks API operations including:


POST Create Task

Create a task that can be assigned to a user or a group.

URL Format

POST https://<tm server>/manager/secure/rest/tasks/v1/

POST Body

The POST request must contain a request parameter named "task", whose value contains a JSON structure describing the task. To support multiple parameters this API uses the HTTP Content Type: application/x-www-form-urlencoded

The set of task JSON attributes is listed below (all attributes are optional unless indicated otherwise):

Attribute Type Description
allowClaimFlag boolean a flag describing whether the task will be claimable (relevant for tasks assigned to groups)
address String a string containing the physical address related to the task
contactEmailAddress String the email address to send email to (must be specified if sendEmailFlag is set to true)
datetimeExpiry String a JSON ISO DateTime string without milliseconds describing when the task should expire automatically if it has not been completed
the required date format is yyyy-MM-dd'T'HH:mm:ssZZ
datetimeScheduled String a JSON ISO DateTime string without milliseconds describing when the task is scheduled
the required date format is yyyy-MM-dd'T'HH:mm:ssZZ
emailMessage String the email message to use in the task notification email (used only if sendEmailFlag is set to true)
emailSubject String the email subject to use in the task notification email (used only if sendEmailFlag is set to true)
formCode String the form code of the form that the task will be based on (required)
formPrefillServiceName String the name of a service definition of type 'Form Prefill' that will be used to provide prefill XML data at task creation time (used only if taskType is "Anonymous")
groups List of String A list of group names to which the task shall be assigned (required if userLoginName is not set and taskType is not "Anonymous")
latitude Double The latitude of the location the task relates to
longitude Double The longitude of the location the task relates to
portalName String The name of the space that will be hosting the task (required if taskType is set to "Anonymous")
receiptNumber String The receipt number that will be used for the task transaction
reviewSubmissionId String The database ID of the submission that this task will review (required and used only if taskType is set to "Review")
saveChallengeAnswer String If you would like to secure the task further, you can specify a secret answer the user will have to enter to access the form (used only if taskType is set to "Anonymous")
sendEmailFlag boolean a flag controlling whether an email shall be sent to notify of the new task (if taskType is set to "Anonymous", the email will be sent to the contact email address)
sequence Integer The task sequence number (mainly used in collaboration job task sequencing)
taskMessage String The task message that will be displayed to assignees
taskSubject String The task subject that will be displayed to assignees
taskType String The type of task you want to create (required).
Possible values:
  • Anonymous: Create an anonymous saved form
  • Form: Create a standalone task assigned to a user or one or more groups
  • Review: Create a task relating to a previous submission and assign it to a user or one or more groups
transRefNumber String A custom reference number that will be stored in the transaction object (used only if the taskType is set to "Anonymous")
userDeletableFlag boolean a flag controlling whether the task can be deleted by assignees
userLoginName String The login name of the assignee (used only if taskType is not "Anonymous")

In addition to the task request parameter, there are two optional parameters you can use to pass in XML task data:

  • formDataXml - the XML data to be used as the seed file
  • inputXmlData - the XML data that will be mapped into the form using XML prefill mappings set up in TM

The two XML parameters can be passed in as request parameters, or alternatively can be included in a Multipart POST request.

Example: Creating an anonymous saved form

This example creates an anonymous saved form secured with a secret code. The person who will fill in the form is notified via email. The example the message body below formatted for easier reading.

Please ensure you specify Content-Type: application/x-www-form-urlencoded

POST <b>/manager/secure/rest/tasks/v1/</b> HTTP/1.1
Host: https://transact.maguire.com
Content-Type: application/x-www-form-urlencoded

<b>task</b>={
    "taskType": "Anonymous",
    "portalName": "Maguire",
    "formCode": "pf-lt41",
    "taskSubject": "Please complete this submission",
    "taskMessage": "This submission has been assigned to you to complete.",
    "saveChallengeAnswer": "b3d5",
    "contactEmailAddress": "test@avoka.com",
    "sendEmailFlag": true,
    "formPrefillServiceName": "Task Prefill"
}

200 Response

{
  "id": 73003,
  "trackingCode": "7FAE76",
  "submitKey": "01b2b3c0ac09dc706fb81c0e47731724",
  "taskFlag": false,
  "taskCreatedTimestamp": "2015-10-06T14:04:40+11:00",
  "taskSubject": "Please complete this submission",
  "taskMessage": "This submission has been assigned to you to complete.",
  "formCode": "pf-lt41",
  "formName": "Payment Form",
  "formVersion": "1.0",
  "clientCode": "lt41",
  "clientName": "Test Client (4.1)",
  "portalName": "Maguire",
  "fieldWorkerFlag": false,
  "testMode": false,
  "contactEmailAddress": "test@avoka.com",
  "formStatus": "Saved",
  "timeSubmission": "2015-10-06T14:04:39+11:00",
  "userAgentBrowser": "",
  "userAgentOs": "",
  "deliveryStatus": "Not Ready",
  "dataDeleted": false,
  "formURL": "https://transact.maguire.com/web-plugin/servlet/SmartForm.html?submitKey=01b2b3c0ac09dc706fb81c0e47731724"
}

Example: Creating a form task with XML form data

This example creates a standalone form task assigned to a single user with the task parameter, and includes the XML form data provided with the formDataXml parameter.

Please note the form prefill data is application/x-www-form-urlencoded encoded, and the message body below formatted for easier reading. In practice it may be eaiser to use a Multipart POST request to upload the form XML data. 

POST <b>/manager/secure/rest/tasks/v1/</b> HTTP/1.1
Host: https://transact.maguire.com
Content-Type: application/x-www-form-urlencoded

<b>task</b>={
    "taskType": "Form",
    "formCode": "pf-lt41",
    "taskSubject": "Monthly activity summary",
    "taskMessage": "Please fill in the monthly activity summary for 2015-09",
    "transRefNumber": "ma-201509-jdoe",
    "sendEmailFlag": true,
    "emailSubject": "TASK: Monthly activity summary",
    "datetimeScheduled": "2015-10-09T09:00:00%2b10:00",
    "datetimeExpiry": "2015-10-16T23:59:59%2b10:00",
    "userLoginName": jdoe,
    "userDeletableFlag": false
}
&amp;<b>formDataXml</b>=%3C%3Fxml+version%3D%221.0%22+encoding%3D%22UTF-8%22%3F%3E%0A%3CAvokaSmartForm%3E%0A++%3CAddressAustralia%3E%0A++++%3CAddressLine1%2F...

200 Response

{
  "id": 73004,
  "trackingCode": "3ZYAA3",
  "submitKey": "d97d8a4be640d6a04cec039a1a657971",
  "taskFlag": true,
  "taskKey": "d97d8a4be640d6a04cec039a1a657971",
  "taskType": "Form",
  "taskCreatedTimestamp": "2015-10-06T14:09:31+11:00",
  "taskScheduledTimestamp": "2015-10-09T10:00:00+11:00",
  "taskExpiryTimestamp": "2015-10-17T00:59:59+11:00",
  "taskSubject": "Monthly activity summary",
  "taskMessage": "Please fill in the monthly activity summary for 2015-09",
  "formCode": "pf-lt41",
  "formName": "Payment Form",
  "formVersion": "1.0",
  "clientCode": "lt41",
  "clientName": "Test Client (4.1)",
  "fieldWorkerFlag": false,
  "testMode": false,
  "userLoginName": "jdoe",
  "formStatus": "Assigned",
  "userAgentBrowser": "",
  "userAgentOs": "",
  "dataDeleted": false
}

Example: Creating a review task

This example creates a review task assigned to a group of users.

POST <b>/manager/secure/rest/tasks/v1/</b> HTTP/1.1
Host: https://transact.maguire.com
Content-Type: application/x-www-form-urlencoded

<b>task</b>={
    "taskType": "Review",
    "formCode": "pf-lt41",
    "taskSubject": "Please review application no. 69618",
    "sendEmailFlag": false,
    "address": "The Corso, Manly NSW 2095",
    "latitude": -33.86,
    "longitude": 151.2,
    "userDeletableFlag": false,
    "allowClaimFlag": true,
    "groups": [
        "Job Reviewers",
        "Job Managers"
    ],
    "reviewSubmissionId": "69618"
}

200 Response

{
  "id": 73008,
  "trackingCode": "KVGGBB",
  "submitKey": "13537f9ab228a8bc50eae0e5d8bb3436",
  "taskFlag": true,
  "taskKey": "13537f9ab228a8bc50eae0e5d8bb3436",
  "taskType": "Review",
  "taskCreatedTimestamp": "2015-10-06T14:14:49+11:00",
  "taskSubject": "Please review application no. 69618",
  "taskAddress": "The Corso, Manly NSW 2095",
  "taskLatitude": -33.86,
  "taskLongitude": 151.2,
  "formCode": "pf-lt41",
  "formName": "Payment Form",
  "formVersion": "1.0",
  "clientCode": "lt41",
  "clientName": "Test Client (4.1)",
  "fieldWorkerFlag": false,
  "testMode": false,
  "submissionGroupNames": "Job Managers, Job Reviewers",
  "formStatus": "Assigned",
  "userAgentBrowser": "",
  "userAgentOs": "",
  "attachmentsStatus": "Optional",
  "dataDeleted": false
}


PUT Update Task

Update the task's form XML data and/or status.

URL Format

PUT https://<tm server>/manager/secure/rest/tasks/v1/<transaction id>

PUT Body

The body of your PUT request must one or more of the following parameters:

  • formDataXml - the form XML data to update the task with
  • formStatus - the form status information to update the task with. Must be either "Assigned", "Saved" or "Abandoned".
  • processingStatus - the transaction processing status entry to add (visible to the user), but does not otherwise influence transaction processing.

Example: Updating a Task

The example below updates Task ID 72492 (as specified by the URL path transaction id), with the form XML data, form status and processing status message.

Please note the form prefill data is application/x-www-form-urlencoded encoded, and the message body below formatted for easier reading. In practice it may be eaiser to use a Multipart POST request to upload the form XML data. 

POST <b>/manager/secure/rest/tasks/v1/72492/</b> HTTP/1.1
Host: https://transact.maguire.com
Content-Type: application/x-www-form-urlencoded

<b>formDataXml</b>=%3C%3Fxml+version%3D%221.0%22+encoding%3D%22UTF-8%22%3F%3E%0A%3CAvokaSmartForm%3E%0A++%3CAddressAustralia%3E%0A++++%3CAddressLine1%2F...
&amp;<b>formStatus</b>=Saved
&amp;<b>processingStatus</b>=Reverted to saved status at user request

200 Response

{
  "id": 72492,
  "trackingCode": "P74L3V",
  "receiptNumber": "pf-lt41-16",
  "submitKey": "9f746b51721051b674b057c37b4bee95",
  "taskFlag": false,
  "formCode": "pf-lt41",
  "formName": "Payment Form",
  "formVersion": "1.0",
  "clientCode": "lt41",
  "clientName": "Test Client (4.1)",
  "portalName": "Maguire",
  "fieldWorkerFlag": false,
  "testMode": false,
  "userLoginName": "john.smith",
  "formStatus": "Saved",
  "timeRequest": "2015-10-02T14:07:39+10:00",
  "timeSubmission": "2015-10-02T14:10:25+10:00",
  "timeLastUserActivity": "2015-10-02T14:11:14+10:00",
  "timeToSubmitSec": 166,
  "ipAddress": "123.134.145.156",
  "requestCookie": "JSESSIONID=pfD+pEOezdTwyev-jINZSn1y; __utma=264897119.59525688.1351658449.1393997213...",
  "referer": "https://transact.maguire.com/maguire/login.htm",
  "userAgent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:40.0) Gecko/20100101 Firefox/40.0",
  "userAgentBrowser": "Firefox 40",
  "userAgentBrowserType": "Firefox",
  "userAgentBrowserVersion": "40",
  "userAgentDeviceType": "Desktop",
  "userAgentOs": "Windows 7",
  "userAgentOsType": "Windows",
  "userAgentOsVersion": "7",
  "attachmentsStatus": "Optional",
  "paymentStatus": "Required",
  "paymentType": "Hosted",
  "paymentTotal": 123.0,
  "processingStatus": "Reverted to saved status at user request",
  "processingStatusTime": "2015-10-02T14:11:14+10:00",
  "deliveryStatus": "Not Ready",
  "dataDeleted": false,
  "formURL": "https://transact.maguire.com/workspace/secure/servlet/SmartForm.html?submitKey=9f746b51721051b674b057c37b4bee95"
}
← REST Service Definitions APIREST TestCenter API →