Expressions in Step Inputs

One of the most powerful features in Y Meadows is the ability to use Expressions. An expression is similar to an Excel Formula. Expressions use information such as text or outputs from other steps and use them to generate new values.

Any time you see an input box that looks like this you can use an expression! This is called the Expression Editor.

The simplest way to use an expression editor is to drag an output from a previous step into it. This simply passes the value that was output by one step into a new step without changing it:

Expressions allow the data to be changed. As an example, users can apply a simple expression to to add additional text to a subject line.

Here “RE:” was added to the beginning of the subject and used the “+” operator to glue the two different pieces of text together. There are lots of other operators and other, more complex, options when using expressions.

Thinking back to the earlier discussion of Excel can provide an idea of the kinds of things that can be accomplished using Y Meadows expressions. Expressions can do math, convert numbers to strings, perform logic and other interesting things.

Expressions in Y Meadows are created using one of the most popular programming languages in the world, Python. This means that there is a lot of help available online, and a large pool of people who are already familiar with the language. The power of Python provides a broad range of possibilities using expressions that must fit in a single line.

The implementation of Python in Y Meadows is referred to as PyMeadows when there are differences between it and standard Python. Python version 3.7 is the basis for PyMeadows and for security some language features have been removed for security reasons to limit exploits of the system.

Let’s look at some simple examples to get started:

For these examples we are going to use 🔵 to stand in for any output from a previous step.

Any literal text needs to be wrapped in quotation marks like this:

"Hello"

'Hello'

If your text has a quote (or apostrophe) in it, use the other kind:

"Can't"

'"Why are you asking?" he said'

For text that contains both kinds of quotes, put 3 quotation marks around it:

"""What is "that" and why can't I see it?"""

To convert a number to a string: str(🔵)

To convert a string to a number use: int(🔵) or float(🔵) Depending on if you want an integer or a decimal number

int("7")

float("0.27")

