How to enable Document Creation Services 1.1 App Connector?

About this article

This article explains how to configure the Document Creation Services 1.1 integration in Templafy Admin. 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:

• Set up Document Creation Services 1.1
• Creating XPath expressions
• Set the StUF-DCR xml file to use the right template
• Create template bindings and form fields

 

The StUF standard is a Dutch standard hence abbreviations and names in this topic are in Dutch. The Dutch translation of this article (pdf) can be found at the bottom of this page and here.

 

Prerequisites

Library and App Connector modules enabled  Integrations module is enabled Document Creations Services 1.1 is enabled under Integrations

 

How to enable Document Creation Services 1.1 in Templafy using an App Connector?

1. In the Admin Center, access Integrations section
2. Go in Available tab
3. Find/Search for Document Creation Services 1.1
4. Click +

General options

• Display Name: This name will be used in Templafy.
• Organization: In the message that is sent to the service, a sender-organization (in Dutch 'zender-organisatie') must be specified (in this example 'BCompany'). 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 (in this example 'Document App'). The value of the element is used to identify the application within the organization.
• Send document to callback endpoint even if synchronous delivery is possible: Option 1 (see below).
• Do not include document content in synchronous response if asynchronous delivery is possible: Option 2 (see below).
  
  • Option 1 and 2 disabled: Synchronous flow. The document is sent back to the user.
  • Option 1 enabled, option 2 disabled: The document is sent to both the DCV (Document Creatie Verzoeker - Document Creation Requester) and the user.
  • Option 1 and 2 enabled: The document is not sent back, but only a response saying the document has been delivered.

• Use file extension in format field instead of a MIME type: When enabled the file extension (for example '.docx') is returned as metadata, else the MIME type (for example 'application/vnd.openxmlformats-officedocument.wordprocessingml.document') is returned.
• Callback URL: The address of the return service, for example 'https://returnservice.mydms.biz/dcvservice.svc'.
• Endpoint: The address the DCV (Document Creatie Verzoeker - Document Creation Requester) needs to use to deliver (xml) messages to Templafy. You can Copy the address to share it with the DCV.

The Endpoint field is only visible after you have filled in all required fields, saved the configuration and reopen the form.

 

Certificates 

• Inbound Certificate: If you Upload a certificate this must be a .cer or .pfx file (see image below). When you upload a .pfx file you need to provide a password (for a .cer file this is not applicable). This certificate should be provided by the DCV.
  You can also Generate a certificate (this is for testing purposes). For a generated inbound certificate to work, you need to download it, then delete the current certificate and upload the (just downloaded) file again.
• Outbound Certificate: This certificate is installed by default. The form shows the properties of the certificate, like the expiration date. You can Download the installed Outbound Certificate to share it with the DCV.

 

Binding Identifiers

Create friendly names that can be used in Template Designer to create bindings, so the user does not have to use XPath values.

 

• Add binding: Click this button to add one or more binding identifier fields.
• Upload sample XML file: You can upload a StUF-DCR (StUF Documentcreatie - StUF Document creation) xml file to verify if you have used the correct XPath expressions for your bindings.

6. In the left field enter the friendly name to use in Template Designer, where the syntax {{HostSystem.<friendly name>}} is used. For example the field Subject in the image above can be used in Template Designer by creating a binding named {{HostSystem.Subject}}.

7. In the right field enter the XPath that points to the correct field in the StUF-DCR xml file. By default Templafy Admin will only show if you have used a Valid XPath or Invalid XPath (see image above), but this only checks the syntax. To really know if you point to the right xml element you can upload a sample xml file. It then shows e.g. Matched: <value> (or Nothing matched) instead of just showing Valid XPath (or Invalid XPath).

To delete a binding, hover your mouse over the field then on the left click the recycle bin icon (see the 'YourReference' field in the image above).

 

Binding Identifiers for adaptive sections

In an XML file values can occur multiple times, i.e. multiple orders.

To display the data of every order (adaptive section), you need to fill in the binding identifier on top level. In this example the XPath expression is //DCr:groep[@type="ORDER"].

