Version: 23.10

POST Create Task

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

Request

HTTP request

POST https://<JM_SERVER>/manager/secure/rest/transactions/v1/

Request body

The POST request must contain a request parameter named task, whose value contains a JSON structure. 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 parameters are optional except where otherwise indicated.

Parameter	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. Note: `contactEmailAddress` is required if `sendEmailFlag` is `true`.
`datetimeExpiry`	`String` When the task should expire (automatically) if it has not been completed. Specify a JSON ISO DateTime string without milliseconds using this date format: `yyyy-MM-dd'T'HH:mm:ssZZ`
`datetimeScheduled`	`String` When the task is scheduled to run. Specify a JSON ISO DateTime string without milliseconds using this date format: `yyyy-MM-dd'T'HH:mm:ssZZ`
`emailMessage`	`String` The email message to use in the task notification email. This is used only if `sendEmailFlag` is `true`.
`emailSubject`	`String` The email subject to use in the task notification email. This is used only if `sendEmailFlag` is `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 is used only if `taskType` is `"Anonymous"`.
`groups`	`List of String` A list of group names to which the task shall be assigned. Note: `groups` 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. Note: `portlName` is 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. `reviewSubmissionId` is required and used only if `taskType` is set to `"Review"`.
`saveChallengeAnswer`	`String` Specify a secret answer that the user must enter to access the form if you need to secure the task further. `saveChallengeAnswer` 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 will be sent to the contact email address.
`sequence`	`Integer` The task sequence number. This 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. Specify one of the following 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. `transRefNumber` 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. `userLoginName` 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 JM.

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

Example

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

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

Example request
POST /manager/secure/rest/transactions/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
{
  "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/maguire/servlet/SmartForm.html?submitKey=01b2b3c0ac09dc706fb81c0e47731724"
}

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

Note that 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/transactions/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
{
  "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
}

Create a review task

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

Example request
POST /manager/secure/rest/transactions/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
{
  "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

Example

Create an anonymous saved form

Create a form task with XML form data

Create a review task

In this topic

Need More Help?

Request​

HTTP request​

Request body​

Example​

Create an anonymous saved form​

Create a form task with XML form data​

Create a review task​

In this topic

Need More Help?

Request

HTTP request

Request body

Example

Create an anonymous saved form

Create a form task with XML form data

Create a review task