Skip to main content

Version: 22.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.

ParameterDescription
allowClaimFlagboolean
Whether the task will be claimable.
This is relevant for tasks assigned to groups.
addressString
The physical address related to the task.
contactEmailAddressString
The email address to send email to.
Note: contactEmailAddress is required if sendEmailFlag is true.
datetimeExpiryString
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
datetimeScheduledString
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
emailMessageString
The email message to use in the task notification email.
This is used only if sendEmailFlag is true.
emailSubjectString
The email subject to use in the task notification email.
This is used only if sendEmailFlag is true.
formCodeString
Required. The form code of the form that the task will be based on.
formPrefillServiceNameString
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".
groupsList 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".
latitudeDouble
The latitude of the location the task relates to.
longitudeDouble
The longitude of the location the task relates to.
portalNameString
The name of the space that will be hosting the task.
Note: portlName is required if taskType is set to "Anonymous".
receiptNumberString
The receipt number that will be used for the task transaction.
reviewSubmissionIdString
The database ID of the submission that this task will review.
reviewSubmissionId is required and used only if taskType is set to "Review".
saveChallengeAnswerString
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".
sendEmailFlagboolean
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.
sequenceInteger
The task sequence number.
This is used mainly in collaboration job task sequencing.
taskMessageString
The task message that will be displayed to assignees.
taskSubjectString
The task subject that will be displayed to assignees.
taskTypeString
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.
transRefNumberString
A custom reference number that will be stored in the transaction object.
transRefNumber is used only if the taskType is set to "Anonymous"
userDeletableFlagboolean
Whether the task can be deleted by assignees.
userLoginNameString
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
}