1. Field Service Management
  2. FSM Configuration
  3. Configuring FSM Features
  4. FSM Service Report Configuration
  5. Preparing and Selecting Custom FSM Service Report Templates

Preparing and Selecting Custom FSM Service Report Templates

FSM uses the FreeMarker template renderer in NetSuite and Big Faceless Organization (BFO) Report Generator to produce service report PDFs.

This topic includes the following sections:

The following table describes the report rendering stages.

Stage

Purpose

Prepare report data

FSM resolves the configured records, searches, and other named values in the attachment's contents object.

Render the template with FreeMarker

FreeMarker inserts those values into the XML template. Its directives control conditional content and repeated rows. The result is an XML document.

Generate the PDF with BFO

NetSuite converts the rendered XML into a PDF using BFO's report format, including page layout, tables, fonts, images, headers, and footers.

The HTML email body is rendered separately with FreeMarker. It is not converted to a PDF by BFO.

Requirements for Custom Templates

Customize a copy of the applicable standard XML template and select it with contents.template. NetSuite provides the rendering engines. Your custom file supplies the template. Follow these requirements:

  • Retain the XML declaration, BFO document type, and <pdf> root used by the standard templates. Use well-formed XML, with closed elements and quoted attributes.

  • Use BFO-supported elements and styling for PDF layout. Browser HTML and CSS support don't establish what the PDF renderer supports.

  • Use FreeMarker references such as ${task.title} to display supplied data, <#if> for conditional content, and <#list> for repeated rows. For the data names and result shapes to use, see Supplying Data to FSM Service Report Templates.

  • Handle missing values and empty collections. Apply appropriate formatting for numbers, dates, and Boolean values.

  • Escape inserted text and attribute values for XML where required, including characters such as & and <. Use the escaping appropriate to the template's FreeMarker output format. Don't assume automatic escaping is enabled.

  • Use template features supported by the rendering environment in NetSuite.

FSM configuration template tags and FreeMarker references can both use ${...}, but each is evaluated in a different context. Configuration tags prepare the report definition and data. FreeMarker references use the named data supplied to the XML file. For information about configuration tags, see FSM Expressions and Template Tags.

Template Authoring References

The following table lists template authoring references.

Reference

Use

BFO Report Generator

Product overview and public landing page for BFO Report Generator.

BFO Report Generator User Guide

XML report structure, layout elements, and styling.

Apache FreeMarker

Public landing page for Apache FreeMarker.

FreeMarker Manual

Template syntax, directives, data handling, and formatting.

FreeMarker Template Author's Guide: Getting Started

Introduction to inserting values, conditions, and lists.

For information about XML templates that use FreeMarker and BFO, see Source Code Editing to Customize Advanced Templates.

NetSuite guidance for XML templates that use FreeMarker and BFO.

The NetSuite reference explains template syntax. FSM selects service report files through configuration and the File Cabinet. For instructions to select a file, see Selecting a Custom Report Template.

Selecting a Custom Report Template

Preserve the supplied template and work from a custom copy. Copy the template for the relevant record type so that its expected data and layout are retained.

To select a custom report template:

  1. Locate the XML file selected by the merged configuration.

  2. Save a custom copy in the File Cabinet.

  3. Modify the copy using valid XML, FreeMarker syntax, and BFO-supported layout. For more information, see Requirements for Custom Templates.

  4. Change the corresponding contents.template reference.

The following custom configuration fragment changes only the CRM task PDF template and its file name. Replace the example path with the File Cabinet path of an existing file.

            {
  "notification": {
    "taskEmail": {
      "servicereport": {
        "attachments": {
          "servicereport": {
            "name": "Task_Service_Report.pdf",
            "contents": {
              "template": "/Templates/FSM/task-service-report.xml"
            }
          }
        }
      }
    }
  }
}

Merge these properties into the existing custom configuration. The inherited PDF type, report data, email body, and recipient settings remain unless changed elsewhere. The explicit file name overrides the file name supplied by the template's title.

This changes the existing servicereport definition, so references to that definition use the revised PDF. Creating a differently named definition doesn't automatically copy the standard definition or select it for a button or automatic rule.

For a separately named report, supply a complete notification definition with the required email body and PDF attachment. Update the applicable button's notification property or notification rule. Keep its data definitions compatible with the selected record type.

Additional Information

Related Topics

General Notices