Custom headers and footers

You can specify custom header and footer texts, merging document data with your own text instead of using the default header and footers for the report. The headers and footers can have global or local scope, depending on the documents in question.

Custom headers and footers can be specified as custom text or as placeholders. The placeholders can in their turn also contain custom text and/or document data.

Custom text

Headers and footers can be added to the report as custom text only, with the defined text being generated on each page of the report.

Example: Free text

Header: "Confidential - do not distribute!"

In this example, each and every page of the report document will contain the header text: Confidential - do not distribute!

You can define header and footer alignment, margins as well as style (font size and colors) to further customize your report headers and footers.

Placeholders

Headers and footers can also contain placeholders. Placeholders can be used to contain and display document data retrieved directly from the document itself. Placeholder values can also be defined directly in the report JSON and you can define custom text in the placeholders.

Placeholder custom text can also be combined with document data in the placeholders and a placeholder can contain multiple instances of custom text and document data.

Custom text in placeholders

You can specify custom text within the placeholder itself by entering the custom text in quotation marks within the placeholder brackets. { }. You can combine the placeholder custom text with placeholder tokens, creating labels or descriptive text for your tokens.

Example: Placeholder custom text with the Title token.

Header: "{"Title of document: " Title}"

If the value of the placeholder token Title is "Annual Report", the header will be displayed as: Title of document: Annual Report.

Document data in placeholders

Tokens are used in the placeholders to display document data. The relevant document data will be populated in the placeholder token when the report is run. The tokens conform to the field codes in Microsoft Word in order to maintain a degree of recognition with the Microsoft Word field codes.

You can combine the tokens with custom text in the place holder and you can specify multiple tokens and custom texts within a single placeholder. Placeholders with multiple custom texts and tokens can be complex and difficult to decipher but might be necessary as you only can define one header or footer per document. You can define multiple placeholders though.

The placeholder tokens are placed without including spaces. You must explicitly define and insert any required spaces within quotation marks.

Including quotation marks in the placeholder custom text

You can include quotation marks in the placeholder custom text by using a backslash before the quotation mark.

Example: Include quotation marks in placeholder text

Header: "{"Placeholder text "\"Quotation text\"" More placeholder text}"

Result: Placeholder text: "Quotation text" More placeholder text

Placeholder tokens

When you use the Select clause in the report JSON, all the properties of the record that is selected are available as placeholder tokens and can be updated with actual values retrieved from OData (e.g. FileKey, PostList, DocLength, etc).

You must include the document contents to the report by setting IncludeDocumentContents parameter to True in the related POST request to the Reports API. The record’s properties and tokens will then updated with actual values on the record’s pages inside the report, whereas all the other pages of the report would not be updated.

No Select clause in the report JSON

When there is no explicit Select clause in the Report JSON, all fields are considered to be selected and are therefore also available as placeholder tokens, for example if a report query selects the whole record (Record is present in the query but no select clause for specific fields), all the record’s properties will be available as placeholder tokens.

Expanded tables in the report JSON

Fields accessed through the Expanded command to the Record table in the report JSON are also available as placeholder tokens for headers and/or footers in the document, including custom fields have been added to the Record (Case), File (document) or contact (Contact) tables.

For an example of an Expand command, see Create the Report JSON file

Custom fields are created and maintained in the WorkZone Configurator module.

Additional placeholder tokens

The following additional placeholder tokens can be used in the header and footer:

• {Title}: The document title – either an original file name or an empty string if not provided.
• {Date}: The current date based on defined culture settings. You can use the AcceptLanguage request HTTP header to set the culture to be used by the WorkZone PDF to handle the request. For example the date format DD.MM.YYYY or DD.MM.YY is particular to Denmark while MM/DD/YYYY is particular for the United States.
• {Page}: The current page number of the document.
• {Numpages}: The total amount of pages in the document.
• {Caption}: Return the report caption, if a caption has been defined.

The placeholder tokens can be used in any combination, even with additional text.

Headers or footers defined as an HTTP header will be global for all documents. Headers or footers defined in the JSON request body will override any defined global header or footer for the specific document where it is declared.

Example: Multiple tokens in a placeholder

Header: "{Page " of " Numpages}"

Result: If Page is 2 and Numpages is 25, the result will be: Page 2 of 25.

Empty document data

If the document data for a token in a placeholder is empty, that token will be displayed as an empty value and any defined custom text will be displayed.

However, if all the values of all the tokens in a placeholder are empty, the entire placeholder will not be displayed, even if there is custom text defined in the placeholder.

This enables you to display header or footer text only when related tokens are populated with data on record-related pages and not display header or footer text on other report pages - for example Case-related pages or report cover pages.

Example: Empty tokens

Header: "{"State is " State ", Type is " Type }"

In this example, the header result will depend on the values of the tokens: State and Type.

Token values	State = A	State empty
Type = B	State is A, Type is B	State is "", Type is B
Type empty	State is A, Type is ""	""

When both tokens are empty, the entire placeholder will not be displayed. As long as a single token contains a non-empty value, the placeholder will be displayed.

Places where headers and footers can be defined

Customized headers and footers for PDF documents are specified in the same fashion as specifying custom headers and footers for reports and use the same placeholder tokens. Custom headers and footers, like nearly all parameters can be defined in the following places: 

• In the Database configuration itself.
• In the HTTP headers for the entire request
• In the POST request body root of the request
• In the POST request body local for the request for the specific document
• In the GET URI

The list above starts at a global level, applying the header/footer parameter setting to all documents and then gets more specific to the individual document, depending on where the header/footer parameters are defined.

Locally defined parameter settings will override more globally defined parameter settings, for example a header defined in the GET Uri of the document will override any settings defined in the POST request, HTTP headers and Database configuration.

For more information about PDF headers and footers, see API documentation