Reference field expressions

The reference field is one of the most powerful field types in BizzStream. As the name suggests, a reference field allows you to refer to one or more other documents. The ability to view data from other documents in a single document makes it indispensable, but it also requires some additional functionality to provide agility in modelling a process.

Syntax of a reference expression

A prefix is used to refer to the location of the referenced field. There are three different types: * source; the referred field is a header field of the document that contains the reference field. * target; the referred field is a header field in the document that is being referred to. * sourceLine; the referred field is a field in the line that contains the reference field.

Source
When you want to refer to the value of the field employee in the document that contains the reference field, you should use:

{!source.employee!}

Target
When you have a reference type field and want to refer to the value of the ingredient field in the document that is being referred to:

{!target.ingredient!}

sourceLine
The sourceLine prefix is used to refer to fields within the same line:

{!sourceLine.price!}

Showing labels

Reference fields have the Reference Label property. This property determines the information that you see when you refer to another document. BizzStream expressions can be used to show information from fiels in the referenced documents.

Imagine that you want to show the name and city of a restaurant in the reference label.

In this case, you can use this expression in the reference field

{!target.name!} - {!target.city!}

Using filters

Filters can be set on reference fields to show a subset of all existing documents.

Imagine that an employee wants to specify the hours worked by project and region. Not all projects are in the same regions. When the employee selects a project, a filter can be set so that he sees only the regions for the selected project.

Filters and Operators
Only documents that match the conditions of the filter can be selected. The so called operators can define the filter-conditions.

Usage of a reference field in a filter condition
When using the logical operators and/or the match operator the fieldname option can be used to use an specific field value of a reference field, for instance: {!target.status!} == {!source.ingredient{"fieldName": "status"}!} or {!target.name!} == {!sourceLine.ingredient{"fieldName": "name"}!}. Note: the fieldName option can only be used in combination with the source / sourceLine options.

In operator
The IN operator is used when a reference is made to the content of one one-to-many (1-N) reference fields. Imagine a document called Order in which the field orderPicker specifies which employees can be selected. This field can contain several employees.

A reference field referring to restaurant and employees is placed within the order document. The values of the reference field can be limited to the employees which belong to the selected restaurant by using the following expression:

{!source.restaurant{"fieldName":"employees","operator":"in"}!}

The part source.restaurant refers to the field restaurant within the document. The "fieldName":"employees" part dictates that we do not look at the BizzStream ID of the restaurant but to the field of the employees in the document in which the restaurant information is set. The "operator":"in" part dictates that we should not look at the list in its completeness but only to the individual values of the list.

You can also use the IN operator to enforce that only documents referenced in a 1-N field in the same document can be selected. For instance, you can use the following expression to determine that only restaurants that are also selected in the field restaurant can be selected:

{!source.restaurant{"operator":"in"}!}

Match operator
The match operator is used to compare the values of two reference fields.

{!target.<referenceField1>!} match {!<source|sourceLine>.<referenceField2>!}

This filter ensures that only documents can be selected where the field allIngredients (a 1-N reference field) contains the value set in demandedIngredient (a 1-1 reference field):

{!target.allIngredients!} match {!source.demandedIngredient!}

• In case both reference fields are of type 1-1, the match operator will behave like == (equals) operator.

• In case both reference fields are of type 1-N, only options are shown that have a minimum of one value in common.

Using placeholders

Placeholders can be used in multiple field types. By setting an inital placeholder in a field, the placeholder will be resolved when a new document is created (in the case of header fields) or when a new line is created (in the case of line fields). The value will not be updated when the referenced field updates. By contrast, regular placeholders are resolved when the referenced fields are updated. A user can overwrite the values that are set when a placeholder is resolved. Both inital and regular placeholders can contain system expressions.

For example, we want BizzStream to automatically fill the orderTaker field of an order document. We therefore use the following expression as initial placeholder in the orderTaker field:

{!source.restaurant{"fieldName":"defaultOrderTaker"}!}

By default, placeholder expressions listen to all related fields changes. Consider the following scenario:

Field 1 - Simple reference field

Field 2 - Reference field with a placeholder to Field 1

Field 3 - Text field with Placeholder based on Field 2 value.

If the user changes Field 1, the change will propagate to Field 2 and also to Field 3.

In order to prevent this behaviour you can add the following option:

{!source.restaurant{"fieldName":"defaultOrderTaker", "propagate": false}!}