Api/Tasks/updateAsXml updates existing task, what is given in specific XML format.
Requirements
API user needs permission to task module, and subpermission allow editing of tasks.
Syntax
Api/Tasks/updateAsXml (xml, version)
XML
: special format explained below, what contains updatable fields of existing task. Referring to existing task goes throughid
orexternalId
fields.version
: if used, there are two possible values:- defaults to original format
- supports task types, forms, and subtasks
XML format
Main element is <task/>
. XML versions 1 and 2 may contain following subitems:
id
: unique database number of task, what you want to update. It's generated on creating on task. Use this orexternalId
to update task. If both are present,id
is used, andexternalId
is updated.externalId
: unique task identifier from customer side. If you want to refer to task using that field, it must be filled earlier.name
: task nametimestamp
: task time in formatYYYY-MM-DD [hh:mm[:ss]]
. Note that time is not mandatory, and you can leave out seconds. Task without time defaults to 00:00.status
: one of valuesTODO
,INPROGRESS
,DONE
,FAILED
description
: any textcustomerId
: database number, what refers to existing customer. If this is used, customerName is overwritten, and address is taken from customer datacustomerName
: free text, what gives name to customer field. Probably no real reference to existing customer is made.driver
: owner of that task. Either driver e-mail, phone or name. System tries to match it with existing user.location
: complex XML, what may contain following subitems:address
- textual address, what gets geocoded into world coordinateslatitude
- D.DD...longitude
- D.DD...
timewindowbegin
: timestamp in formatYYYY-MM-DD hh:mm:ss
, used together with timewindowend to specify time window, when this task is available (like shop, what can take cargo in only on specified time). It's used for optimisation for scheduling driver task ordertimewindowend
: timestamp in formatYYYY-MM-DD hh:mm:ss
quantity
: number used for optimisation
Version 2 additionally supports following fields:
type
: external ID of task type. See this page, where this ID must be inserted.forms
: lists forms and their values. Format is described below.subtasks
: lists subtasks
Note that not all elements are mandatory, only name and timestamp.
If you are interested in XML schema definition, look for attachments in that document: task_update_v2.xsd.
Forms
You have to use ExternalId
values on forms and their fields to add and update forms via API. See this page, how to prepare forms for API. You cannot update form fields, what does not have external ID values.
General format for updating forms is following:
<forms> <form key="form1ExternalId"> <fields> <field key="field1ExternalId">field1Value</field> <field key="field2ExternalId">field2Value</field> .... </fields> </form> <form key="form2ExternalId"> ... </form> ... </forms>
See examples, how this may look like on real task.
Subtasks
<subtasks>
element contains list of <task>
elements, what have same format than described here.
<subtasks> <task>...</task> <task>...</task> ... </subtasks>
Response
If task format was correct, and there was no syntax errors, inside response element, there is element tasks, what has array of one or more tasks inside task element:
<?xml version="1.0" encoding="utf-8" ?> <nodes> <status>0</status> <response> <tasks> <task> <id>taskid</id> <!--other data--> </task> </tasks> </response> </nodes>
Examples
Minimal task
This task requires only task name for updating:
<task> <id>1234</id>
<name>Installing 123ABC</name> </task>
As you can see, you can be very conservative about fields you want to update, include only necessary fields.
Task type and forms
This example is taken from setup introduced under task types. It creates task with type Installation and fills form installation with required fields (although this is just example, some of them are probably filled on installation).
<task>
<id>1234</id>
<timestamp>2020-03-26 15:20</timestamp>
<name>Installing 123ABC</name>
<type>installation</type>
<forms>
<form key="Installation">
<field key="installationDate">2020-03-26</field>
<field key="vehicle">123ABC</field>
<field key="notes">Tracker installed under hood, right.
Wires connected to mass</field>
<field key="signer">Markus Seeker</field>
</form>
</forms>
</task>
Troubleshooting
You may meet following errors: