Creating templates requires basic knowledge of Microsoft Word ® and a little knowledge of Docati. For the latter, all you need is this section of our site.
The Quick-Start Manual is a MUST-READ! It consists of a set of exercises that will teach you step-by-step how to create Docati templates.
Even if you haven’t decided to use Docati, these exercises can give you a great impression of how Docati works and what scenarios are possible!
Open the Quickstart-Manual!
Available placeholders are:
ValueOf: inserts data
Does what document generation is all about: insert data. By default data is inserted as-is (text). However it’s also possible to specify formatting options, which allows for formatting as a number with a certain amount of digits, a date/time and even allows you to provide a custom formatting string.
ForEach: repeats its contents for each data-item
A very powerfull placeholder which allows for iterating over a set/list of data and will create for each item a table row, list-item (eg: for a bullet list), chapters/paragraphs, etc. Items in the list can also be sorted first.
ImageOf: insert an image
Just like ValueOf/Value this placeholder inserts content into the document. Instead of just text, this placeholder inserts an image. The image can be provided within the data (base64-encoded)
or referred to using an URL. Image width and height can be manually set, but it's also possible to keep the aspect ratio correct, by locking it to either the width or the height of the placeholder.
If: only renders its content if the condition is met
Allows for conditional parts of the document, eg: a specific chapter only appears if the data contains a specific element.
UseContext: specifies the data-context
For more experienced users (with xpath-knowledge): when processing its contents, the data-context is set in advance. This allows for shorter/easier data-queries for its child placeholders, thus resulting in better maintainability of the template.
ImportTemplate: imports a (sub)-template
A powerfull placeholder that allows you to create templates templates that you can reuse (like sub-templates), for example: a standard header template, a address-block template, etc. Templates can be imported in the main document, header and footer. The ImportTemplate-placeholder can also be used inside a ForEach- or If-placeholder.
Placeholders that work with data need to be told what part of the dataset to use. This is done by specifying a 'query'. To make it more concrete: the dataset is provided as an XML-structure (json is internally converted to XML) and the query specifies which part of that XML-structure is relevant for the placeholder.
Docati supports queries in two variants:
Regular: Only the name of the desired node is specified. Docati will search for any elements or attributes which match that name. The search is case-insensitive and ignores namespaces.
Regular queries are so easy to use that these can be used without support of IT-personnel.
Advanced: XPath-query. XPath is a complex XML query-language, yet very powerfull. If you know XPath, you probably prefer advanced queries. Advanced queries are slightly faster than regular queries. Advanced queries are required when using custom functions (like setop(…), current(…), etc).
Docati supports the XPath 1.0 specification.
Both type of queries search within the complete XML, unless a context-node is active (eg by using the UseContext or the ForEach placeholder).
For example, take this data-XML::
If you need the name of the examinee, these are the queries you would specify:
- Regular: Name
(or when namespaces are specified in the XML: /d:exam-result/d:name)
Regular and advanced queries can be combined. This means it is fine to use regular queries most of the time and use advanced queries for more complex situations only.
Namespaces (advanced queries only)
When the data-XML contains namespaces, querying becomes slightly harder. Regular queries still work great, but advanced queries require the use of namespace prefixes (even if the namespace is defined as the default namespace (xmlns="...")).
The namespaces that are used in the queries, must be registered in the template ("Template Settings" on the Docati-ribbon of the Word add-in): for each namespace a prefix is specified which can then be used in the queries. This prefix does not need to be the same as the one used in the data XML, but it usually more clear to use the same prefixes.
When generating a document, Docati automatically registers the namespace of the root-element of the data-XML with the prefix d (which stands for 'default'). If that is the only namespace used in the data XML, there's no need to explicitly register the namespace.
This also means the template will keep working fine when the namespace of the data XML changes after some time.
Namespaces are complex stuff, so lets put all situations together:
Data XML uses NO namespaces:
Don't use prefixes in your queries.
Data XML uses a SINGLE namespace:
Use the prefix 'd' that is auto-registered by Docati during document generation.
Data XML uses MULTIPLE namespaces:
Register each namespace and supply a prefix for each. Use these prefixes in the queries.
If the prefix 'd' is not explicitly registered in the template, Docati will still register it itself. So the 'd' prefix can still be used.
When the data was provided in json-format, Docati will internally convert it to XML. This XML does not use namespaces.
Docati can be integrated natively in .NET applications by using the Docati.Api NuGet-package. A code sample can be found here. Remember to add your own (trial) licensefile to the project.
A webservice is also available and provides an API which can be used to integrate with you own solutions. It uses widely adapted standards and is supported in practically any programming environment:
- SOAP-endpoint (with MTOM-support)
- REST-endpoint, supporting both XML and Json
The SOAP-endpoint has a well described interface (WSDL) and is preferred by most people. However, the REST-endpoint supports the use of json and therefore comes with less message overhead. Since request can become quite large (because of the data inside), json may be a better choice.
You can download the WSDL for the SOAP-endpoint by navigation to the endpoint itself and supply "?singleWsdl" at the end. Eg, when the service is installed on you local machine, the URL would be: http://localhost/docati/docgen/v1.svc?singleWsdl.
The SOAP-endpoint are actually two separate endpoints: one that uses MTOM for efficient streaming of data and another regular ‘text’ endpoint to make sure less sophisticated application platforms can use the API as well.
The REST-endpoint does not come with a strict contract description. However, the SoapUI sample project contains a few examples that are pretty self-describing (see below).
Whatever API and endpoint you choose, logically they are similar since they all publish a single operation: GenerateDocument.
It takes a single argument of type GenerateDocumentRequest, which contains all information that needs to be supplied:
Name of the template, includings its extension, eg: Order4.docx
Order4.docx is the template that is created in the last exercise of the Quickstart-manual. A clean installation of the Docati-service includes this template, so the service can be easily tested after installation.
The data to be merged with the template is provided as either XML or json (either DataXML or DataJson must be provided). If data is provided in the json-format, Docati will internally convert the json to XML.
When using the SOAP-endpoint, the data needs to be properly escaped (if your platform doesn't do this automatically already), because in the contract it is specified as xs:string (eg: <exam-result />). The REST-endpoint can use inline json (no escaping is needed).
No choice-construct was used in the WSDL/XSD because this is not very well supported on many application platforms.
The desired outputformat for the generated document. Currently supported formats are:
Internally the Docati-service will always first generate to Word. If a different outputformat was specified, the generated Word-document is then converted to the desired format.
When specified, the generated document will be password-protected (encrypted): the correct password must be provided in order to be able to the document. Password-protection is supported for both Word and PDF.
To get started quickly, sample code is provided here. Choose whichever fits you best: