Articles in this section

How to enable Document Creation Services 1.1 App Connector

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

  • Library, Dynamics Templates and App Connectors modules enabled.
  • Document Creation Services 1.1 is enabled under Integrations.
  • Admin/owner access to the Templafy tenant for the configuration of the app connector.
  • Space owner access to the Templafy tenant for the configuration of the Word templates.

  Note

The 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

  1. In the Admin Center, access Integrations section.
  2. In the Integration Management screen, go in Available tab.
  3. Find/Search for Document Creation Services 1.1.
    Document Creation Services 1.1 App Connector.png
  4. Click + to create the app connector.
  5. Now the app connector can be configured.
    Document Creation Services 1.1 App Connector Setup.png
    • 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'.
  6. 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.
Document Creation Services 1.1 App Connector Endpoint.png

The certificates have become available:

Document Creation Services 1.1 App Connector Certificates.png

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

  • The Inbound Certificate cannot be self signed.
  • The Root certificate must have a trusted authority (should either be publicly trusted or signed by the KPN PKIoverheid Private Services CA - G1 CA)

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.

Document Creation Services 1.1 App Connector Binding Identifiers.png

  • 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.

StUF-XML.png

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.

StUF-AddSubIdentifier.png

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.

StUF-SubBindings.png

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:
dcs_stufdcrxml.png
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

  • When referring to an element in an XPath you need to use the complete element name, so including namespaces, 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 message to use the right template, select the template in Templafy Admin and click Copy asset ID:

dcs_copyassetid.png

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':

dcs_uniformresourcename.png

  Important

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:

dcs_copyfolderid.png
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':

dcs_uniformresourcenamefolder.png

  Important

  • In the xml file the folder ID must be preceded by the text 'urn:folder:' as shown in the example above.
  • Users need to have access to the folder where the template is located that is being used to create a document from through the app connector. When on the Folder settings tab the option Restrict Access (Security) or Target audience is enabled and the user does not have access to the folder, the document creation will fail if it is a template with user interaction. The error message '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':

dcs_rootid.png

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

dcs_rootidancestor.png

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

dcs_rootidasset.png

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:

Document Creation Services 1.1 App Connector HostSystem Binding.png

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.

app Teams Microsoft Teams app connector access to data Salesforce data Salesforce limitations admin_role
Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Article is closed for comments.