This Web service is used to execute the APE's merge step.

Input message format

The JSON input message format is as follows:

{
"jsonDataModel": {},
"locale": "string",
"mimeType": "string",
"namespace": "string",
"options": {},
"templateName": "string"
}

When the Web service runs without error, the returned HTTP code is 200 and the response is an XML document (when an .ftlx template is processed).

If there is an error, the returned HTTP code is either 400 if the query body is incorrect, or 500 when an error occurs during template processing. If there is an error, the returned response is JSON type.

↑ Top of page

Attributes

The message must represent a JSON object with the following attributes:

templateName

This attribute is mandatory and String type. It represents the template name (file name.ftlx). See "Template" section in "Apache FreeMarker Template Engine".

namespace

This attribute is optional and String type. It represents the namespace used by the engine to look up the template. See "Template loader" section in "Apache FreeMarker Template Engine".

jsonDataModel

This attribute is mandatory and Object type. It represents the data model which will be used by the engine to process the template. See "Data model" section in "Apache FreeMarker Template Engine".
Table of correspondences between FreeMarker data types and JSON data types:

FreeMarker type	JSON type
String	String
Number	Number
Date	String or Number according to the type of transformation used. See option jsonPathConv.
Time	String or Number according to the type of transformation used. See option jsonPathConv.
Date-time	String or Number according to the type of transformation used.See option jsonPathConv.
Boolean	Boolean
Hash	Object
Sequence	Array

↑ Top of page

locale

This attribute is optional and String type. It represents the locale used by the engine to look up and process the template. See "Locale" section in "Apache FreeMarker Template Engine". If this attribute is not specified, the JVM default locale is used. The alphanumeric string representing the locale must be in IETF BCP 47 format.

mimeType

This attribute is optional and String type. It represents the MIME type of the Web service response.

FreeMarker is configured to automatically return a MIME type according to the file extension of the executed template:

.ftlx: application/xml (charset=UTF-8) type response
.ftlh (HTML document template): text/html (charset=UTF-8) type response
.ftlx (XML document template): application/xml (charset=UTF-8) type response

A value does not, therefore, need to be set for this attribute when executing .ftlx templates.

When using this Web service outside the APE (to merge data with a CSV template for example), a value needs to be set to this attribute ("text/csv" for example).

↑ Top of page

options

This attribute is optional and Object type.

It represents the additional parameters to take into account when processing the template.

extOutputTransform
Result document formatting option (JSON String type)
jsonPathConv
Option to convert data from the data model before it is processed by the template (JSON Object array type)
jsonGenerator
Option to produce a fake data model used in place of the data model in the template development phase (JSON Object type).

↑ Top of page

Headers

Some headers can be added in the HTTP request which triggers this web service. These headers are treated as additional input or input/output parameters:

Name

Type

Description

Ape-Template-Url

Input/Output

When it is present in the request, it is returned in the response with the value of the URI of the template file executed to produce the document.

The URI syntax depends on the type of template loader (template loader key in freemarker.properties) which loaded the template:

if FileTemplateLoader: the URI syntax is file:/<template URL>,
if ClassTemplateLoader: the URI syntax is jar:file:/<URL of the jar file containing the template>!/<Template path in the jar>,
if ZipFileTemplateLoader: the URI syntax is jar:file:///<URL of the zip file containing the template>!/<Template path in the zip>.

Notes:

The non-ASCII characters of the URI are encoded according to RFC 2396 (e.g. a space is replaced by the %20 string; the é character is replaced by the %C3%A9 string). The VatoolBx VaToolBxJavaDecodeURL function decodes the URI.
If the requested template is localized, the file URI will point to the one which corresponds to the requested locale. For example, if the "templateName" parameter of the JSON message is "foo.ftlx" and the "locale" parameter is "it", if there is a "foo_it.ftlx" file, the URI will point to this file (otherwise, it will point to the "foo.ftlx" file).
If there is an error, the returned alphanumeric string is empty.

Ape-Template-Loader

Input/Output

Description in JSON format of the template loader which loaded the template. The JSON object has several properties which depend on the template loader type:

if FileTemplateLoader:

{
 "classname":"com.hardis.adelia.mergedocengine.freemarker.conf.FileTemplateLoader", 
"baseDir":"file:/<absolute URL of the baseDir parameter in the template_loader key>", 
"disableCanonicalPathCheck":<true or false: value of the disableCanonicalPathCheck parameter in the template_loader key> 
}

Non-ACSII characters of the baseDir property are encoded according to RFC 2396 (see above).

if ClassTemplateLoader:

{ 
"classname":"com.hardis.adelia.mergedocengine.freemarker.conf.ClassTemplateLoader", 
"resourceLoaderClass":"<value of the resourceLoaderClass parameter in the template_loader key>", 
"basePackagePath":"<value of the basePackagePath parameter in the template_loader key>" 
}

if ZipFileTemplateLoader:

{ 
"classname":"com.hardis.adelia.mergedocengine.freemarker.conf.ZipFileTemplateLoader",
"schemeFileURI":"<value of the schemeFileURI parameter in the template_loader key>", 
"basePackagePath":"<value of the basePackagePath parameter in the template_loader key>", 
"useCache":<true or false: value of the useCache parameter in the template_loader key> 
}

Non-ASCII characters of the schemeFileURI and basePackagePath properties are encoded according to RFC 2396 (see above).

Note: if there is an error, the returned JSON value is "null".

↑ Top of page