Versions Compared

Version Old Version 15 New Version Current
Changes made by

Fiona Sargeant (Unlicensed)

Zoe Baldwin

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Introduction

Many fields can be configured with scripts and simple expressions however for the purposes of the examples here we have assumed that the reader is configuring a Stream Attribute field unless otherwise stated. This field is in no way special and in general all of the scripting elements and techniques described are available in all of the dynamic fields. Any special cases are documented on the help screen describing the individual form.

Assigning a Literal Value to a Field

The most basic expressions simply assign a constant value to the field. For example these three expressions assign the integer 3, the floating point number 3.2 and the string "Hello" to the field:

ExpressionResult
33
3.23.2
"Hello""Hello"
Note that if you want to assign a string value (as in the last example) then the characters must be enclosed in either single 'Hello' or double "Hello" quotes.
Panel
borderColor#7da054
titleColorwhite
titleBGColor#7da054
borderStylesolid
titleSections on this page

Table of Contents
indent12px
stylenone

Parameter

Insert excerpt
_Banners
_Banners
namephixScript
nopaneltrue

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)
Tip

The internal variables that you can use in an expression depend on the context. When you are writing an expression, always check the relevant help page. This will have information about which internal variables your expression can include.

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.

NotationUse for
//

 short comments up to 1 line

/* <comment> */multi-line comments

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

Literal Values and Data Types

Data Types 
Anchor
paramTypes
paramTypes

When writing expressions, it is important to consider the type of the result. For example,

if you have written a Stream Attribute

it is possible write an expression to return the integer 3

but have defined the type of the Stream Attribute to be a String then PhixFlow will stop and report the error when the expression is evaluated.

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

below. It's not necessary to understand the meaning of the individual types at this stage, however just be aware that the different types exist.

in the following table. 

Data TypeDescriptionSee
Array
A list
 An object that contains an ordered list of values, e.g. [1,2,3]
. For details about what other values arrays can hold and Array handling in general see
Arrays and Record Sets
.
DateA date
. For details about date manipulation functions go to
Date Functions
.
DatetimeA date and time
. For details about date manipulation functions go to Date Functions.
FloatA floating point number, e.g. 3.2 or 3.0 or 0.0
IntegerAn integer, e.g. 3 or 0
NumberAn integer or floating point number
StringA string value, e.g. "Hello" or the empty string ""Text Expressions and Escape Characters
BooleanA logical value of either true or false.
Note that any

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

  • in forEach loops
  • when using look-up pipes
  • 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, below.

Assigning Values From a Pipe

One of the most common type of expression is

Any non-null, non-zero value is treated as true
Regular Expression
Regular Expressions allow string patterns to be expressed. See Regexp ToDelete for more detailsUsing $-variables in Calculations Anchordollarvar-introdollarvar-intro

In stream attribute 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. In PhixFlow you can use a $-variable for this, by prefixing the variable name with the $ symbol.

Tip

It can be helpful to distinguish between $-variables that are:

  • only used in the current attribute: use a lower case variable name, for example $percent
  • also used in another attribute: use an initial capital letter, for example $Percent.
Panel
titleSimple $-variable example

The following expression sets 2 $-variables $A and$ B, then uses them in a simple calculation that returns 10. 

Code Block
do(
   $A = 5,
   $B = 2,
   $A*$B
)

Another expression can reference the $A and $B variables in a different calculation. The following expressin returns 100.

Code Block
do(
   $c = 10,
   $A*$B*$C
)
Special character sequences that match a string patternRegular Expressions

Assigning a Literal Value

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

ExpressionAssigns valueData type
33integer
3.23.2floating point
"Hello""Hello"string


Tip

To assign a string, it must be enclosed in:

  • either single quotes: 'Hello'
  • or double quotes: "Hello"

When working with strings, be aware that some characters have special meaning. You need to use an escape character for strings that include special characters; see Text Expressions and Escape Characters

Referencing Attribute Names

Assigning Values From a Pipe 
Anchor
pipe
pipe

Attribute expressions are commonly used to fetch the value returned by a Pipe. This is simply done by suffixing the

