Overview

This page explains the basics of writing expressions and scripts in the dynamic fields in PhixFlow property tabs.  It's also useful to know the style conventions recommended for expressions; see Expression Style.

The elements you can use in an expression include:

• a comment that provides documentation about what the expression does. PhixFlow ignores comments.
• a literal value, for example a number or string
• a variable; see Using Variables. This can be:
  • either a pre-defined internal variable
  • or your own user-defined $-variable.
• a special string that matches a pattern in a string or array; see Regular Expressions
• another expression
• a Function, which has a comma-separated list of arguments, enclosed in brackets.
  For example: dateGet(date,dateField)

Adding Comments

It is always a good idea to add comments to document your expression. Comments help anyone who needs to modify the expression in the future.

There are two ways to tell PhixFlow that a line is a comment, and can be ignored.

For some examples of using comments, plus other style tips for expressions, see Expression Style.

Literal Values and Data Types

Data Types 

When writing expressions, it is important to consider the type of the result. For example, it is possible write an expression to return the integer 3 for an attribute with the type string. However, this has a mis-match between data types. When PhixFlow evaluates an expression that contains a data-type mismatch, processing stops and PhixFlow reports an error.

The full list of data types handled by PhixFlow is shown in the following table. 

Assigning a Literal Value

The most basic expression simply assigns a constant value to the field.

Referencing Attribute Names

Assigning Values From a Pipe 

Attribute expressions are commonly used to fetch the value returned by a Pipe. This is simply done by suffixing the pipe name with the name of the attribute to be returned. For example: 

  in.accountRef

This expression causes PhixFlow to look at the pipe named "in" and return the value in the field called "accountRef".

Calculating an Attribute Name Using a $-variable

In PhixFlow, you can create your own variables using a $ symbol, for example $variableName; see Using Variables.

If the name of the attribute whose value you want has to be calculated based on other factors, you can assign the attribute name to a $-variable. You then use the variable instead of the attribute name itself. For example:

  in.$attrName

Handling Invalid Characters in Attribute Names

There are two options for handling an attribute name that contains invalid characters.

• Either assign that name to a variable and use the variable instead of the actual attribute.
• Or enclose the name in quotes, for example:  in.'account-ref'.

Numbers and Strings

Mathematical Operators (+, -, *, /)

Several values can be combined using the usual basic mathematical operators. For example when in.numProducts has the value 9:

The usual calculation precedences apply, so * and / operations are carried out before + and -. When the mathematical statements involve multiple calculations, use brackets ( ) to force the correct processing order.

String Concatenation (+)

The + operator also serves as the string concatenation operator. This means you can use + to  join strings together. For example if in.customerName returns "Smith" and in.title returns "Mr":

Functions, Arguments and $-Variables

PhixFlow has a set of functions you can use in expressions. Functions have a set of comma-separated arguments, enclosed in backets, like this: name (arg1, arg2), where arg is an argument. Each function has a help page explaining it's syntax and what PhixFlow expects for each argument ; see Functions.

$-Variables in the Do() Function

In expressions that have complex calculations, you may need a variable to hold the result of a calculation. You can then reference the variable later in the expression, or in other attribute expressions for the same table.

The following expression uses do() function and $-variables for a simple calculation.

When to Use $-variables

$-variables are not really needed in simple calculations. They are useful:

• in forEach loops
• calculating attibute names from pipes; see Assigning Values From a Pipe.
• to store a value from a look-up pipe, when you need the value in multiple attributes
  1. In the first attribute, look-up the value.
  2. Use a $-variable to store the value that is returned by the look-up.
  3. When you need the value in another attribute, reference the $-variable instead of repeating the look-up.
• in complex expressions, to break up multiple consecutive functions into separate lines. In this case, use a $-variable to store the intermediate values; see Multiline Statements and $-variables.

True or False using the If() Function

It is common to want to evaluate whether or not data meets a condition. To do this use the if() function in an expression. This function has 3 arguments.

if(
    //argument 1 - the condition
   _out.AppleHarvestDate < _toDate('20210101'),

    //argument 2 - return this if true
    1,

    //argument 3 - return this if false
    0

)

In this expression, the first argument is the condition, which is also an expression. This selects records that have a date before 1st January 2021. The remaining arguments are simple integers. For records that:

• meet the condition, PhixFlow returns 1 to indicate true.
• do not meet the condition, PhixFlow returns 0 to indicate false.

Alternatively, the expression could return strings, which must be enclosed in quote marks.

if(
   _out.AppleHarvestDate < _toDate('20210101'),
    "true",
    "false"
)

Multiline Statements

When you are working with more complex expression, you may have several different statements to evaluate first. To group statements together, use the do() function.

In multi-line statements, you usually need to assign the value of an expression to a $-variable, to use later in the expression. For example:

PhixFlow uses the value from the last statement to be evaluated. In simple expressions, such as the example above, the last statement to be evaluated is the last line of the expression. However, in Conditional Statements, the last statement evaluated is not always the last statement in the expression. For example:

Expressions in Other Dynamic Fields

In some cases, a dynamic field is expecting a form of code other than an expression. For example a database collector has a dynamic field where you can enter SQL statements. If you want to include an expression in this type of field, it needs to be enclosed in curly brackets. For example, the following SQL statement includes the expression in.key.

select * from mytable where mykey = {in.key}

Popup Help for Expressions

When you are writing an expression, PhixFlow provides popup windows to help you. You can:

• start to enter an expression. Select a string to display a popup with information about whether the string is valid.
• start to enter a Function name. PhixFlow displays a list that you can scroll to find the function name you require.
      
• Enter a function. Click into the brackets to see a summary of the function syntax.
  Click Learn More to see the full help page for the function.