Quote Template Development

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

Setup

1. Download and install Visual Studio Code from https://code.visualstudio.com/Download.

2. Install the 'Live Preview' extension to render the html. Search for it in the extensions section and make sure to install the one by Microsoft.

Build or Modify Quote Template

1. Download and open the template. Navigate to the 'Setup / Import or Export Files' page in Catch-e and export the quote_novate.zip file, selecting the 'Catch-e' Platform and 'Quote Template' File type from the respective drop-down lists. Extract the files into a folder.

2. Within Visual Studio, select the 'File / Open Folder...' option and select the folder you have extracted the files to.

3. Click on the html file to view the code. To preview it, right click on the file and select 'Show Preview'.

4. The file should render. You will need to add ?quote_id= to the end of the URL to show the quote.

5. Access the Dev Tools pane by using the menu option in Visual Studio. In the Dev Tools pane, you can expand the 'object' to see all the placeholders available with the value relevant to the current quote. You can use ctrl + F to search for a value or placeholder you are looking for.

6. Note that you may need to further expand the list of placeholder by clicking the three dots '(...)', at the bottom of the list.

Quote Template Placeholders

Quote data is delivered into PDF quotes using the HTML zip, the getQuoteFieldsWebService 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.

quotespackagingall — '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 quoteinclusionplans 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 'quotespackagingall'.

Settings

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

derivedfieldlibraryforquotepackaging (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 'quotespackagingall' library, test the use of 'quote' here thoroughly as values used may not match. Default: quote

totalleaseperpaycyclegstcalc_flag (qt) — If this is 'yes', the placeholder {totalleaseperpaycyclegst} is calculated from SUM(qtquotebudgets.amountnet). This makes the "Total GST" exactly 10% of the quotes "Total Net". If this is 'no', the placeholder {totalleaseperpaycyclegst} is calculated from SUM(qtquotebudgets.amountgst). 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 {totalleasemonthlygst} and {totalleaseperpaycyclegst} where the pay cycle is also monthly and these two placeholders are used in the quote template. Default: yes

paygtaxcalcs_flag (qt) — This control is applied only when the derivedfieldlibraryforquotepackaging 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

html2pdfservice_login (gb) — A web services user must be created 'webquotes'. 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

htmlquoteusetype2benefit_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 getQuote calls using prefixes gbbefvfmclients and gbbefvqtquotes.

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

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 "parentreport" can be passed in the JSON file as follows. Place this parameter under the "pageformat" 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.

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> 

5. Go back to sample.zip and delete the original document.xml file.

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

7. Rename sample.zip back to sample.docx.

8. 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

Headers

Response Details

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

Headers

Body - Form-Data

Response Details