Skip to main content

Upgrading to Version 4

  • Updated

vWork API V4

We're adding some great new features to the API. The new features are optional and will be rolled out with a new version of the API, V4. This means your existing integration will continue to work and you can choose to add support for the new features when you are ready. No changes will be made to existing API versions.

However, please note, that if you continue to use the existing API versions, you will have no visibility of the features below, even if your web users decide to start using them in your account. So, if you decide not to use these features, please ensure your web admins are aware of this decision.

All of the various vWork API calls will be updated to version 4 and these calls will be available in production shortly, along with updated documentation.

The following information is intended to highlight changes between older versions of the API and V4.

 

Changes to Custom Fields

  • New Header Custom Field - We are adding a new header custom field type. This will allow you to separate your custom fields into groups with big, bold, collapsible, headers. This doesn’t change any of the existing vWork functionality, but should make it easier to organise your custom field data for your users. The header custom field will be added to the Jobs API V4 call.
  • Custom Field Ordering - As part of this work, we are also changing how the custom fields are ordered in the XML that we return to you. In the older API calls, the order was alphabetical. In the API V4 call, we will return the custom fields to you in the same order that you submitted them to us. We will be doing this to preserve the order that you set and ensure that the correct fields appear under the correct headers.
  • Multi Value Pick List Custom Field - We are also adding a new option to the pick list custom field type. With API V4 it will be possible to specify more than one value for a pick list. Any of your existing pick lists can be converted to a multi value pick list, there is no need to create new pick lists from scratch. This option will be added to the Jobs API V4 call. The single value pick list will still be available.
  • Signature Custom Field - The final change to the custom fields is the ability to add a new custom field type for signatures. This means you will be able to require multiple signatures on a job or offer the ability to sign off different parts of the job as they are completed. To maintain compatibility, the existing proof of delivery signature and photo will remain available on all jobs. The signature custom field will be added to the Jobs API V4 call and there will also be a new call to retrieve the signature data as an image.
  • Duplicate Custom Field Names - Older versions of the API allowed you to make more than one custom field with the same name in a job. This causes issues if the field needs to be updated later. V4 of the API will enforce uniqueness for custom field names within a job.
  • Types and Permissions - We have cleaned up a number of issues around types and permissions, including: mobile tags are no longer required, free_text is now text, and types and permissions are all now shown correctly after a job PUT or POST.
  • Pick List ID - We also now include the pick list ID when you read a job from the API, so that you have confirmation that the job has been setup as you intended.

 

New Health and Safety Features

  • Tags - API V4 will also add support for vWork’s new Health and Safety module. The first part of this is tags. Tags can be added to the account via the web app or the API. They can then be applied to workers and jobs as required. If a job has a tag included such as “Current Electrical Certificate”, you will only be able to assign that job to a worker who has the matching tag. The tags will be added to the Users API V4 call, the Jobs API V4 call, and there will be a new set of calls to manage tags in the account.
  • Hazards - The 2nd element of Health and Safety is Hazards. Hazards can be added to a job by a worker or a dispatcher or via the API. These hazards then become part of the job data and must be acknowledged by the worker before a job can be completed. You can customise by stipulating when the acknowledgment must occur in the completion of steps in the job. Hazards will be added to the Jobs API V4 call.
  • Accidents and Incidents - The final piece of the Health and Safety puzzle is the ability for workers to create Accidents and Incidents related to Health and Safety. These can be created by mobile workers and will appear in the API along with all the other jobs in the account. No specific calls are being added to the API to handle these jobs, but you should be aware that you may see new jobs in the account created from this method.

 

 Shift On/Off

  • Shifts - Recently, we added the ability for workers to shift on and off. This can be done from the website or from the mobile app. This release will add the ability to view a worker’s current shift state to the Users API V4 call. Shift history will not be available via the API at this stage.

 

Changes to State, Progress State, Confirmation and Status

  • Status - In the past, many API consumers have been confused by the difference between state, progress state and confirmation. V4 of the API combines these into one field, called status. Status more accurately reflects what the web app users see.
  • Paused Status - It is now possible for webapp users and mobile users to pause a job that has been started. V4 of the API adds a new status called paused, this can be viewed as well as set via the API. We are also adding a new node called "paused_at", this displays when a paused job was paused.
  • Worker Duration - As a paused job can now have a total duration that does not reflect the actual time spent working on the job, we are also adding a new element called Worker Duration. Worker Duration is calculated as the total time from start to finish minus any paused periods. The best way to think of this is billable time. This will be a read only field on the Jobs API V4 call.
  • Canceled Status- Canceling a job has been available in the web app for a few months now and API V4 adds the ability for you to cancel a job via the API. Canceled jobs are removed from worker's phones but remain in the webapp and API for reporting purposes.
  • Draft Status - Also new in API V4 is draft status.  This allows dispatchers to create jobs in vWork that do not appear on the schedule or on worker's phones.
  • Searching by Status - We are adding a new search to the API to allow you to search by status. This replaces the search by state and search by progress state options.

 

Changes to Workers and Users

  • V4 of the API will remove the ability to administer Workers, this has been replaced with the ability to administer Users.
  • There will be a new permissions array format for Users, this is intended to be easier to consume and require fewer node arrays.

 

Need More Information? 

Feel free to get in touch with the support team if you would like any extra information about any of these features and how you can take advantage of them.

We expect the documentation and live calls to be available by June 7th. While we would like to see everyone take advantage of this update, the timing of this is over to you.

 

Related articles