DocX Engine Module

The DocX Report Engine resides in the Repository module and make use of a DocX file and the DS file as data to generate the required report.

The DocX engine can be invoked using either the user interface in the Repository module or through the ETL chainset in the ETL module.

The Repository module has a job queue to allow multiple jobs to be triggered on the same report. Some delay may be experienced on the return results or reports if there are jobs that need to be completed before yours could begin.

Module Interface

To use the user interface to access the DocX report engine, you need to have the privilege to access the Repository module.

Interface Description Required Privilege
Repository Allows access to Repository page. mod-repository
Repository Allows repository administrator access. mod-repository-admin
DocX Engine Allows DocX Report Engine access. mod-docx-engine

To use ETL chainset to access the DocX report engine, you need to have the privilege to access the ETL module.

Interface Description Required Privilege
ETL Allows ETL module access. mod-etl
ETL Designer Allows ETL Designer access. mod-etl-designer

Datasource Engine

A datasource (DS) file provides the configuration details to access a collection of records, for example by loading from JDBC, XLSX or MongoDB. The DS file is used by the DocX report engine to generate reports.

The DS engine can be invoked either through the user interface in the Repository module or the ETL chainset in the ETL module. For more information on the DS engine, refer to Datasource Engine.

DocX File

The DocX file is a template that contains the format and defines which DS file to use to generate the report.

