Publishing Templates - DOCX Template - Lab

Lab Info

Lesson	Publishing Templates
Category / Topic / Section	Pricefx Core / Cross Module / CFG 2
Target Audience	Certified Configuration Engineer
Estimated Time to complete	0:30

Learning Outcomes

At the end of the Lab, you should be able to:

Export a Quote (or other document) to a DOC using a DOC template, and then further also to PDF.

Figure 1. Sneakpeek of a DOCX Export template with data from quote document

Pre-requisites

In order to be able to complete this laboratory exercise, please complete the prerequisites before you proceed.

Provided resources

Review the provided resources, to get familiar with their content

Quote Type "PublishingTemplates_QuoteType", to be able to create a quote document with data, used to export the Quote to XLS.

Additional Software

For this lab you will need a software, which can open, edit and save files with extension DOCX, for example MS Office or Libre Office.

User Story / Requirements

As a Sales Representative, I want to export the Quote to DOCX (and also PDF) with corporate look and feel, so that I can send the document with the offer to the customer.

Acceptance Criteria

On the Quote Detail page, the Sales Representative can export the quote to DOCX - the quote header information will be displayed together with line items info on one page
information required in the export are:
- Quote info
  - ID of the Quote
  - Quote label
- Each Line item
  - Product ID
  - Product Description
  - Negotiated Quantity
  - negotiated Sales Discount
  - Invoice price per unit
  - Total Invoice Price
The exported DOCX has corporate look and feel (at least some colors and logo)

Configuration/Implementation Steps

Prepare Simple Quote document

Before you start, quickly prepare a Quote document, which you will use for testing this Lab.

in Unity UI, navigate to Quoting › Quotes
create New Quote of type PublishingTemplates_QuoteType
set data
1. On Header tab
  1. Description to "Publishing Template Test"
  2. Customer CD-00006
2. On Items tab
  1. add Product MB-0001 with some Quantity and some small Sales Discount %
  2. add Product MB-0002 with some Quantity and some small Sales Discount %
Save the Quote
Notice the button Export appears
try click on Export, it will show the list of options - at least you should see Export XLSX

Review the Quote data structure

The DOCX Template can get the data of the Quote in 2 different ways - either the whole Quote document, or pre-processed by the supplied Preprocessing Logic. In both cases it’s important to recall the structure of the Quote document, so that you know exactly, how to retrieve the data from it.

An easy way to review the structure of the Quote document is following:

in Studio, create a new Pricing Logic of Nature "Quote Header". No elements needed.
on Parameters tab, write the ID of your Quote "Publishing Template Test" to the Quote Name input field.
Test Logic

review the data of the "Quote" result which came back. It can look something like this (Warning: this is only excerpt of the real data):

{
  "quote": {
    "uniqueName": "P-5298",
    "label": "Publishing Template Test",
    "targetDate": "2021-03-01",
    "expiryDate": "2021-03-31",
    "customerId": "CD-00006",
    "customerName": "Soupo AG",
    "quoteType": "PublishingTemplates_QuoteType",

    "inputs": [
      {
        "name": "Customer",
        "label": "Customer",
        "type": "CUSTOMER",
        "value": "CD-00006",
        "valueHint": "Soupo AG"
      }
    ],

    "outputs": [],

    "lineItems": [
      {
        "sku": "MB-0001",
        "label": "Meatball Bl",
        "inputs": [
          {
            "name": "Quantity",
            "label": "Required Quantity",
            "value": 1000
          },
          {
            "name": "SalesDiscountPct",
            "label": "Sales Discount (%)",
            "value": 0.02
          }
        ],
        "outputs": [
          {
            "resultName": "InvoicePrice",
            "resultLabel": "Invoice Price",
            "result": 6.0662,
            "warnings": null,
            "alertMessage": null,
            "suffix": null
          },
          {
            "resultName": "TotalInvoicePrice",
            "resultLabel": "Total Invoice Price",
            "result": 6066.2000,
            "formatType": "MONEY_EUR"
          }
        ]
      },
      {
        "label": "Meatball BM ",
        "sku": "MB-0002"
      }
    ]
  }
}

Prepare the data for the DOCX Template by the Preprocessing logic

In this lab, we will focus on the scenario, where the data for the template are prepared by "preprocessing" logic. In this way you have the full flexibility in preparation of the data for your template.

Note	when the pre-processing logic is not supplied for the Publishing Template, then the system will simply provide the full content of the Quote document (as in the JSON above) as data for the template.

in Studio, create a new Pricing Logic, Nature Default, name it "PublishingTemplate_Quote_Publishing_Template"
add a new Element "AbortOnInputGeneration", DisplayMode "Never", with usual code:
```
if (api.isInputGenerationExecution()) {
    api.abortCalculation()
}
```
we need to supply a header data to the template:
1. Add a new Element "Quote", DisplayMode does not matter here, but let’s set it to Everywhere.
  return api.currentItem() //(1)
  1. api.currentItem() returns the content of the whole Quote as a Map. It’s exactly in the same form as in the Header or Workflow logics - so you can refer to the JSON excerpt above to have a quick idea, what information is available.
