Report Template Editor

Introduction

With the PDF Template Report Editor, you create or modify the XML templates used in FieldFX Mobile. You can generate PDF reports, a type of FX Report. PDF reports attach to records as PDFs. The PDFs are easier to print and email. You can also use repeating headers and footers, pagination, and many other advanced formatting options. The PDF Template Report Editor provides templates for commonly generated reports, easing the burden of creating reports.

For more information, consult the Report Editor Admin Tool Release Notes.

Prerequisites

To use the PDF Report Editor,

Have these user licenses Have these permissions Before continuing
complete these tasks
  • FX E-Ticketing minimum permissions

  • To use the Report Template Editor and have it appear in the Miscellaneous block of the Admin Portal, enable the FX5.Admin Tool - Advanced Report Editor permission.

Grant Access to Admin Tools

Access to Admin Tools is available to anyone with the ability to edit or update your org’s Static Resource files. You can only give access to users using Permission Sets. The user must have a Salesforce license.
  1. From Setup, enter Permission Sets in the Quick Find box, then select Permission Sets.

  2. Click the link for the Permission Set Label you need to modify.

  3. Scroll to the bottom of the page and select System Permissions.

  4. Click Edit Properties.

  5. Mark the Enabled checkbox for Customer Application.

  6. Click Save.

  7. Repeat the steps for other permission sets as needed.

XML Templates

An XML template is a file containing XML markup that controls the design and content of a PDF report.

XML templates use:

You can create XML templates in a text editor.

PDF Metadata

  • The Report Template can be used to add PDF file metadata via an <info> tag.

  • Supported metadata attributes are:

    • title - You can also use this for the PDF filename.

    • author

    • subject

    • keywords

  • Report designers can use Handlebars expressions to add dynamic content to the metadata fields.

  • If added manually, the <info> tag must be a direct child of the <template> tag.

PDF Metadata Examples

Use the Job Safety Report as the Report Title Each Time a Report Generates

In the title field of the Report Template, enter Job Safety Report.

This adds the following to the XML for the report template:

<template>
  <info title="Job Safety Report" />
</template>

Dynamically Use the Customer and a Timestamp for the Report’s Title

If multiple PDF reports are created, the customer and timestamp are added to the report title to set them apart. In the title field of the Report Template, enter the following Handlebars expression:

{{FX5__Customer_Account__r.Name}}-{{formatDate (formula "NOW()") format="MM/DD/YYYY HH:mm:ss"}}

The following is then added to the XML for the report template:

<template>
  <info title="{{FX5__Customer_Account__r.Name}}-{{formatDate (formula "NOW()") format="MM/DD/YYYY HH:mm:ss"}}"/>
</template>

The resulting report might display as follows:

List of Report Titles in FX Mobile
Figure 1. In FX Mobile
List of Report Titles in FX Back Office
Figure 2. In FieldFX Back Office Notes List
Microsoft Windows File Properties
Figure 3. In a Microsoft Windows File Properties displayed by right clicking the file

How Report Templates Works

Use the Report Templates tool to add new reports for Quotes, Jobs, Tickets, and Invoices.

If a new version of the same report is created, the PDF filenames are appended with the data and time in the filename.

Use the wizard to create or modify an XML template for the report.

Start from a preloaded format or create a new report from a blank template.

After creating the report with the wizard, advanced users can modify the XML directly.

Considerations

Existing reports continue to work as designed, but may not be edited with the wizard tool.

Existing HTML report templates and XML report templates can be edited in the code editor within the tool.

New reports are created as XML templates.

HTML reports are deprecated and will not receive enhancements or new features.

Best Practices

Be aware of the objects used for the report. Consider creating a diagram or writing down the objects and their relationships.

If defining the XML manually, use margins to assist in readability and accessibility of the report. Keep spaces at the edges of the report and between sections.

Margins are always set clockwise: Left, Top, Right, Bottom.
<table margin="36 40 36 40"> sets the left margin at 36, then the top margin at 40, then the right margin at 36, then the bottom margin at 40.

Consider the content of the report data and whether a the width of a landscape orientation is better than the height of a portrait orientation.

If there is any chance of ever printing the report, always print an example.

Step-by-Step Guides

Add only a single attachment per report template. Adding more than one could cause issues for a FieldFX Mobile user.

Getting There

  1. Access the Admin Portal from https://admin.fieldfx.com.

  2. Select the Report Templates button on the Dashboard.

    Screenshot of the Report Templates button on the Admin Portal Dashboard
    Figure 4. Report Templates is one of the tools available on the Admin Portal’s Dashboard page