It can be created using Microsoft Word from Office 2007 onwards. To view a DocX file, you may need to install the File Compatibility Pack which an be downloaded from Microsoft Download Center (http://www.microsoft.com/downloads/). If Open Office is used, the Compatibility Pack is not required for viewing.

After the DocX file is being created, place the DocX file in the Ambience Repository folder so the rendering engine can find it. See Repository on how to add a add the file into the module.

Comments

There are markers in the document that indicate the locations of the different bands of the template. In most cases, only the start of a comment and the text associated with the comment is important. For RenderIf, described later, both the start and end of the comment are important.

Some comments have special meanings to them and they are listed below.

Comment Description
Section Indicates the start of data processing.
This can be defined by any name. For example: /Elx/Section1.
Header Presents information about the particular data group being viewed.
For instance, the group name and a brief description about the data contained in the group which appears at the beginning of a new group of record. This can be defined by adding the following into the comment:
/Elx/Header
Subreport Contains data from another report.
It can be defined by adding the following:
/Elx/Subreport
RenderIf Allows for conditional rendering.
It has the same use as RenderIf in regular RML reports. This can be defined by adding the following:
/Elx/RenderIf <script>
where <script> can be any JavaScript, such as age>=18.
If the script evaluates to true then all the content between the start and end of the comment is included.
If the script evaluates to false then all the content between the start and end of the comment is skipped.
RenderIf scripts should only be used within, not across report band boundaries like /Elx/Header, /Elx/Detail and /Elx/Footer. If the script is likely to be long, it is advisable to create a function elsewhere and reference it, for example:
/Elx/RenderIf testAge(age)
instead of putting the full script in the comment. See /Elx/Script for more details on creating long scripts.
Detail Contains the main body of the report’s data.
The detail section prints individual records and repeat until all records have been printed. It can be defined by adding the following into the comment:
/Elx/Detail
Image Contains a column name, extracts the value of image as Binary Array data type from a datasource, i.e., Blob from a database, and displays the extracted value as image.
The data type of this column should by ByteArray, and its name must be consistent with the column name in the datasource. This can be defined by adding the following:
/Elx/Image/<ColumnName>
Note
Add this comment where a blob image is supposed to appear, and add a placeholder image as well. The comment should be added just before the placeholder image following the syntax above. In case the placeholder image is not replaced after rendering, check if the /Elx/Image comment is before the image in reading order (typically left/right top/bottom).
Footer Contains totals or similar information that appears at the end of each group.
This can be defined by adding the following:
/Elx/Footer
Footer/PageBreakAfter Forces a page break after each group of the report.
This is different from using /Elx/Footer comment alone, which will generate line breaks between groups. This can be dfined by adding the following:
/Elx/Footer/PageBreakAfter
End Refers to the end of the Section.
This can be defined by adding the following:
/Elx/End

Datasource

A datasource (DS) file provides the configuration details to access a collection of records, for example by loading from JDBC, XLSX or MongoDB. The DS file need to be defined in the DocX file to be used by the DocX report engine to generate reports.

Define DS File

The DS file can be defined in the DocX file by using the following:

/Elx/DataSource/<SectionName>/Name/<datasourceName>.ds

For example:

/Elx/Datasource/Section1/Name/FruitSales.ds

Define DS Parameter

This can be added using the following:

/Elx/DataSource/<SectionName>/Parameter/Name/<ParameterValue>

For example:

/Elx/Datasource/Section1/Parameter/Name/${Company}

Group and Sort Data

Grouping is done for categorization of data into various logical collection. Sorting is for arranging the data in ascending or descending order.

You can group and sort the data using the following:

/Elx/DataSource/<SectionName>/Group/<dsFieldName>/<SortOrder>

For example:

/Elx/DataSource/Section1/Group/City/Ascending

Note

There are four different types of sorting available: - Normal sorting - Ascending - Descending - Lexicographic sorting - Ascending-Lexicographic - Descending-Lexicographic

The differences between ascending/descending and ascending/descending-lexicographic: - Normal sorting follows a proper dictionary sort algorithm in which spaces are ignored. Lexicographic sorting does not follow the proper full sort definition, instead it treats every character as significant. - Dictionary normal sorting sorts in the order of symbols first followed by alphabets, ignoring any spaces between the words. Lexicographic sorting is in the order of spaces, symbols and then alphabets. - Lexicographic sorting is especially useful when sorting data that contains any symbols, abbreviation, initials and spaces.

Parameter

A parameter is “declared” when a user enters a string like ${parameterName} within a DocX report. A parameter is defined when a value is supplied. A report may have multiple declarations and mixed with normal text. Below is an example:

My name is ${first} ${last}.

There are two ways of defining parameters:

  • Define parameter individually - Defining each parameter one by one in the DocX report. It can be defined as:
    /Elx/Parameter/<ParameterName>/Value
    For example:
    /Elx/Parameter/Text/${User##MyName}

  • Load properties file - all parameters declared are to be placed in a “Properties” file together with the desired elements defined. It can be defined as:
    /Elx/ParameterFile/<Properties-FileName>.properties
    The parameters should follow the following format:
    <ParameterName>=Value.
    For example:

    Password=${Password#password#MyPassword}
    Name=${User##MyName}
    PreferredChoice=${MyChoice#choice(Apple,Orange,Pear)#Pear}
    Data=${Date#date#2011-06-01}
    Integer=${Integer#integer#20}
    Number=${Number#number#25-6}
    

Parameter Element

Each parameter can have up to three elements; name, type and default value. These elements are separated by the character #, which can be omitted when there are no subsequent elements.

Syntax Description
${name} This syntax is used to specify a parameter name.
${name#type} This syntax is used to specify the name and type of dynamic parameter.
${name#type#value} This syntax is used to specify the name, type and value.
${name##value} This syntax is used to specify the name and value.

Substitutions

You can include substitutions in table names, headers and footers, to replace variables with field values.

Before adding substitutions, ensure to define the datasource where the data comes from at the end of the DocX document. For example:
/Elx/DataSource/Section2/Name/MySample/DocX/MyDataSource.ds

Table Names

To substitute for table names, define as follows ${Section2:MyField} to allows data from other datasources to be rendered as table names, which does not have to be within one section. When the datasource is within one section (where the substitution will be included), leave out the prefix and only use ${MyField}. When the datasource is from another section, you will get the data from the first record in the table.

Headers and Footers

Similar with above, you can render data fields and parameters into headers, using ${Section2:MyField}, ${S1:Field} or other code following the syntax. When the datasource is defined within one section, remove the prefix and only use ${MyField}. When the datasource is from another section, you will get values from the first record of the referenced data table.

Scripts

You can add a script into the DocX document, by declaring them individually or by loading a script file.

Defines Individually

To define scripts individually, it can be defined as following:
/Elx/Script/<Define scripts here>

For example:
/Elx/Script/function sumFn(a,b){return a+b;}
var script2=sumFn(2,4);

To use the script in the report, enter ${=script2}.

Load Script File

To load a script file, define as follows:
/Elx/ScriptFile/<ScriptFileNAme>.js

For example:
importScript("ElixirSamples/Reports/Scripting/minusJS.js");
function sumFn(a,b)
{ return a+b; }

To use the script in the DocX report, enter the following:
${=sumFn(2,4)}

Alias

Alias are used to shorten substitutions in order to fit the available space better. For example:

${=elxfn.dataDiff(new java.util.Date(107,0,1), new java.util.Date(),'d')}

The result is probably a few integers which will fit in a table cell. However, Microsoft Word will try to show the whole substitution ${=elxfn.dataDiff(new java.util.Date(107,0,1), new java.util.Date(),'d')} in the field, which will later the layout. Therefore, for report neatness, we use substitution as an alias. Instead of a long string, we can use ${@1} (1 is used here, but any name is fine).

Note
The alteration of layout is only during the designing of the DocX report. When rendered, the tables will display according to the height and length of the text.

Hiding Processing Instructions

Processing instructions can be temporarily disabled in two ways; by adding an additional slash or the word Hide.

  • Adding additional slash - use the following syntax:

    /Elx//Datasource/Sectional1/Name/FruitSales.ds

  • Use Hide - use the following syntax:

    /Elx/Hide/Datasource/Sectional1/Name/FruitSales.ds

Formatting

Very often, substituted values need to be formatted. For example, a user wishes to show only the hours and minutes of a date, or show thousand separator and two decimal places for calculated results. This is handled by prefixing the substitution with a format string, which always begins with the character #. This follows the standard Java formatting syntax. The end of the string is marked with the | character.

Data Field

The formatting syntax for data field is as follows:

${%,.<numOfDecimalPlaces>f|<DataFieldName>}

For example:

${%,.2f|2000}

Script

The formatting syntax for script is as follows:

${%,.<numOfDecimalPlaces>f|<JavascriptHere>}

For example:

${%,.2f|=var a=2; var b=4; totalSum=a+b;}

Alias

The formatting syntax for alias is as follows:

/Elx/@/<AliasName>/%,.<numOfDecimalPlaces>f|<JavascriptHere>

For example:

/Elx/@/1/%,.2f|=var a=2; var b=4; totalSum=a+b;

Note
As Javascript has no integer type, always use %f (floating point) when referring to numbers returned from Javascript. If you refer to %d (decimal integer), an error will occur. To show a floating number as an integer, use %.0. To show a numeric figure such as 12.34, use %.2, which indicates two decimal places.

Example of DocX File

Below is an example of a DocX file. The upper part of the DocX file defines the format of the report. The first line below the table defines the location of the DS file. The rest defines the order and the format of the fields used.

The DS file must reside in the location defined in the DocX file, otherwise an empty report will be generated.

Generate DocX Via Repository

To generate the report using the user interface of the Repository module, select the DocX document and click the “Render” button.

The DocX Report Engine page will appear.

Key in the desired city in the “city” field. In the “Render as” field, select the desired output format. Currently only DocX format is supported. Click on the “Render” button.

In the example below, the city defined is “Haney”. The report is generated using the DS file as content and the DocX file as template.

Generate DocX Via ETL

Another alternative way to generate DocX report is to use the ETL chainset.

In the simple example below, the ETL chainset generates the DocX report and writes to a DocX file.

This ETL chainset performs the following:

  • Reads in a JSON record indicating the DocX file and the required parameters
  • Generates DocX report using the parameters in the JSON record, as well as the parameters defined in the DocX file
  • Writes the output file to the desired location and filename

Click on the “Run Steps” icon to generate the DocX report.

Examples

The following sub-sections are examples of how reports can be generated using some DocX template elements.

Render DocX with New Line Substitutions

In this example, the parameter ${text#textarea:5} is used on the DocX file. Below is the sample code in the DocX file.

/Elx/Parameter/text/${text}
/Elx/Parameter/text2/${text2#textarea:6}
Here we have a simple example of mail merge where ${text] is passed in as a parameter.
We also pass in ${text2} from a teatarea, so that it can contain newlines.

Save the above code in a DocX file (in this case, its NewLines.docx) and load it into the Repository module. In the Repository module, select the above DocX file and click on the “Render” button.

The DocX Report Engine page will appear.

In the “text” and “textarea” fields, key in some text. Below is an example.

Click on the “Render” button to render the report. The report generated as per the screenshot below.

The text entered into the fields are substituted into the report.

Render DocX with New Line in Datasource

In this example, the datasource (DS) file is used to tabulate tables in the DocX file. Below is the sample DocX file.

Save the DocX file (in this case, its NewLine_Table.docx) and load it into the Repository module. Ensure the DS file is in the location specified in the DocX file in the Repository module. In this example, the location is QA_Samples/DocX/datasource/NewLine.ds. In the Repository module, select the above DocX file and click on the “Render” button.

The DocX Report Engine page will appear.

Click on the “Render” button to generate the report. The report generated is as per the screenshot below.

Render DocX with RenderBlockIf Scripts

There may be a situation where you wish to generate a report for certain data, not all the data in the datasource file. In this case, you can use script to limit the data to be used in the report.

For example, a datasource contains information on companies and the product they sell. You wish to generate report for all companies except Company B. You can use a script to limit the data.

Below is an example of the DocX file named RenderBlockIf.docx.

Place the DocX file into the Repository module and render the report.

In the DocX Report Engine page, click on the “Render” button.

The generated report contains all companies except Company B as indicated in the script in the DocX file.

Customise Data Picker Via Script

Some RML or DocX report needs to input date or to pick a date. The default date can be initiated using a properties file.

In this simple example, a DocX report requires to select a date for delivery.

The default date is initiated using a properties file with the following code.

DeliveryDate=${Delivery Date#date#2008-10-01}

Render the DocX file in Repository. In DocX Report Engine page, the “Delivery Date” uses the initial date in the properties file.

If the date is unchanged, the report generated uses the date from the properties file.