Api/Tasks/addXml adds new task, what is given in specific XML format.

Requirements

API user needs permission to task module, and subpermission allow creation of tasks.

Syntax

Api/Tasks/addXml (xml, version)

XML: special format explained below, what contains contents of task
version: if used, there are two possible values:
1. defaults to original format
2. supports task types, forms, and subtasks
Depending on value, XML support some other subvalues more or less.

XML format

Main element is <task/>. XML versions 1 and 2 may contain following subitems:

externalId: unique task identifier from customer side. You can use it to access to that task later.
name: required field, what gives name to that task
timestamp: task time in format YYYY-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 values TODO, INPROGRESS, DONE, FAILED
description: any text
message: goes to task log
customerId: database number, what refers to existing customer. If this is used, customerName is overwritten, and address is taken from customer data
customerName: 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 coordinates
- latitude - D.DD...
- longitude - D.DD...
servicetime: task duration, how long it takes to service that task. It will be used for optimisation
timewindowbegin: timestamp in format YYYY-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 order
timewindowend: timestamp in format YYYY-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_add_v2.xsd.

Location

Location XML looks like this:

<location>
   <address>address in text form</address>
   <latitude>D.DDD</latitude>
   <longitude>D.DDD</longitude>
</location>

Validation rule works as following:

if only address is given, location is geocoded from it
if only coordinates are given, address is reverse-geocoded from it
if no address is given, location is taken from customer location

You may skip elements you don't need.

See decision graph:

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

<task>
    <name>123ABC installation</name>
    <timestamp>2020-03-26 15:20</timestamp>
</task>

Task with location

<task>
  <name>123ABC installation</name>
  <timestamp>2020-03-26 15:20</timestamp>
  <location>
     <address>P. Sherman 42 Wallaby Way Sidney</address>
     <latitude>-33.7559627</latitude>
     <longitude>150.6034065</longitude>
  </location>
</task>

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>
  <name>123ABC installation</name>
  <timestamp>2020-03-26 15:20</timestamp>
  <type>installation</type>
  <forms>
    <form key="Installation">
      <fields>
        <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>
      </fields>
    </form>
  </forms>
</task>

Troubleshooting

You may meet following errors:

"No permissions": please add tasks module to role of API user
"User does not have the permissions to create new tasks": please add permission "Allow creation of tasks" to role of API user