RenderQuotePDF

This API replicates the system function of printing a quote using a provided template zip file.

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.

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

RenderQuotePDFWithTemplate

This API replicates the system function of printing a quote.

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

Upload a New Quote Template

Qualifiers

• Catch-e has notified you of a quote zip update for UAT in Staging

• UAT in Staging has passed

• Upload your own quote zip files into Live for the following reasons:

  • You can update your Live as soon as UAT is complete

  • The emails back and forth with Catch-e support are reduced

  • The zip files are not being emailed. This is more secure and some email systems will block zip files

In Staging

1. Go to Setup / Import or Export Files

2. Select the Export radio button

3. File Type: select 'Quote Templates'

4. File Name: select the required quote zip file

5. Click on Export

6. Save the zip file down

7. Keep an archive copy of this zip file. Older versions of the file are not kept in the system.

In Live

1. Go to Setup / Import or Export Files

2. Select the Import radio button

3. File Type: select 'Quote Templates'

4. File Name: select the required quote *.zip file

5. Drop or browse to attach the zip file saved from Staging

6. Click on Import

Export a Form

Qualifiers

• You want to get the current form to review or modify

Process

1. Go to Setup / Import or Export Files

2. Select the Export radio button

3. Platform: leave as 'Catch-e'

4. File Type: select the required type

5. File Name: select the required file name

6. Click on Export

7. Open and save the file

Quote Template Setup

The information below details the steps required to set-up a quote template using the recommended method and settings.

Setup Steps

1. Create a record in the gb_files table

2. Edit Contract Type / Details "Quote Template" field to link to the new quote template

3. Upload zip folder for the quote template

4. Add a gb_templates entry to enable emailing

Use the following APIs to aid development of quote templates:

• getQuoteFieldsWebService: to return available quote placeholders

• Render Quote PDF with Template

• Render Quote PDF

Create a gb_files Record

Create a record in the gbfiles table that is linked to quote templates. The name of the file should be descriptive of the quote, but it can be called anything you like that describes the template, as an example quotenovated.zip. It needs to be a zip file.

Create a gb_templates Record

Create a record in the gb_templates table. This creates the email content that is used when quotes are emailed from the Quotes / Contact tab.

Standard email set-up details apply, except for the following specific settings:

• The field name should be 'pdfhtmlquote'

• The field subname should be the name of the zip file e.g. quotenovated.zip

Update Contract Types / Details "Quote Template"

Edit the Contract Type and update the "Quote Template" field to link to the new quote template. Once this is in place, you can use the getQuote web-service to review placeholders outputs.

Create a quote.zip File

Create a zip file that contains the following elements:

• images folder

• *.html

• *.json

• *.css

• temporendertoken_api.js

• phantomjs-regression-patch.js (optional file, required if active hyperlinks will be embedded)

Images Folder

The images folder should contain any images used in the template. For consistency name this folder 'images'. Note: you can keep the image files in the main folder, but an 'images' sub-folder helps keep the files organised.

Be careful not to nest folders inside your zip files. Visit the Troubleshooting page for more details about this issue.

*.html

The *.html document must reference the temporendertoken_api.js file as shown below. This file is required so that your quotes continue to work properly after the Legacy Web Services have been deprecated.

</body></html> 

If you are including active hyperlinks into the rendered pdf document, the html file must reference the phantomjs-regression-patch.js file. This is done by finding </head> in the html code and adding the following below it:

<script src="phantomjs-regression-patch.js"></script> 

*.json

A *.json file is created and held in the zip folder for local development and testing, e.g. testing in VS Code. It and is not referenced in Staging or Production environments.

When run from the system, quote credentials are passed dynamically at render time, and are used in preference to the JSON file content. The quote credentials are sourced from records in the gb_websystems table.

temporendertoken_api.js

Include a file named 'temporendertoken_api.js' within the zip folder. This file is required so that your quotes continue to work properly after Legacy Web Services have been deprecated.

Contents of the file can be found in the Catch-e support documentation.

phantomjs-regression-patch.js (if Active Hyperlinks Used in PDF)

To include active hyperlinks into the rendered pdf document, the global control phantomjs_render_bin_path should be set to '/usr/local/phantomjs-2.1.1-linux-x86_64/bin/phantomjs'. This control invokes the use of Phantom JS 2.1.1 which is used in the quote rendering process to activate hyperlinks embedded in the code.

An additional file is needed and should be called 'phantomjs-regression-patch.js'. The content of the phantomjs-regression-patch.js file is:

// Workaround for page scaling, zoomfactor regression var css = 'body { transform-origin: 0 0; -webkit-transform-origin: 0 0; transform: scale(0.75); -webkit-transform: scale(0.75); }'; var head = document.head || document.getElementsByTagName('head')[0]; var style = document.createElement('style'); style.type = 'text/css'; if (style.styleSheet){ style.styleSheet.cssText = css; } else { style.appendChild(document.createTextNode(css)); } head.appendChild(style); // Workaround for blank page bug var $html = $(document.getElementsByTagName('html')[0]); $html.height(0); 

Channel Quotes - Extra Steps

The information below details the steps required to set-up a channel quote template using the recommended method and settings.

1. Create a new record in the gbfiletypes table. This identifies the folder that the channel template should be stored in. You'll see that it's in the quote folder under a new sub-folder called 'channels'. Note that one folder is called 'channel1' - this must match and in the directory field, the full path must all be in lowercase.

2. Create a record in the gb_files table that is linked to the channel quote templates record you just created.

   • If you are using an existing Contract Type to generate channel quote, the channel-level quote must be the same name as the existing template. In this example it is quote_novated.zip. It needs to be a zip file.

   • If you want to set up a Contract Type that is only used by a channel or channels, create a general gb_files record, but don't upload the zip file. In this case, the quote will only print for linked channel clients.

3. Upload the required zip file (see general instructions).

4. Optional step: Link the template to a Contract Type (if required). This is only required if a Contract Type is only intended for use with one channel only.

5. Optional step: Create a record in the gb_templates table. This creates the email content that is used when quotes are emailed from the Quotes / Contact tab.

   If you don't set-up a channel-specific email, the quote email will use the generic email content.

   Standard email set-up details apply, except for the following specific settings:

   • The field channel_id should match the selected channel

   • The field name should be 'pdfhtmlquote'

   • The field subname should be the name of the zip file e.g. quotenovated.zip

Switching Existing Quotes to HTML

Current clients can develop an html quote and continue to use the placeholder library that's currently in use, rather than switching to the new one.

This is a good approach if you are happy with the current values you are using, but just want to rejuvenate the quote.

When setting up the html quote above, add the parameter "parentreport" into the JSON file under the "pageformat" parameter as per this example JSON file:

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

Note: The web-service getQuote will deliver the new placeholders. For analysis and diagnostic work, you will need to switch the Contract Type "Quote Template" back to the original one. E.g for the example above, this would be 'Quote Nofb Lease'.

Update the quote.zip File

Your zip file should contain the following elements:

• images folder

• *.html - update this file

• *.json

• *.css

• temporendertoken_api.js - update this file

• phantomjs-regression-patch.js - optional file, required if active hyperlinks will be embedded

*.html

The *.html document must reference the temporendertoken_api.js file as shown below. This file is required so that your quotes continue to work properly after the Legacy Web Services have been deprecated.

</body></html> 

temporendertoken_api.js

Include a file named 'temporendertoken_api.js' within the zip folder. This file is required so that your quotes continue to work properly after the Legacy Web Services have been deprecated.

Contents of the file can be found in the Catch-e support documentation.