Skip to main content
Quote Templates & Forms

Quote Template Development

The information below details the steps required to build or modify a quote template using the recommended method and settings.

⚠️ Catch-e Use Only

This section is intended for Catch-e administrators and developers maintaining quote templates.

Setup

  1. Download and install Visual Studio Code.

  2. Install the Live Preview extension published by Microsoft.

Build or Modify Quote Template

  1. Navigate to Setup β†’ Import or Export Files in Catch-e.

  2. Export the quote_novate.zip file, selecting:

    • Platform: Catch-e

    • File Type: Quote Template

  3. Extract the ZIP file to a local folder.

  4. Open the extracted folder in Visual Studio Code.

  5. Open the HTML file and select Show Preview.

  6. Append ?quote_id= to the preview URL to display a quote.

  7. Open Developer Tools to inspect available placeholders and values.

  8. Use Ctrl + F to search for placeholders.

  9. Expand additional placeholders using the (...) option if required.

πŸ’‘ Tip: Use Developer Tools to identify and copy available placeholders directly into the quote template.

Quote Template Placeholders

Quote data is delivered into PDF quotes using the HTML zip, the getQuote API and Web Quotes using placeholders from a library.

Placeholder Libraries

There are two placeholder libraries in use in the system. The standard and recommended quote library is 'quote' and we also have an older library called 'quotespackagingall'.

quote β€” 'quote' is the standard and recommended library. This has been designed to work with HTML.zip templates. The getQuote spreadsheet contains a list of the placeholders that are available if you are using this library.

quotes_packaging_all β€” 'quotespackagingall' is an older library that may be in use by long-standing clients. You can use this library with HTML.zip templates by updating some system settings. Visit Switching existing quotes to HTML to see how you can use your existing placeholder library in HTML.zip templates. Client-specific placeholder libraries can be added to work in conjunction with this library. For example, if you want to use Lease Inclusion Plans in your quotes and you are using this library, the required placeholders can be linked. See the GetQuote quote_inclusion_plans library spreadsheet for the list of available placeholders and contact your Account Manager to arrange a client-specific task to do this.

Determining Your Placeholder Library

  • If you run the web service getQuoteFieldsWebService, the returned fields will match the getQuote spreadsheet if your quote library is 'quote'.

  • If it does not match, you must be using 'quotes_packaging_all'.

Settings

There are some key Global Controls used to determine the calculations used in quote templates:

derived_field_library_for_quote_packaging (qt) β€” When set to 'quote' the placeholders on the quote form will come from the 'quote' library. Note: If your quotes are created using the 'quotes_packaging_all' library, test the use of 'quote' here thoroughly as values used may not match. Default: quote

total_lease_per_paycyclegstcalc_flag (qt) β€” If this is 'yes', the placeholder {totalleaseperpaycyclegst} is calculated from SUM(qt_quote_budgets.amount_net). This makes the "Total GST" exactly 10% of the quotes "Total Net". If this is 'no', the placeholder {totalleaseperpaycyclegst} is calculated from SUM(qt_quote_budgets.amount_gst). This makes the GST the sum of each budgets' GST component. It is recommended when using this control with html based quote templates that the control be set to 'no' in order to avoid a mismatch between {total_lease_monthly_gst} and {total_lease_per_pay_cycle_gst} where the pay cycle is also monthly and these two placeholders are used in the quote template. Default: yes

payg_tax_calcs_flag (qt) β€” This control is applied only when the derived_field_library_for_quote_packaging is set to "quote" (used for html based quote templates). Setting to 'yes' applies ATO coefficients, scales and rounds up PAYG calculations. Catch-e recommends using this setting ('yes'), because it matches with ATO practice. Setting to 'no' defaults to the existing calculations that provide an "absolute" number including cents. This setting cascades across all placeholder calculations that are dependent in some way on the tax calculation. Default: no

html_2pdf_service_login (gb) β€” A web services user must be created 'web_quotes'. The password used for that user must match the password stored in this Global Control. The password stored here in encrypted and can only be updated by Catch-e staff. Contact your Account Manager for assistance. Type: encrypted

html_quote_use_type2_benefit_flag (qt) β€” Where this is 'yes', the placeholder {packagedbalancegrossupperpaycycle} will be used to show FBT Type 2 Benefit calculations where the Client FBT Type is a Concessional value, if used in the quote template. Default: no

Bespoke Fields

Where the Catch-e 'quotespackagingall' and 'quote' libraries are used, bespoke fields in Quotes and Clients are also returned in data sets generated from the API getQuoteFieldsWebService.

Bespoke fields elements are identified in get_Quote calls using prefixes gb_befv_fm_clients and gb_befv_qt_quotes.

As an example the bespoke field registration_number taken from the Quotes / Other tab would look like this: gb_befv_qt_quotes_registration_number.

