Expression Structure and Referencing

An expression is a logic statement to determine the value for a Field. In order to create an expression it will require the correct syntax. To make up the logic for the value being calculated it will use a combination of functions, field references and operators.

Referencing Fields

Most expression will need you to refer to the values in other Fields. Suppose that you have a scenario where you are calculating the priority of a Risk occurring and this is evaluated by multiplying the probability by the impact. 

To do this we need to add an expression to the Priority Field that references both the Probability and Impact Field values. This is achieved by using the Field ID in square brackets. Therefore the expression for Priority becomes:

[Probability] * [Impact] 

The GridField is a Field that contains a number of individual cells defined in one Field. The configuration for the Field is to define Data Sets and Fields with the Grid and to reference an individual cell the structure of the ID is in the form GridFieldID_DataSetID_FieldID.

To Reference the value for the Audit Manager Name in the Owners GridField it would be an ID of the form:

[Owners_AuditManager_Name]

Note: Only single value Fields can be referenced in an expression, values that are part of a ListField or a multi-value selection field are not available for selection.

How to find a Field ID

Finding a field ID has never been easier. Now in workspace you can see your field ID, field type, expression in the field, while also being able to click straight through to the field and the template it's in. This can be done by hovering of the field you want to go to and clicking on the 'i' icon. This will show pop out with the options to clickthrough.

Backing Fields

There are a number of Fields in the platform that will store multiple values. There will be one Field that is the true value and then also values that are stored as Backing Field values for more options such as the text name for a Person Field or a Numeric value for a Status Field. The following are Fields with Backing Fields

Selection: A single value selection Field will store two pieces of data against the Field. One is the Value for the Field, the other is the _Text Backing Field that contains the Text value of the option selected. Lets say we have a Selection Field for Impact and the option selected has value 1 and text 'High':

[Impact] returns 1 & [Impact_Text] returns 'High'

ImageList: The Image List behaves in a similar manor to the Selection Field. It has an additional Backing Field that returns the Image URI. So if I had a Select List for RAID Type with value 'A', text 'Action' and image '/ImageListAsset/58rd421d30a542cd481639c7':

[RAIDType] returns 'A', [RAIDType_Text] returns 'Action' & [RAIDType_ImageListAssetUri] returns '/ImageListAsset/58rd421d30a542cd481639c7'

Multi-State: There are two types of multi-state Fields. One is the RAG or RAGBB Field. This cycles through the options of Red, Amber, Green, Blue, Black and Unset. Alongside the value for the Field a backing _Numeric Field holds a value of 5, 4, 3, 2, 1 & 0 respectively. So for a Status Field with a value of Amber:

[Status] returns 'Amber' & [Status_Numeric] returns 4

Person & Team: Person and Team Fields allow the User to select from a List of the User Accounts and Teams on the Site. The value will be the unique ID for the Person or Team and then the name on the account or name for the Team will be stored in an _Text backing Field. For a Person Field with the User 'Antony Jones' selected:

[Person] returns '31135df8wk464627848093d8wk461c2e' & [Person_Text] returns 'Antony Jones'

Format Strings: If an App Builder has added a Format String to display numeric or date values in a specific format, then the value for this will be stored in a _Formatted backing Field. On date Field with the value 2017-03-04T00:00:00Z and format string {0:d}:

[Date] returns 2017-03-04T00:00:00Z & [Date_Formatted] returns 4/3/2017

Operators

For Text Expressions you can use the '+' operator to concatenate multiple text values together. For example, if the Reference for a Project takes it's value as the Company, Process and Leader then using the '+' operator can concatenate these values:

[Company] + ' - ' + [Process] + ' - ' + [Leader] 

Numeric data can use the '()/*+-' operators to perform calculations. We saw in our example above that the value from two Fields can be multiplied together to give a new value.

([Probability] * [Impact])

We may find that we have an expression which uses a function that needs two logical statements to be met. An example would be the Status of a Project being Red only if the Project Stage is not Closed and the Priority is greater then 15. In this scenario we can use a logic operator to say both conditions are met.

if([Stage] <> 'Closed' & [Priority] > 15, 'Red', ...

The two logic operators we can use are || for OR and & for AND.

Functions

A function will take one or more parameters that will then be used to compute a value. For example the if() function takes three parameters. The first parameter is a logic statement that can take a value of true or false. The second parameter is the value that is returned if the logic statement is true. The third parameter is the value that the function will return if the logic statement is false.

if([Priority] > 15, 'Red', 'Green')

More information on the If statement can be found here 

Some parameters are optional. The expression to count how many Child Actions there are for a Project that are status Red would be of the form:

childSum('Actions','{"Status":"Red"})

The first parameter is the Child App to count records from and the second parameter is a filter on the Child Records returned. The filter is optional so it could be that we count all records so just the first parameter is valid:

childSum('Actions')

Functions can also be nested within other functions as part of an expression. The following combines if(), len() and substring() to shorten any title that is longer then 50 characters to just show the first 50.

if(len([Title]) > 50, substring([Title],0,50), [Title])

By combining Field Value References, Operators and Functions we build up an expression that can be used to set the value for a Field.

Make sure to click the 'Save' button when making any changes in order for them to be added to the next app version. Once you have made all the changes you need to an application you are then ready to publish it to workspace.

Note on Field Dependencies - Read more here

Field dependencies are by definition the other field(s) that are reliant on a given field, usually dependent fields are interlinked to one another by expressions and are indicated by an atom symbol. They are a crucial tool when looking to delete Fields within an App or, when it comes to understanding the structure and data flows of an App.