Document Creation Services 1.1 technical documentation

About this article

This article explains the technical part of the Document Creation Services 1.1 integration.

The Document Creation Services 1.1 integration is based upon the StUF standard. StUF stands for: Standaard Uitwisseling Formaat - Standard Exchange Format.

Sections in this article:

• Configuration of Document Creation Services 1.1
• Authentication
• Users
• Templates
• Difference between synchronous and asynchronous
• Extensions - Extensie #3 (Extension #3)
• Technical architecture
• Web services

 

The StUF standard is a Dutch standard hence abbreviations and names in this topic are in Dutch.

 

Prerequisites

Templafy Hive App Connector module is enabled Document Creation Services 1.1 is enabled under Integrations

 

The Templafy document creation service is based on the specification standard from VNG (Vereniging van Nederlandse Gemeenten - Association of Dutch Municipalities). More information about the standard can be found on these websites (Dutch language only):

• Documentcreatie services
• Specificatie Documentcreatieservices v1.1

The VNG test report for Templafy can be found here: www.softwarecatalogus.nl/pakket/templafy.

 

Configuration of Document Creation Services 1.1

The Templafy Admin configures the Document Creation Services 1.1 integration in Templafy Admin:

 

• For every application (DCV), a Document Creation Services (StUF-DCR) app connector configuration needs to be created, because the endpoint of the DCV and the corresponding certificate must be set.
• Organization: In the message that is sent to the service, a sender-organization (in Dutch 'zender-organisatie') must be specified. The value of the element is used to identify the organization in Templafy.
• Application: In the message that is sent to the service, a sender-application (in Dutch 'zender-applicatie') must be specified. The value of the element is used to identify the application within the organization.
• The Endpoint of the service (URL) is dynamic and is generated per app connector configuration.
• The Callback URL is provided by the requesting applications (DCV) to be linked.
  
  
  

 

Authentication

The service uses TLS two-way authentication. This means that the client is sure they connect with the right server and that the server is sure of the identity of the client calling it. The image below shows a simplified picture of the authentication:

 

 

• Steps 1 to 3 are handled by the https mechanism. The storage of the server certificate is in Templafy's hosting environment. This certificate at https://templafyprod1.stuf.templafy.com/ is the public server TLS certificate of Templafy and needs to be trusted by the requester (DCV).
• In step 5 Templafy verifies the received client certificate with the certificate stored in Templafy for the specific endpoint. This saved certificate is an export of the original certificate without the private key (file format is .cer or .crt).

When using asynchronous request handling, the Templafy service will send the result (a document) to the requester (DCV) by calling the return service (DCV service). In this case Templafy is the client and the DCV is the server. See the image below:

 

 

• Steps 1 to 3 are handled by the https mechanism.
• In step 4 Templafy sends its client certificate (this is the outbound certificate of Templafy, that is set per environment/endpoint).
• In step 5 this client certificate is validated. During the configuration of the link, an export of this certificate has been handed over to the DCV (and added to its environment/application).

 

Users

In the message that is sent by the DCV the organization and application are specified. In addition, the user must also be included in the message, so that it can be validated whether the user is authorized to use the specific template. The user in the message must contain the User Principal Name (UPN).

 

Templates

The templates in Templafy are specified in the message based on their unique ID (URI, Unique Resource Identifier, or more specific: URN, Uniform Resource Name). In the calling application (DCV), this ID must be set so that a document is created from the linked template. Linking templates in the application is application specific.

 

Difference between synchronous and asynchronous

Document creation can take place in various ways. This handling is set per template. The standard describes two mandatory options for the document creation process: synchronous and asynchronous processing. The standard also has the optional variant #3 - user interaction during creation.

 

Synchronous

In synchronous processing, the request is immediately responded to and a document is immediately created - without user interaction - and returned to the requester.

 

1. The DCV sends a request to create a document (start message 'verzoekStartenDocumentcreatieDi02').
2. Templafy (DCA, Document Creatie Applicatie - Document Creation Application) responds immediately and returns a message with the document (result message 'verstrekDocumentcreatieResultaatDi01' including BLOB).

 

Asynchronous

In asynchronous processing, Templafy (DCA) returns a message that the request has been received. The document is not immediately created and returned (although there is usually not much time difference in between). When the DCA creates and returns the document, it will also be accompanied by a message. In this case no user interaction takes place either.

 

1. The DCV sends a request to create a document (start message 'verzoekStartenDocumentcreatieDi02').
2. Templafy (DCA) responds and returns a result message (result message 'leverDocumentcreatieResultaatDu02').
3. After creating the document (without user interaction) Templafy (DCA) returns a message with the document (result message 'verstrekDocumentcreatieResultaatDi01' including BLOB).
4. In response, the DCV sends an 'empty' confirmation (Bv03).

 

Extensions - Extensie #3 (Extension #3)

Extensions are optional functionalities that the standard offers. These functionalities are not mandatory in order to comply with the standard. Templafy supports extensie #3 - Opnemen resultaatURL in bericht (extension #3 - Include result URL in message) 'verstrekDocumentcreatieResultaatDi01' and/or 'leverDocumentcreatieResultaatDu02'. This means that the asynchronous variant has been extended with user interaction.

The other extensions described in chapter 8 of the Specificatie Documentcreatie VNG (Specification Document Creation VNG) are not supported.

Explanation of asynchronous with user interaction:

• DCV sends start message to DCA;
• DCA sends first result message containing an 'interaction link' (URL);
• DCV can start the specific document creation process based on the link;
• DCA starts the document creation process.

 

Technical architecture

The links can be made directly between the different applications. This means that every application sets the endpoint of Templafy and that Templafy sets the different endpoints of the applications. Schematically it looks like this:

 

 

It is also possible that an enterprise service bus (ESB) that handles communication between the various applications is used. Templafy then only communicates via the ESB - 1 endpoint and 1 certificate that are exchanged. The ESB is provides communication with the respective applications:

 

 

Web services

The connections between the various applications in the chain are made through standardized web services. By default, these web services use the https protocol for information exchange.

By default TCP port 443 is used for all secure connections for Document Creation Services 1.1.

 

 

Related articles

How to enable Document Creation Services 1.1 App Connector