Articles in this section

See more

Using a HostSystem binding

Updated
Follow

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?

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

 

hs_salesforce.png

 

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

 

hs_sharepoint.png

 

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:

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

 

hs_bindingidentifiers.png

 

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

hs_customtextbinding.png

 

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:

hs_json.png


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:

    hs_customtextbinding.png

    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:

    hs_customtextbindingdate.png

    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.

 

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

hs_json.png

 

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:

hs_textprefilltext.png

When a document is created with the JSON above the result 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:

hs_numberprefillednumericvalue.png

When a document is created with the JSON above the result will be '123.45'.

 

Use as default value for a Dropdown field

A Dropdown form field is for example linked to the data source 'Products':

hs_datasourceproducts.png

In the field Default value, instead of selecting 'Apple', 'Banana' or 'Pear', type {{HostSystem.Product}}. The result looks like this:

hs_dropdowndefaultvalue.png

When a document is created with the JSON above the result 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:

hs_flexibledropdownprefilltext.png

When a document is created with the JSON above the result 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:

 

hs_checkboxdefaultvalue.png

When a document is created with the JSON above the result 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 articles

 

 

 

 

Related articles

Comments

0 comments

Article is closed for comments.