Output Management

Output Management turns JSON data into documents: emails, PDF attachments, invoices, contracts, Word or Excel files, and plain-text outputs such as XML payloads or device configurations. It is part of the DMS service (tsm-dms) and is used by processes, notifications, integrations and the public REST API.

This page explains the concepts and how the pieces fit together. The follow-up pages go into detail:

Page	What you learn there
Layout Designer	The visual editor: panels, blocks, tSM components, test data and preview.
Templates	Content configurations built on top of a Layout and edited through a form.
PDF and Email Layouts	Rules and pitfalls for print-ready PDFs and email-safe HTML.
Handlebars Reference	Placeholders, blocks and all helpers available in templates.

Building blocks

Concept	Menu	API entity	Purpose
Layout	Output management → Layout	FormatterTemplate	The document structure: header, footer, content areas, styles and Handlebars placeholders. Designed by a configurator in the Layout Designer.
Template	Output management → Templates	FormatterDocumentTemplate	A content variant of one Layout (e.g. Contract closure and Deadline reminder on the same email Layout). Edited by business users through a form. See Templates.
Form	Forms	Form	Defines the fields a business user fills in on a Template. Assigned to the Layout.
Handlebars	–	–	The template engine that replaces placeholders such as {{customer.name}} with data. See the Handlebars Reference.

Privileges follow the same split: Om.FormatterTemplate.* for Layouts and Om.FormatterDocumentTemplate.* for Templates.

Layout

The Layout is the primary element. It takes input JSON and renders a document according to a predefined structure. A Layout has these properties:

Property	Values	Meaning
Code, Name	text	Identification. The code is what callers use to generate a document directly from the Layout.
Type	Editor (HTML), File (FILE)	Editor: the body is HTML with Handlebars, edited in the designer or as source code. File: the body is an uploaded file (for example a Word or Excel document) attached to the Layout.
Formatter document type	PDF, EMAIL, SOURCE, EXCEL	Selects the editor mode and the export behaviour, see the table below.
Formatter document size	AUTO, PORTRAIT, LANDSCAPE, A4, B5, LETTER	Paper size for PDF output. Shown only for the PDF document type.
Form	form	Form used in the Template detail to enter the Template content.
Test data	JSON	Sample input used by the designer for autocomplete and live preview. It is not used when documents are generated in production.
Labels, Configuration Type	–	Standard configuration metadata.

Document type	Editor	Export and preview
PDF	Visual designer with the PDF blocks (page layout, header, footer, paginator, page break).	CSS stays in a <style> block, page size and margins become an @page rule. Preview pdf renders the real PDF.
EMAIL	Visual designer without the PDF blocks.	CSS is inlined into style attributes, because many email clients ignore <style> blocks. Send a test email sends the rendered email to an address you enter.
SOURCE	Source code only, no visual designer.	Use it for text outputs such as XML, JSON or configuration files.
EXCEL	Visual designer without the PDF blocks.	–

Templates

Because Layouts contain graphics, styles and technical structure, they are not meant to be edited by business users. A Template is a content configuration built on top of one Layout. For example, one email Layout defines where Header, Content and Footer appear, and several Templates fill those fields with different texts for different notifications.

The fields of a Template are defined by the Form assigned to its Layout, so a business user fills in a structured form instead of editing JSON. Details are on the Templates page.

Typical workflow

1. Create a Form that describes the content fields, for example Header, Content and Footer.
2. Create a Layout, assign the Form, paste sample Test data and design the document in the Layout Designer. Place the form fields and the runtime data into the document with Handlebars placeholders.
3. Create one or more Templates on the Layout and fill in their content through the form.
4. Generate the document from a process, a notification or the API by the Template code.

This separation keeps the document structure consistent while business users change the content without touching the Layout.

How Handlebars renders data

Handlebars replaces placeholders in the form {{property.path}} with values from the input JSON.

Given this input:

{
  "customer": {
    "name": "John Doe",
    "orderNumber": "12345"
  },
  "invoice": {
    "total": "$250.00",
    "dueDate": "2024-11-10"
  }
}

and this template:

Dear {{customer.name}},

Thank you for your order #{{customer.orderNumber}}. The total amount due is {{invoice.total}}.
Please make your payment by {{invoice.dueDate}}.

Best regards,
Your Company

the output is:

Dear John Doe,

Thank you for your order #12345. The total amount due is $250.00.
Please make your payment by 2024-11-10.

Best regards,
Your Company

HTML values need triple braces

{{value}} escapes HTML, so a rich-text value such as <p>Hello</p> is printed literally. Use {{{value}}} when the value already contains HTML.

Conditions, loops and formatting helpers are described in the Handlebars Reference.

Generating output

From SpEL

A common scenario is generating a document from a tSM process with SpEL, for example a PDF or an XML configuration built from process data.

Generate a PDF

@formatterPublicService.generate("MyDoc", "pdf", {
    customer: #order.customer,
    order: #order
})

The first argument is the code of the Template, the second the output format and the third the input data. The call returns the generated document as bytes.

Generate a PDF and save it as an attachment

#with(
    #doc = @formatterPublicService.generate("MyDoc", "pdf", {
        customer: #order.customer,
        order: #order
    })
).do(
    @attachmentPublicService.create({
        "ownerType": "Order",
        "ownerId": #order.id,
        "attachmentType": "MyDoc",
        "name": "MyDoc.pdf",
        "data": #doc.encodeBase64()
    })
)

The document is generated and stored as a base64-encoded attachment of the order. See Attachment for the attachment fields.

From the REST API

The DMS service exposes the generator as a public API:

Endpoint	Purpose
POST /api/v1/formatter/{documentTemplateCode}/{format}	Renders one document. The path takes the code of a Template or a Layout, the body is the input JSON, the response is the document content.
POST /api/v1/formatter/generate-multiple-documents/{format}	Renders several documents in one call. The body is a list of {documentId, documentTemplateCode, data}, the response a list of {documentId, data}.
POST /api/v1/formatter/generate-file-name/{templateCode}	Returns only the file name generated for the given data.

format is html, pdf or another format LibreOffice can convert HTML to, such as doc, docx, xls and xlsx. PDF is rendered directly, the other formats are converted by LibreOffice.

From notifications

Output Management is the usual way to design notification content. A Notification Template points to an Output Management Template (formatterDocumentTemplateId, shown as Output design) and the notification data is passed to it when the notification is rendered. Parts of the content can be overridden per notification with formatterDocumentTemplateDataOverride. See Notification.

From integrations

The SOAP connector can render a request body from an Output Management template with fromTemplate(...), so large XML payloads stay in configuration instead of script code. See SpEL connectors.