About this article
This article explains how data from a third party system can be used in a document using a HostSystem binding.
Prerequisites
|
- What is a HostSystem binding?
- Link a HostSystem binding to a field
- Use a HostSystem binding as default value
What is a HostSystem binding?
A document creation flow can be started from another system through an App connector, such as Salesforce, SharePoint, Document Creation Services 1.1 or a custom app connector.
It's also possible to start the flow creating (unattended) documents through the Document Generation API.
If you want to use external data originating from the App connector or API request, then you need a HostSystem binding. A HostSystem binding is used to import values from a third party system and display them in the generated document.
HostSystem logic
Use this syntax if the data is in the first layer:
Syntax | {{HostSystem.Key}} |
If the data is for example in the third layer then this syntax should be used:
Syntax | {{HostSystem.KeyLayer1.KeyLayer2.KeyLayer3}} |
|
Link a HostSystem binding to a field
With some third party systems like Salesforce or SharePoint, or when using the Document Generation API, you can directly link a HostSystem binding to a specific field, while with other systems like Document Creation Services 1.1 you first need to set up Binding Identifiers in the Admin Center, as shown below:
Example Salesforce
You can use Developer Tools (F12) in the browser to find the data available from the Salesforce App Connector (see this article for the exact steps):
Once you've found the data you can easily link to the (purple) fields in the HostSystem binding.
For example {{HostSystem.AccountNumber}}
will show the value ‘CD355118’ in the document, and{{HostSystem.CreatedBy.Address.city}}
will show 'Eindhoven'.
Example SharePoint
You can use Developer Tools (F12) in the browser to find the data available from the SharePoint App Connector (see this article for the exact steps):
Once you've found the data you can easily link to the (purple) fields in the HostSystem binding.
For example {{HostSystem.List.Title}}
will show the value ‘Documents’ in the document and {{HostSystem.Web.Title}}
will show 'My Team Site'.
Example Document Creation Services 1.1
The document creation service can use the content of the received (xml) message to automatically fill the document with the correct values (see this article for more information).
Unlike Salesforce and SharePoint you cannot directly link to the fields. In the Admin Center you need to create Binding Identifiers with an XPath expression to retrieve the correct values from the xml message (provided by the third party). Once created you can use the names of the Binding Identifiers in your HostSystem bindings.
The example below shows part of a StUF-DCR xml message, where e.g. the element 'betreft' is shown (Dutch for 'concerning'), which will be 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 also use //DCr:betreft
.
In the Admin Center click View details
of the Document Creation Services 1.1 App Connector.
In the form click + Add binding
and type Subject
in the Identifier name
field. Then type //DCr:betreft
in the XPath expression
field. The result looks like this:
|
After the field is saved you now can refer to it in Template Designer using the binding {{HostSystem.Subject}}
.
Click + Add smart field
then choose Custom text binding
and add the HostSystem binding to the Binding
field. The result looks like this:
When a document is created then the binding {{HostSystem.Subject}}
will show the value 'besluit op uw aanvraag omgevingsvergunning'.
Example Document Generation API
You can directly link a HostSystem binding to a specific field in a JSON file when using the Document Generation API (see this article for more information). For example this JSON file is used:
Depending on the type of field you want to use you can create a simple binding, e.g. for the text field 'Subject', or you need a more advanced binding (using a function) for the date fields 'Date1' and 'Date2':
-
Subject: In Template Designer click
+ Add smart field
then chooseCustom text binding
and add{{HostSystem.Subject}}
to theBinding
field. The result looks like this:
When a document is created then the binding{{HostSystem.Subject}}
will show the value 'hello world' in the document.
-
Date1: The date in the JSON has the format 'yyyyMMdd'. If you want the result in the document to be 'd MMMM yyyy' and in US English, then follow these steps:
In Template Designer click+ Add smart field
then chooseCustom text binding
and add{{FormatDateTime(HostSystem.Date1, "d MMMM yyyy", "en-US", "yyyyMMdd", "en-US")}}
to theBinding
field. The result looks like this:
When a document is created then the result will be '14 July 2023'.
-
Date2: This date field has the format that conforms to ISO 8601. If you want the result in the document to be 'd MMMM yyyy' and in US English, then follow these steps:
In Template Designer click+ Add smart field
then chooseCustom text binding
and add{{FormatDateTime(HostSystem.Date2, "d MMMM yyyy", "en-US")}}
to theBinding
field.
When a document is created then the result will be '14 July 2023'.
Use a HostSystem binding as default value
HostSystem bindings can also be used as the default value of a form field (depending on the type of form field this field is named Default value
, Prefill text
or Prefilled numeric value
).
|
Like above the values can be retrieved from e.g. Salesforce, SharePoint or Document Creation Services 1.1, but the source can also be a JSON file (this file is used in the examples below):
Use as default value for a Text field
With a Text
form field, type {{HostSystem.Subject}}
in the field Prefill text
. The result looks like this:
When a document is created with the JSON above the result in the form field in the response form will be 'hello world'.
Use as default value for a Number field
With a Number
form field type {{HostSystem.OrderId}}
in the field Prefilled numeric value
field. The result looks like this:
When a document is created with the JSON above the result in the form field in the response form will be '123.45'.
Use as default value for a Date field
With a Date
form field, it depends on the formatting of the date in the source what you need to type in the Default value
field. In case of "Date1": "20230714"
in the JSON above, you need to use HostSystem together with the DateValue() function, because the plain text date needs to be converted into a date object. The result looks like this:
In case of "Date2": "2023-07-14T08:55:16.974Z"
in the JSON above, the date is already in the correct (ISO 8601) formatting and you only have to use HostSystem. The result looks like this:
When a document is created with the JSON above then in both cases the result in the form field in the response form will be '14 July 2023':
|
Use as default value for a Dropdown field
A Dropdown
form field is for example linked to the data source 'Products':
In the field Default value
, instead of selecting 'Apple', 'Banana' or 'Pear', type {{HostSystem.Product}}
. The result looks like this:
When a document is created with the JSON above the result in the form field in the response form will be 'Apple'.
|
Use as default value for a Flexible dropdown field
A Flexible dropdown
form field is for example linked to the same data source 'Products' as shown in the dropdown form field example above. In the field Prefill text
type {{HostSystem.Product}}
. The result looks like this:
When a document is created with the JSON above the result in the form field in the response form will be 'Apple'.
Use as default value for a Checkbox field
With a Checkbox
form field instead of selecting 'false', 'true' or '(none)', type {{HostSystem.ShowLogo}}
in the field Default value
. The result looks like this:
When a document is created with the JSON above the result in the form field in the response form will be 'True' (the checkbox is ticked).
While the dropdown shows the values true
and false
, you can also use values like 1
or 0
in the JSON to pass a 'True' or 'False' value:
- These values pass a 'True' value (ticked checkbox):
true
,"true"
,"TRUE"
,"True"
,1
. - These values pass a 'False' value (unticked checkbox):
false
,"false"
,"FALSE"
,"False"
,0
.
|
Related articles
Comments
Article is closed for comments.