How to select a specific item from an array

Updated August 22, 2024 14:10

About this article

This article explains how to create a binding that selects a specific item from an array using a data connector.

Prerequisites

Library and at least one Dynamics module enabled
External data is available (via Data Connector)
Templafy Desktop and Office VSTO add-in installed
Tenant admin/owner access or Space owner access

Technical clarifications

The binding is only supported for arrays.
HostSystem bindings are not supported.
The index starts from zero, so the first item of the array is accessed by [0], the second item by [1] etc..
The index must be within the range of the array.
The index must be a non-negative integer number (otherwise it will be treated as out of range).

Logic

Syntax	{{Smart field[index]}}
Input	number
Output	Item x from the array

Example

In this example a document with a data connector is created which allows a user to select a category of products in the dropdown. Each category contains one or more products, but only one specific item of the selected category will be shown in the document.

The external data sources below are used in the example.

The data source 'Categories' which contains an array named 'Products':

In the schema an array can be recognized by the square brackets [] behind the name, like Product[] in the screenshot above.
The fields 5.1 - ProductID, 5.2 - ProductName, 5.4 - QuantityPerUnit and 5.5 - UnitPrice will be used in the template.

Below some records of the external data source 'Categories' are shown:

The 'Products' data source:

Note that both external data sources only show a sample of the content, so the data sources might actually contain thousands of items.

To create a data connector that selects only one specific item from an array follow the steps below:

In Word open a new document then in Template Designer click + Create template.
On the Form tab click + Add question, then in the Type field select Data connector.
In the Question field type 'Product category'.
In External data source select Categories, then in Label column select CategoryName (this is the second column shown in the second screenshot above). The result looks like this:
Click Add to form.
In the template type 'Selected Product Category: [Category]'.
Below the text create a table with 2 rows and 4 columns. In the first row type the heading texts 'Product Name', 'Unit Price', 'Quantity Per Unit' and 'Product ID' (each text in a separate column). In the second row type the placeholder texts '[ProductName]', '[UnitPrice]', '[QuantityPerUnit]' and '[ProductId]' (each text in a separate column). The result looks like this:

In the template select the placeholder text '[Category]'. On the Template tab expand Form responses, then expand Productcategory, select the CategoryName form field and click Add to template:

If the Template tab already contains smart fields, then you first need to click+ Add smart field to display Form responses.
In the Advanced menu you can specify e.g. the visibility of the field (optional).

In the table select the placeholder text '[ProductName]'. On the Template tab click + Add smart field then click Custom text binding.
In the Binding field type the binding {{Form.ProductCategory.Products[0].ProductName}} (the [0] means the first item will be selected when a document is created). The result looks like this:
Click Add to template.
Repeat steps 9-11 for the other placeholder texts with the values below:

- [UnitPrice]: {{Form.Productcategory.Products[0].UnitPrice}}.
- [QuantityPerUnit]: {{Form.Productcategory.Products[0].QuantityPerUnit}}.
- [ProductId]: {{Form.Productcategory.Products[0].ProductID}}.
The result looks like this (with Design Mode enabled):
Save the template and upload it to the Admin Center.
When a document is created and the category 'Beverages' (this is Category Id '1') is selected, then the result shows 'Chai | 18 | 10 boxes x 20 bags | 1' (this is the first item that has Category Id '1' in the 'Products' data source as shown in the 3rd screenshot on top of this article):

When 'Condiments' (this is Category Id '2') is selected, the result shows 'Aniseed Syrup | 10 | 12 - 550 ml bottles | 3' (this is the first item that has Category Id '2' in the 'Products' data source as shown in the 3rd screenshot on top of this article):
Now verify what happens when you change the [0] in the bindings to e.g. [2] (this will select the third item). So the bindings created in step 10 and 12 become:

- [ProductName]: {{Form.Productcategory.Products[2].ProductName}}.
- [UnitPrice]: {{Form.Productcategory.Products[2].UnitPrice}}.
- [QuantityPerUnit]: {{Form.Productcategory.Products[2].QuantityPerUnit}}.
- [ProductId]: {{Form.Productcategory.Products[2].ProductID}}.

When a document is created and the category 'Beverages' is selected, then the result now shows
'Côte de Blaye | 263.5 | 12 - 75 cl bottles | 8'.
When a document is created and the category 'Condiments' is selected, then the result now shows
'Chef Anton's Gumbo Mix | 21.35 | 36 boxes | 5'.

If you want to show all items of the selected category in the document (instead of only one specific item) then you need to create an adaptive section (repeating group).
If you want to create an unattended document then you can use the ExternalDataSources[] function, so the binding becomes e.g. {{ExternalDataSources.Categories["2"].Products[0].ProductName}}.
This will select the first item from (always) category '2' (Condiments).
If you want to category to be variable, then e.g. this binding can be used: {{ExternalDataSources.Categories[HostSystem.CategoryID].Products[0].ProductName}}.
This will select the first item from category x, where the value of x is determined by HostSystem.CategoryID.

As mentioned in Technical clarifications above, HostSystem bindings (like {{HostSystem.Productcategory.Products[2].ProductName}}) are not supported, but you can use a HostSystem value as part of the ExternalDataSources[] function.

Related to

adaptive section repeating group repeater array array item

Articles in this section