Creating a job template using the Okappy API
Okappy is a connected field service management platform where you can connect to your customers, employees and subcontractors, create jobs and assign those jobs to the right person or company.
This guide shows how to create a new job template using the Okappy API. A job template controls the job sheet used when creating jobs, including the job type name, fields shown on the job and options such as signature, payment and alert settings.
Authentication
First you will need to get an up to date authentication token. For further information see authenticating with Okappy.
Creating a job template
To create a job template, send a POST request to the job templates endpoint.
POST /jobs/templates
The full URL is:
https://api.okappy.com/rest/v2/jobs/templates
Headers
| Header | Content |
|---|---|
| Authorization | Bearer token |
| Content-Type | application/json |
The token should be the string from the access_token field returned by an authentication request.
Example request
Body data
The body data should contain a JSON object. The main field is customTemplate, which contains the template definition. The API requires customTemplate.jobSheet and customTemplate.jobSheet.name.
The example below creates a template called Drainage callout with two simple fields.
Some integrations serialize the template as a JSON string. The API also accepts that shape because the server parses the customTemplate value before creating the template.
Fields
The request is made up of the following fields.
customTemplate – required
The job template definition. This should include a jobSheet object. The API accepts this either as a JSON object or as a JSON string.
jobSheet.name – required
The name of the job template. This is the job type name shown in Okappy. Long names are shortened by the server when saved.
jobSheet.groups
The groups and fields shown on the job sheet. Use the same structure returned by the template builder or the retrieve templates endpoint.
jobSheet.options
Optional template settings such as signature, payment, alert timings and whether on-site or completed times are shown.
customChecksheet
Set this to 0 for a normal job template. Other values are used internally for custom checksheet modes.
style / Style
Optional custom CSS or style content for the template.
js / JS
Optional custom JavaScript content for the template.
Template options
The following options can be supplied inside customTemplate.jobSheet.options. If an option is omitted, Okappy uses the default shown in brackets.
signature_mandatory (false) – whether a signature is mandatory.
payment_required (false) – whether payment is required for jobs using the template.
job_duration (60) – default job duration in minutes.
alert_if_not_viewed (60) – first alert timing if the job has not been viewed, in minutes.
second_alert_if_not_viewed (120) – second alert timing if the job has not been viewed, in minutes.
alert_if_not_on_site (60) – first alert timing if the job has not moved on site, in minutes.
second_alert_if_not_on_site (120) – second alert timing if the job has not moved on site, in minutes.
alert_if_not_completed (1440) – alert timing if the job has not been completed, in minutes.
show_on_site_time (false) – whether to show the on-site time.
show_completed_time (false) – whether to show the completed time.
link_from_invoice (false) – whether jobs using this template can be linked from invoices.
message (blank) – optional message for the template.
messageOnDay (blank) – optional message shown on the day.
images_mandatory (false) – whether images are mandatory.
Responses
200 – operation successful. The response includes the new jobTypeId.
400 – bad request, such as no template in the request or no job template name.
401 – unauthorised.
415 – data sent in the wrong format. Send JSON with Content-Type: application/json.
429 – too many requests in a short period of time. Please try again later.
500 – the server could not create the template.
Success response
Error response
Using the new template
When the request succeeds, Okappy returns the new jobTypeId. Use that ID as the job type when creating jobs with the API. You can also retrieve your templates again using Retrieving job templates to confirm the template is available.
Designing the job sheet from an example
When a template is based on a PDF or another form, use the example to identify the headings, fields, tables, answer choices, header and footer. Keep the job details section for the small amount of information needed when the office creates the job. Put the engineer’s inspection questions and answers in the Work done checksheet. Do not duplicate standard job information such as the Job ID, appointment date or assigned engineer.
Map a field to an Okappy data column only after confirming the available column name and what it contains in the template builder or a retrieved template. For example, use Address1 for the premises address when that is the correct site-address column. Confirm the mapping on a test job so the value appears in the intended field.
Add the document’s header and footer using the template’s header and footer areas. Header images are displayed at their supplied size, so resize the logo image to the intended dimensions before adding it. Keep the logo, company details and report title in separate, sensibly sized elements to avoid overlap.
Use the template’s style field for CSS. First inspect the generated job sheet and target only the elements you need to change. Use narrowly scoped selectors for the report headings, fields and answer boxes; avoid broad rules or fixed positioning that can move the job summary, enlarge the header or break the field layout. Make one small change at a time and check the rendered sheet after each version. API success confirms the template was saved, not that the styling matches.