How to create a HostSystem binding

Updated August 22, 2024 14:29

About this article

This article explains how data from a third party system can be used in a document using a HostSystem binding.

Prerequisites

Library and at least one Dynamics module enabled
App Connector module enabled
Templafy Desktop and Office VSTO add-in installed on the PC
Tenant admin/owner access or Space owner access

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}}

In the above syntax replace the italic names by the actual path to the data.
Field names are case-sensitive.
HostSystem bindings cannot be validated so make sure you use the correct binding.

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:

Explanation about creating XPath expressions is beyond this help topic.

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 choose Custom text binding and add {{HostSystem.Subject}} to the Binding 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 choose Custom text binding and add {{FormatDateTime(HostSystem.Date1, "d MMMM yyyy", "en-US", "yyyyMMdd", "en-US")}} to the Binding 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 choose Custom text binding and add {{FormatDateTime(HostSystem.Date2, "d MMMM yyyy", "en-US")}} to the Binding 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).

Field names are case-sensitive.
The field types Date, Data connector, Header and Description do not have a default value field.
Using other form fields ({{Form.FieldName}}) as default value is not supported.
The API is used for creating unattended documents, so the response form is not shown. However when Update Document is clicked after the document is generated, the response form will show the default values in the form fields.
Be careful using IfElse() functions like {{IfElse(Equals(HostSystem.Product, "Apple"), "Fruit", "Vegetable")}} as default value when Allow updates is enabled.
When a document is created initially the value Apple (see JSON file below) is sent, so the output is Fruit as expected. However when Update Document is clicked the IfElse() function will be processed again, but this time no value is sent, so now the output will be Vegetable.

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

The API is used for creating unattended documents, so the response form is not shown. However when Update Document is clicked after the document is generated, the response form will show the default date values.

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

The value used in the JSON must match one of the values in the data source. If it doesn't (for example the value is 'Orange') then the result in the document will be an empty value.
The values in the data source are case-sensitive. So if for example the value in the JSON is 'apple' (instead of 'Apple') then the result in the document will be an empty value.

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.

The values "1" or "0" (with quotes) will both pass a 'False' value.
The values True, TRUE,False and FALSE are invalid.

Related to

xpath hostsystem default value prefill text json prefilled numeric value hostsystem binding

Articles in this section