Skip to main content

Output Management

The Output Management component is used to convert data from JSON format into various text or graphical outputs. It is designed for generating emails, attachments, invoices, and other documents, such as XML configurations or complex network settings (e.g., for CISCO devices).

Output Management supports multiple document types, including HTML, Microsoft Word, and Excel documents. For HTML formatting, a visual designer is provided, enabling users to easily edit and customize document appearance.

Layout and Template System​

Layout​

The primary element in Output Management is called a Layout. Its main function is to take an input JSON and render a document according to a predefined structure. The Layout defines the overall structure of the document, specifying how different elements, such as headers, footers, and main content, should be arranged.

For rendering content, the Handlebars template engine is used. Handlebars replaces placeholders in the format {{property.name}} with the corresponding data from the input JSON. This makes it a flexible tool for creating dynamic documents.

Handlebars Example​

Given the following JSON input:

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

The Handlebars template could be defined as:

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

When rendered, this would generate the following document:

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

Templates​

Since Layouts can be complex and contain graphical elements (e.g., headers, footers, logos), they are not always suitable for direct editing by business users. Therefore, an additional abstraction called Templates is created. Templates are content-specific configurations built on top of a Layout. For example, you may have one Layout for an email notification with defined fields such as Header, Content, and Footer, but multiple Templates for different use cases, such as a contract closure notification or a reminder of an upcoming deadline.

Form Designer for Templates​

To make it easier for business users to create and manage Templates, a Form Designer is used to build custom configuration forms. Each form defines the structure of the input for a specific Layout, making it simple for users to fill in content fields without worrying about the underlying Layout structure.

For instance, consider an email Layout with fields like Header, Content, and Footer. Instead of requiring the user to manually enter these fields into JSON, a form is created called Email Template. The form provides a structured way to define the content for each field.

Example Workflow​

  1. Create a Layout: Define a Layout that specifies where Header, Content, and Footer data should appear in the email.
  2. Create a Form: Use the Form Designer to create a form that maps to the JSON fields Header, Content, and Footer.
  3. Create a Template: Build multiple Templates that utilize the same Layout but vary in the contents of Header, Content, and Footer. For instance, a template for a contract closure notification might have a static Header ("Contract Closure") and a Content that includes dynamic data like customer name or order details.

This separation of Layouts and Templates ensures that while the document structure (e.g., graphics, headers, and layout) remains consistent, business users can easily create and update the content for specific notifications without altering the base Layout.

Typical Usage with tSM Scripting​

A common usage scenario involves calling the Output Management component from a tSM process using SpEL (Spring Expression Language). This is useful when generating documents such as PDF files or XML configurations directly from process logic, using data gathered from various parts of the process.

Example 1: Generating a PDF Document from Process Data​

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

In this example, the generate method creates a PDF document (MyDoc.pdf) using the specified Layout and the data from the #order object.

Example 2: Saving the Generated Document as an Attachment​

The following example demonstrates how to generate a PDF and save it as an attachment to an order:

#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()
    })
)

In this case, the document is created and then saved as a base64-encoded attachment associated with the specific order.

Example 3: Using Output Management for User Notifications​

Output Management is also frequently used for user notifications. In this scenario, the document template is set as the "Output Design" of the notification template property. This allows the system to generate custom messages, such as emails or alerts, using predefined templates.

For more details on configuring notifications with Output Management, refer to the [Notifications Documentation].