With our community of partners, you can get expert advice and training so you can be up and running in no time! SETUP PARTNERS

WorkflowMax API Upgrade Guide: Version 1 to Version 3

The WorkflowMax API is releasing a new version, which will introduce breaking changes. We will be changing all entities that use a numeric ID, to use a new unique UUID.  

Version 3 is going to introduce breaking changes to the current API in the following ways:

  1. New URL - change to use V3 in the url
  2. New Authentication Method - removing the api/account keys from the query string and switching to OAuth 2.0
  3. New data structures - change from <ID> to <UUID> 

To aid with the upgrade to V3 we will introduce a Transition Mode to the current API. This new mode will simply add the new UUID fields to the existing V1 responses where applicable - making it easier to start using the new UUID field. Transition Mode will also allow the use of UUIDs in your requests, making it possible to start using these fields before switching to V3.

What Version Am I on?

If the url you are using have no version number, and is still using https://api.workflowmax.com, then you will need to upgrade.

 

How to deal with each breaking change:

  • New Url requirements - Base URL changes
    • Full details in the Upgrade Guide
  • New Authentication method
    • Full details in the v1 to OAuth migration guide
  • New Data Structures - ID to GUID change

Transition Guide - Only for API consumers that store numeric ID Fields:

If you do not store any numeric ID fields from the WorkflowMax API, you can skip straight to the Upgrade to V3 Guide. See the Exceptions section for more information about the distinction between numeric and non-numeric IDs.

Transition mode allows you to start storing the new UUID alongside any ID

If you do store numeric IDs you can begin the process of transitioning to (only) using UUIDs by simply enabling Transition Mode in your current implementation. This will add the UUID field to all responses that currently use numeric IDs, without changing anything else in the response. You can then begin storing the new UUID values alongside any ID values, to enable you to eventually transition to only using UUIDs.

Step 1.

Add uuidMode=transition to the query string of your current requests.

E.g. https://api.workflowmax.com/job.api/list?uuidMode=transition

The WorkflowMax API will now start including UUID fields alongside any ID fields in the response. This may break your consumption of the WorkflowMax API, depending on your implementation.

Step 2.

Adjust your implementation of the WorkflowMax API so that it can accept the new UUID fields.

Step 3.

For each WorkflowMax entity that you store an ID, adjust your storage solution so that you can also store a UUID against that entity.

Step 4.

Start saving the UUID values from all responses alongside any ID values you are already storing. Upon completing this step you should now have a solution where any time you use the WorkflowMax Api, and save data, you are saving both the ID and UUID.

Over time as your customers use your add-on, the UUID values will be slowly backfilled.

Step 5.

This optional step can be used to download all IDs to UUID mappings at once, instead of filling it in slowly in Step 4.

For each account key linked to an app key, call our ID-to-UUID Endpoint, and download the files generated. For each WorkflowMax entity type (ie Job, Client, Staff, etc) there will be a file listing all your account’s IDs and UUIDs for that entity type. For each ID in each file, find the related entity in your chosen storage solution, and import the UUID value for that entity.

If you are an API Add-on Partner, you will need to repeat this step for each account using your API key and each.

Upon completing this step you should now have a solution where all of your current (and future) data that uses the WorkflowMax ID field has a value for UUID as well. Please ensure this is the case before moving on to the Upgrade to V3 Guide.


Upgrade to V3 Guide - For All API Consumers

If you do not store any numeric ID fields from the WorkflowMax API, or you have completed all steps in the Transition Guide, you are ready to upgrade to V3.

Step 1. Fixing the URL breaking change:

Add “v3/” after the WorkflowMax API base URL, but before the controller segment, in your request. E.g. https://api.workflowmax.com/v3/job.api/current

Step 1-A. (Transition Users only):

Remove uuidMode=transition from your query string.

Step 2:

Ensure your implementation of the WorkflowMax API can handle the new UUID field(s) and the removal of the ID field(s) as outlined in the V3 schema documentation.

Step 3-A (Transition Users only):

Stop storing any numeric IDs


Quick Tips

For requests that contain an ID in the URL

  • Swap out the ID with the entity’s UUID.
    • GET task.api/get/1232 becomes GET task.api/get/ffa44485-...

For requests that contain an ID in the Body

  • If the XML Node is <ID> and only ever contains numbers
    • Change the Node to <UUID> and swap out the ID value with the entity’s UUID.
    • <ID>456</ID> becomes <UUID>ad759d98-...</UUID>
  • If the XML Node has a descriptor before ‘ID’, eg <StaffID>
    • Keep the Node descriptor the same, but change ID to UUID.
    • <StaffID>123</StaffID> becomes <StaffUUID>daad601a-...</StaffUUID>
    • Note: This also applies to the <InternalID> fields exposed by the Job api and the Invoice api

 

Exceptions

The following <ID> nodes are not numeric and therefore do not require changing: 

Controller

Field Name

Example

 

Job

 

Job Number

<Job>

<ID>J000123</ID>

</Job>

 

Quote

 

Quote Number

<Quote>

<ID>Q000456</ID>

</Quote>

 

Purchase Order

 

Purchase Order Number

<PurchaseOrder>

<ID>PO000789</ID>

</PurchaseOrder>

Invoice

Invoice Number

<Invoice>

<ID>INV0234</ID>

</Invoice>

 

These fields are labeled as <ID> but are referred to as Job Number, Quote Number, Purchase Order Number and Invoice Number respectively in the documentation (ie get/[job number]). V3 will continue to include this <ID> field in the response, and will continue to accept it in any route that documents so. Please be aware that these four <ID> nodes (Job Number, Quote Number, Purchase Order Number and Invoice Number) are the only <ID> nodes that are not numeric and therefore not changing to a UUID.

 

Example Request Using Entity Number

V1

V3

GET get/[job number]

GET get/[job number]

https://api.workflowmax.com/job.api/get/J00309

https://api.workflowmax.com/v3/job.api/get/J00309

 

Example Response With Entity Number And Regular Numeric ID

V1

V3

<Job>

<ID>J000309</ID>

<Client>

<ID>678</ID>

</Client>

</Job>

<Job>

<ID>J000309</ID>

<Client>

<UUID>caa9f7a7-...</UUID>

</Client>

</Job>

 

More examples are available on our official V3 documentation page.