{"items":[{"type":"link","label":"vWork API v5 Templated Jobs - Creation Only (Stable Release)","link":"/v5-templated-jobs","routeSlug":"/v5-templated-jobs","content":{"contentType":"overview","meta":{"name":"vWork API v5 Templated Jobs - Creation Only (Stable Release)"},"children":[{"nodeType":"container","panels":[{"title":"Download OpenAPI description","titleTranslationKey":"download.description.title","children":[{"kind":"download","label":"v5-templated-jobs.json","url":"/_bundle/v5-templated-jobs.json?download"},{"kind":"download","label":"v5-templated-jobs.yaml","url":"/_bundle/v5-templated-jobs.yaml?download"}]},{"title":"Overview","titleTranslationKey":"info.title","children":[]},{"title":"Servers","titleTranslationKey":"servers.title","children":[{"kind":"servers","servers":[{"url":"https://api.vworkapp.com/api"}],"mode":"default"}]}],"children":[{"nodeType":"overview-section-wrapper","children":[{"nodeType":"header","level":1,"label":"vWork API v5 Templated Jobs - Creation Only (Stable Release)","showPageActions":true},{"nodeType":"overview-section-wrapper","children":[{"nodeType":"markdoc","content":[]}],"sectionId":"/v5-templated-jobs"}],"sectionId":"/v5-templated-jobs"},{"nodeType":"overview-section-wrapper","children":[{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"heading","attributes":{"level":1,"id":"section/getting-started"},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Getting Started"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"em","inline":true,"attributes":{"marker":"*"},"children":[{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"We have broken our API documentation into three parts. The following documentation is for creating jobs from existing vWork templates."},"children":[]}]}]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"em","inline":true,"attributes":{"marker":"*"},"children":[{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"If you need full control over your jobs and don't want to reference your templates, then you should use our "},"children":[]},{"$$mdtype":"Node","type":"tag","tag":"html","inline":true,"attributes":{"name":"a","attrs":{"href":"/v5-jobs"}},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"job API documentation"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"."},"children":[]}]}]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"em","inline":true,"attributes":{"marker":"*"},"children":[{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"If you need to access something other than jobs, then you should use our "},"children":[]},{"$$mdtype":"Node","type":"tag","tag":"html","inline":true,"attributes":{"name":"a","attrs":{"href":"/v5"}},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"vWork API documentation"},"children":[]}]}]}]}]}]}]}],"sectionId":"/v5-templated-jobs/section/getting-started"},{"nodeType":"overview-section-wrapper","children":[{"nodeType":"overview-section-wrapper","children":[{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"heading","attributes":{"level":2,"id":"section/getting-started/the-use-of-templates"},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"The Use of Templates"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"vWork software is centred on the use of templates to manage multiple job types. This makes it easy for website users to create the same job type over and over again."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"The use of templates is not supported via our standard API. You define what a job looks like when you send the job XML to the API."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"However, the Templated Job API does use the templates saved in your vWork account.  In essence, you supply us with the template name (or the template ID) that you wish to use when creating the job, we will then inherit everything we can from the template; Step names, Custom Field Logic, Custom Labels, Duration, Tags, Time Windows, etc."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"The only other information you may need to supply are any values that you wanted to include on the job creation.  This may include a customer ID, or a customer name, an address for the job, any custom field values you want to supply, or invoice line items that need to appear on the job."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"You are welcome to use the Templated Job API for your initial job creation, and then our standard API for updating, cancelling, downloading or deleting jobs. Our standard API also includes many other non-job related functions such as managing hazards, groups, messages, assets, users, etc.."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"The base URL for our API is:  https://api.vworkapp.com/"},"children":[]}]}]}]}],"sectionId":"/v5-templated-jobs/section/getting-started/the-use-of-templates"}],"sectionId":"/v5-templated-jobs/section/getting-started/the-use-of-templates"},{"nodeType":"overview-section-wrapper","children":[{"nodeType":"overview-section-wrapper","children":[{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"heading","attributes":{"level":2,"id":"section/getting-started/what-does-stable-mean"},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"What does Stable mean?"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Stable means that this version is final and is not going to change in the future, even if we add new features to the product."},"children":[]}]}]}]}],"sectionId":"/v5-templated-jobs/section/getting-started/what-does-stable-mean"}],"sectionId":"/v5-templated-jobs/section/getting-started/what-does-stable-mean"},{"nodeType":"overview-section-wrapper","children":[{"nodeType":"overview-section-wrapper","children":[{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"heading","attributes":{"level":2,"id":"section/getting-started/what-can-you-build"},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"What can you build?"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"vWork’s API allows you to build our dispatching functionality into other software. For example, you can use our API so that our dispatch software works hand-in-hand with your CRM software."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"You can also pull data from vWork’s API to produce a tailored management report."},"children":[]}]}]}]}],"sectionId":"/v5-templated-jobs/section/getting-started/what-can-you-build"}],"sectionId":"/v5-templated-jobs/section/getting-started/what-can-you-build"},{"nodeType":"overview-section-wrapper","children":[{"nodeType":"overview-section-wrapper","children":[{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"heading","attributes":{"level":2,"id":"section/getting-started/getting-your-api-key"},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Getting your API key"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"You need to have a vWork account with the API enabled to obtain an API key."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"If you already have an API enabled vWork account, you can create your own API Key "},"children":[]},{"$$mdtype":"Node","type":"tag","tag":"html","inline":true,"attributes":{"name":"a","attrs":{"href":"https://go.vworkapp.com/html_client/admin/api"}},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"here on the integrations page"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"If you do not yet have a vWork account, please "},"children":[]},{"$$mdtype":"Node","type":"tag","tag":"html","inline":true,"attributes":{"name":"a","attrs":{"href":"https://www.vworkapp.com/contact-us"}},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"get in touch"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" with us."},"children":[]}]}]}]}],"sectionId":"/v5-templated-jobs/section/getting-started/getting-your-api-key"}],"sectionId":"/v5-templated-jobs/section/getting-started/getting-your-api-key"},{"nodeType":"overview-section-wrapper","children":[{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"heading","attributes":{"level":1,"id":"section/need-more-help"},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Need More Help?"},"children":[]}]}]}]}],"sectionId":"/v5-templated-jobs/section/need-more-help"},{"nodeType":"overview-section-wrapper","children":[{"nodeType":"overview-section-wrapper","children":[{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"heading","attributes":{"level":2,"id":"section/need-more-help/where-to-get-more-help"},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Where to get more help"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"There is a list of frequently asked questions on our "},"children":[]},{"$$mdtype":"Node","type":"tag","tag":"html","inline":true,"attributes":{"name":"a","attrs":{"href":"https://help.vworkapp.com/forums/20898176"}},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"helpdesk"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" page as well as "},"children":[]},{"$$mdtype":"Node","type":"tag","tag":"html","inline":true,"attributes":{"name":"a","attrs":{"href":"https://help.vworkapp.com/hc/en-us/articles/204087140"}},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"a brief intro to the vWork API"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":". If you get stuck, please don't hesitate to send us an email at: "},"children":[]},{"$$mdtype":"Node","type":"tag","tag":"html","inline":true,"attributes":{"name":"a","attrs":{"href":"mailto:support@vworkapp.com"}},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"support@vworkapp.com"},"children":[]}]}]}]}]}],"sectionId":"/v5-templated-jobs/section/need-more-help/where-to-get-more-help"}],"sectionId":"/v5-templated-jobs/section/need-more-help/where-to-get-more-help"},{"nodeType":"overview-section-wrapper","children":[{"nodeType":"overview-section-wrapper","children":[{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"heading","attributes":{"level":2,"id":"section/need-more-help/mailing-list"},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Mailing List"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Do you want to be emailed when we make a change to the API? You can "},"children":[]},{"$$mdtype":"Node","type":"tag","tag":"html","inline":true,"attributes":{"name":"a","attrs":{"href":"https://www.vworkapp.com/api_notes"}},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"signup for notifications about the vWork API here"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":". We don't email very often, but we will notify you about any changes, as well as notifications about both planned and unplanned outages."},"children":[]}]}]}]}],"sectionId":"/v5-templated-jobs/section/need-more-help/mailing-list"}],"sectionId":"/v5-templated-jobs/section/need-more-help/mailing-list"},{"nodeType":"overview-section-wrapper","children":[{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"heading","attributes":{"level":1,"id":"section/tech-notes"},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Tech Notes"},"children":[]}]}]}]}],"sectionId":"/v5-templated-jobs/section/tech-notes"},{"nodeType":"overview-section-wrapper","children":[{"nodeType":"overview-section-wrapper","children":[{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"heading","attributes":{"level":2,"id":"section/tech-notes/http-compression"},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"HTTP Compression"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"By default, the vWork API requires users to support gzip HTTP response compression on all requests. This is enabled by setting a 'Accept-Encoding: gzip' header on requests, and properly handling the 'Content-Encoding' header on responses. For more information please see http://en.wikipedia.org/wiki/HTTP_compression."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"em","inline":true,"attributes":{"marker":"_"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Failure to specify HTTP compression may result in requests being rejected with a HTTP response of type 406/Not Acceptable."},"children":[]}]}]}]}]}],"sectionId":"/v5-templated-jobs/section/tech-notes/http-compression"}],"sectionId":"/v5-templated-jobs/section/tech-notes/http-compression"},{"nodeType":"overview-section-wrapper","children":[{"nodeType":"overview-section-wrapper","children":[{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"heading","attributes":{"level":2,"id":"section/tech-notes/iso8601-date-and-time-format"},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"ISO8601 Date and Time Format"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"When providing dates you must supply them in the following ISO8601 format: YYYY-MM-DDTHH:MM:SS."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"The API uses GMT by default. In order for you to use your local time you must also supply a timezone on your ISO8601 date (e.g. 2011-12-25T22:32:07+10)."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Finally, you may need to url encode the date string depending on your environment (e.g. 2011-12-25T22%3A32%3A07%2B10)"},"children":[]}]}]}]}],"sectionId":"/v5-templated-jobs/section/tech-notes/iso8601-date-and-time-format"}],"sectionId":"/v5-templated-jobs/section/tech-notes/iso8601-date-and-time-format"},{"nodeType":"overview-section-wrapper","children":[{"nodeType":"overview-section-wrapper","children":[{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"heading","attributes":{"level":2,"id":"section/tech-notes/error-codes"},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Error Codes"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Here is an explanation of some of the error codes you may see when developing your integration."},"children":[]}]}]},{"$$mdtype":"Node","type":"list","attributes":{"ordered":false,"marker":"*"},"children":[{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"HTTP 401 (Authorization Required) is returned if you don’t have permission to call this service. Check that your api_key is correct."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"HTTP 404 (Not Found) is returned if the resource requested was not found."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"HTTP 406 (Not Acceptable) is returned if the request did not include headers for http compression."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"HTTP 422 (Unprocessable Entity) is returned if vWork wasn’t able to process the request body, for example when the XML is incorrectly formatted."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"HTTP 429 (Too Many Requests) is returned if vWork is unable to process the number of requests you have sent, please throttle your queries and try again in a minute or two."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"HTTP 500 (Server Error) is returned if a logic error was found, such as a required field is missing."},"children":[]}]}]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Please note, that quite often the reason for a 422 error is included in the body of the XML that is returned to you.  This is often an excellent source of debugging information, here is a sample that says a date time custom field value was not a valid date and time."},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"<?xml version='1.0' encoding='utf-8' ?>\n<errors>\n    <error>\n        <attribute>custom_fields.custom_field</attribute>\n        <message>&#39;tomorrow night&#39; must be a valid ISO8601 value.</message>\n    </error>\n</errors>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"<?xml version='1.0' encoding='utf-8' ?>\n<errors>\n    <error>\n        <attribute>custom_fields.custom_field</attribute>\n        <message>&#39;tomorrow night&#39; must be a valid ISO8601 value.</message>\n    </error>\n</errors>\n"},"children":[]}]}]}],"sectionId":"/v5-templated-jobs/section/tech-notes/error-codes"}],"sectionId":"/v5-templated-jobs/section/tech-notes/error-codes"},{"nodeType":"overview-section-wrapper","children":[{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"heading","attributes":{"level":1,"id":"section/webhooks"},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Webhooks"},"children":[]}]}]}]}],"sectionId":"/v5-templated-jobs/section/webhooks"},{"nodeType":"overview-section-wrapper","children":[{"nodeType":"overview-section-wrapper","children":[{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"heading","attributes":{"level":2,"id":"section/webhooks/what-are-webhooks"},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"What are Webhooks?"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"For general information about Webhooks, see http://en.wikipedia.org/wiki/Webhook"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"To minimise the requirement for a vWork API consumer to frequently poll the API for updates, vWork can send webhook callbacks to a predetermined endpoint URL when a change is made."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Depending on the information contained in the webhook, the consumer may then choose to perform a GET on that specific resource to retrieve the updated resource."},"children":[]}]}]}]}],"sectionId":"/v5-templated-jobs/section/webhooks/what-are-webhooks"}],"sectionId":"/v5-templated-jobs/section/webhooks/what-are-webhooks"},{"nodeType":"overview-section-wrapper","children":[{"nodeType":"overview-section-wrapper","children":[{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"heading","attributes":{"level":2,"id":"section/webhooks/what-webhooks-are-available"},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"What Webhooks are Available?"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"You can select to recieve a webhook when any of the following actions occur: Job Created, Job Assigned, Job Unassigned, Job Reassigned, Job Declined, Job Accepted, Job Rescheduled, Job Started, Job Completed, Job Deleted, Job Paused, Job Unpaused, Step Completed, Step Uncompleted, Custom Field Updated, Invoice Updated, User Created, User Updated, User Deleted, Proof of Delivery (POD) Created, and Proof of Delivery Deleted."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Note that if a single action triggers multiple events (for example, creating an assigned job will trigger both a Job Created and a Job Assigned webhook), the order of these events is not guaranteed. But if multiple separate changes happen, those events will be sent in order."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Please also note, that the Job Reassigned webhook only triggers if the job is reassigned from the jobs tab or the mobile app.  If a job is reassigned by dragging it to a new worker on the schedule, this will result in two webhooks, a Job Unassigned followed by a Job Assigned."},"children":[]}]}]}]}],"sectionId":"/v5-templated-jobs/section/webhooks/what-webhooks-are-available"}],"sectionId":"/v5-templated-jobs/section/webhooks/what-webhooks-are-available"},{"nodeType":"overview-section-wrapper","children":[{"nodeType":"overview-section-wrapper","children":[{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"heading","attributes":{"level":2,"id":"section/webhooks/setting-up-webhooks"},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Setting up Webhooks"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"You can configure your webhook endpoint, select the format you prefer (JSON or XML), as well as select what actions should trigger a webhook to be sent, from the admin section of the vWork website: https://go.vworkapp.com/html_client/admin/webhooks"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"The callback endpoint will be provided and maintained by the API consumer, and should support SSL/TLS encryption."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Given the potential for a relatively high volume of callbacks, it is strongly advised that the consumer employ asynchronous background task execution and/or a message queueing pattern for handling incoming Webhook callback events. Platforms such as Delayed Job, Resque and RabbitMQ are some well-known examples of asynchronous processing platforms."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"(If you are using our legacy webhooks, turning on the new webhooks will not turn off the old ones. Please email "},"children":[]},{"$$mdtype":"Node","type":"tag","tag":"html","inline":true,"attributes":{"name":"a","attrs":{"href":"mailto:support@vworkapp.com"}},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"support@vworkapp.com"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" when you are ready for us to turn off the old webhooks. NB: If you update your webhook endpoint on the website, this will update the endpoint for both new and old webhooks.)"},"children":[]}]}]}]}],"sectionId":"/v5-templated-jobs/section/webhooks/setting-up-webhooks"}],"sectionId":"/v5-templated-jobs/section/webhooks/setting-up-webhooks"},{"nodeType":"overview-section-wrapper","children":[{"nodeType":"overview-section-wrapper","children":[{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"heading","attributes":{"level":2,"id":"section/webhooks/sample-webhooks"},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Sample Webhooks"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"An example of a Job Created XML webhook is below:"},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"<?xml version=\"1.0\"?>\n<event>\n  <transaction_id>617d4a74-7a19-11e6-bf7a-55542dc9080d</transaction_id>\n  <event_type>job_created</event_type>\n  <event_time>2016-09-14T01:20:10Z</event_time>\n  <resource>Job</resource>\n  <resource_id>9876234</resource_id>\n  <account_id>7829</account_id>\n  <request_user_type>User</request_user_type>\n  <request_user_id>123</request_user_id>\n</event>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"<?xml version=\"1.0\"?>\n<event>\n  <transaction_id>617d4a74-7a19-11e6-bf7a-55542dc9080d</transaction_id>\n  <event_type>job_created</event_type>\n  <event_time>2016-09-14T01:20:10Z</event_time>\n  <resource>Job</resource>\n  <resource_id>9876234</resource_id>\n  <account_id>7829</account_id>\n  <request_user_type>User</request_user_type>\n  <request_user_id>123</request_user_id>\n</event>\n"},"children":[]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"An example of a Job Created JSON webhook is below:"},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"{\n  \"transaction_id\": \"617d4a74-7a19-11e6-bf7a-55542dc9080d\",\n  \"event_type\": \"job_created\",\n  \"event_time\": \"2016-09-14T01:20:10Z\",\n  \"resource\": \"Job\",\n  \"resource_id\": 9876234,\n  \"account_id\": 7829,\n  \"request_user_type\": \"User\",\n  \"request_user_id\": 123\n}\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"{\n  \"transaction_id\": \"617d4a74-7a19-11e6-bf7a-55542dc9080d\",\n  \"event_type\": \"job_created\",\n  \"event_time\": \"2016-09-14T01:20:10Z\",\n  \"resource\": \"Job\",\n  \"resource_id\": 9876234,\n  \"account_id\": 7829,\n  \"request_user_type\": \"User\",\n  \"request_user_id\": 123\n}\n"},"children":[]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"An example of a Step Completed XML webhook is below:"},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"<?xml version=\"1.0\"?>\n<event>\n  <transaction_id>63d75660-7a1a-11e6-8d5a-474090628a07</transaction_id>\n  <event_type>step_completed</event_type>\n  <event_time>2016-09-14T01:27:24Z</event_time>\n  <resource>Step</resource>\n  <resource_id>25062292</resource_id>\n  <account_id>8723</account_id>\n  <request_user_type>User</request_user_type>\n  <request_user_id>123</request_user_id>\n  <event_location>\n    <lat>-36.86524165519692</lat>\n    <lng>174.7806050757642</lng>\n  </event_location>\n  <data>\n    <step_name>Start Job</step_name>\n    <completed_at>2016-09-15T02:00:12Z</completed_at>\n    <job_id>8626773</job_id>\n  </data>\n</event>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"<?xml version=\"1.0\"?>\n<event>\n  <transaction_id>63d75660-7a1a-11e6-8d5a-474090628a07</transaction_id>\n  <event_type>step_completed</event_type>\n  <event_time>2016-09-14T01:27:24Z</event_time>\n  <resource>Step</resource>\n  <resource_id>25062292</resource_id>\n  <account_id>8723</account_id>\n  <request_user_type>User</request_user_type>\n  <request_user_id>123</request_user_id>\n  <event_location>\n    <lat>-36.86524165519692</lat>\n    <lng>174.7806050757642</lng>\n  </event_location>\n  <data>\n    <step_name>Start Job</step_name>\n    <completed_at>2016-09-15T02:00:12Z</completed_at>\n    <job_id>8626773</job_id>\n  </data>\n</event>\n"},"children":[]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"An example of a Step Completed JSON webhook is below:"},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"{\n  \"transaction_id\": \"63d75660-7a1a-11e6-8d5a-474090628a07\",\n  \"event_type\": \"step_completed\",\n  \"event_time\": \"2016-09-14T01:27:24Z\",\n  \"resource\": \"Step\",\n  \"resource_id\": 25062292,\n  \"account_id\": 8723,\n  \"request_user_type\": \"User\",\n  \"request_user_id\": 123,\n  \"event_location\": {\n    \"lat\": -36.86525719794106,\n    \"lng\": 174.780580958473\n  },\n  \"data\": {\n    \"step_name\": \"Start Job\",\n    \"completed_at\": \"2016-09-15T02:58:31Z\",\n    \"job_id\": 8621412\n  }\n}\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"{\n  \"transaction_id\": \"63d75660-7a1a-11e6-8d5a-474090628a07\",\n  \"event_type\": \"step_completed\",\n  \"event_time\": \"2016-09-14T01:27:24Z\",\n  \"resource\": \"Step\",\n  \"resource_id\": 25062292,\n  \"account_id\": 8723,\n  \"request_user_type\": \"User\",\n  \"request_user_id\": 123,\n  \"event_location\": {\n    \"lat\": -36.86525719794106,\n    \"lng\": 174.780580958473\n  },\n  \"data\": {\n    \"step_name\": \"Start Job\",\n    \"completed_at\": \"2016-09-15T02:58:31Z\",\n    \"job_id\": 8621412\n  }\n}\n"},"children":[]}]}]}],"sectionId":"/v5-templated-jobs/section/webhooks/sample-webhooks"}],"sectionId":"/v5-templated-jobs/section/webhooks/sample-webhooks"},{"nodeType":"overview-section-wrapper","children":[{"nodeType":"overview-section-wrapper","children":[{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"heading","attributes":{"level":2,"id":"section/webhooks/webhook-content"},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Webhook Content"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Webhooks will always contain the following fields:"},"children":[]}]}]},{"$$mdtype":"Node","type":"list","attributes":{"ordered":false,"marker":"*"},"children":[{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"transaction_id - an internal vwork audit ID, can be ignored"},"children":[]}]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"event_type - the action that triggered the webhook"},"children":[]}]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"event_time - the time the server recieved the event, this may not be the time of the event (in UTC)"},"children":[]}]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"resource - the resource that was updated: job, custom field, proof of delivery, step or user."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"resource_id - the vWork ID for the resource that was updated."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"account_id - the ID of your vWork account (can be useful if you are recieving webhooks for multiple accounts.)"},"children":[]}]}]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"In addition, some webhooks may contain these extra fields:"},"children":[]}]}]},{"$$mdtype":"Node","type":"list","attributes":{"ordered":false,"marker":"*"},"children":[{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"request_user_type - Who triggered the action: a user, or a customer portal user. Will not be present for API events or automatic events (like an auto decline event)."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"request_user_id - The ID of the user who triggered the action. Will not be present for API events or automatic events (like an auto decline event)."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"resource_third_party_id - The 3rd Party ID for the resource that was updated. Only present when a 3rd Party ID exists."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"data_worker_id - The ID of the worker the job is assigned to. Present on Job Accepted, Job Assigned and Job Reassigned Webhooks."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"data_worker_name - The name of the worker the job is assigned to. Present on Job Accepted, Job Assigned and Job Reassigned Webhooks."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"data_field_label - The label of the custom field that was updated. Only present on Custom Field Updated webhooks."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"data_field_value - The new value of the custom field that was updated. Only present on Custom Field Updated webhooks."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"data_field_type - The type of the custom field that was updated. Only present on Custom Field Updated webhooks."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"event_location_lat - the lattitude of the worker's location when they completed the action. Only present on Step Completed, Step Uncompleted, Job Start and Job Complete when a location is available."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"event_location_long - the longitude of the worker's location when they completed the action. Only present on Step Completed, Step Uncompleted, Job Start and Job Complete when a location is available."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"data_step_name - The name of the step that was updated. Only present on Step Completed and Step Uncompleted webhooks."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"data_completed_at - The time when the step was completed (in UTC). Only present on Step Completed webhook."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"data_job_id - The job that the POD, step, or custom field is for. Only present on POD Created, POD Deleted, Custom Field Updated, Step Completed, and Step Uncompleted webhooks."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"data_paused_at - The time when the job was paused (in UTC). Only present on Job Paused webhooks."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"data_unpaused_at - The time when the job was unpaused (in UTC). Only present on Job Unpaused webhooks."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"data_signed_at - When the POD was signed. Only present on POD Created and Deleted webhooks."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"data_signed_by - Who Signed the POD. Only present on POD Created and Deleted webhooks."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"data_name - The name of the user. Only present on User Created and User Updated webhooks."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"data_email - The email address of the user. Only present on User Created and User Updated webhooks."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"data_phone - The phone number of the user. Only present on User Created and User Updated webhooks."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"data_notes - Any notes saved against the user. Only present on User Created and User Updated webhooks."},"children":[]}]}]}]}]}]}],"sectionId":"/v5-templated-jobs/section/webhooks/webhook-content"}],"sectionId":"/v5-templated-jobs/section/webhooks/webhook-content"},{"nodeType":"overview-section-wrapper","children":[{"nodeType":"overview-section-wrapper","children":[{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"heading","attributes":{"level":2,"id":"section/webhooks/webhook-reliability-and-monitoring"},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Webhook Reliability and Monitoring"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"The vWork Webhook notifier will expect a HTTP/200 status code in the HTTP response from the callback endpoint provided by the API consumer. If a non-200 response is received, or the endpoint cannot be reached, vWork will discard the callback event."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Callbacks will always be sent in the order they were created; in the event of a single callback failure as described above, the failing callback will be discarded, but the Webhook notifier will attempt to send all subsequent callbacks in the normal manner."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Various factors could cause a callback to be discarded, such as an internet connection dropout or a momentary server problem. vWork recommends that the API consumer implement a low-frequency polling mechanism (e.g. hourly or daily) to “fill in” any data which may have been missed as a result of a discarded callback."},"children":[]}]}]}]}],"sectionId":"/v5-templated-jobs/section/webhooks/webhook-reliability-and-monitoring"}],"sectionId":"/v5-templated-jobs/section/webhooks/webhook-reliability-and-monitoring"},{"nodeType":"overview-section-wrapper","children":[{"nodeType":"overview-section-wrapper","children":[{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"heading","attributes":{"level":2,"id":"section/webhooks/security-layer-hmac-sha"},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Security Layer - HMAC SHA"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"We implement a layer of security which is simple to consume. Using your api key and a \"signature\" that is calculated and sent with the Webhook, you can verify the contents of a Webhook as being authentic and un-tampered."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Webhooks are signed with a signature generated by taking an HMAC-SHA-256 hex digest of the raw HTTP Body of the Webhook post, using your api key as the secret."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"This signature will be sent with the Webhook post in the header X-Vwork-Webhook-Signature-Hmac-Sha-256. If you chose not to implement this measure, you can just ignore the header."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"As an example, the HMAC signature is generated in Ruby with this code:"},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"OpenSSL::HMAC.hexdigest(OpenSSL::Digest::Digest.new('sha256'), api_key, webhook.body)\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"OpenSSL::HMAC.hexdigest(OpenSSL::Digest::Digest.new('sha256'), api_key, webhook.body)\n"},"children":[]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"If your api key is 123 and the Webhook request body contents are:"},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"<job><name>test</name></job>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"<job><name>test</name></job>\n"},"children":[]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"using code like this:"},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"OpenSSL::HMAC.hexdigest(OpenSSL::Digest::Digest.new('sha256'), '123', '<job><name>test</name></job>')\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"OpenSSL::HMAC.hexdigest(OpenSSL::Digest::Digest.new('sha256'), '123', '<job><name>test</name></job>')\n"},"children":[]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"the signature for this Webhook would be:"},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"7643b9dbcab60ae6ae32e5683e1fae1db105bd31f1f0b5d51e5b773235359ff0\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"7643b9dbcab60ae6ae32e5683e1fae1db105bd31f1f0b5d51e5b773235359ff0\n"},"children":[]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Please note, that when calculating the HMAC SHA we strip out all line breaks and whitespace from the body of the webhook, in order for you to get the same result, you will need to do the same."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Also the webhook body should be ASCII encoded."},"children":[]}]}]}]}],"sectionId":"/v5-templated-jobs/section/webhooks/security-layer-hmac-sha"}],"sectionId":"/v5-templated-jobs/section/webhooks/security-layer-hmac-sha"},{"nodeType":"overview-section-wrapper","children":[{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"heading","attributes":{"level":1,"id":"section/postman"},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Postman"},"children":[]}]}]}]}],"sectionId":"/v5-templated-jobs/section/postman"},{"nodeType":"overview-section-wrapper","children":[{"nodeType":"overview-section-wrapper","children":[{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"heading","attributes":{"level":2,"id":"section/postman/what-is-postman"},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"What is Postman?"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Postman is an API development and testing tool. We encourage our customers to use Postman as a way of quickly learning the capabilities of the vWork API. vWork support staff can often provide sample Postman collections or Postman friendly XML samples to assist you."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"You can download a copy from here: https://www.getpostman.com/"},"children":[]}]}]}]}],"sectionId":"/v5-templated-jobs/section/postman/what-is-postman"}],"sectionId":"/v5-templated-jobs/section/postman/what-is-postman"}]}]}},{"type":"group","label":"Getting Started","link":"/v5-templated-jobs/section/getting-started","routeSlug":"/v5-templated-jobs/section/getting-started","items":[{"type":"link","label":"The Use of Templates","link":"/v5-templated-jobs/section/getting-started/the-use-of-templates","routeSlug":"/v5-templated-jobs/section/getting-started/the-use-of-templates","content":null},{"type":"link","label":"What does Stable mean?","link":"/v5-templated-jobs/section/getting-started/what-does-stable-mean","routeSlug":"/v5-templated-jobs/section/getting-started/what-does-stable-mean","content":null},{"type":"link","label":"What can you build?","link":"/v5-templated-jobs/section/getting-started/what-can-you-build","routeSlug":"/v5-templated-jobs/section/getting-started/what-can-you-build","content":null},{"type":"link","label":"Getting your API key","link":"/v5-templated-jobs/section/getting-started/getting-your-api-key","routeSlug":"/v5-templated-jobs/section/getting-started/getting-your-api-key","content":null}],"content":null},{"type":"group","label":"Need More Help?","link":"/v5-templated-jobs/section/need-more-help","routeSlug":"/v5-templated-jobs/section/need-more-help","items":[{"type":"link","label":"Where to get more help","link":"/v5-templated-jobs/section/need-more-help/where-to-get-more-help","routeSlug":"/v5-templated-jobs/section/need-more-help/where-to-get-more-help","content":null},{"type":"link","label":"Mailing List","link":"/v5-templated-jobs/section/need-more-help/mailing-list","routeSlug":"/v5-templated-jobs/section/need-more-help/mailing-list","content":null}],"content":null},{"type":"group","label":"Tech Notes","link":"/v5-templated-jobs/section/tech-notes","routeSlug":"/v5-templated-jobs/section/tech-notes","items":[{"type":"link","label":"HTTP Compression","link":"/v5-templated-jobs/section/tech-notes/http-compression","routeSlug":"/v5-templated-jobs/section/tech-notes/http-compression","content":null},{"type":"link","label":"ISO8601 Date and Time Format","link":"/v5-templated-jobs/section/tech-notes/iso8601-date-and-time-format","routeSlug":"/v5-templated-jobs/section/tech-notes/iso8601-date-and-time-format","content":null},{"type":"link","label":"Error Codes","link":"/v5-templated-jobs/section/tech-notes/error-codes","routeSlug":"/v5-templated-jobs/section/tech-notes/error-codes","content":null}],"content":null},{"type":"group","label":"Webhooks","link":"/v5-templated-jobs/section/webhooks","routeSlug":"/v5-templated-jobs/section/webhooks","items":[{"type":"link","label":"What are Webhooks?","link":"/v5-templated-jobs/section/webhooks/what-are-webhooks","routeSlug":"/v5-templated-jobs/section/webhooks/what-are-webhooks","content":null},{"type":"link","label":"What Webhooks are Available?","link":"/v5-templated-jobs/section/webhooks/what-webhooks-are-available","routeSlug":"/v5-templated-jobs/section/webhooks/what-webhooks-are-available","content":null},{"type":"link","label":"Setting up Webhooks","link":"/v5-templated-jobs/section/webhooks/setting-up-webhooks","routeSlug":"/v5-templated-jobs/section/webhooks/setting-up-webhooks","content":null},{"type":"link","label":"Sample Webhooks","link":"/v5-templated-jobs/section/webhooks/sample-webhooks","routeSlug":"/v5-templated-jobs/section/webhooks/sample-webhooks","content":null},{"type":"link","label":"Webhook Content","link":"/v5-templated-jobs/section/webhooks/webhook-content","routeSlug":"/v5-templated-jobs/section/webhooks/webhook-content","content":null},{"type":"link","label":"Webhook Reliability and Monitoring","link":"/v5-templated-jobs/section/webhooks/webhook-reliability-and-monitoring","routeSlug":"/v5-templated-jobs/section/webhooks/webhook-reliability-and-monitoring","content":null},{"type":"link","label":"Security Layer - HMAC SHA","link":"/v5-templated-jobs/section/webhooks/security-layer-hmac-sha","routeSlug":"/v5-templated-jobs/section/webhooks/security-layer-hmac-sha","content":null}],"content":null},{"type":"group","label":"Postman","link":"/v5-templated-jobs/section/postman","routeSlug":"/v5-templated-jobs/section/postman","items":[{"type":"link","label":"What is Postman?","link":"/v5-templated-jobs/section/postman/what-is-postman","routeSlug":"/v5-templated-jobs/section/postman/what-is-postman","content":null}],"content":null},{"type":"separator","label":"Reference","content":null},{"type":"group","label":"Templated Job Creation","link":"/v5-templated-jobs/templated-job-creation","routeSlug":"/v5-templated-jobs/templated-job-creation","items":[{"label":"Create A New Job","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/v5-templated-jobs/templated-job-creation/create-a-new-job","routeSlug":"/v5-templated-jobs/templated-job-creation/create-a-new-job","metadata":{"seo":{"title":"Create A New Job","description":"Either template_name or template_id is the only required field for creating a new job using this API. Everything else is optional"}},"content":{"contentType":"item","itemVariant":"httpItem","meta":{"sourceId":"create-a-new-job","name":"Create A New Job","isWebhook":false,"pointer":"/paths/~1v5~1jobs~1clone.xml/post","hasSamples":true},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Create A New Job","isWebhook":false,"showPageActions":true}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Request","labelTranslationKey":"request","deepLinkSuffix":"request"},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Either template_name or template_id is the only required field for creating a new job using this API. Everything else is optional"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"The sample in this section creates a job from a template called \"Sample Template\"."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"You can see in the reply that this template includes three steps and one example of each of the custom field types."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Depending on what features are configured in your account, you may see additional fields. More detailed information on other possible fields are available in the following sections."},"children":[]}]}]}]},{"nodeType":"security","requirements":[{"schemes":[{"name":"apiKey","scopes":[],"type":"apiKey","in":"query","paramName":"api_key","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Get your key at https://go.vworkapp.com/html_client/admin/api"},"children":[]}]}]}]}]}]},{"nodeType":"item-content","variant":"query","label":"Query","labelTranslationKey":"query","parameters":[{"name":"api_key","in":"query","schemaId":"schema_62","description":"","required":true}],"pointer":"/paths/~1v5~1jobs~1clone.xml/post/parameters"},{"nodeType":"item-content","variant":"headers","label":"Headers","labelTranslationKey":"header","parameters":[{"name":"Accept-Encoding","in":"header","schemaId":"schema_63","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Must be "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"gzip"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":". The vWork API requires HTTP compression on all requests; requests without it may be rejected with 406 Not Acceptable (see Tech Notes → HTTP Compression)."},"children":[]}]}]}],"required":true,"example":"gzip"}],"pointer":"/paths/~1v5~1jobs~1clone.xml/post/parameters"},{"nodeType":"item-content","variant":"body","label":"Request Body","labelTranslationKey":"body","mediaTypes":["application/xml; charset=utf-8"],"mediaTypeSchemas":{"application/xml; charset=utf-8":{"schemaId":"schema_64","exampleIds":["paths/~1v5~1jobs~1clone.xml/post/requestBody/content/application~1xml; charset=utf-8/examples/request"]}},"schemaId":"schema_64","exampleIds":["paths/~1v5~1jobs~1clone.xml/post/requestBody/content/application~1xml; charset=utf-8/examples/request"],"pointer":"/paths/~1v5~1jobs~1clone.xml/post/requestBody"}],"panels":[{"children":[{"kind":"code-sample","source":{"kind":"code-sample","operationType":"http","method":"POST","path":"/v5/jobs/clone.xml","servers":[{"url":"https://api.vworkapp.com/api"}],"parameters":{"path":[],"query":[{"name":"api_key","in":"query","required":true,"schemaId":"schema_62"}],"querystring":[],"header":[{"name":"Accept-Encoding","in":"header","required":true,"example":"gzip","schemaId":"schema_63"}],"cookie":[]},"security":[{"schemes":[{"id":"apiKey","type":"apiKey","name":"api_key","in":"query"}],"scopes":[]}],"requestBody":{"application/xml; charset=utf-8":{"schemaId":"schema_64","exampleIds":["paths/~1v5~1jobs~1clone.xml/post/requestBody/content/application~1xml; charset=utf-8/examples/request"]}},"responseCodes":["200"],"pointer":"/v5/jobs/clone.xml","href":"templated-job-creation/create-a-new-job","openApiOperationId":"create-a-new-job","summary":"Create A New Job"},"isWebhook":false,"hideReplay":false,"servers":[{"url":"https://api.vworkapp.com/api"}],"schemaId":"schema_64","exampleIds":["paths/~1v5~1jobs~1clone.xml/post/requestBody/content/application~1xml; charset=utf-8/examples/request"],"mediaTypes":["application/xml; charset=utf-8"],"mediaTypeSchemas":{"application/xml; charset=utf-8":{"schemaId":"schema_64","exampleIds":["paths/~1v5~1jobs~1clone.xml/post/requestBody/content/application~1xml; charset=utf-8/examples/request"]}},"examples":[{}]}]}]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Responses","labelTranslationKey":"responses","deepLinkSuffix":"responses"},{"nodeType":"item-content","variant":"responses","responses":[{"code":"200","description":"OK","mediaType":"application/xml; charset=utf-8","mediaTypes":["application/xml; charset=utf-8"],"mediaTypeContent":{"application/xml; charset=utf-8":{"schemaId":"schema_64","exampleIds":["paths/~1v5~1jobs~1clone.xml/post/responses/200/content/application~1xml; charset=utf-8/examples/response"]}},"schemaId":"schema_64","exampleIds":["paths/~1v5~1jobs~1clone.xml/post/responses/200/content/application~1xml; charset=utf-8/examples/response"],"headers":{"Status":{"schema":{"type":"string"},"example":"200 OK"},"Cache-Control":{"schema":{"type":"string"},"example":"max-age=0, private, must-revalidate"},"Content-Encoding":{"schema":{"type":"string"},"example":"gzip"}},"headerSchemaId":"schema_65"}],"pointer":"/paths/~1v5~1jobs~1clone.xml/post/responses"}],"panels":[{"children":[{"kind":"response","headerTitle":"Response","responseCodes":[{"code":"200","schemaId":"schema_64","exampleIds":["paths/~1v5~1jobs~1clone.xml/post/responses/200/content/application~1xml; charset=utf-8/examples/response"],"mediaTypes":["application/xml; charset=utf-8"],"mediaTypeContent":{"application/xml; charset=utf-8":{"schemaId":"schema_64","exampleIds":["paths/~1v5~1jobs~1clone.xml/post/responses/200/content/application~1xml; charset=utf-8/examples/response"]}}}],"examples":[]}]}]},{"nodeType":"container","children":[{"nodeType":"feedback","pageSlug":"/templated-job-creation/create-a-new-job"}],"panels":[]}]},"httpPath":"/v5/jobs/clone.xml"}],"content":{"contentType":"group","meta":{"name":"Templated Job Creation"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Templated Job Creation","showPageActions":true},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"A job represents a task that gets assigned to (and completed by) a mobile worker. As well as the job’s basic details (when, where, and who for) you can also specify the job’s workflow (i.e. steps) and additional information (like custom fields or invoice line items) for the job."},"children":[]}]}]}]}],"panels":[{"children":[{"kind":"group-items","title":"Operations","titleTranslationKey":"operations","items":[{"title":"/v5/jobs/clone.xml","summary":"Create A New Job","prefix":{"name":"post","color":"post"},"badges":[],"link":"/templated-job-creation/create-a-new-job","deprecated":false}]}]}]}]}},{"type":"group","label":"Jobs and 3rd Party IDs","link":"/v5-templated-jobs/jobs-and-3rd-party-ids","routeSlug":"/v5-templated-jobs/jobs-and-3rd-party-ids","items":[],"content":{"contentType":"group","meta":{"name":"Jobs and 3rd Party IDs"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Jobs and 3rd Party IDs","showPageActions":true},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Jobs will accept a third_party_id. This is useful for passing through an external job ID from another system. To supply a 3rd party ID for your job, include the following XML in your POST:"},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"<third_party_id>INV12345</third_party_id>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"<third_party_id>INV12345</third_party_id>\n"},"children":[]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"If you do supply a third_party_id, it must be unique."},"children":[]}]}]}]}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"feedback","pageSlug":"/jobs-and-3rd-party-ids"}],"panels":[]}]}},{"type":"group","label":"Jobs and Customer Info","link":"/v5-templated-jobs/jobs-and-customer-info","routeSlug":"/v5-templated-jobs/jobs-and-customer-info","items":[],"content":{"contentType":"group","meta":{"name":"Jobs and Customer Info"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Jobs and Customer Info","showPageActions":true},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"vWork supports both Job records and Customer records.  When creating a job, you should link it to a customer record.  This can be done by the customer name, the customer ID, or a customer 3rd party ID. Examples are as follows:"},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"<customer_id>2883055</customer_id>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"<customer_id>2883055</customer_id>\n"},"children":[]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"<customer_third_party_id>123456789</customer_third_party_id>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"<customer_third_party_id>123456789</customer_third_party_id>\n"},"children":[]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"<customer_name>John Smith</customer_name>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"<customer_name>John Smith</customer_name>\n"},"children":[]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"We suggest using one of the IDs and not the name to ensure you are linking to the correct customer as there can be multiple customer records with the same name."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Documentation for creating customers can be found under our standard API documentation."},"children":[]}]}]}]}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"feedback","pageSlug":"/jobs-and-customer-info"}],"panels":[]}]}},{"type":"group","label":"Jobs and Steps","link":"/v5-templated-jobs/jobs-and-steps","routeSlug":"/v5-templated-jobs/jobs-and-steps","items":[],"content":{"contentType":"group","meta":{"name":"Jobs and Steps"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Jobs and Steps","showPageActions":true},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Steps within a job define the workflow of the job."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Completing the first step starts the job, and completing all steps completes the job. Steps must be completed in order, so that no steps are skipped."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Steps may optionally include an address.  Steps will be automatically inherited from the template, you only need to supply step information if you are supplying a street address that is not saved in the template."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"If you are sending a step address, ensure that you send a display name as well as the lat and long of the location, the format is as follows:"},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"   <steps type=\"array\">\n        <step>\n            <name>Step Name Here</name>\n             <location>\n                <formatted_address>18 Railway Street, Newmarket, Auckland, New Zealand</formatted_address>\n                <lat>-36.865387</lat>\n                <lng>174.780437</lng>\n            </location>\n        </step>\n    </steps>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"   <steps type=\"array\">\n        <step>\n            <name>Step Name Here</name>\n             <location>\n                <formatted_address>18 Railway Street, Newmarket, Auckland, New Zealand</formatted_address>\n                <lat>-36.865387</lat>\n                <lng>174.780437</lng>\n            </location>\n        </step>\n    </steps>\n"},"children":[]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"In the example above, the street address is supplied for a named step.  If you prefer, you can also define the step that needs the address from the step order.  The following example supplies an address for the 2nd step on the job:"},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"    <steps type=\"array\">\n        <step>\n            <order>2</order>\n            <location>\n                <formatted_address>Auckland Hospital Park Road, Grafton, Auckland, New Zealand</formatted_address>\n                <lat>-36.859552</lat>\n                <lng>174.770386</lng>\n            </location>\n        </step>\n    </steps>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"    <steps type=\"array\">\n        <step>\n            <order>2</order>\n            <location>\n                <formatted_address>Auckland Hospital Park Road, Grafton, Auckland, New Zealand</formatted_address>\n                <lat>-36.859552</lat>\n                <lng>174.770386</lng>\n            </location>\n        </step>\n    </steps>\n"},"children":[]}]}]}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"feedback","pageSlug":"/jobs-and-steps"}],"panels":[]}]}},{"type":"group","label":"Jobs and Custom Fields","link":"/v5-templated-jobs/jobs-and-custom-fields","routeSlug":"/v5-templated-jobs/jobs-and-custom-fields","items":[{"type":"link","label":"Custom Field Types","link":"/v5-templated-jobs/jobs-and-custom-fields/custom-field-types","routeSlug":"/v5-templated-jobs/jobs-and-custom-fields/custom-field-types","content":{"contentType":"item","itemVariant":"markdown","meta":{"name":"Custom Field Types"},"children":[{"nodeType":"container","children":[{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"heading","attributes":{"level":2,"id":"jobs-and-custom-fields/custom-field-types"},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Custom Field Types"},"children":[]}]}]},{"$$mdtype":"Node","type":"table","attributes":{},"children":[{"$$mdtype":"Node","type":"thead","attributes":{},"children":[{"$$mdtype":"Node","type":"tr","attributes":{},"children":[{"$$mdtype":"Node","type":"th","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Name"},"children":[]}]}]},{"$$mdtype":"Node","type":"th","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Type"},"children":[]}]}]},{"$$mdtype":"Node","type":"th","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Description"},"children":[]}]}]}]}]},{"$$mdtype":"Node","type":"tbody","attributes":{},"children":[{"$$mdtype":"Node","type":"tr","attributes":{},"children":[{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"text"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"String"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Allows users to enter text into the custom field. (This is the default, unless you specify a different type)"},"children":[]}]}]}]},{"$$mdtype":"Node","type":"tr","attributes":{},"children":[{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"image"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"String"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Creates a custom field for a dispatcher or worker to upload an image. (Images cannot be uploaded via the API, but links to images uploaded via the website or mobile apps are available to download via the attachments API call.)"},"children":[]}]}]}]},{"$$mdtype":"Node","type":"tr","attributes":{},"children":[{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"datetime"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"DateTime"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Shows a date-time picker to make it easier for users to enter a date and time. The format of the date/time must be ISO8601 as per the tech note."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"tr","attributes":{},"children":[{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"number"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"String"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"This field can only contain numbers, plus the minus and decimal place characters. The custom field input on the device will show a number keypad layout."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"tr","attributes":{},"children":[{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"link"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"String"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Creates a clickable URL field. URLs must begin with http:// or https:// and should be a valid URL."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"tr","attributes":{},"children":[{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"checkbox"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"String"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Creates a check box field where the value must be true or false. Accepted values for true include '1','true','t','checked' and 'on'."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"tr","attributes":{},"children":[{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"currency"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Decimal"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Creates a numerical decimal field. This field can only contain numbers, plus the minus and decimal place characters."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"tr","attributes":{},"children":[{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"signature"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"String"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Creates a custom field for a worker to collect a signature. Please note, this is in addition to the default proof of delivery signature that appears on every job by default. (Signatures cannot be uploaded via the API, but links to signatures uploaded from the mobile apps are available to download via the signatures API call.)"},"children":[]}]}]}]},{"$$mdtype":"Node","type":"tr","attributes":{},"children":[{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"pick_list"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"String"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Uses an existing pick list from the account, users can choose one of the pre-defined values. (Pick lists can be administered via the pick lists api call.)"},"children":[]}]}]}]},{"$$mdtype":"Node","type":"tr","attributes":{},"children":[{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"multi_pick_list"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"String"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Uses an existing pick list from the account, users can choose more than one of the pre-defined values. (Pick lists can be administered via the pick lists api call.)"},"children":[]}]}]}]},{"$$mdtype":"Node","type":"tr","attributes":{},"children":[{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"location"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Two Decimals and a String"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Creates a location custom field. This field may contain a lat/long as well as a free text string that describes the location. This string is often (but not always) a street address. There is an example of the format in the custom field samples section below."},"children":[]}]}]}]}]}]}]}],"panels":[]}]}},{"type":"link","label":"Custom Field Permissions","link":"/v5-templated-jobs/jobs-and-custom-fields/custom-field-permissions","routeSlug":"/v5-templated-jobs/jobs-and-custom-fields/custom-field-permissions","content":{"contentType":"item","itemVariant":"markdown","meta":{"name":"Custom Field Permissions"},"children":[{"nodeType":"container","children":[{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"heading","attributes":{"level":2,"id":"jobs-and-custom-fields/custom-field-permissions"},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Custom Field Permissions"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"You may also specify some constraints on how your mobile user interacts with the custom fields"},"children":[]}]}]},{"$$mdtype":"Node","type":"table","attributes":{},"children":[{"$$mdtype":"Node","type":"thead","attributes":{},"children":[{"$$mdtype":"Node","type":"tr","attributes":{},"children":[{"$$mdtype":"Node","type":"th","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Name"},"children":[]}]}]},{"$$mdtype":"Node","type":"th","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Type"},"children":[]}]}]},{"$$mdtype":"Node","type":"th","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Description"},"children":[]}]}]}]}]},{"$$mdtype":"Node","type":"tbody","attributes":{},"children":[{"$$mdtype":"Node","type":"tr","attributes":{},"children":[{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"optional"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"String"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"All users will be able to update this field, but will not be required to. (this is the default, unless you specify a different permission)"},"children":[]}]}]}]},{"$$mdtype":"Node","type":"tr","attributes":{},"children":[{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"required"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"String"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"All users will be unable to complete the job without entering a value for this field."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"tr","attributes":{},"children":[{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"read_only"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"String"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Allows dispatchers to update the value, but mobile workers will only be able to read this field."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"tr","attributes":{},"children":[{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"hidden"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"String"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Allows dispatchers to view and update the value, but mobile workers will not see this field."},"children":[]}]}]}]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"All custom field types can have any of the permissions above, apart from the following exceptions:"},"children":[]}]}]},{"$$mdtype":"Node","type":"list","attributes":{"ordered":false,"marker":"-"},"children":[{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"link  - must be set to either hidden or read_only"},"children":[]}]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"signature - must be set to either optional or required"},"children":[]}]}]}]}]}]}],"panels":[]}]}},{"type":"link","label":"Custom Field Samples","link":"/v5-templated-jobs/jobs-and-custom-fields/custom-field-samples","routeSlug":"/v5-templated-jobs/jobs-and-custom-fields/custom-field-samples","content":{"contentType":"item","itemVariant":"markdown","meta":{"name":"Custom Field Samples"},"children":[{"nodeType":"container","children":[{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"heading","attributes":{"level":2,"id":"jobs-and-custom-fields/custom-field-samples"},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Custom Field Samples"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"To populate a custom field called \"A Sample Field, with the value of \"testing\", you would include the following XML in your POST."},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"    <custom_fields type=\"array\">\n        <custom_field>\n            <name>A Sample Field</name>\n            <value>testing</value>\n        </custom_field>\n    </custom_fields>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"    <custom_fields type=\"array\">\n        <custom_field>\n            <name>A Sample Field</name>\n            <value>testing</value>\n        </custom_field>\n    </custom_fields>\n"},"children":[]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Populating custom field values works the same way regardless of type or permission. The type of field and the field permission will be inherited from the template."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"To replicate the example above, but as a multi value pick list, you would include the following XML within the custom fields array on the job:"},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"    <custom_field>\n        <name>A Sample Field</name>\n        <values type=\"array\">\n            <value>testing 1</value>\n            <value>testing 2</value>\n        </values>        \n    </custom_field>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"    <custom_field>\n        <name>A Sample Field</name>\n        <values type=\"array\">\n            <value>testing 1</value>\n            <value>testing 2</value>\n        </values>        \n    </custom_field>\n"},"children":[]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"To create a populated location custom field, you would include the following XML within the custom fields array on the job:"},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"<custom_field>\n    <name>Location of Damaged Equipment</name>\n    <lat>-36.849919</lat>\n    <lng>174.7624623</lng>\n    <formatted_address>34893 Albert Street, Auckland CBD, Auckland 1010, New Zealand</formatted_address>\n</custom_field>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"<custom_field>\n    <name>Location of Damaged Equipment</name>\n    <lat>-36.849919</lat>\n    <lng>174.7624623</lng>\n    <formatted_address>34893 Albert Street, Auckland CBD, Auckland 1010, New Zealand</formatted_address>\n</custom_field>\n"},"children":[]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Supplying values for images, or signatures is not currently supported."},"children":[]}]}]}]}],"panels":[]}]}}],"content":{"contentType":"group","meta":{"name":"Jobs and Custom Fields"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Jobs and Custom Fields","showPageActions":true},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Custom fields are where you can either supply extra information to workers in the field or prompt them to collect information when they are completing the job."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Every custom field has a name, type, value, and permission."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"You cannot have two custom fields within a job with the same name."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"There are 11 different custom field types. A custom field type defines the type of data expected. (eg: text, photo, signature, etc.) The type of custom field will determine what values you can add. (eg: you cannot add a photo to a text field.)"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Each custom field has a permission associated with it that determines how it is displayed to the mobile worker (eg: hidden, optional, mandatory, etc.)"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"All custom field info stored in the template will be automatically populated in the job when using the templated jobs API.  You only need to specify any values that you are suppling."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"A full list of custom field types, permissions, as well as some samples are listed below."},"children":[]}]}]}]}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"feedback","pageSlug":"/jobs-and-custom-fields"}],"panels":[]}]}},{"type":"group","label":"Jobs and Custom Field Sections","link":"/v5-templated-jobs/jobs-and-custom-field-sections","routeSlug":"/v5-templated-jobs/jobs-and-custom-field-sections","items":[],"content":{"contentType":"group","meta":{"name":"Jobs and Custom Field Sections"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Jobs and Custom Field Sections","showPageActions":true},{"nodeType":"markdoc","content":"Custom field sections are an optional feature that allow you to group your custom fields into sections with a bold heading.  It can make them easier to read for your workers.\n\nYou do not need to do anything as sections will be inherited from the template."}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"feedback","pageSlug":"/jobs-and-custom-field-sections"}],"panels":[]}]}},{"type":"group","label":"Jobs and Conditional Logic","link":"/v5-templated-jobs/jobs-and-conditional-logic","routeSlug":"/v5-templated-jobs/jobs-and-conditional-logic","items":[],"content":{"contentType":"group","meta":{"name":"Jobs and Conditional Logic"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Jobs and Conditional Logic","showPageActions":true},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Conditional logic builds on the sections functionality and allows you to expose or hide sections based on questions asked in other custom fields."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"You do not need to do anything special as the conditional logic will be inherited from the template."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"You can supply field values that will drive conditional logic.  For example, you could supply a yes value to a question that then exposes another set of custom fields.  This is done the same way as setting the value in a regular custom field."},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"    <custom_fields type=\"array\">\n        <custom_field>\n            <name>Is there a dog on site?</name>\n            <value>yes</value>\n        </custom_field>\n    </custom_fields>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"    <custom_fields type=\"array\">\n        <custom_field>\n            <name>Is there a dog on site?</name>\n            <value>yes</value>\n        </custom_field>\n    </custom_fields>\n"},"children":[]}]}]}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"feedback","pageSlug":"/jobs-and-conditional-logic"}],"panels":[]}]}},{"type":"group","label":"Jobs and Invoices","link":"/v5-templated-jobs/jobs-and-invoices","routeSlug":"/v5-templated-jobs/jobs-and-invoices","items":[],"content":{"contentType":"group","meta":{"name":"Jobs and Invoices"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Jobs and Invoices","showPageActions":true},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"If invoicing is enabled for your account, you can add an invoice to a job."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"If there is invoice information already saved against the template, your job will inherit the invoice information from the template."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"If you need to supply specific invoice information when creating a job you can supply the following XML with the job."},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"    <invoice>\n        <description>A Standard Heat Pump Service</description>\n        <tax_rate>15</tax_rate>\n        <line_items type=\"array\">\n            <line_item>\n                <code>CALL</code>\n                <description>Call Out Fee</description>\n                <unit_cost>100.0</unit_cost>\n                <requested_quantity>1.0</requested_quantity>\n                <actual_quantity>1.0</actual_quantity>\n            </line_item>\n        </line_items>\n    </invoice>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"    <invoice>\n        <description>A Standard Heat Pump Service</description>\n        <tax_rate>15</tax_rate>\n        <line_items type=\"array\">\n            <line_item>\n                <code>CALL</code>\n                <description>Call Out Fee</description>\n                <unit_cost>100.0</unit_cost>\n                <requested_quantity>1.0</requested_quantity>\n                <actual_quantity>1.0</actual_quantity>\n            </line_item>\n        </line_items>\n    </invoice>\n"},"children":[]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"You may have multiple line items in the array. vWork will calculate the line item totals and invoice totals for you."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Dispatchers and mobile workers may also be able to add, edit and delete invoice information depending on their permissions."},"children":[]}]}]}]}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"feedback","pageSlug":"/jobs-and-invoices"}],"panels":[]}]}},{"type":"group","label":"Jobs and Pricebooks","link":"/v5-templated-jobs/jobs-and-pricebooks","routeSlug":"/v5-templated-jobs/jobs-and-pricebooks","items":[],"content":{"contentType":"group","meta":{"name":"Jobs and Pricebooks"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Jobs and Pricebooks","showPageActions":true},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Pricebooks are simply an easy way to define what items are available to be added to an invoice."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Pricebooks can contain up to 2000 items, each item has a code, description and unit cost."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Web users can select a pricebook for each of their templates.  You can either inherit the pricebook saved against the template or you can select a specific pricebook for each job you create."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"If you are using our customer specific pricebooks features, you can also inherit the pricebook from the customer record."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Here is an example of an invoice with pricebook 12345 attached to it:"},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"<invoice>\n     <number></number>\n     <description>Sample Description Here</description>\n     <pricebook_id>12345</pricebook_id>\n     <tax_rate>5.5</tax_rate>\n     <line_items type=\"array\">\n         <line_item>\n             <code>wid1</code>\n             <description>Widgets</description>\n             <unit_cost>100.0</unit_cost>\n             <requested_quantity>0.0</requested_quantity>\n             <actual_quantity>1.0</actual_quantity>\n         </line_item>\n     </line_items>\n </invoice>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"<invoice>\n     <number></number>\n     <description>Sample Description Here</description>\n     <pricebook_id>12345</pricebook_id>\n     <tax_rate>5.5</tax_rate>\n     <line_items type=\"array\">\n         <line_item>\n             <code>wid1</code>\n             <description>Widgets</description>\n             <unit_cost>100.0</unit_cost>\n             <requested_quantity>0.0</requested_quantity>\n             <actual_quantity>1.0</actual_quantity>\n         </line_item>\n     </line_items>\n </invoice>\n"},"children":[]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"It also now possible to control the content of a pricebook via the API. You can use the pricebook API route to get a list of available pricebooks and their matching IDs.  More information on this route can be found in our "},"children":[]},{"$$mdtype":"Node","type":"tag","tag":"html","inline":true,"attributes":{"name":"a","attrs":{"href":"/v5/pricebooks"}},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"standard documentation"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"."},"children":[]}]}]}]}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"feedback","pageSlug":"/jobs-and-pricebooks"}],"panels":[]}]}},{"type":"group","label":"Jobs and Notes","link":"/v5-templated-jobs/jobs-and-notes","routeSlug":"/v5-templated-jobs/jobs-and-notes","items":[],"content":{"contentType":"group","meta":{"name":"Jobs and Notes"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Jobs and Notes","showPageActions":true},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Dispatchers and workers can both add notes to a job."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Notes are visible to all vWork users, but can only be edited or removed by the person who added the note."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Adding a note to a job does not remove or overwrite old notes, it simply adds a new note to the array."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"If you would like to add a note to a job, you include the following XML in a POST:"},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"<notes type=\"array\">\n    <note>\n    <body>This is a sample note.</body>\n    </note>\n</notes>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"<notes type=\"array\">\n    <note>\n    <body>This is a sample note.</body>\n    </note>\n</notes>\n"},"children":[]}]}]}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"feedback","pageSlug":"/jobs-and-notes"}],"panels":[]}]}},{"type":"group","label":"Jobs and Image Custom Fields","link":"/v5-templated-jobs/jobs-and-image-custom-fields","routeSlug":"/v5-templated-jobs/jobs-and-image-custom-fields","items":[],"content":{"contentType":"group","meta":{"name":"Jobs and Image Custom Fields"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Jobs and Image Custom Fields","showPageActions":true},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"If you need information on how to download the image from an image custom field it can be found "},"children":[]},{"$$mdtype":"Node","type":"tag","tag":"html","inline":true,"attributes":{"name":"a","attrs":{"href":"/v5/attachments"}},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"here"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"This section documents how to upload a file to an image custom field when creating a job. Please note, this varies slightly from other custom field types in that you must include the custom field type."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"You can upload one JPG, PNG, or PDF file to an image custom field.  The file must be less than 5MB in size."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"To upload an image you must first encode the image as base 64 encoded text. You then include this text in the data field shown in the example below."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"If you would like to add a image to a job, you include the following XML in a POST:"},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"    <custom_fields type=\"array\">\n        <custom_field>\n            <name>The name of your image custom field here.</name>\n            <type>image</type>\n            <data>The base64 encoded value for your image file here.</data>\n        </custom_field>\n    </custom_fields>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"    <custom_fields type=\"array\">\n        <custom_field>\n            <name>The name of your image custom field here.</name>\n            <type>image</type>\n            <data>The base64 encoded value for your image file here.</data>\n        </custom_field>\n    </custom_fields>\n"},"children":[]}]}]}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"feedback","pageSlug":"/jobs-and-image-custom-fields"}],"panels":[]}]}},{"type":"group","label":"Jobs and Deadlines","link":"/v5-templated-jobs/jobs-and-deadlines","routeSlug":"/v5-templated-jobs/jobs-and-deadlines","items":[],"content":{"contentType":"group","meta":{"name":"Jobs and Deadlines"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Jobs and Deadlines","showPageActions":true},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Deadlines are an optional feature that is not enabled by default."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Deadlines allow you to set a deadline for job completion that is not related to the planned start time."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"For example, you may have a job with a 5:00 Friday deadline, but the dispatcher can still plan for it to start at any time during the week."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"The website allows users to specify a deadline duration in the template, for example an emergency water main job may automatically get a deadline that is 3 hours after the job create time to meet the customer's SLA for this type of job."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"If you are creating jobs via the API and a deadline duration has been set in the template, your job will automatically inherit the correct deadline."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"If you need to set a deadline and the duration is not configured in the template, then you set a specific date and time rather than a duration."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"The following example sets a job deadline of Dec 31 2019 at 5pm."},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"<complete_deadline>2019-12-31T17:00:00+13:00</complete_deadline>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"<complete_deadline>2019-12-31T17:00:00+13:00</complete_deadline>\n"},"children":[]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Note: The +13:00 at the end of the time means that we are operating in a time zone that is 13 hours ahead of UTC, so this deadline is \"local time\"."},"children":[]}]}]}]}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"feedback","pageSlug":"/jobs-and-deadlines"}],"panels":[]}]}},{"type":"group","label":"Jobs and Groups","link":"/v5-templated-jobs/jobs-and-groups","routeSlug":"/v5-templated-jobs/jobs-and-groups","items":[],"content":{"contentType":"group","meta":{"name":"Jobs and Groups"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Jobs and Groups","showPageActions":true},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Groups are another optional feature that is not enabled by default."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Groups enable you to separate your workers into different teams. (For example: sales and service, electricians and plumbers, North and South, East Coast and West Coast, Boston and Chicago, etc…)"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Each group can have a different time zone."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Workers can belong to one or many groups."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"If you need to create a job for a specific group, you need to include the group ID in the job XML like so:"},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"<group_ids>123</group_ids>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"<group_ids>123</group_ids>\n"},"children":[]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"You can use the group API route to retrieve a list of groups for your account and their associated IDs.  You can also use the groups route to create, edit and delete groups as needed. Documentation for managing your groups may be found under our normal API documentation."},"children":[]}]}]}]}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"feedback","pageSlug":"/jobs-and-groups"}],"panels":[]}]}},{"type":"group","label":"Jobs and Tags","link":"/v5-templated-jobs/jobs-and-tags","routeSlug":"/v5-templated-jobs/jobs-and-tags","items":[],"content":{"contentType":"group","meta":{"name":"Jobs and Tags"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Jobs and Tags","showPageActions":true},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Tags are a subset of vWork's Health and Safety module and are not enabled by default."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Once they are enabled, you can add specific tags to your workers, jobs and templates. This will prevent your dispatchers from assigning jobs to workers that do not have the required qualifications for a certain job."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"If you need to include a tag (or tags) on a job, you can include the tag IDs in the job XML. The following example adds tag 123 and tag 456 to the job."},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"<tags>123,456</tags>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"<tags>123,456</tags>\n"},"children":[]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"You can retrieve a list of tags for your account via the API using the tags route. Documentation for managing your tags may be found under our normal API documentation."},"children":[]}]}]}]}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"feedback","pageSlug":"/jobs-and-tags"}],"panels":[]}]}},{"type":"group","label":"Jobs and Hazards","link":"/v5-templated-jobs/jobs-and-hazards","routeSlug":"/v5-templated-jobs/jobs-and-hazards","items":[],"content":{"contentType":"group","meta":{"name":"Jobs and Hazards"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Jobs and Hazards","showPageActions":true},{"nodeType":"markdoc","content":"Hazards are also included in the Health and Safety module.\n\nThe job hazard register allows your dispatchers and workers to identify and record hazards on a job. Workers will not be able to complete the job until they acknowledge the hazards identified and confirm it is safe to proceed.\n\nHazards include 6 mandatory pieces of information: Description, Initial Risk, Control Type, Controls Required, Person Responsible, and Residual Risk. This information all needs to be filled in before the hazards can be acknowledged. However, it doesn't all have to be done via the API.\n\nWhen creating a job using the templated jobs API (and using a template that has hazards enabled) hazards will be automatically enabled on the created job and the trigger step will be populated from the template.  Any hazards present on the template will also be present on the job."}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"feedback","pageSlug":"/jobs-and-hazards"}],"panels":[]}]}},{"type":"group","label":"Jobs and Time Windows","link":"/v5-templated-jobs/jobs-and-time-windows","routeSlug":"/v5-templated-jobs/jobs-and-time-windows","items":[],"content":{"contentType":"group","meta":{"name":"Jobs and Time Windows"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Jobs and Time Windows","showPageActions":true},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Time windows are an optional feature that is enabled with route optimisation. Time windows will be automatically inherited from the template, or they can be added when you create the job as per the samples below."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Time windows allow you to define times when jobs can't be done. (eg: We can't mow the sportsfield on Saturday and Sunday mornings between 8am and 1 pm because of the soccer games.)  This is an exclusion time slot and can be added to a job like so:"},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"<time_windows type=\"array\">\n    <time_window>\n        <start_time>28800</start_time>\n        <end_time>46800</end_time>\n        <day_of_week>6</day_of_week>\n    </time_window>\n    <time_window>\n        <start_time>28800</start_time>\n        <end_time>46800</end_time>\n        <day_of_week>0</day_of_week>\n    </time_window>\n</time_windows>\n<negative_time_windows>true</negative_time_windows>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"<time_windows type=\"array\">\n    <time_window>\n        <start_time>28800</start_time>\n        <end_time>46800</end_time>\n        <day_of_week>6</day_of_week>\n    </time_window>\n    <time_window>\n        <start_time>28800</start_time>\n        <end_time>46800</end_time>\n        <day_of_week>0</day_of_week>\n    </time_window>\n</time_windows>\n<negative_time_windows>true</negative_time_windows>\n"},"children":[]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"The days of the week start from Sunday as day 0, so Monday is day 1 and Saturday is day 6."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"The start time and end time are in seconds from midnight, so 8am is 28800 and 1pm is 46800."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"You can also define times when jobs must be done. (We only have access to the forklift between 9 and 12 on Mon, Wed and Fri.) This is an inclusion time slot and can be added to a job like so:"},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"<time_windows type=\"array\">\n    <time_window>\n        <start_time>32400</start_time>\n        <end_time>43200</end_time>\n        <day_of_week>1</day_of_week>\n    </time_window>\n        <time_window>\n        <start_time>32400</start_time>\n        <end_time>43200</end_time>\n        <day_of_week>3</day_of_week>\n    </time_window>\n    <time_window>\n        <start_time>32400</start_time>\n        <end_time>43200</end_time>\n        <day_of_week>5</day_of_week>\n    </time_window>\n</time_windows>\n<negative_time_windows>false</negative_time_windows>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"<time_windows type=\"array\">\n    <time_window>\n        <start_time>32400</start_time>\n        <end_time>43200</end_time>\n        <day_of_week>1</day_of_week>\n    </time_window>\n        <time_window>\n        <start_time>32400</start_time>\n        <end_time>43200</end_time>\n        <day_of_week>3</day_of_week>\n    </time_window>\n    <time_window>\n        <start_time>32400</start_time>\n        <end_time>43200</end_time>\n        <day_of_week>5</day_of_week>\n    </time_window>\n</time_windows>\n<negative_time_windows>false</negative_time_windows>\n"},"children":[]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"The day and time logic works the same way, but negative time windows are set to false instead of true."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"If these time windows are added to a job (either by the webapp or the API) we will prevent jobs from breaking these rules when they are being optimised."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"We will also warn dispatchers if they manually schedule a job that breaks one of these rules, but won't prevent it."},"children":[]}]}]}]}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"feedback","pageSlug":"/jobs-and-time-windows"}],"panels":[]}]}},{"type":"group","label":"Jobs and Capacity","link":"/v5-templated-jobs/jobs-and-capacity","routeSlug":"/v5-templated-jobs/jobs-and-capacity","items":[],"content":{"contentType":"group","meta":{"name":"Jobs and Capacity"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Jobs and Capacity","showPageActions":true},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"A job's capacity setting is also turned on when route optimisation is enabled. This feature allows you to set a capacity allowed for a vehicle and a capacity required on a job. The vWork optimisation module will then prevent overloading a vehicle."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Capacity can be measured however you like: meals, boxes, pallets, tonnes, cubic metres, etc. But you need to use the same metric on both vehicles and jobs.  You cannot use capacity to solve complex load planning problems."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"For example, a small van could carry 100 meals, and a customer may order two meals in a job."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"You would then need to add a capacity of \"2\" to a job, so include the following XML when POSTing the job."},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"<required_capacity>2</required_capacity>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"<required_capacity>2</required_capacity>\n"},"children":[]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"As you've probably guessed by now, any value saved in the template will be automatically inherited by the job when using the templated jobs API, unless you supply a new value as per the sample code above."},"children":[]}]}]}]}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"feedback","pageSlug":"/jobs-and-capacity"}],"panels":[]}]}},{"type":"group","label":"Jobs and Ad Hoc Alert Recipients v1, please do not use.","link":"/v5-templated-jobs/jobs-and-ad-hoc-alert-recipients-v1","routeSlug":"/v5-templated-jobs/jobs-and-ad-hoc-alert-recipients-v1","items":[],"content":{"contentType":"group","meta":{"name":"Jobs and Ad Hoc Alert Recipients v1"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Jobs and Ad Hoc Alert Recipients v1, please do not use.","showPageActions":true},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"tag","tag":"html","inline":true,"attributes":{"name":"b","attrs":{}},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"This is a Legacy feature, that is being deprecated, please refer to v2 in the next section."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Out of the box you can use vWork to send SMS and email alerts to workers, customers, dispatchers, etc.  However, what if you need to send an alert to someone specific to the job (like a 3rd party site manager who needs to enable access for your team).  This is where ad hoc alerts come in."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Ad hoc alerts allow you to add these one off contact details to the specific jobs that require them.  You can then use the vWork alerts module to trigger alerts to these ad hoc recipients."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"If you need to add an ad hoc email recipient to a job, you can use the following XML:"},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"    <adhoc_alert_email_recipient>\n        <name>Steve</name>\n        <email>steve.taylor@vworkapp.com</email>\n    </adhoc_alert_email_recipient>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"    <adhoc_alert_email_recipient>\n        <name>Steve</name>\n        <email>steve.taylor@vworkapp.com</email>\n    </adhoc_alert_email_recipient>\n"},"children":[]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"And for an SMS recipient, you can use the following XML:"},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"    <adhoc_alert_sms_recipient>\n        <name>John</name>\n        <mobile>64 21234567</mobile>\n    </adhoc_alert_sms_recipient>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"    <adhoc_alert_sms_recipient>\n        <name>John</name>\n        <mobile>64 21234567</mobile>\n    </adhoc_alert_sms_recipient>\n"},"children":[]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"You can include both SMS and email to a job, but you can only have one of each per job."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Please ensure that you include the country code followed by a space when specifying the mobile number."},"children":[]}]}]}]}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"feedback","pageSlug":"/jobs-and-ad-hoc-alert-recipients-v1"}],"panels":[]}]}},{"type":"group","label":"Jobs and Ad Hoc Alert Recipients v2","link":"/v5-templated-jobs/jobs-and-ad-hoc-alert-recipients-v2","routeSlug":"/v5-templated-jobs/jobs-and-ad-hoc-alert-recipients-v2","items":[],"content":{"contentType":"group","meta":{"name":"Jobs and Ad Hoc Alert Recipients v2"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Jobs and Ad Hoc Alert Recipients v2","showPageActions":true},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Please speak to your account manager to ensure this has been enabled for your account."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Out of the box you can use vWork to send SMS and email alerts to workers, customers, dispatchers, etc.  However, what if you need to send an alert to someone specific to the job (like a 3rd party site manager or security guard who needs to enable access for your team)?  This is where ad hoc alerts come in."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Ad hoc alerts allow you to add these one off contact details to the specific jobs that require them.  You can then use the vWork alerts module to trigger alerts to these ad hoc recipients."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"You may add up to three recipients for each job as per the example below:"},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"<adhoc_contact>\n  <name>Steve</name>\n  <email>Steve@example.com</email>\n  <phone>64 123456789</phone>\n</adhoc_contact>\n\n<origin_adhoc_contact>\n  <name>Jane</name>\n  <email>Jane@example.com</email>\n  <phone>64 123456789</phone>\n</origin_adhoc_contact>\n\n<destination_adhoc_contact>\n  <name>Bob</name>\n  <email>Bob@example.com</email>\n  <phone>64 123456789</phone>\n</destination_adhoc_contact>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"<adhoc_contact>\n  <name>Steve</name>\n  <email>Steve@example.com</email>\n  <phone>64 123456789</phone>\n</adhoc_contact>\n\n<origin_adhoc_contact>\n  <name>Jane</name>\n  <email>Jane@example.com</email>\n  <phone>64 123456789</phone>\n</origin_adhoc_contact>\n\n<destination_adhoc_contact>\n  <name>Bob</name>\n  <email>Bob@example.com</email>\n  <phone>64 123456789</phone>\n</destination_adhoc_contact>\n"},"children":[]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Please ensure that you include the country code followed by a space when specifying the mobile number."},"children":[]}]}]}]}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"feedback","pageSlug":"/jobs-and-ad-hoc-alert-recipients-v2"}],"panels":[]}]}},{"type":"group","label":"Jobs and Planned Start Time","link":"/v5-templated-jobs/jobs-and-planned-start-time","routeSlug":"/v5-templated-jobs/jobs-and-planned-start-time","items":[],"content":{"contentType":"group","meta":{"name":"Jobs and Planned Start Time"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Jobs and Planned Start Time","showPageActions":true},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"If you want to schedule when a job should be started, you need to include the planned start time.  The following example shows a job that is planned to start at 08:30 UTC on Oct 22nd 2020."},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"<planned_start_at>2020-10-22T08:30:00+00:00</planned_start_at>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"<planned_start_at>2020-10-22T08:30:00+00:00</planned_start_at>\n"},"children":[]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Note that the planned start at is defined in local time by adding the UTC offset to the end of the timestamp. In the example below, this is +13:00."},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"<planned_start_at>2019-12-22T10:15:00+13:00</planned_start_at>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"<planned_start_at>2019-12-22T10:15:00+13:00</planned_start_at>\n"},"children":[]}]}]}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"feedback","pageSlug":"/jobs-and-planned-start-time"}],"panels":[]}]}},{"type":"group","label":"Jobs and Workers","link":"/v5-templated-jobs/jobs-and-workers","routeSlug":"/v5-templated-jobs/jobs-and-workers","items":[],"content":{"contentType":"group","meta":{"name":"Jobs and Workers"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Jobs and Workers","showPageActions":true},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Jobs are created as \"unassigned\" by default and are queued in the vWork client ready for the dispatcher to assign to a time and worker."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Alternatively, you can pre-assign the job to a worker by setting the worker_id and planned_start_at values. (If you do not supply a planned start at, but do specify a worker, the job will be assigned to the worker straight away.)"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"To create a job with a worker that should be started immediately, you can send either worker_id, worker_name, or worker_third_party_id as per the following examples:"},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"<worker_id>4016</worker_id>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"<worker_id>4016</worker_id>\n"},"children":[]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"<worker_third_party_id>steverino</worker_third_party_id>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"<worker_third_party_id>steverino</worker_third_party_id>\n"},"children":[]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"<worker_name>Truck 09</worker_name>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"<worker_name>Truck 09</worker_name>\n"},"children":[]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"If you wish to assign the job to a worker now, but have the job scheduled for a future time, you need to also include the planned_start_at as per the example below:"},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"<worker_name>Truck 09</worker_name>\n<planned_start_at>2019-12-22T10:15:00+13:00</planned_start_at>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"<worker_name>Truck 09</worker_name>\n<planned_start_at>2019-12-22T10:15:00+13:00</planned_start_at>\n"},"children":[]}]}]}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"feedback","pageSlug":"/jobs-and-workers"}],"panels":[]}]}},{"type":"group","label":"Jobs and Broadcast Workers","link":"/v5-templated-jobs/jobs-and-broadcast-workers","routeSlug":"/v5-templated-jobs/jobs-and-broadcast-workers","items":[],"content":{"contentType":"group","meta":{"name":"Jobs and Broadcast Workers"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Jobs and Broadcast Workers","showPageActions":true},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"If you are using vWork's broadcast dispatch functionality, you can assign jobs to multiple workers and whoever accepts the job first gets the job.  It is then automatically removed from the other workers schedules."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"If this feature is enabled in your account, you can send the job to multiple workers, like so:"},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"<worker_id>4016,13045,604</worker_id>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"<worker_id>4016,13045,604</worker_id>\n"},"children":[]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"You can also use worker_third_party_id, worker_name and planned_start_at as per the worker examples above."},"children":[]}]}]}]}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"feedback","pageSlug":"/jobs-and-broadcast-workers"}],"panels":[]}]}},{"type":"group","label":"Jobs and Multiple Workers","link":"/v5-templated-jobs/jobs-and-multiple-workers","routeSlug":"/v5-templated-jobs/jobs-and-multiple-workers","items":[],"content":{"contentType":"group","meta":{"name":"Jobs and Multiple Workers"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Jobs and Multiple Workers","showPageActions":true},{"nodeType":"markdoc","content":"vWork also has the ability to assign multiple workers to a job.  In this scenario, there is a master worker responsible for all the custom fields and subworkers get read only copies of the job and the ability to record their start and finish times.\n\nWhilst this is not fully supported by the API at this stage, you can create a job with this functionality enabled and add the master worker.  Dispatchers then have the ability to add sub workers as needed.\n\nTo use this functionality, ensure that it has been enabled on your account and then tick the box for \"Allow Additional Workers\" on the template itself.\n\nYou can then simply create a job using that template name."}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"feedback","pageSlug":"/jobs-and-multiple-workers"}],"panels":[]}]}},{"type":"group","label":"Jobs and Status","link":"/v5-templated-jobs/jobs-and-status","routeSlug":"/v5-templated-jobs/jobs-and-status","items":[],"content":{"contentType":"group","meta":{"name":"Jobs and Status"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Jobs and Status","showPageActions":true},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"There are 11 job statuses in vWork. You may include a status when creating a job if you wish, but this is optional."},"children":[]}]}]},{"$$mdtype":"Node","type":"table","attributes":{},"children":[{"$$mdtype":"Node","type":"thead","attributes":{},"children":[{"$$mdtype":"Node","type":"tr","attributes":{},"children":[{"$$mdtype":"Node","type":"th","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Name"},"children":[]}]}]},{"$$mdtype":"Node","type":"th","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Description"},"children":[]}]}]}]}]},{"$$mdtype":"Node","type":"tbody","attributes":{},"children":[{"$$mdtype":"Node","type":"tr","attributes":{},"children":[{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"draft"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Draft jobs are visible to dispatchers and can be scheduled, but will not be shown to workers until they are undrafted."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"tr","attributes":{},"children":[{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"unassigned"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Jobs with no worker assigned yet."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"tr","attributes":{},"children":[{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"unpublished"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Jobs dragged to a worker's time slot on the schedule, but not sent out to the worker yet."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"tr","attributes":{},"children":[{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"pending"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"If accept/decline is enabled, a job that has been given to a worker and they have not yet accepted or declined it yet."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"tr","attributes":{},"children":[{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"declined"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"If accept/decline is enabled, a job declined by the worker."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"tr","attributes":{},"children":[{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"assigned"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"If accept/decline is enabled, a job accepted by the worker (or if accept/decline is not enabled, simply a job assigned to a worker)."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"tr","attributes":{},"children":[{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"started"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"The worker has completed at least one job step."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"tr","attributes":{},"children":[{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"paused"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"The job has been paused, it's been started, but has not yet been completed. (Pause time is not included in the worker job duration.)"},"children":[]}]}]}]},{"$$mdtype":"Node","type":"tr","attributes":{},"children":[{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"postponed"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"The customer has postponed the job to a later date. This date needs to be confirmed by a dispatcher."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"tr","attributes":{},"children":[{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"canceled"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"The job has been canceled, it will be removed from the worker's schedule automatically."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"tr","attributes":{},"children":[{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"completed"},"children":[]}]}]},{"$$mdtype":"Node","type":"td","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"All steps on the job have been completed."},"children":[]}]}]}]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"In theory, you can set any of these via the API, however there are some restrictions, including:"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"For a job to be assigned, started, or completed, it must have a worker."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"For a job to be started, it must have a worker, and at least one completed step."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"For a job to be completed all steps must be completed."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"For a job to be unassigned, it may not have a worker, etc.."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"To set a status, you can include the following XML in a job:"},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"  <status>canceled</status>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"  <status>canceled</status>\n"},"children":[]}]}]}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"feedback","pageSlug":"/jobs-and-status"}],"panels":[]}]}},{"type":"group","label":"Jobs and Duration","link":"/v5-templated-jobs/jobs-and-duration","routeSlug":"/v5-templated-jobs/jobs-and-duration","items":[],"content":{"contentType":"group","meta":{"name":"Jobs and Duration"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Jobs and Duration","showPageActions":true},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"You can set a planned_duration (in seconds) when you create the job."},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"<planned_duration>7200</planned_duration>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"<planned_duration>7200</planned_duration>\n"},"children":[]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"If you do not set a duration, one will be inherited from the template."},"children":[]}]}]}]}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"feedback","pageSlug":"/jobs-and-duration"}],"panels":[]}]}},{"type":"group","label":"Jobs and Equipment","link":"/v5-templated-jobs/jobs-and-equipment","routeSlug":"/v5-templated-jobs/jobs-and-equipment","items":[],"content":{"contentType":"group","meta":{"name":"Jobs and Equipment"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Jobs and Equipment","showPageActions":true},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Equipment is an optional feature that allows dispatchers to schedule both mobile workers and equipment required for jobs."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"For example, you may need to schedule Bob, the Forklift, Truck 23 and Trailer 15 for a specific job."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Once this feature is enabled and your equipment has been setup, you can add an array of equipment to a job, like so:"},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"<equipments type=\"array\">\n    <equipment>\n        <id>9267</id>\n    </equipment>\n    <equipment>\n        <id>9266</id>\n    </equipment>\n</equipments>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"<equipments type=\"array\">\n    <equipment>\n        <id>9267</id>\n    </equipment>\n    <equipment>\n        <id>9266</id>\n    </equipment>\n</equipments>\n"},"children":[]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"You can also add empty equipment slots to a job to indicate to a dispatcher that equipment is expected for a job:"},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"<equipments type=\"array\"> \n    <equipment> \n        <id>9267</id> \n    </equipment>\n    <equipment>\n        <id></id> \n    </equipment> \n</equipments>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"<equipments type=\"array\"> \n    <equipment> \n        <id>9267</id> \n    </equipment>\n    <equipment>\n        <id></id> \n    </equipment> \n</equipments>\n"},"children":[]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"You can retrieve a complete list of equipment in your account using the equipment API route."},"children":[]}]}]}]}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"feedback","pageSlug":"/jobs-and-equipment"}],"panels":[]}]}},{"type":"group","label":"Jobs and Assets","link":"/v5-templated-jobs/jobs-and-assets","routeSlug":"/v5-templated-jobs/jobs-and-assets","items":[],"content":{"contentType":"group","meta":{"name":"Jobs and Assets"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Jobs and Assets","showPageActions":true},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Assets is an optional feature that allows you to maintain a database of customer owned assets and information associated with them."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"If an asset is added to the template, jobs created from that template will inherit that asset, or you can add an asset to a job using either the asset ID, asset name, or the asset third party ID, like so:"},"children":[]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"<asset_id>1234</asset_id>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"<asset_id>1234</asset_id>\n"},"children":[]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"<asset_third_party_id>8336</asset_third_party_id>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"<asset_third_party_id>8336</asset_third_party_id>\n"},"children":[]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"<asset>\n<name>St James Rose Garden</name>\n</asset>\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"<asset>\n<name>St James Rose Garden</name>\n</asset>\n"},"children":[]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"And if your template has been configured to use the asset's address for one of the steps, we will automatically populate the step address for you."},"children":[]}]}]}]}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"feedback","pageSlug":"/jobs-and-assets"}],"panels":[]}]}},{"type":"group","label":"Jobs and Custom Labels","link":"/v5-templated-jobs/jobs-and-custom-labels","routeSlug":"/v5-templated-jobs/jobs-and-custom-labels","items":[],"content":{"contentType":"group","meta":{"name":"Jobs and Custom Labels"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Jobs and Custom Labels","showPageActions":true},{"nodeType":"markdoc","content":"It is possible to set custom labels for jobs in the template editor. These replace the default job labels of customer name, template name and job ID.\n\nYou can set up to three different custom labels for dispatcher views and another three for mobile worker views.\n\nYou do not need to do anything special as the custom labels will be inherited from the template."}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"feedback","pageSlug":"/jobs-and-custom-labels"}],"panels":[]}]}}],"store":{"schemaStore":{"schema_62":{"kind":"json-schema","data":{"type":"string"},"id":"schema_62"},"schema_63":{"kind":"json-schema","data":{"type":"string","enum":["gzip"]},"id":"schema_63"},"schema_64":{"kind":"json-schema","data":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Raw XML payload — see the example."},"children":[]}]}]}]},"id":"schema_64"},"schema_65":{"kind":"json-schema","data":{"type":"object","properties":{"Status":{"type":"string","example":"200 OK"},"Cache-Control":{"type":"string","example":"max-age=0, private, must-revalidate"},"Content-Encoding":{"type":"string","example":"gzip"}}},"id":"schema_65"}},"exampleStore":{"paths/~1v5~1jobs~1clone.xml/post/requestBody/content/application~1xml; charset=utf-8/examples/request":{"value":"<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<job>\n    <template_name>Sample Template</template_name>\n</job>","key":"request","summary":"request","id":"paths/~1v5~1jobs~1clone.xml/post/requestBody/content/application~1xml; charset=utf-8/examples/request"},"paths/~1v5~1jobs~1clone.xml/post/responses/200/content/application~1xml; charset=utf-8/examples/response":{"value":"<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<job>\n<id readonly=\"readonly\">26780729</id>\n<job_type readonly=\"readonly\">job</job_type>\n<status>unassigned</status>\n<third_party_id></third_party_id>\n<customer_name></customer_name>\n<template_name>Sample Template</template_name>\n<customer_id></customer_id>\n<customer_third_party_id></customer_third_party_id>\n<worker_id></worker_id>\n<worker_third_party_id></worker_third_party_id>\n<worker_name></worker_name>\n<worker_duration>0</worker_duration>\n<published_at type=\"datetime\"></published_at>\n<published_by readonly=\"readonly\"></published_by>\n<has_pod readonly=\"readonly\">false</has_pod>\n<signed_at readonly=\"readonly\"></signed_at>\n<signed_by readonly=\"readonly\"></signed_by>\n<paused_at></paused_at>\n<planned_duration>10800</planned_duration>\n<planned_start_at type=\"datetime\"></planned_start_at>\n<planned_end_at type=\"datetime\" readonly=\"readonly\"></planned_end_at>\n<actual_start_at type=\"datetime\" readonly=\"readonly\"></actual_start_at>\n<actual_duration readonly=\"readonly\"></actual_duration>\n<alarm_at type=\"datetime\"></alarm_at>\n<requested_at type=\"datetime\"></requested_at>\n<code></code>\n<notes type=\"array\">\n</notes>\n<steps type=\"array\">\n    <step>\n        <id readonly=\"readonly\">80220109</id>\n        <name>Start</name>\n        <completed_at type=\"datetime\"></completed_at>\n        <created_at type=\"datetime\" readonly=\"readonly\">2021-02-16T03:02:53+00:00</created_at>\n        <updated_at type=\"datetime\" readonly=\"readonly\">2021-02-16T03:02:53+00:00</updated_at>\n    </step>\n    <step>\n        <id readonly=\"readonly\">80220110</id>\n        <name>Onsite</name>\n        <completed_at type=\"datetime\"></completed_at>\n        <created_at type=\"datetime\" readonly=\"readonly\">2021-02-16T03:02:53+00:00</created_at>\n        <updated_at type=\"datetime\" readonly=\"readonly\">2021-02-16T03:02:53+00:00</updated_at>\n    </step>\n    <step>\n        <id readonly=\"readonly\">80220111</id>\n        <name>Done</name>\n        <completed_at type=\"datetime\"></completed_at>\n        <created_at type=\"datetime\" readonly=\"readonly\">2021-02-16T03:02:53+00:00</created_at>\n        <updated_at type=\"datetime\" readonly=\"readonly\">2021-02-16T03:02:53+00:00</updated_at>\n    </step>\n</steps>\n<custom_fields type=\"array\">\n    <custom_field>\n        <name>Notes</name>\n        <value></value>\n        <type>text</type>\n        <permission>optional</permission>\n    </custom_field>\n    <custom_field>\n        <name>Photos</name>\n        <value></value>\n    <type>image</type>\n        <permission>optional</permission>\n    </custom_field>\n    <custom_field>\n        <name>Dates</name>\n        <value></value>\n        <type>datetime</type>\n        <permission>optional</permission>\n    </custom_field>\n    <custom_field>\n        <name>Numbers</name>\n        <value></value>\n        <type>number</type>\n        <permission>optional</permission>\n    </custom_field>\n    <custom_field>\n        <name>Links</name>\n        <value></value>\n       <type>link</type>\n        <permission>read_only</permission>\n    </custom_field>\n    <custom_field>\n        <name>Checkboxes</name>\n        <value>0</value>\n        <type>checkbox</type>\n        <permission>optional</permission>\n    </custom_field>\n    <custom_field>\n        <name>Currencies</name>\n        <value></value>\n        <type>currency</type>\n        <permission>optional</permission>\n    </custom_field>\n    <custom_field>\n        <name>Signatures</name>\n        <value>\n            <signature>\n                <signed_by></signed_by>\n                <signed_at type=\"datetime\"></signed_at>\n                 <image></image>\n         </signature>\n        </value>\n        <type>signature</type>\n        <permission>optional</permission>\n    </custom_field>\n</custom_fields>\n<sections type=\"array\">\n    <section>\n        <title>Headers</title>\n        <custom_fields type=\"array\">\n         <custom_field>\n                <name>Pick Lists</name>\n                <value></value>\n                <type>pick_list</type>\n                <pick_list_id>14656</pick_list_id>\n                <permission>optional</permission>\n            </custom_field>\n        </custom_fields>\n    </section>\n</sections>\n<created_at type=\"datetime\" readonly=\"readonly\">2021-02-16T03:02:53+00:00</created_at>\n<created_by readonly=\"readonly\">The API</created_by>\n<updated_at type=\"datetime\" readonly=\"readonly\">2021-02-16T03:02:54+00:00</updated_at>\n</job>\n","key":"response","summary":"response","id":"paths/~1v5~1jobs~1clone.xml/post/responses/200/content/application~1xml; charset=utf-8/examples/response"}},"securitySchemeStore":{"apiKey":{"id":"apiKey","type":"apiKey","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Get your key at https://go.vworkapp.com/html_client/admin/api"},"children":[]}]}]}],"in":"query","paramName":"api_key"}},"servers":[{"url":"https://api.vworkapp.com/api"}],"logo":{"imageUrl":"./assets/vWork-Logo.png","altText":"vWork"}},"options":{"hideReplay":true,"codeSamples":{"languages":[]},"sortRequiredPropsFirst":true,"jsonSamplesExpandLevel":2,"hideDownloadButtons":false,"hideSidebar":true,"mockServer":{"off":true},"disableRouter":true,"downloadUrls":[{"url":"/_bundle/v5-templated-jobs.json?download"},{"url":"/_bundle/v5-templated-jobs.yaml?download"}],"excludeFromSearch":false,"specType":"openapi","markdocOptions":{"tags":{},"nodes":{},"components":{}},"metadata":{"title":"vWork API v5 Templated Jobs - Creation Only (Stable Release)","description":"# Getting Started\n\n***We have broken our API documentation into three parts. The following documentation is for creating jobs from existing vWork templates.***\n\n***If you need full control over your jobs and don't want to reference your templates, then you should use our <a href=\"/v5-jobs.json\">job API documentation</a>.***\n\n***If you need to access something other than jobs, then you should use our <a href=\"/v5.json\">vWork API documentation</a>***\n\n## The Use of Templates\n\nvWork software is centred on the use of templates to manage multiple job types. This makes it easy for website users to create the same job type over and over again.\n\nThe use of templates is not supported via our standard API. You define what a job looks like when you send the job XML to the API.\n\nHowever, the Templated Job API does use the templates saved in your vWork account.  In essence, you supply us with the template name (or the template ID) that you wish to use when creating the job, we will then inherit everything we can from the template; Step names, Custom Field Logic, Custom Labels, Duration, Tags, Time Windows, etc.\n\nThe only other information you may need to supply are any values that you wanted to include on the job creation.  This may include a customer ID, or a customer name, an address for the job, any custom field values you want to supply, or invoice line items that need to appear on the job.\n\nYou are welcome to use the Templated Job API for your initial job creation, and then our standard API for updating, cancelling, downloading or deleting jobs. Our standard API also includes many other non-job related functions such as managing hazards, groups, messages, assets, users, etc..\n\nThe base URL for our API is:  https://api.vworkapp.com/\n\n## What does Stable mean?\n\nStable means that this version is final and is not going to change in the future, even if we add new features to the product.\n\n## What can you build?\n\nvWork’s API allows you to build our dispatching functionality into other software. For example, you can use our API so that our dispatch software works hand-in-hand with your CRM software.\n\nYou can also pull data from vWork’s API to produce a tailored management report.\n\n## Getting your API key\n\nYou need to have a vWork account with the API enabled to obtain an API key.\n\nIf you already have an API enabled vWork account, you can create your own API Key <a href=\"https://go.vworkapp.com/html_client/admin/api\">here on the integrations page</a>.\n\nIf you do not yet have a vWork account, please <a href=\"https://www.vworkapp.com/contact-us\">get in touch</a> with us.\n\n# Need More Help?\n\n## Where to get more help\n\nThere is a list of frequently asked questions on our <a href=\"https://help.vworkapp.com/forums/20898176\">helpdesk</a> page as well as <a href=\"https://help.vworkapp.com/hc/en-us/articles/204087140\">a brief intro to the vWork API</a>. If you get stuck, please don't hesitate to send us an email at: <a href=\"mailto:support@vworkapp.com\">support@vworkapp.com</a>\n\n## Mailing List\n\nDo you want to be emailed when we make a change to the API? You can <a href=\"https://www.vworkapp.com/api_notes\">signup for notifications about the vWork API here</a>. We don't email very often, but we will notify you about any changes, as well as notifications about both planned and unplanned outages.\n\n# Tech Notes\n\n## HTTP Compression\n\nBy default, the vWork API requires users to support gzip HTTP response compression on all requests. This is enabled by setting a 'Accept-Encoding: gzip' header on requests, and properly handling the 'Content-Encoding' header on responses. For more information please see http://en.wikipedia.org/wiki/HTTP_compression.\n\n_Failure to specify HTTP compression may result in requests being rejected with a HTTP response of type 406/Not Acceptable._\n\n## ISO8601 Date and Time Format\n\nWhen providing dates you must supply them in the following ISO8601 format: YYYY-MM-DDTHH:MM:SS.\n\nThe API uses GMT by default. In order for you to use your local time you must also supply a timezone on your ISO8601 date (e.g. 2011-12-25T22:32:07+10).\n\nFinally, you may need to url encode the date string depending on your environment (e.g. 2011-12-25T22%3A32%3A07%2B10)\n\n## Error Codes\n\nHere is an explanation of some of the error codes you may see when developing your integration.\n\n* HTTP 401 (Authorization Required) is returned if you don’t have permission to call this service. Check that your api_key is correct.\n\n* HTTP 404 (Not Found) is returned if the resource requested was not found.\n\n* HTTP 406 (Not Acceptable) is returned if the request did not include headers for http compression.\n\n* HTTP 422 (Unprocessable Entity) is returned if vWork wasn’t able to process the request body, for example when the XML is incorrectly formatted.\n\n* HTTP 429 (Too Many Requests) is returned if vWork is unable to process the number of requests you have sent, please throttle your queries and try again in a minute or two.\n\n* HTTP 500 (Server Error) is returned if a logic error was found, such as a required field is missing.\n\nPlease note, that quite often the reason for a 422 error is included in the body of the XML that is returned to you.  This is often an excellent source of debugging information, here is a sample that says a date time custom field value was not a valid date and time.\n\n```\n<?xml version='1.0' encoding='utf-8' ?>\n<errors>\n    <error>\n        <attribute>custom_fields.custom_field</attribute>\n        <message>&#39;tomorrow night&#39; must be a valid ISO8601 value.</message>\n    </error>\n</errors>\n```\n\n# Webhooks\n\n## What are Webhooks?\n\nFor general information about Webhooks, see http://en.wikipedia.org/wiki/Webhook\n\nTo minimise the requirement for a vWork API consumer to frequently poll the API for updates, vWork can send webhook callbacks to a predetermined endpoint URL when a change is made.\n\nDepending on the information contained in the webhook, the consumer may then choose to perform a GET on that specific resource to retrieve the updated resource.\n\n## What Webhooks are Available?\n\nYou can select to recieve a webhook when any of the following actions occur: Job Created, Job Assigned, Job Unassigned, Job Reassigned, Job Declined, Job Accepted, Job Rescheduled, Job Started, Job Completed, Job Deleted, Job Paused, Job Unpaused, Step Completed, Step Uncompleted, Custom Field Updated, Invoice Updated, User Created, User Updated, User Deleted, Proof of Delivery (POD) Created, and Proof of Delivery Deleted.\n\nNote that if a single action triggers multiple events (for example, creating an assigned job will trigger both a Job Created and a Job Assigned webhook), the order of these events is not guaranteed. But if multiple separate changes happen, those events will be sent in order.\n\nPlease also note, that the Job Reassigned webhook only triggers if the job is reassigned from the jobs tab or the mobile app.  If a job is reassigned by dragging it to a new worker on the schedule, this will result in two webhooks, a Job Unassigned followed by a Job Assigned.\n\n## Setting up Webhooks\n\nYou can configure your webhook endpoint, select the format you prefer (JSON or XML), as well as select what actions should trigger a webhook to be sent, from the admin section of the vWork website: https://go.vworkapp.com/html_client/admin/webhooks\n\nThe callback endpoint will be provided and maintained by the API consumer, and should support SSL/TLS encryption.\n\nGiven the potential for a relatively high volume of callbacks, it is strongly advised that the consumer employ asynchronous background task execution and/or a message queueing pattern for handling incoming Webhook callback events. Platforms such as Delayed Job, Resque and RabbitMQ are some well-known examples of asynchronous processing platforms.\n\n(If you are using our legacy webhooks, turning on the new webhooks will not turn off the old ones. Please email <a href=\"mailto:support@vworkapp.com\">support@vworkapp.com</a> when you are ready for us to turn off the old webhooks. NB: If you update your webhook endpoint on the website, this will update the endpoint for both new and old webhooks.)\n\n## Sample Webhooks\n\nAn example of a Job Created XML webhook is below:\n\n```\n<?xml version=\"1.0\"?>\n<event>\n  <transaction_id>617d4a74-7a19-11e6-bf7a-55542dc9080d</transaction_id>\n  <event_type>job_created</event_type>\n  <event_time>2016-09-14T01:20:10Z</event_time>\n  <resource>Job</resource>\n  <resource_id>9876234</resource_id>\n  <account_id>7829</account_id>\n  <request_user_type>User</request_user_type>\n  <request_user_id>123</request_user_id>\n</event>\n```\n\nAn example of a Job Created JSON webhook is below:\n\n```\n{\n  \"transaction_id\": \"617d4a74-7a19-11e6-bf7a-55542dc9080d\",\n  \"event_type\": \"job_created\",\n  \"event_time\": \"2016-09-14T01:20:10Z\",\n  \"resource\": \"Job\",\n  \"resource_id\": 9876234,\n  \"account_id\": 7829,\n  \"request_user_type\": \"User\",\n  \"request_user_id\": 123\n}\n```\n\nAn example of a Step Completed XML webhook is below:\n\n```\n<?xml version=\"1.0\"?>\n<event>\n  <transaction_id>63d75660-7a1a-11e6-8d5a-474090628a07</transaction_id>\n  <event_type>step_completed</event_type>\n  <event_time>2016-09-14T01:27:24Z</event_time>\n  <resource>Step</resource>\n  <resource_id>25062292</resource_id>\n  <account_id>8723</account_id>\n  <request_user_type>User</request_user_type>\n  <request_user_id>123</request_user_id>\n  <event_location>\n    <lat>-36.86524165519692</lat>\n    <lng>174.7806050757642</lng>\n  </event_location>\n  <data>\n    <step_name>Start Job</step_name>\n    <completed_at>2016-09-15T02:00:12Z</completed_at>\n    <job_id>8626773</job_id>\n  </data>\n</event>\n```\n\nAn example of a Step Completed JSON webhook is below:\n\n```\n{\n  \"transaction_id\": \"63d75660-7a1a-11e6-8d5a-474090628a07\",\n  \"event_type\": \"step_completed\",\n  \"event_time\": \"2016-09-14T01:27:24Z\",\n  \"resource\": \"Step\",\n  \"resource_id\": 25062292,\n  \"account_id\": 8723,\n  \"request_user_type\": \"User\",\n  \"request_user_id\": 123,\n  \"event_location\": {\n    \"lat\": -36.86525719794106,\n    \"lng\": 174.780580958473\n  },\n  \"data\": {\n    \"step_name\": \"Start Job\",\n    \"completed_at\": \"2016-09-15T02:58:31Z\",\n    \"job_id\": 8621412\n  }\n}\n```\n\n## Webhook Content\n\nWebhooks will always contain the following fields:\n\n* transaction_id - an internal vwork audit ID, can be ignored\n\n* event_type - the action that triggered the webhook\n\n* event_time - the time the server recieved the event, this may not be the time of the event (in UTC)\n\n* resource - the resource that was updated: job, custom field, proof of delivery, step or user.\n\n* resource_id - the vWork ID for the resource that was updated.\n\n* account_id - the ID of your vWork account (can be useful if you are recieving webhooks for multiple accounts.)\n\nIn addition, some webhooks may contain these extra fields:\n\n* request_user_type - Who triggered the action: a user, or a customer portal user. Will not be present for API events or automatic events (like an auto decline event).\n\n* request_user_id - The ID of the user who triggered the action. Will not be present for API events or automatic events (like an auto decline event).\n\n* resource_third_party_id - The 3rd Party ID for the resource that was updated. Only present when a 3rd Party ID exists.\n\n* data_worker_id - The ID of the worker the job is assigned to. Present on Job Accepted, Job Assigned and Job Reassigned Webhooks.\n\n* data_worker_name - The name of the worker the job is assigned to. Present on Job Accepted, Job Assigned and Job Reassigned Webhooks.\n\n* data_field_label - The label of the custom field that was updated. Only present on Custom Field Updated webhooks.\n\n* data_field_value - The new value of the custom field that was updated. Only present on Custom Field Updated webhooks.\n\n* data_field_type - The type of the custom field that was updated. Only present on Custom Field Updated webhooks.\n\n* event_location_lat - the lattitude of the worker's location when they completed the action. Only present on Step Completed, Step Uncompleted, Job Start and Job Complete when a location is available.\n\n* event_location_long - the longitude of the worker's location when they completed the action. Only present on Step Completed, Step Uncompleted, Job Start and Job Complete when a location is available.\n\n* data_step_name - The name of the step that was updated. Only present on Step Completed and Step Uncompleted webhooks.\n\n* data_completed_at - The time when the step was completed (in UTC). Only present on Step Completed webhook.\n\n* data_job_id - The job that the POD, step, or custom field is for. Only present on POD Created, POD Deleted, Custom Field Updated, Step Completed, and Step Uncompleted webhooks.\n\n* data_paused_at - The time when the job was paused (in UTC). Only present on Job Paused webhooks.\n\n* data_unpaused_at - The time when the job was unpaused (in UTC). Only present on Job Unpaused webhooks.\n\n* data_signed_at - When the POD was signed. Only present on POD Created and Deleted webhooks.\n\n* data_signed_by - Who Signed the POD. Only present on POD Created and Deleted webhooks.\n\n* data_name - The name of the user. Only present on User Created and User Updated webhooks.\n\n* data_email - The email address of the user. Only present on User Created and User Updated webhooks.\n\n* data_phone - The phone number of the user. Only present on User Created and User Updated webhooks.\n\n* data_notes - Any notes saved against the user. Only present on User Created and User Updated webhooks.\n\n## Webhook Reliability and Monitoring\n\nThe vWork Webhook notifier will expect a HTTP/200 status code in the HTTP response from the callback endpoint provided by the API consumer. If a non-200 response is received, or the endpoint cannot be reached, vWork will discard the callback event.\n\nCallbacks will always be sent in the order they were created; in the event of a single callback failure as described above, the failing callback will be discarded, but the Webhook notifier will attempt to send all subsequent callbacks in the normal manner.\n\nVarious factors could cause a callback to be discarded, such as an internet connection dropout or a momentary server problem. vWork recommends that the API consumer implement a low-frequency polling mechanism (e.g. hourly or daily) to “fill in” any data which may have been missed as a result of a discarded callback.\n\n## Security Layer - HMAC SHA\n\nWe implement a layer of security which is simple to consume. Using your api key and a \"signature\" that is calculated and sent with the Webhook, you can verify the contents of a Webhook as being authentic and un-tampered.\n\nWebhooks are signed with a signature generated by taking an HMAC-SHA-256 hex digest of the raw HTTP Body of the Webhook post, using your api key as the secret.\n\nThis signature will be sent with the Webhook post in the header X-Vwork-Webhook-Signature-Hmac-Sha-256. If you chose not to implement this measure, you can just ignore the header.\n\nAs an example, the HMAC signature is generated in Ruby with this code:\n\n```\nOpenSSL::HMAC.hexdigest(OpenSSL::Digest::Digest.new('sha256'), api_key, webhook.body)\n```\n\nIf your api key is 123 and the Webhook request body contents are:\n\n```\n<job><name>test</name></job>\n```\n\nusing code like this:\n\n```\nOpenSSL::HMAC.hexdigest(OpenSSL::Digest::Digest.new('sha256'), '123', '<job><name>test</name></job>')\n```\n\nthe signature for this Webhook would be:\n\n```\n7643b9dbcab60ae6ae32e5683e1fae1db105bd31f1f0b5d51e5b773235359ff0\n```\n\nPlease note, that when calculating the HMAC SHA we strip out all line breaks and whitespace from the body of the webhook, in order for you to get the same result, you will need to do the same.\n\nAlso the webhook body should be ASCII encoded.\n\n# Postman\n\n## What is Postman?\n\nPostman is an API development and testing tool. We encourage our customers to use Postman as a way of quickly learning the capabilities of the vWork API. vWork support staff can often provide sample Postman collections or Postman friendly XML samples to assist you.\n\nYou can download a copy from here: https://www.getpostman.com/"}},"baseSlug":"/v5-templated-jobs","routesMapping":{}}