vWork supports 11 types of custom fields. Any of these can be included when you create a job via the API.
You can create them as empty fields for the worker to fill in (by leaving the value field blank) or you can pre-populate them with the required value as well. (NB: The image field and signature field can be created, but not pre-populated via the API.)
Here are some examples of the XML you need to supply when creating your jobs:
(Please note, that the examples below are specific to API Version 4.)
FREE TEXT
To create a custom field that allows free text entry, include the following XML in your job:
<custom_field>
<name>What you want to name the field</name>
<type>text</type>
<value>What text you want to appear in the field</value>
</custom_field>
To create a custom field where a worker or dispatcher can enter a number, include the following XML:
<custom_field>
<name>What you want to name the field</name>
<type>number</type>
<value>What number you want to appear in the field</value>
</custom_field>
In this case the value may not contain any characters apart from the following: -.0123456789
DATE/TIME
To create a custom field where a worker or dispatcher can enter a date and a time, include the following XML:
<custom_field>
<name>What you want to name the field</name>
<type>datetime</type>
<value>What date and time you want to appear in the field</value>
</custom_field>
In this case the value must be in ISO8061 format.
LINK
To create a custom field that links to another system, include the following XML in your job:
<custom_field>
<name>What you want to name the field</name>
<type>link</text>
<value>What link you want to appear in the field</value>
<permission>read_only</permission>
</custom_field>
In this case the value must be a valid URL beginning with HTTP or HTTPS.
The permission must be set to either hidden or read_only.
CHECKBOX
To create a custom field that is displayed as a checkbox, include the following XML in your job:
<custom_field>
<name>What you want to name the field</name>
<type>checkbox</text>
<value>What value you want to appear in the field</value>
</custom_field>
In this case, the value must be t or f.
CURRENCY
To create a custom field that can display a currency value, include the following XML in your job:
<custom_field>
<name>What you want to name the field</name>
<type>currency</text>
<value>What value you want to appear in the field</value>
</custom_field>
In this case the value may not contain any characters apart from the following: -.0123456789
PICK LIST
You can also reference an existing pick list when creating a job, here's what the XML looks like:
<custom_field>
<name>What you want to name the field</name>
<type>pick_list</type>
<pick_list_id>12345</pick_list_id>
<value>What text you want to appear in the field</value>
</custom_field>
The example above references an existing pick list with an ID of "12345" and sets the default value to be "Fred". If you want to set the default value for a pick list it needs to be a value that is present in the pick list. (It also needs to be a pick list present in your account.) You can view your pick list IDs using the API call documented here.
MULTI VALUE PICK LIST
If you wish to reference an existing pick list and allow users to enter more than one value, include the following XML in your job:
<custom_field>
<name>What you want to name the field</name>
<type>multi_pick_list</type>
<pick_list_id>12345</pick_list_id>
<values type="array">
<value>Fred</value>
<value>Jane</value>
<value>Bob</value>
</values>
</custom_field>
The example above references an existing pick list with an ID of "12345" and sets the default value to be "Fred", "Jane" and "Bob". If you want to set the default value for a pick list it needs to be a value that is present in the pick list. (It also needs to be a pick list present in your account.) You can view your pick list IDs using the API call documented here.
IMAGE
To create a custom field where a worker or dispatcher can upload a photo, include the following XML:
<custom_field>
<name>What you want to name the field</name>
<type>image</type>
<value></value>
</custom_field>
Because you are creating an empty field, the value must be left blank when creating an image custom field.
SIGNATURE
To create a custom field where a worker can add a signature, include the following XML:
<custom_field>
<name>What you want to name the field</name>
<type>signature</type>
<value></value>
</custom_field>
Because you are creating an empty field, the value must be left blank when creating an image custom field and the permission must be optional or required.
SECTION HEADER
To create a custom field that displays a nice, bold section header so that you can better organise your custom fields, include the following XML in your job:
<custom_field>
<name>What you want to name the field</name>
<type>section_header</text>
<value></value>
<permission>read_only</permission>
</custom_field>
The name field will be displayed as the section header, the value should be left blank when creating an image custom field.
The permission must be read_only.