Version: 23.10

POST Create Task

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

Request

HTTP request

POST https://<TM_SERVER>/manager/secure/rest/tasks/v1/

Request 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 HTTP Content Type: application/x-www-form-urlencoded.

The set of task JSON attributes is listed below. All attributes are optional unless otherwise indicated.

Attribute	Description
allowClaimFlag	`boolean` Whether the task will be claimable. This is relevant for tasks assigned to groups.
address	`String` The physical address related to the task.
contactEmailAddress	`String` The email address to send email to. This must be specified if `sendEmailFlag` is set to `true`.
datetimeExpiry	`String` When the task should expire automatically if it has not been completed. Specify a JSON ISO DateTime string without milliseconds, using the date format: `yyyy-MM-dd'T'HH:mm:ssZZ`
datetimeScheduled	`String` When the task is scheduled to occur. Specify a JSON ISO DateTime string without milliseconds, using the date format: `yyyy-MM-dd'T'HH:mm:ssZZ`
emailMessage	`String` The email message to use in the task notification email. This parameter is used only if `sendEmailFlag` is set to `true`.
emailSubject	`String` The email subject to use in the task notification email. This parameter is used only if `sendEmailFlag` is set to `true`.
formCode	`String` Required. The form code of the form that the task will be based on.
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. This parameter is used only if `taskType` is `"Anonymous"`.
groups	`List of String` A list of group names to which the task shall be assigned. This parameter is 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. This parameter is required if `taskType` is set to `"Anonymous"`.
receiptNumber	`String` The receipt number that will be used for the task transaction.
reviewSubmissionId	`String` Required (if `taskType` is set to `"Review"`). The database ID of the submission that this task will review. This parameter is used only if `taskType` is set to `"Review"`.
saveChallengeAnswer	`String` A secret answer the user must enter to access the form if you need to secure the task further. This parameter is used only if `taskType` is set to `"Anonymous"`.
sendEmailFlag	`boolean` Whether an email shall be sent to notify of the new task. If `taskType` is set to `"Anonymous"`, the email is sent to the contact email address.
sequence	`Integer` The task sequence number. This parameter is used mainly 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` Required. The type of task you want to create. 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. This parameter is used only if the `taskType` is set to `"Anonymous"`.
userDeletableFlag	`boolean` Whether the task can be deleted by assignees.
userLoginName	`String` The login name of the assignee. This parameter is 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.

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

Response

If successful, this operation returns a response with a HTTP 200 OK status code.

Examples

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.

info

Ensure you specify Content-Type: application/x-www-form-urlencoded.

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

task={
    "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": "[email protected]",
    "sendEmailFlag": true,
    "formPrefillServiceName": "Task Prefill"
}

Example response for a successful request
{
  "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": "[email protected]",
  "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"
}

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.

The form prefill data is application/x-www-form-urlencoded encoded. In practice, it may be easier to use a multipart POST request to upload the form XML data.

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

task={
    "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
}
&formDataXml=%3C%3Fxml+version%3D%221.0%22+encoding%3D%22UTF-8%22%3F%3E%0A%3CAvokaSmartForm%3E%0A++%3CAddressAustralia%3E%0A++++%3CAddressLine1%2F...

Example response for a successful request
{
  "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
}

Review task

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

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

task={
    "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"
}

Example response for a successful request
{
  "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
}

POST Create Task

Request

HTTP request

Request body

Response

Examples

Anonymous saved form

info

Form task with XML form data

Review task

In this topic

Need More Help?

Request​

HTTP request​

Request body​

Response​

Examples​

Anonymous saved form​

info

Form task with XML form data​

Review task​

In this topic

Need More Help?

Request

HTTP request

Request body

Response

Examples

Anonymous saved form

Form task with XML form data

Review task