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.
Prerequisites
|
NoteThe StUF standard is a Dutch standard hence abbreviations and names in this topic are in Dutch. |
How to enable the Document Creation Services 1.1 app connector
- In the Admin Center, access Integrations section.
- In the Integration Management screen, go in Available tab.
- Find/Search for Document Creation Services 1.1.
- Click + to create the app connector.
- Now the app connector can be configured.
- Display Name: This is the name of application from where the document creation is starting from also known as the DCV (Document Creatie Verzoeker - Document Creation Requester). The name will be used in Templafy on the Save button when the document is saved back to the DCV.
- Organization: In the XML request 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 XML request 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.
- Always have documents go through the asynchronous flow: Option 1 (see below).
-
Do not include document content in synchronous response : 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 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'.
- Click Save to finish the creation of the app connector.
Now the app connector is created, it has become available on the Installed tab under Integration Management. Click View details to open the app connector. Here you can see a Templafy endpoint has been created. This is the address the DCV needs to use to deliver XML messages to Templafy. You can Copy the address to share it with the DCV.
The certificates have become available:
The Document Creation Services 1.1 needs an inbound and outbound certificate for a secure connection.
-
Inbound certificate: This is the certificate of the DCV. If you Upload a certificate this must be a .cer, .crt or .pfx file . When you upload a .pfx file you need to provide a password (for a .cer or .crt file this is not applicable). This certificate should be provided by the DCV.
You can also Generate a certificate (this is for testing purposes only). 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 is the certificate of Templafy and 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.
Important
|
Binding Identifiers
In order to use data from XML message into generated documents, you need to configure Binding identifiers. Binding identifiers can be used for HostSystem bindings in a Templafy Word template. These bindings will be replaced by the XML data when creating a document through the app connector.
- 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.
- In the Identifier name 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}}
. - In the XPath expression 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, 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).
Binding Identifiers for adaptive sections
In an XML message, 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.
The 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.
Important
|
Set the StUF-DCR xml file to use the right template
To set the StUF-DCR XML message 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':
ImportantIn 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':
Important
|
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 selecting ancestor-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 Template 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 response form, which makes it possible for the user to answer additional questions that could not be taken from the received XML message.
Comments
Article is closed for comments.