Technical manual CIB jsMerge

Scope Of Delivery

CIB jsMerge is delivered as a binary module, in the form of DLLs or shared libraries (Unix).

Also part of the package are the header and library files for C(++) programming as well as a version history.

Introduction

CIB jsMerge is a central component within the CIB office modules (CoMod) and is used to create dynamically generated documents using ODT file formats and JavaScript.

XML based open document formats like Open Document and Office Open XML are getting more and more popular, especially since Microsoft decided to use Office Open XML as the standard format for current versions of Microsoft Office.

Thus, for text programming, XML based open document formats are becoming an alternative to the commonly used Rich Text format (RTF).
Various CIB modules currently process documents in the RTF-format, CIB jsMerge now adds the processing of ODT and DOCX formats.

CIB jsMerge interprets field instructions in document templates and merges with optional variable data. The resulting document contains the resolved field instructions and the additional merged data. This variable data can be supplied via CSV or XML files.
Currently the ODT format is supported for templates. Using DOCX templates is possible but not fully implemented yet.

This document provides information about implementing CIB jsMerge into an existing technical architecture and calling CIB jsMerge. For detailed text programming related information (field instructions, examples and conventions) please refer to the document "CIB jsMerge Command Reference".

System-Platforms

CIB jsMerge runs on MS Windows 7 and higher and is available for Linux platforms.

For additional information please see section “scope of delivery”.

Additional modules

Following the modular approach of the CIB office Modules (=CoMod), additional components are available for CIB jsMerge that make it easier for the developer to integrate CIB jsMerge into their preferred architecture or can extend functionality.

Detailed descriptions of all additional products are available in separate technical manuals. Please visit the CIB documentation website https://www.cib.de/de/support/dokumentationen.html for additional information about these CIB modules. For further questions, please do not hesitate to contact CIB support.

• CIB runshell

CIB runshell is a commandline tool to control all CIB products that are available as DLLs or shared libraries. In a CIB runshell call it is possible to set all properties of a specific CIB office Module that are available to the user.

CIB runshell is perfectly suited to be used within (batch) jobs and for creating your own processes (instances) with the CIB modules.

• CIB job

CIB job can receive a task description in XML format that contains a formal description of the inputs, outputs, options and even data (XML-based task processing). The XML file describing the task (job file) is created by the user. It contains all the job steps that have to be executed by the called modules (CIB jsMerge, CIB format, etc.).

CIB job processes this job file step by step.

Data Supply

In addition to interpreting field instructions like conditions, loops, expressions and include-statements, the merging of variable data is a central task of CIB jsMerge.

There are 2 different kinds of data sources:

• The data is structured using the CSV format (with the possibility of using multiple CSVs in a structure)
• The data is structured using the XML format.

CSV

CSV files are one ore several textfiles that contain the names of input fields and the respective values. The Acronym CSV means "comma separated values".

The first line of the control data file contains the control data record that is made up of field names, seperated by a ";". The control data record can hold any amount of field names, only limited by available memory.
Every following line exists of exactly one data record. A data record contains the templates or data that is to be included in the same order as the field names, separated by ";". The number of entries in a data record has to match the number of fieldnames in the control data record.
CIB jsMerge can process a single CSV file or multiple, so called multi-CSV files.

The property "datafile <datasource>" sets the required CSV file for CIB jsMerge.

Notes about special characters

If a text snippet contains semicolon, tabstop or quotation mark, the whole snippet has to be put in quotation marks. Quotation marks in a text snippet have to be doubled.

Example:

If you want to insert the company name Yachting "Black Pearl" into a template, the entry in the CSV control file has to be in the following form: ; "Yachting ""Black Pearl"""; .

UTF-8 encoded Data-CSVs

The CSV file and the provided data have to be UTF-8 encoded.

Single-CSV-file

Description:

In a single-CSV-file the values are directly associated to the input fields. The user has access to the values directly via the field name in the template.

Multi CSV file

Description:

A multi CSV file enables managing several CSV files. It contains the names of all CSV files that should be loaded in the current merge run. Via the fields in the header of the multi CSV file every CSV file is assigned an alias that can be referenced in a document and grants access to a specific CSV file.

Usage with CIB jsMerge:

To use a multi CSV data supply the properties "datafile" - specifiying the multi CSV file - and "multidatafile" have to be set.

Advantages to XML:

• Simple format
• Simple 1-n relation
• Smaller filesize

XML

Additional XML components