2. Since this element is named "Quote", the content returned from this element will be accessible in the Template under Quote tag.
another thing needed is the data of the line items. Even though line items are available also without the pre-processing logic, you would not be able to reach the inputs and outputs from the template. That’s the reason, why we had to use the logic.
1. add a new Element "LineItems", Display Mode does not matter, so you can keep Everywhere
  out.Quote.lineItems.each { line -> line << line.inputs.collectEntries { [(it.name): (it.value)] } //(1) line << line.outputs.collectEntries { [(it.resultName): (it.result)] } //(2) if (line.SalesDiscountPct != null) { line.SalesDiscountPct = line.SalesDiscountPct * 100.0 //(3) } } return out.Quote.lineItems //(4)
  1. we need to move the content of Quantity & SalesDiscountPct inputs directly to the line item, so that it’s reachable by the DOCX template
  2. the same with the outputs InvoicePrice & TotalInvoicePrice, we’re putting them directly to the line item, so it’s reachable from the DOCX template
  3. the percentage value must be multiplied here, cannot do it in DOCX template
  4. return the modified line items - it’s a List of Maps
2. the content returned from this element will be accessible in the Template under LineItems tag.
Deploy the logic PublishingTemplate_Quote_Publishing_Template to the partition

Prepare DOCX Template file

create a new empty DOCX file
Add your logo into the header (or to the document content, this is up to you)
Add information from the Quote header:
1. quickly review the data in the JSON above - what’s available in the header of the Quote
2. put the replacements to the document - generally they’re in the form of {fieldName}
  1. we gave out a map named "Quote" as result of the logic. To "dive" into the content provided by the "Quote", we need to open it using {#…} and then use {/…} to close it.
  2. uniqueName contains the ID of the quote. This was available already in the data provided by the api.currentItem(), we only passed it to the DOCX template.
  3. label contains the Description of the quote. This was available already in the data provided by the api.currentItem(), we only passed it to the DOCX template.
  4. the same approach is used here for the customerName and customerId, it’s also nested inside of Quote. Look at the JSON above to understand the content.
Add information about the line items:
1. review the JSON structure for the "lineItems" plus what we’ve added there by the preprocessing logic
2. add to your DOCX document a table with 6 columns
  - Prod.No.
  - Description
  - Quantity
  - Discount %
  - Invoice Price (per unit)
  - Total Amount (i.e. Total Invoice Price)
3. add only 1 row to this table - the templating system will then repeat the line based on the data supplied.
  1. {#LineItems} - marks beginning of iteration over the list provided in LineItems. {/LineItems} - marks the end of the iteration
  2. {label} and {sku} were available on the line item already from the api.currentItem(), we only passed them to the template.
  3. Values of {Quantity} and {SalesDiscount} were added by the logic from the input fields values. Values of {InvoicePrice} and {TotalInvoicePrice} were added by the logic from the output fields values.
Save the DOCX template with name "PublishingTemplate_Quote.docx" to your local computer.

Create Template Configuration

in Unity UI, navigate to Configuration › System Configuration, and on that page open section Templates › Publishing Templates. This page serves both - templates for export of documents (which we will do here), and also templates when exporting data, for example, via a button on Dashboard.
In the dropdown Manage template that formats specific type of object, select item Quotes.
1. the list will be either empty or possibly contain some of your template you created before
Add a New template - the dialog New Template will appear:
1. Name: "Quote DOC Publishing Template"
2. Default: No
3. Convertible to PDF: YES (this will cause the Export PDF action to be available)
4. To Sign: No
5. Preprocessing Logic: PublishingTemplate_Quote_Publishing_Template
Upload your DOCX file:
1. select the line with your new Template
2. click on Upload Template
3. the browser will prompt you for a file with template - use your PublishingTemplate_Quote.docx file
4. once uploaded, notice the column Template Input Type shows "WORD" to indicate the type of template.
in Studio, fetch this new Publishing Template Quote DOC Publishing Template to your project.
1. review the content of the folder created in your project by the fetch. What files can you see there? What is in them?

Verify the functionality in UI

in Unity UI, open your quote so that you’re on the quote detail page
to ensure, the UI picks up the new DOC template and displays it in the button selector, do following:
1. reload the browser
2. recalculate the Quote
Export the Quote:
1. click on Export and then Export DOCX
2. a DOCX file will be downloaded
open the downloaded file and review it
1. you should see the header information populated with data
2. and also all your line items, created from the data by the templating system

Export the DOCX as PDF

in Unity UI, open your quote so that you’re on the quote detail page
Export the Quote:
1. click on Export and then Export PDF
2. a PDF file will be downloaded
open the downloaded file and review it - it should contain exactly the same as the exported DOCX file

Testing the Template Logic in Studio

While testing the template, you will likely do it in several rounds, so instead of always manually uploading the DOCX template, you can let Studio to deploy it.

Important: This works only after you have created the Template in UI and then fetched it to your project.

To review this functionality, do following:

in Studio, find the folder with your publishing template, and inside you will find a file template.json
open the file template.json. Ensure it opened on the tab PublishingTemplateDTO and not on the tab Text.
1. Enter the ID of your testing Quote
2. if you want your your DOCX file (in the PublishingTemplate directory) to be deployed each time when you want to render the template, then cross this checkbox. It’s handy while you’re working on the DOCX template itself.
3. click on the <MS Word> icon to start the rendering. It processes on the backend, and then opens the result DOCX on your computer. Note: Make sure you save the document before deploying.

References

Documentation

Knowledge Base

Export of PL with ResultMatrix object

External - DOCX Templates