Insurance Placeholders

The 'quote' library supplies the following insurance and declaration placeholders. They are available to every HTML quote template built on the 'quote' library, including templates that extend it, and are returned by getQuoteFieldsWebService. They are not available in the 'quotespackagingall' library.

Placeholder

Returns

Notes

insurance_type_name

The name of the quote's insurance type, as shown in the Ins Type field.

Returned even if the insurance type is no longer active. Empty if no insurance type is chosen.

insurance_type_code

The code of the quote's insurance type.

As insurance_type_name.

insurance_claim_excess

The claim excess held on the quote's insurance details.

insurance_premium_monthly

The monthly insurance premium, excluding GST.

One twelfth of the quote's annual insurance figure (Annual Ins), less the monthly levy, stamp duty and broker fee. Rounded to the nearest cent. Empty if the result would be below zero.

insurance_levy_monthly

The monthly emergency services levy held on the quote's insurance details.

insurance_stamp_duty_monthly

The monthly stamp duty held on the quote's insurance details.

insurance_gst_monthly

The GST charged on the quote's insurance, as the quote holds it.

insurance_broker_fee_monthly

The monthly insurance broker fee held on the quote's insurance details.

Separate from the existing quote-level broker_fee placeholder, which is unchanged.

insurance_at_fault_flag

yes if "At fault incidents?" is ticked on the quote, otherwise no.

Always returned.

insurance_conviction_flag

yes if "DUI/PCA Conviction?" is ticked on the quote, otherwise no.

Always returned.

  • Where the quote has no insurance, or Comprehensive Insurance is not selected, the eight insurance placeholders are empty. The two declaration placeholders still return yes or no.

  • A held amount of zero is returned as zero, not empty.

  • Levy, stamp duty, GST and broker fee report what the quote holds. They are not recalculated, and no default amount is applied, including where the insurance amount has been typed or locked.

  • Values are unformatted. The template controls presentation, such as currency symbols and number format.

  • Where the first year of insurance is funded, or deferred months make the monthly insurance line higher than one twelfth of the annual figure, the premium, levy, stamp duty, GST and broker fee will not add up to the monthly insurance line.

Channels

Where the Client selected is linked to a channel and the channel has its own quote template, the calculations will be based on the channel quote template.

Historical Libraries

For clients migrating from a Catch-e developed Quote Template who wish to continue to use the same field library from their current Catch-e developed Quote Template, an additional parameter "parent_report" can be passed in the JSON file as follows. Place this parameter under the "page_format" parameter:

{ "login": "web_quote", "password": "ADD_YOUR_PASSWORD_HERE", "service": { "host": "https://your_name.catch-e.net.au", "method": "qt/quotes/getQuote", "arguments": { "output_mode": "fields" } }, "template_element": "quote", "page_format": "A4", "parent_report": "/clients/your_name/core/fleet/administration/quotes/templates/pdf_quote_nofb_lease.phpo", "page_orientation": "portrait", "page_margin": "0cm" } 

Form Process

  1. Go to Setup / Import or Export Files and Export the current form.

  2. Each form has a different set of placeholders, so print the field list to see what's available for this one.

  3. Use these details to create the layout of the document you want, save this file.

  4. Go to Setup / Import or Export Files and upload your new form.


Form Troubleshooting

Tip: Visit the main Troubleshooting page for a list of all the available problem-solving tips.

My Dates Present as 'YYYY-MM-DD'

Some of our older forms show dates in the database format.

If you want to present dates as 'DD/MM/YYYY' in excel, you can set-up a cell reference to do this.

A1

B1

C1

{start_date}

=VALUE(A1)

=B1

2021-06-01

44348

01/07/2021

I Uploaded a Form But It Has Not Updated in the System

The Catch-e system is hosted on multiple servers. It can take time for forms you have imported in Setup / Import or Export Files to populate through to all the servers.

If you have tried to use the form and still get the old version, please wait an hour and check again. If it is still not working, please contact Catch-e Support.

Docx Files

{placeholders} sometimes don't work in a docx file if it has been marked by the spellchecker. Review and 'ignore' or 'add' the word, then save before uploading.

Alternatively, go to File > Options > Proofing and un-check the last two checkboxes for Spelling and Grammar error checks.