XML data supplies are supported via additional DLLs that have to be installed along with the CIB jsMerge DLL. These additional DLL files are included in the CIB jsMerge packages and are only called dynamically by CIB jsMerge if a XML datasource is used.

XML-Characteristics

XML-documents have a physical structure and a logical composition.

The physical structure of a XML document is made up of:

Entities. The first entity is the main file of the XML file. Additional possible entities are:

Strings, embedded via entity references (&name; for a document or %name; for the document type definition),

References to strings to embed single characters that are referenced via there number (&#decimalnumber; or &#xHexadecimalnumber;).

A XML declaration is optional to specify the XML version, character encoding and processing without document type definition.

A document type definition is used to specify entities and their allowed logical structure.

The logical structure of a XML document is a tree structure and thus hierarchical. The nodes can be following elements:

• Elements that can be marked with a matching pair made up of a start tag (<Tag-name>) and an end tag (</Tag-name>) or and empty element tag (<Tag-name/>)
• Attributes as key-value pairs (attribute-name="attribute-value"), providing additional information about elements (a kind of meta informaton)
• Processing instructions (<?Target-name parameter?>)
• Comments (<!--comment text-->)
• Text, either as normal text or as a CDATA section (<![CDATA[any text]]>)

A XML document has to have exactly one element on the top level. Below this document element more elements can be nested.

Usage with CIB jsMerge:

The Property datafile <data source> sets the XML-file for CIB jsMerge.

XML file

Multi-XML file

Advantages over using CSV:

• Less files
• Works with nodes internally
• With XPATH in XML, structures in the document can be simplified.

Many of these properties are optional, some are mandatory.

Properties

The following chapter describes all available properties that can be specified in a CIB jsMerge call.

Supported Properties Overview

Property datafile

Filename of the data supply.
Data supply can be a CSV file or a XML file. These files contain data that is used later on in the root document or it‘s embedded templates.

Syntax

datafile=<datafile-name> 

Example

datafile=Testdata/Customers.csv

Property Headerfile

The property "headerfile" can be used when the data supply is realized via XML. The property points to the datafile that is set. It is normally used for multidatafiles:
If “headerfile“ is used in combination with the property “multidatafile”, “datafile” returns the XPath to the multi node. Using the property with a CSV data supply is not recommended.

Syntax

headerfile=<datafile-name>

Example

headerfile=Testdata/Customers.xml
datafile=//multi
multidatafile=1

Property ignoreInvalidXMLCharacters

This Boolean property filters invalid XML characters from the data supply.
If it is set to “1”, invalid XML characters are filtered from the data supply. If this property is set to “0”, CIB jsMerge returns an error if invalid characters are found.
For valid/invalid characters please look at XML-Spezification  http://www.w3.org/TR/xml/#charsets

Syntax

ignoreInvalidXMLCharacters=0

Property inputfile

Filename of the root document.
Use this property to set an .odt file for inputfile. This file represents the root document. Additional documents (templates) can be included in the the root document.

Syntax

inputfile=<inputfile-name>

Example

inputfile=templates/letter.odt

Property LicenseCompany

This property sets the licensee from the license information. This property has to be set in a CIB jsMerge call.

Syntax

licenseCompany=CustomerLicensee

Property LicenseKey

This property sets the license Key from the license information. This property has to be set in a CIB jsMerge call.

Syntax

licenseKey=xxxx-xxxx-xxxxxxxx

Example

LicenseCompany=CIB software GmbH
LicenseKey=4444-cccc-88888888

Property logfile

The property “logfile” sets the filename (and path) for error logging. This logfile is written by CIB jsMerge each time. The property cannot be set via the script file.
If there is no error, an empty logfile is created.

Any existing logfile with the same name will be overwritten.

Syntax

logfile=<Error logfile>

Example

logfile=error.log

Property loglevel

Via the property “loglevel” it is possible to set the type and amount of error messages in the logfile. This property cannot be set via the script file. The more general the level that is set, the larger the logfile gets.

If no “loglevel” is set, the default level “INFO” is used.

Syntax

loglevel=<level>
<level>: FATAL | ERROR | WARN | INFO | DEBUG | TRACE | ALL

Example

loglevel=INFO

The messages FATAL+ERROR+WARN+INFO are output.

Property Multidatafile

Flag to indicate a multi data supply.
If the CSV or XML file that is used is a multi data supply, this property has to be set to “1”.

Syntax

multidatafile=1

Property outputfile

The intended output filename of the resulting document can be specified by this property. The resulting document contains all the information merged from templates and the data supply.

Syntax

Outputfile=<outputfile-name>

Example

outputfile=templates/output.odt

Property scriptfile

Filename of the script file.
Global functions, written in the scripting language JavaScript can be defined in the script file. These global functions then are available in all templates.
In addition most properties mentioned in the previous chapters can be set in the scriptfile.
The scriptfile has to be UTF-8 encoded.

Syntax

scriptfile=<scriptfile-name>

Example

scriptfile=script.js

Calling CIB jsMerge

CIB jsMerge can be called as CibJSMerge32.dll via CIB runshell or CIB job. The properties that can be passed in these calls are listed and described in detail in chapter Properties. To call CIB jsMerge from your own application using the CIB jsMerge API, please refer to chapter Technical Interface.

CIB runshell

CIB jsMerge can be called via CIB runshell as follows:

Cibrsh.exe <property1>=<value1> <property2>=<value2> -js [<inputfile name><outputfile name>]

Example 1:

Cibrsh.exe scriptfile=myScript.js licenseCompany=licensee licenseKey=xxxx-xxxxx-xxxxxxxx datafile=data.csv –js input.odt output.odt 

When calling via CIB runshell it is possible to insert "inputfile name" and "outputfile name" via property using prefix “inputfile=” and “outputfile=”:

Example 2:

Cibrsh.exe scriptfile=myScript.js licenseCompany=licensee licenseKey=xxxx-xxxxx-xxxxxxxx
datafile=data.csv inputfile=input.odt outputfile=output.odt –js

Notes:

The properties licenseCompany and licenseKey have to be set for every call.

Properties can be set directly in the CIB runshell call (command line) or in the script file. The following rules apply:

• If properties are set directly in the CIB runshell call, they by default take precedence over script file properties.
• If the properties set in the scriptfile should take effect, the override-parameter within the setProperty() command has to be set to "true".

Example:
For the CIB runshell call already shown above

Cibrsh.exe scriptfile=myScript.js licenseCompany=licensee licenseKey=xxxx-xxxxx-xxxxxxxx datafile=data.csv
inputfile=input.odt outputfile=output.odt –js 

The following is set in the script file "myScript":

setProperty("inputfile", "./differentInput.odt", true);
setProperty("outputfile", "differentOutput.odt", false);
setProperty("datafile", "test/differentData.csv");

In this example the input file "differentInput" from the script "myScript.js" is passed to CIB jsMerge because the override-parameter was set to "true". The property passed via the direct command line CIB runshell call is ignored in this case.

The outputfile "output.odt" and the data source "data.csv" are passed as specfified in the direct command line CIB runshell call because the properties’ override parameters set in the scriptfiles are either set to "false" or have no override-parameter set.

CIB job

Support of CIB job interface is in the pipeline.

Setting Properties via Scriptfile

Most properties mentioned in the previous chapters can also be set in the scriptfile.

Example Scriptfile example.js:

setProperty("licenseCompany","Companyname", true);
setProperty("licenseKey","xxxx-xxxx-xxxxxxxx", true);
setProperty("inputfile", "./filename.odt", true);
setProperty("outputfile", "filename_out.odt", false);
setProperty("datafile", "testfolder/control.csv");
setProperty("multidatafile", "1");

Note:

The properties "logfile" and "loglevel" currently can not be set via the scriptfile.

When calling CIB jsMerge via CIB runshell, the properties set directly in the CIB runshell call take precedence by default unless the override parameter is set to "true" within the scriptfile setProperty() call.

Technical Interface

This chapter provides an overview of the available API and its parameters.
These functions are also described in the headerfile that is delivered with your version of CIB jsMerge.

The basic steps for initiating a CIB jsMerge run are:

• Creating a job handle
• Setting (getting) the required properties for the task
• Executing the job
• Getting error information
• Releasing the job handle

The required functions and calls will be described in the following chapters.

CibJsMergeJobHandle

Every CIB jsMerge task is assigned a "job handle" that is of the type CibJsMergeJobHandle. This object represents the task. The steps

• setting and reading properties (CibJsMergeJobSetProperty/CibJsMergeJobGetProperty)
• executing the task (CibJsMergeJobRun)
• Getting error information (CibJsMergeJobGetErrorCode/CibJsMergeJobGetErrorMessage)

Always refer to such a job handle.

A CIB jsMerge task is initiated by creating a Job handle (CibJsMergeJobCreate). After setting the necessary properties and running the task the job handle is released again (CibJsMergeJobFree).

CibJsMergeJobCreate

unsigned int CibJsMergeJobCreate( CibJsMergeJobHandle* a_Handle );

This method creates a job handle. It should be released again with CibJsMergeJobFree after the task is completed.

CibJsMergeJobSetProperty

CibJsMergeJobSetProperty( CibJsMergeJobHandle a_Handle, const char* a_Name, const char* a_Value );

This function allows setting additional properties for a merge run. The names and values are expected to be UTF-8 encoded zero terminated strings.

CibJsMergeJobSetPropertyW

unsigned int CibJsMergeJobSetPropertyW( CibJsMergeJobHandle a_Handle, const wchar_t* a_Name, const wchar_t* a_Value );

This function allows setting additional properties for a merge run. The names and values are expected to be zero terminated wide strings.

CibJsMergeJobGetProperty

unsigned int CibJsMergeJobGetProperty( CibJsMergeJobHandle a_Handle, const char* a_Name, char* a_Value, size_t a_MaxLength );

This function returns the property values that are currently set. The returned names and values are zero terminated strings in UTF-8 encoding.

CibJsMergeJobGetPropertyW

unsigned int CibJsMergeJobGetPropertyW( CibJsMergeJobHandle a_Handle, const wchar_t* a_Name, wchar_t* a_Value, size_t a_MaxLength );

This function returns the property values that are currently set. The returned names and values are zero terminated wide strings.

CibJsMergeJobRun

unsigned int CibJsMergeJobRun( CibJsMergeJobHandle a_Handle );

This function executes the CIB JsMerge Job.

CibJsMergeJobGetErrorCode

unsigned int CibJsMergeJobGetErrorCode( CibJsMergeJobHandle a_Handle, int * a_ErrorCode );

This function gives access to the current error state of CIB jsMerge after executing various functions.

CibJsMergeJobGetErrorMessage

unsigned int CibJsMergeJobGetErrorMessage( CibJsMergeJobHandle a_Handle, char* a_pText, size_t a_MaxLength );

This function returns the error text that is output after executing a function.

CibJsMergeJobFree

unsigned int CibJsMergeJobFree( CibJsMergeJobHandle* a_Handle );

This function frees the created CibJsMergeJobHandle and other resources allocated by CIB jsMerge.

CibJsMergeGetVersion

unsigned int CibJsMergeGetVersion( unsigned int *a_pVersion );

This function provides access to the current CIB jsMerge version number as an integer.

CibJsMergeGetVersionText

unsigned int CibJsMergeGetVersionText( char* a_pText, size_t a_MaxLength );

This function provides access to the current CIB jsMerge version number as a string.

Returncodes

The following error codes can be returned. The description does not necessarily match the text of the output error message.

C++ Example

#include <iostream>
#include "CibJSMerge.h"
 
#define BUFSIZE 4*1024
 
int main(int argc, char** argv)
{
      CibJsMergeJobHandle job = NULL;
      int errorCode;
      char buf[BUFSIZE];
      int res = 0;
 
      try
      {
            if( CibJsMergeJobCreate(&job) != 0 )
                  throw std::string("could not create merge job");
 
            if( CibJsMergeGetVersionText(buf, BUFSIZE) != 0 )
                  throw std::string("could not read version text");
            std::cout << "Using version: " << buf << std::endl;
 
            // set some properties
            res += CibJsMergeJobSetProperty(job, "licenseKey", "xxx");
            res += CibJsMergeJobSetProperty(job, "licenseCompany", "yyy");
 
            res += CibJsMergeJobSetProperty(job, "inputfile", "input.odt");
            res += CibJsMergeJobSetPropertyW(job, L"outputfile", L"out.odt");
 
            if( res != 0 )
                  throw std::string("could not set the required properties");
 
            if( CibJsMergeJobRun(job) != 0 )
            {
                  if( CibJsMergeJobGetErrorCode(job, &errorCode) != 0 )
                        throw std::string("could not read the error code");
 
                  if( CibJsMergeJobGetErrorMessage(job, buf, BUFSIZE) != 0)
                        throw std::string("could not read the error message");
 
                  std::cout << "Error " << errorCode << ": " << buf << std::endl;
            }
            else
                  std::cout << "OK: Finfished successfully" << std::endl;
 
      }
      catch( std::string &e )
      {
            std::cout << "Exception: " << e << std::endl;
      }
 
      if(job)
            CibJsMergeJobFree(&job);

}