Then you have to create a sub identifier to display every value in that group. Click Add sub binding to add an item.

De XPath expression must always start with / and the XPath is the path directly beneath the value at top level. In this example /DCr:element[@naam="SUPPLIER"]

Repeat these steps to fill in all the required XPath expressions.

 

Creating XPath expressions

The document creation service can use the content of the received (xml) message to automatically fill the document with the correct values. To achieve this you have to create XPath expressions that retrieve the correct values.

The example below shows part of a StUF-DCR xml message, where e.g. the element 'betreft' is shown (Dutch for 'concerning'), which is used to provide a value for the form field 'Subject' in the document:

When referring to an element (in this case 'betreft') you don't have to use the full XPath. So instead of using //DCr:verzoekStartenDocumentcreatieDi02/DCr:documentspecificatie/DCr:betreft for the subject, you can use //DCr:betreft like in the example from step 5 above.

 

When referring to an element in an XPath you need to use the complete element name, so including e.g. 'DCr:', 'ZKN:', 'StUF:' or 'BG:', but if an element name does not contain a namespace (e.g. the element name is <betreft> instead of <DCr:betreft>), then you still need to use 'DCr:' (or 'ZKN:', 'StUF:', 'BG:') in your XPath value (note: if you upload a sample XML then in this case the message 'Nothing matched' can be ignored). The correct XPath values can be provided by the DMS application manager.

 

Set the StUF-DCR xml file to use the right template

To set the StUF-DCR xml file to use the right template, select the template in Templafy Admin and click Copy asset ID:

 

This asset ID is the Uniform Resource Name of the template. The URN should be specified as the template ID in the message for the Document Creation Specification. In other words: copy the asset ID value and use it in the element <DCr:sjabloonidentificatie> (template identification) of the StUF-DCR xml file. In this example the asset ID is '123456787654321':

 

In the xml file the asset ID must be preceded by the text 'urn:' as shown in the example above.

 

It is also possible to set a folder instead of a template. This is used when you want to show the contents of a folder, so users can select any template themselves to create a document.

Select a folder and click Copy folder ID:

 

Use the folder ID value in the element <DCr:sjabloonidentificatie> (template identification) of the StUF-DCR xml file. In this example the folder ID is '876543212345678':

 

In the xml file the folder ID must be preceded by the text 'urn:folder:' as shown in the example above. For the folder ID to work the Composer module needs to be enabled. Users need to have access to a folder to be able to create a document with a template contained in that folder. lf on the Folder settings tab the option Restrict Access (Security) orTarget audience is enabled and the user does not have access to the folder, then when creating a document with user interaction (using Document Creation Services) the error 'Failed - Something went wrong. Please try again.' will be shown.

 

If you want to show the contents of the root folder ('Documents') there's no option to copy the folder ID. In this case open the developer tools of your browser by pressing F12. Then in Templafy Admin, in the Library overview, click Documents. In the developer tools on the Network tab, now the ID of the root folder is shown. In this example the ID is '12345432123454321':

 

 

If the ID is not shown then you can find it by selectingancestor-folders and then the Preview tab:

 

Another option is to select asset-folder-content, then the Preview tab and expand currentAssetFolder:

 

Create template bindings and form fields

The last step is to create bindings and (optional) form fields in your template.

In case your template doesn't require any user input the only thing you need to do in Template Designer is to create a binding to the correct field on the Element tab, using the syntax {{HostSystem.<friendly name>}}, so for example {{HostSystem.Subject}} as shown below:

 

 

If your template requires user input (also known as 'enrichment', in Dutch 'verrijking') then the only thing you need to do is to create at least one form field on the Form tab. The presence of a form field is a trigger for Templafy to show the Dynamics wizard, which makes it possible for the user to answer additional questions that have not been filled in by the received (xml) message.

 

To use enrichment ('verrijking') the Composer module needs to be enabled.

 

Related articles

Document Creation Services 1.1 technical documentation

 

Downloads