If this does not work, you may find that extensive formatting in word has disrupted the placeholders that have been added. This can be fixed, but requires a few steps:

  1. Save the file down and rename it to sample.zip by direct-editing the suffix (let's call the form sample.docx for this example).

  2. Open the sample.zip folder and go to the word folder within.

  3. Find the file document.xml and save it somewhere else.

  4. Open document.xml in notepad and search for placeholders that don't work. Search on part of the placeholder only. E.g. for {driver_name}, search to find 'driver'. You can see there is a lot of weird formatting like this:

<w:t>{</w:t></w:r><w:r w:rsidR="00A25BD4" w:rsidRPr="00A25BD4"><w:rPr><w:sz w:val="18"/></w:rPr><w:t>driver_name</w:t></w:r><w:r w:rsidR="00A25BD4"><w:rPr><w:sz w:val="18"/></w:rPr><w:t>}</w:t> 

Remove this and replace with:

<w:t>{driver_name}</w:t> 
  1. Go back to sample.zip and delete the original document.xml file.

  2. Paste in the new document.xml file that you have just edited.

  3. Rename sample.zip back to sample.docx.

  4. Open and check that sample.docx looks OK and then import the form.


Render Quote PDF

This API replicates the system function of printing a quote in PDF format. Use this API to aid quote template development.

To return quote placeholders, use the getQuoteFieldsWebService API.

Permissions

To run this API, the nominated 'web-services' role needs to be given permission. If you are not actively using the API, leave the permission off for better security.

Go to Roles / Apis and check on WebServices and Quotes:RenderPDF.

Note: This API is not configured for external use. Contact your Account Manager to discuss access to this API.

Authentication

Authenticate with the API before running this API.

HTTP Method

Use the HTTP Method 'POST' for consuming this web service.

URL Examples

https://api.test.catch-e.com/qt/quotes/{quote_id}/render-pdf 

Parameters - Path

Key

Format

Notes

Default Value Mandatory

quote_id

string

Quote to print.

Yes

Headers

Key

Format

Notes

Default Value Mandatory

Time-Zone

string

No

Response Details

Status

Response

Comments

201 Success

The request was successful. Quote PDF will be returned.

401 Unauthorized

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unauthorized", "status": 401, "detail": "Unauthorized"}

You have not authenticated before running this API or The token_timeout of the current session has passed. You need to authenticate again.

403 Forbidden

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Forbidden", "status": 403, "detail": "Forbidden"}

You do not have permissions for this request. Go to System Roles and enter 'web_services'. Navigate to the Roles / APIs tab to make sure the permission you need to run this API is checked.

422 Unprocessable Entity

{ "validationMessages": { "quote_id": { "noRecordFound": "no record matching the input was found"}} }

The record for the quote_id you have used does not exist or is inactive. Check your API details and update the quote_id KEY.

422 Unprocessable Entity

{ "validationMessages": { "quote_id": { "requiredPermission": "The user associated with the gb::html2pdf_service_login credential is missing the WebServices API permission"}} }

Your role as the authenticated user must have the WebServices and Quotes:RenderPDF permissions enabled, but additionally the html2pdfservice_login user must also have those permissions enabled. Go to Roles / APIs and enable the required permissions.


Render Quote PDF with Template

This API replicates the system function of printing a quote. This API is typically used to aid quote template development.

Permissions

To run this API, the nominated 'web-services' role needs to be given permission. If you are not actively using the API, leave the permission off for better security.

Go to Roles / Apis and check on Quotes:RenderPDF and Quotes:TemplateDeveloper.

Note: This API is not configured for external use. Contact your Account Manager to discuss access to this API.

Authentication

Authenticate with the API before running this API.

HTTP Method

Use the HTTP Method 'POST' for consuming this web service.

URL Examples

https://api.test.catch-e.com/qt/quotes/{quote_id}/render-pdf-with-template 

Parameters - Path

Key

Format

Notes

Default Value Mandatory

quote_id

string

Quote to print.

Yes

Headers

Key

Format

Notes

Default Value Mandatory

Time-Zone

string

No

Body - Form-Data

Key

Format

Notes

Default Value Mandatory

template

file

Quote template to render. This is useful for development purposes. This should be a zip archive containing the quote template files.

Yes

Response Details

Status

Response

Comments

201 Success

The request was successful. Quote PDF will be returned.

401 Unauthorized

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unauthorized", "status": 401, "detail": "Unauthorized"}

You have not authenticated before running this API or The token_timeout of the current session has passed. You need to authenticate again.

403 Forbidden

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Forbidden", "status": 403, "detail": "Forbidden"}

You do not have permissions for this request. Go to System Roles and enter 'web_services'. Navigate to the Roles / APIs tab to make sure the permission you need to run this API is checked.

422 Unprocessable Entity

{ "validation_messages": { "quote_id": { "templateMisconfigured": "Quote template does not contain a quote_novated_1.html or index.html file"}} }

The HTML file within the zip archive is not named correctly. Rename the file to one of the following: Set the name to index.html OR Set the name to be the same name as the zip file. e.g.: quote_novated.zip

422 Unprocessable Entity

{ "validationMessages": { "quote_id": { "noRecordFound": "no record matching the input was found"}} }

The record for the quote_id you have used does not exist or is inactive. Check your API details and update the quote_id KEY.

Was this helpful?

Still need help? Ask the team