Pipe

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".

Tip

This expression can return multiple values; see Arrays and Record Sets.

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

then

, you can assign the attribute name

can be assigned

to a

variable (see the section below on mulitline statements and $-variables) and the variable used in place

$-variable. You then use the variable instead of the attribute name itself

e

.

g.

For example:

  in.$attrName

If the name of the attribute whose value you want contains characters that would otherwise be invalid you can either

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
(see the section below on multiline statements
  • and
$-variables) and
  • use the variable instead of the actual attribute
as discussed above or simply
  • .
  • Or enclose the name in quotes
e.g.
  • , 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:

ExpressionResult
in.numProducts + 312
in.numProducts - 36
in.numProducts * 327
in.numProducts / 33

The usual calculation precedences apply

i.e.

, so * and / operations are carried out before + and -. When the mathematical statements involve multiple calculations, use brackets ( )

can be used

to force the correct processing order

:

.

ExpressionResult
3 * 3 + 312
3 * (3 + 3)18

String Concatenation (+)

The + operator also serves as the string concatenation operator

i.e. joins

. This means you can use + to  join strings together. For example if in.customerName returns "Smith" and in.title returns "Mr":

ExpressionResult
"Hello" + " to " + "you""Hello to you"
"Dear " + in.title+ " " in.customerName + "," +"Dear Mr Smith,"
Note that if you attempt to


Note

If you use + to concatenate a

String

string and a

numeric value (e.g. an Integer ) then PhixFlow will simply treat

number (integer or floating point), then PhixFlow treats the number as if it is a string

and concatenate it. E.g.

. For example:

ExpressionResult
"Hello" + 3"Hello3"
"4" + 3"43"
Multiline Statements and $-variables AnchordollarVardollarVarOften there is a need to work out the result of a more complex expression which may require several different statements to be evaluated first. To group several statements together in this way, you should make use of


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
Anchor
dollarvar-intro
dollarvar-intro

Insert excerpt
Using Variables
Using Variables
nopaneltrue

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.

Code Block
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.

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

Multiline Statements
Anchor
dollarVar
dollarVar

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 nearly all multiline statements, it is also very convenient

In multi-line statements, you usually need to assign the value of an expression to a $-variable

which may then be used

, to use later in the expression.

E.g.

For example:

ExpressionResult

do (

    $name = in.customerName,

    $title = in.title,

    $salutation = "Dear",

    $result = $salutation + ' ' + $title + $name

)

"Dear Mr Smith"
Please note that every statement within


Note

Statements in the do() function

(except the last) ends

end in a comma

"

,

"

 except the last one.

Please also note that the value of an expression (e.g. the value that will be assigned into a Stream Attribute ) is the value of the

PhixFlow uses the value from the last statement to be evaluated. In simple expressions, such as the example above

example

,

this seems very trivial as

the last statement to be evaluated is the last line of the expression. However

when we look at See the Expressions and Scripts topic page for links to more information on expressions and scripts.

, in Conditional Statements, the last statement evaluated is not always the last statement in the expression. For example:

ExpressionResult

if (

    in.customerName == "Smith",
    45 ,

// else

    36

)

45 if the customer's name is "Smith" but otherwise the value 36.

Adding Comments

In longer scripts (and even short scripts) it is a good idea to add comments to remind yourself (and anyone else who may need to modify the script in future) what steps are being followed. For short, 1 line comments, just prefix the line with // and for longer, multiline comments, enclose the lines in /* .... */. For example:

/* Get the discount rate that should apply to the calls which match the filter conditions */ $discountRate = discount.rate, // Now apply the discount $value = $value * ( 1 - $discountRate)

The lines above are comments and are ignored by PhixFlow.

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.

Code Block
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.
        Image Added
  • 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.
        Image Added

Live Search
spaceKey@self
additionalnone
placeholderSearch all help pages
typepage

Panel
borderColor#00374F
titleColorwhite
titleBGColor#00374F
borderStylesolid
titleSections on this page

Table of Contents
maxLevel3
indent12px
stylenone