Add a Logo File

The same logo file is used across report templates for the org.

  1. Go to https://admin.fieldfx.com.

  2. Select the button on the Dashboard for Report Templates.

    Screenshot of the Report Templates button on the Admin Portal Dashboard
    Figure 5. Report Templates is one of the tools available on the Admin Portal’s Dashboard page
  3. Click the Upload Logo button in the bottom right.

    Screenshot of the Upload Logo button
    Figure 6. Click the Upload Logo button to add a new logo or replace an existing logo to use on all reports for the org

    The Template Logo Management displays a current logo on the left.

    Screenshot of the Template Logo Management screen with a logo file
    Figure 7. A preview of the uploaded logo displays on the Template Logo Management screen
  4. Click inside the dotted rectangle on the right with "Select File to Upload" to upload a new logo file.

    Use a file in .GIF, .JPG, .PNG, or .SVG format.

    Transparent backgrounds work best.

  5. Select the image file to use in your system’s file tool.

  6. Click Save.

Create a Report Template

When creating a new Report Template, complete these steps:

Define the Report Parameters

  1. Select the + New Template button on the top right.

    Screenshot of the New Template button
    Figure 8. Begin creating a template by clicking the New Template button
  2. Select an example template to start from or choose Blank to begin from scratch.

    Screenshot of the Report Template Wizard’s template selection screen
    Figure 9. The Report Template Admin Portal Tool provides a number of templates for a quick start, or you can create a brand new report
  3. Enter a Report Name and select the Object for the report, then click Next.

  4. Select the Page Size for the report, then click Next.

    Letter

    8.5" × 11"

    Legal

    8.5" × 14"

    A4

    8.3" × 11.7"

  5. Select the Orientation of the paper for the report, then click Next.

    Portrait:

    Tall perspective

    Landscape:

    Wide perspective

  6. Add Optional Filters to control when the report is available:

    All fields are optional.

    Field Name Description

    Sequence Number

    Order in which to display the template in a list of report options.

    Job Type

    Record type for the FX5__Job__c object for which the template is valid. Select from the picklist values.

    Segment

    Business segment for which the template is valid. Select from the picklist values.

    Account

    Customer account for which the template is valid. Enter two or more characters from the Account name to search.

    Office

    Office for which the template is valid. Select from the picklist values.

    Record Type

    Record type of the report’s selected object for which the template is valid. Select from the picklist values.

  7. Click Next then continue to create the report’s Header.

Create the Report Header

The report header contains three columns

  • Column 1 contains a space for the logo, if included.

  • Column 2 contains space for a line of text, such as a report title.

  • Column 3, always on the right, contains space for a table of data that is two columns wide and allows up to seven rows.

Screenshot of the logo placement options screen of the report wizard
Figure 10. If used, a logo can be placed in either the left or middle column of the header
  1. Choose whether the organization’s logo should appear:

    • Align the logo to the left of the page with the single line in the middle.

    • Align the logo in the center of the page with the single line to the left.

    • Do not include the logo. Single line column is left aligned.

  2. Click Next

  3. Customize the Header Properties that appear at the top of the report.

    You can fill any of these fields in the header with:

    • Custom Text: Select the option and then enter the text that should display.

    • Page number and page count

    • Date

    • Results of a SOQL formula

    • Field from the report’s object

    1. To add content for the single line field, select any of the following:

      • Blank field, then choose a field from the report’s object

      • Property, such as the number of pages

      • Date

      • Results of a SOQL formula

      • Custom Text to add a title or other heading for the report

    2. When using a two-column table, you can add content and it displays in the top right of the page.

      By default, the wizard presents two fields.
      Add additional fields by clicking Add Column to add a new row with space for two additional fields.

      You can add up to a total of seven rows.

      Use the left column as the row label by selecting Custom Text as the field type, then replacing the words "Custom Text" with the label to use.

  4. Click Next after adding all desired fields for the top of the report.

