What Types of Custom Fields Does the API Support?

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>

 

NUMBER

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.

 

 

 

 



Need more information? ask us hereHave more questions? Submit a request