Start Expressions in Embedded Templates

Start Expressions are used with embedded workflow templates to display a list of records. The Start Expression controls which records are displayed. The embedded template is used to format each record.

Each embedded template starts with <<Start:StartExpression>> and ends with <<End>>. The Start Expression following the colon yields a list of records to be formatted using the embedded template. To be more specific, the Start Expression yields the list of key values of the table rows to be formatted using the embedded template.

A workflow template may contain one or more embedded templates. You can display a hierarchy of records by embedding one template within another. For example, you can display Customers, Orders, and Order Details records in a three level hierarchy by creating an embedded template for Customers. Then create an embedded template for Orders within the Customers template. Then create an embedded template for Order Details within the Orders template.

An Embedded template with a Start Expression is used in these cases.

  1. Embedded expression in a change workflow rule: a change workflow rule is fired when a specific record of a specific table is modified. For example, a change workflow rule associated with the Orders table is triggered when an Order is changed. The workflow template is evaluated in the context of that specific changed record. Your template can display both the specifics of that Orders record and the Order Details records associated with that Orders record. Your template must include an embedded template with a Start Expression to display the Order Details records.
  2. Top-level expression in a scheduled workflow rule: in a scheduled workflow rule, you can display a set of records. For example, you can display all Orders or all "open" Orders. Your template must include an embedded template with a Start Expression to display the Orders records.
  3. Embedded expression in a scheduled workflow rule: in a scheduled workflow rule, you can display a hierarchy of records. For example, you can display all "open" Orders records along with their related Order Details records. Your template must include an embedded template with a Start Expression to display the Orders records. Then create an embedded template for Order Details within the Orders template.

 

 

An example:

Consider this template which is used in a change workflow rule when an Orders record is updated. It contains an embedded template to display all of the Order Details records for the updated Orders record. The embedded template contains this Start Expression:

<<Start:[Related Order Details [Order Id]]>>

It is important to remember that the Start Expression is evaluated in the context of the template that contains it. In this case, the outer template is used to format the Orders record, so the Start Expression is evaluated in the context of that Orders record. Therefore, the Start Expression can make use of the columns in the current Orders record.

By contrast, the expressions between <<Start>> and <<End>>, other than the Start Expressions, are evaluated in the context of each child record. In our example, since the Start Expression refers to Order Details records, the expressions between <<Start>> and <<End>> are evaluated in the context of a child Order Details record. The expressions between <<Start>> and <<End>> normally refer to the columns of the Order Details record.

The embedded template is evaluated once for each child record returned by the Start Expression. For example, if there are five child Order Details records, the embedded template is evaluated five times.

 

Start Expression Variations

A Start Expression may take several forms.

 

An Entire Table

The simplest Start Expression is the name of a table and its key column:

<<Start:Orders[Order Id]>>

This form of Start Expressions is typically only meaningful as the top-level Start expression in a scheduled workflow rule.

 

Reverse Reference

A common Start Expression is the name of a Reverse Reference virtual column. For example:

<<Start:[Related Order Details [Order Id]]>>

The Orders record contains the Reverse Reference virtual column "Related Order Details [Order Id]". This virtual column was automatically added by AppSheet to contain the reverse references from the Orders table to the child Order Details table. It contains the list of key values of the related child Order Details records. In the example above, the column name "Related Order Details [Order Id]" is enclosed in square brackets.

 

Select Expression

You can display a subset of the child records by specifying a Select expression that yields the key values of the child records you wish to display. 

<<Start: SELECT(Orders[Order Id], AND(IN([Order Id],[_THISROW].[Related Orders [Customer Name]]),  [Order Status] = "Open"))>>

The Select expression must yield a list of key values. In this example, the "Order Id" column is the key of the "Orders" table.

 

Controlling Record Order

You can use OrderBy to control the order in which records are displayed. For example, you can display the Order Details records in order from most expensive to least expensive using this Start Expression. The Total column contains the total value of each Order Details record. 

<<Start:OrderBy([Related Order Details [Order Id]], [Total], FALSE)>>

The parameters to the OrderBy() function are OrderBy(ListOfRecords, SortColumn, SortDescending?).

 

Controlling the Number of Records Displayed

You can limit the total number of records displayed by using the Top() function. For example, you can display at most 3 records as follows:

  <<Start:TOP(OrderBy([Related Orders [Customer Name]], [Order Date]), 3)>>

The parameters of the Top() function are Top(OrderedListOfRecords, MaxNumberOfRecords). Note that Top() only works with OrderBy and cannot be used in isolation.

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.