Define the Table Contents

  1. Select the Table Type that defines the main content the report displays.

  2. Typically, reports list the Items for the object.

    A Ticket Report would add a Ticket Items table type.

    Screenshot of the Select Table Type screen in the Report Template wizard
    Figure 11. Specify the type of table for the main contents of your report
  3. Enter text in the unlabeled field to filter and select an option.

    or

    Click the drop down to scroll through the list.

  4. Click Next after making the selection.

    Advanced users can skip this step and create the table in the XML code later.

  5. Define the Columns that should appear in the table on the report:

    Field Name Description

    Field

    Data from the referenced object to display on the report

    Enter the fields in any sequence.
    The display order is defined on the next screen.

    For example, on a Ticket report of Ticket Items, the field from the FX5__Ticket_Item__c object to display on a Ticket report.

    Label

    Heading to use for the column

    Total Label

    Description to display for the last row of the report

    This option is only available for the Column selected as the Show column.

    Show

    Field to sum as the total amount

    You can only select one Column Field to Show

    The example shown creates a basic Ticket Item report with Quantity, Discount, Price, and Extended Amounts.

    Screenshot of a list of columns for a ticket report
    Figure 12. Add the columns that should display on the report, with labels and a total as desired
  6. Click Next.

  7. Define how to sort entries on the table:

    Field Name Description

    Sort by

    Field to use to sort the table entries

    Direction

    Ascending to sort A-Z or from lowest to highest.
    Descending to sort Z-A or from highest to lowest.

    Filter By Formula

    SOQL query to limit records that display

    Screenshot of the Sort and Filter Table Fields screen
    Figure 13. Define how the data in the table should display with sort, direction, and filtering options
  8. (Optional) Modify the column display order.

    Use the up and down arrows to change the display order.
    Fields print in order from left to right based on this sequence.

    Screenshot of the Order of column fields section
    Figure 14. Use the up and down arrows next to the list of Column Fields to change the sequence they display from left to right across the report
  9. (Optional) Add Another Table to the report.

  10. Click Next to Add Terms and Conditions.

Add Terms and Conditions

  1. Enter text that should display after the contents of the table.

    • Copy and paste from another program or type in the field.

    • Most formatting copies well.Use the buttons to add headings or other formatting to selected text.

      Screenshot of the terms and conditions editor
      Figure 15. Add Terms and Conditions to your report with a familiar editing and formatting interface
  2. Click Next to Add Signatures.

Add Signatures

Reports can contain slots for up to three signatures.
  1. Select the number of signatures required.

    Screenshot of the signature selection screen
    Figure 16. If a report requires signatures, the wizard allows for up to three
  2. Click Next.

  3. If you added signatures, enter a descriptive label to print for each signature.

    For example, Customer, Supervisor, or Field Technician

    Screenshot of the Signature Properties screen
    Figure 17. Add the labels to use for each signature line
  4. After adding caption labels for the signatures, click Next.

  5. Select the type of Capture Signature Header to include, then click Next.

    The optional Capture Signature Header allows you to configure rows to text that display on the signature screen.
    Table 1. Field Options
    Field Description

    No Capture Header

    Don’t display additional text on the signature screen.

    Top

    Displays the text above the signature box

    Right

    Displays the text to the right of the signature box

Example of the options to select the signature capture position
  1. (Optional) If you selected to include a signature capture header, add one or more rows of text to display in the Define Capture Signature Header Properties window.

    • There are two columns per row.

    • Select the available property to add from the list.

    • Select Custom Text to add row labels or other static values, then select the pencil icon to customize the text that displays.

    • Select Formula to enter a SOQL formula for the value to use.

    • Use + Add Row to create additional row(s)

    • Select the red trash can icon to delete a row

      Example of selecting the property to display on a row in the Define Capture Signature Header Properties window
  2. Click Next

  • The optional footer allows for a main statement line and two places for additional fields.

    1. Select the arrangement of the footer information.

      Screenshot of the Select a Footer page
      Figure 18. Select how the main statement and additional fields should appear at the bottom of each page
    2. Click Next.

    3. Add labels and fields to use in the Footer.

      If needed, you can add up to six additional rows to the two-column tables.
      Screenshot of the Define Footer Properties screen
      Figure 19. Add fields to show in the footer, including adding additional rows to the tables as needed.
    4. Click Finish.

The report template is not saved until you finalize and save the report!

Finalize the Report

A preview of the report displays.

  1. Click on a section to make changes as needed.

  2. Use the Filters and Layout navigation panels on the left of the screen to modify report information.

  3. Click a report section to access additional edit options for the section.

    Screenshot of a section of the report selected for editing
    Figure 20. Select any section of the report preview to make changes if needed

    Click the table section to add a new table above or below the existing table.

    If multiple tables exist, a trash can icon appears allowing you to delete a table.

    At least one table must exist on the report.

    Screenshot of a table section from the preview
    Figure 21. The wizard allows you to add new tables, rearrange tables, or delete a table
  4. Click Preview in the top left to generate a sample report
    Select a particular record to use for the sample when prompted.

    Screenshot of the record selection prompt
    Figure 22. Preview the report by selecting a particular record’s data to use
  5. Add Optional Metadata

    Metadata is additional information added to the PDF file.

    The Report Template supports four pieces of metadata:

    • Document Title (also used for the file name)

    • Author

    • Subject

    • Keywords

      You can use Handlebars expressions to include dynamic content in the report metadata.

      Optional Metadata
  6. Click Save in the top left to make the report template available.

    Screenshot of the Report Templates screen with a report preview and the save button
    Figure 23. Click Save to confirm changes and make the report available for records