Putting two strings together: (don't forget to add spaces to avoid seeing HelloWorld.)

"Hello " + "World"

"Hello " + 🔵

Change a string to uppercase: "Hello There".upper()

This may feel unfamiliar compared to Excel, so Excel-like functions are being added to make the transition easier for all the spreadsheet literal out there.

Simple math: (1 + 3) *(🔵/2)

More Advanced Examples

In the following examples 🔵 represents a step output.

To input a different value based on logic

Assume that 🔵 is an age and the goal is to categorize a person by age. This expression will accomplish that:

"Child" if 🔵 < 13 else "Teen" if 🔵 < 20 else "Adult"

Testing Equality

There is a special way to test for equality in Python using == (instead of just =)

"Baby" if 🔵 == 1 else "Child" if 🔵 < 13 else "Teen" if 🔵 < 20 else "Adult"

True and False

Using Python it is possible to get True/False results that can be used in any input that requires one. For example, the Y Meadows decision step is able to change the path of a message based on True/False expressions.

In Python True and False are used literally - to always make something happen set the input to True

🔵 <= 100 will evaluate as True if the output is less than or equal to 100 and False in all other cases

In Python it is common to use an object, such as a list or dict, in an expression to check for "truth". In the Y Meadows application we suggest that you explicitly ask for a true/false value.

This is done with the bool() command such as with: bool(🔵) to check if the data pill has any data in it

Python Modules Available For Use In Y Meadows Expressions

While you can not import modules for use in expressions Y Meadows has provided a list of common modules that can be used.

The available Python Modules that can be used in expressions:

• math (eg: math.ceil(), etc)

• re (eg: re.sub(“xyz”,”XYZ”, “wxyz”))

• datetime is imported as dt with the following modules directly availble:

  • datetime

  • date

  • time

  • timezone

  • tzinfo

• unicodedata

• time as tm (eg: tm.time() note that time.sleep() is blacklisted )

• json

Python module imports for testing

Sometimes it is useful to test python expressions outside of Y Meadows. When doing this it can be helpful to use the following import statements at the beginning of the test session/program.

import re
import datetime as dt
import math
import time as tm
tm.sleep = None  # NB: time.sleep() is blacklisted
from datetime import datetime, date, time, timezone, tzinfo
import json
import unicodedata

Any expressions that work correctly using the above imports should work identically in Y Meadows.

Testing Y Meadows expression in a code environment

When copying expressions out of Y Meadows into a coding environment the data pills will be expanded to show their internal representation. For example:

data.ef601145-a0cf-475d-89de-3392e4327d1f.subject == 'Hello World'

by removing everything up to the last '.' you can see the expression reduced to a testable form

subject == 'Hello World'

When moving an expression from a coding environment into Y Meadows be aware that the data pills can only be dragged into whitespace in an expression. In some cases you may need to add space to make room for the variable substitution. For example, the following is a valid python expression:

f"{subject} {body}"

Hwever, when attempting to replace the variables with output pills it will be easier to perform the drag-and-drop operation if the expression is written as:

f"{ subject } { body }"

Data Types

Each Step Input is expecting a specific kind of data, commonly called a data type. Some inputs expect a True/False answer, some expect numbers and others take text (or strings), etc. When inserting data from a previous step it's important to make sure that the output data is aligned with the expectation of the input.

When you have data that does not match the expected type there are simple ways to create alignment. For example if an output pill contains a number (eg:123) and the input requires a string (eg:"123") it is possible to use:

str( 🔵 )

in the expression editor. Notice that the difference between 123 and "123" is pretty subtle! Different ways of aligning data will be shown below as each different data type is discussed.

Plain Text (string)

Most inputs expect a plain-text or string input. If the desired string is Hello World, then the expression needed is any of the following:

'Hello World'

"Hello World"

"""Hello World"""

Put some kind of quotation mark around the text, using care when your text contains a quotation mark. ("Let's go!" or '"I will not", said Jamet' or '''Willy said "I can't"'''. Note that it is never correct to put quotation marks around the data "pill" for a step output.

When the input requires a string and the output is not a string the str() function may be helpful:

str( 🔵 )

Boolean (boolean)

Inputs that answer a Yes/No question are often Boolean. The literal values that can be used for Boolean inputs are:

True

False

Quotation marks are NOT used here!

The Python computer language that the expression editor uses has a broad concept of truth for Booleans. Any number other than zero is True, any non-empty string is True and a list that contains any items is True. You can read more here.

It's also possible to use <,>,==, etc. to compare data. So, expressions like

🔵 < 100

🔵 > '"m"

"C" <= 🔵 <= "F"

are all possible. Read more about Python comparison operators here.

HTML (string)

HTML is not really a data type but an expression of what kind of content is expected. In the Y Meadows application HTML is used as an indication that the input is compatible with HTML markup. For example, if the input described the body of an email message then the use of HTML markup would not be seen by the recipient literally but would affect things like BOLD or italic words in the message. There is a wealth of information online about how to use HTML for formatting text.

Like Strings, HTML must be encased in quotation marks. Triple quotes are probably safest.

List (list)

Some inputs expect more than one piece of information. For example it is possible to send an email message to more than one recipient. Lists usually expect a list of strings but other types of data are possible. Unless the output data that is being used is also a list it will be common to use [] brackets and commas to fill in a list like so:

["one", "two", "three"]

[ 🔵 ]

Are both lists. Even if there is only one item in the list it must still be wrapped in brackets []

The Python language has a sophisticated list handling feature called List Comprehension that can be very helpful when working with outputs that contain lists. It is beyond the scope of this document to explain list comprehension but it can be used to modify a list, change values in a consistent way or to exclude items from a list and is very useful within a Y Meadows Journey.

Number (number)

Inputs that expect numbers are common. Unfortunately outputs that return strings that are really numbers are also common. When there is a need to convert a string to a number there are two methods that are commonly used:

float( 🔵 )

int( 🔵 )

float turns a string into a number with decimals ("78" becomes 78.0) while int turns a string into an integer ("7.99" becomes 7). Pay attention to the unexpected way that int throws away information instead of rounding in the expected way.

Key/Value Pair

The Y Meadows application has a special input type called Key/Value Pairs that is used for some steps and looks like this:

This input type is used when both a name and a value are needed, such as when setting values for a custom web-form. The Name is treated specially in that it is a string that does not need quotation marks around it. For most steps that accept Key/Value pairs the Names are determined by external system requirements and they often can not start with numbers or contain spaces.

The Value side of the input will have a data type as described above and will be treated accordingly. String Values must have quotes, etc.