Modify an Existing Report Template

  1. Go to https://admin.fieldfx.com.

  2. Select the button on the Dashboard for Report Templates.

    Screenshot of the Report Templates button on the Admin Portal Dashboard
    Figure 24. Report Templates is one of the tools available on the Admin Portal’s Dashboard page
  3. Select the report template’s object from the list on the left.

    If the report is not for a Quote, Job, Ticket, or Invoice, select Other Templates.

    Screenshot of the Report Templates screen with the object selection options displayed
    Figure 25. Report templates are grouped by object or collected into "Other Templates"
  4. Select the template’s edit icon to modify the report template.

    The Report Template’s Edit button
    Figure 26. Use the pencil icon for a particular report template to edit the report
  5. Select whether to use the XML code editor or the XML Wizard to edit the report.

    See the instructions for the wizard discussed above in the Create New Report Template section.

    Reports that were created without the wizard and legacy HTML reports can only be edited using the code editor.

    XML or Wizard selection screen
    Figure 27. Choose whether to modify the report in the Wizard or the XML editor
  6. From the report wizard, click Save to save the changes to the report, exit the Template Wizard, and return to the report template list.

    or

    From the code editor, click Save or click the Templates menu option to return to the report template list.

    XML Editor screen
    Figure 28. Click Save after making changes in the XML editor to return to the Report Template list

Copy an Existing Report Template

  1. Go to https://admin.fieldfx.com.

  2. Select the button on the Dashboard for Report Templates.

    Screenshot of the Report Templates button on the Admin Portal Dashboard
    Figure 29. Report Templates is one of the tools available on the Admin Portal’s Dashboard page
  3. Select the report template’s object from the list on the left.

    Use the Author and Filter dropdown options to narrow the list of templates.

    If the report is not for a Quote, Job, Ticket, or Invoice, select Other Templates.

    Screenshot of the Report Templates screen with the object selection options displayed
    Figure 30. Report templates are grouped by object or collected into "Other Templates"
  4. Select the copy icon for the template to copy.

    Screenshot of the copy button
    Figure 31. Use the Copy button to duplicate an existing Report Template
  5. Confirm the copy by clicking Copy.

  6. From the Report Template selection screen, select the template and modify it using the wizard or code editor.

Delete an Existing Report Template

  1. Go to https://admin.fieldfx.com.

  2. Select the button on the Dashboard for Report Templates.

    Screenshot of the Report Templates button on the Admin Portal Dashboard
    Figure 32. Report Templates is one of the tools available on the Admin Portal’s Dashboard page
  3. Select the report template’s object from the list on the left.

    Tip: If the report is not for a Quote, Job, Ticket, or Invoice, select Other Templates.

    Screenshot of the Report Templates screen with the object selection options displayed
    Figure 33. Report templates are grouped by object or collected into "Other Templates"
  4. Select the trash can icon for the desired Report Template.

    Screenshot of the trash can icon
    Figure 34. The trash can icon deletes an existing report template
  5. Confirm the deletion by clicking Delete.

    This cannot be undone.

Troubleshooting

To display forms in the browser, you must disable the Google Chrome setting that determines whether the browser displays or downloads PDF files.

Google Chrome is a 3rd party application, and the instructions for how to disable this option may change at any time without warning.
  1. In Google Chrome, go to chrome://settings/content/pdfDocuments.

    (Enter that path directly in the browser’s address bar.)

  2. Verify the toggle for Download PDF files instead of automatically opening them in Chrome is disabled.

Alternatively:

  1. Access Google Chrome’s settings.

    There are several ways to do this, but one is to select the vertical dot Customize and Control button in the top right corner of the browser, then select Settings.
  2. Select Privacy and security in the left navigation bar.

  3. Select Site Settings.

  4. Select PDF documents.

    You may need to expand the Additional content settings group of options first.
  5. Verify the toggle for Download PDF files instead of automatically opening them in Chrome is disabled

Sample PDF Report

  • Advanced users can take advantage of the Handlebars template library.