Introduction

Expressions are an integral part of Connect and are used extensively to add flexibility and logic to flows. They provide a compact, text-based way of describing operations that would otherwise require multiple nested instruction blocks. This makes flows easier to design and maintain, while still supporting complex processing requirements.

The expression language is primarily based on C# expression syntax, making it familiar to most developers. In nearly all cases, basic knowledge of writing typical programming expressions is enough to work effectively.

Expressions can be placed wherever a data source is expected, allowing them to generate values, transform inputs, or directly construct data structures.

They are always evaluated within a defined context, and JSON paths can be used inside them to access values stored in that context.

The capabilities range from standard operators such as +, -, *, /, <, >, =, and != to more complex manipulations. For example, arrays can be modified and strings can be concatenated directly. Helper functions extend the language further, enabling many common integration tasks to be handled within a single expression.

The following section provides a detailed description of the advanced syntax, available operators, and predefined helper functions.

Binary Operators

A binary expression represents an operation between two values, such as arithmetic or comparison. Both sides of the operator can be literals, JSON paths, or nested expressions in parentheses.

Type Casting

Connect expressions use a set of .NET types. When a JSON node is referenced inside an expression and a cast is requested, the node is first resolved to its literal value. After resolution, the cast is attempted against the supported types:

Type hints are also recognized on literals, such as 1m for decimal, 1f for float, 1d for double, or 0b1010 for binary numbers. These markers explicitly control the literal’s type without requiring a cast.

Casting examples

Important: When working with values from JSON paths, they may resolve as JsonNode objects instead of primitive types. Comparisons or operations can fail if the types do not align. Use explicit casts in such cases, for example:

(string)$.test == "test"

or

$.test == (JsonNode)"test"

Collections

Collection expressions define arrays or lists directly within an expression, allowing multiple values to be grouped together. Mixed-type collections are not supported.

Element Access

Element access expressions in Connect follow the same syntax as in C#. They allow indexed access to elements of collections, but in practice the most useful application is working with strings. Strings can be treated like character arrays, making it possible to select individual characters or ranges of characters.

String Manipulation

Methods

Connect exposes helpful members. Common examples:

"abc".Contains("a") // true

" abc ".Trim() // "abc"

"abcdef".Substring(1, 3) // "bcd"

"abc".ToUpperInvariant() // "ABC"

"ABC".ToLowerInvariant() // "abc"

"a,b,c".Split(",") // ["a","b","c"]

"abc".Replace("b","x") // "axc"

Interpolation

String interpolation allows expressions to be evaluated directly inside strings. The syntax uses $"..." with { } braces to insert the result of an expression into the string. This makes it easy to combine text with values, including results from expressions or built-in .NET helpers.

Examples

$"Now: {DateTime.Now}"

Inserts the current date and time 9/25/2025 10:35:50 PM.

$"ID: {Guid.NewGuid()}"

Inserts a newly generated GUID, for example ID: 3f8a4c3e-2b8e-4f61-8f20-97c3b12d92bb.

$"$.data.books['{(DateTime.Now.Year).ToString()}']"

A JSON Path pointing to the books entry for the current year $.data.books['2026'].

Array Operations

In Connect, arrays can be transformed in more complex ways using expressions. This is mainly possible through the .NET Enumerable methods, which are also applicable to JSON arrays. Below is an example setup followed by selected expressions.

Rendering...

Transform tags to uppercase

($.book.tags).AsArray().Select(x => x.ToString().ToUpperInvariant())

// ["SOFTWARE", "ENGINEERING", "PROGRAMMING", "CRAFT"]

Filter ratings > 3

($.book.ratings).AsArray().Where(r => ((JsonNode)r).GetValue() > 3)

// [5, 4, 5, 4]

Average of ratings

($.book.ratings).AsArray().Select(x => ((JsonNode)x).GetValue()).Average()

// 4.2

Maximum rating

($.book.ratings).AsArray().Select(x => ((JsonNode)x).GetValue()).Max()

// 5

Append title length to each tag

($.book.tags).AsArray().Select(t => t.ToString() + ":" + ($.book.title).ToString().Length)

// ["software:24", "engineering:24", "programming:24", "craft:24"]

Check if tags contain ‘craft’

($.book.tags).AsArray().Select(x => (x.ToString()).Contains("craft"))

// [false, false, false, true]

.NET Helpers

Member access in Connect expressions uses the dot operator (.). It is allowed to access members on instances, but not on types.

Valid:

"text".ToUpper()

123.ToString()

($.store.categories).ToString()

Invalid:

bool.TrueString

DateTime: Working with timestamps

DateTime.Now.ToString("yyyy-MM-dd") // "2025-09-25"

DateTime.Now.AddDays(1) // tomorrow's date

DateTime.UtcNow.Hour // current UTC hour

DateOnly: Calendar dates without time

DateOnly.FromDateTime(DateTime.Now) // "2025-09-25"

DateOnly.Parse("2025-01-01").Day // 1

TimeOnly: Clock times without date

TimeOnly.FromDateTime(DateTime.Now) // "23:15"

TimeOnly.Parse("08:30").AddMinutes(45)// "09:15"

TimeSpan: Durations and intervals

TimeSpan.FromHours(1.5) // 01:30:00

DateTime.Now.Add(TimeSpan.FromDays(7))// one week later

Enumerable: Sequence utilities

Enumerable.Range(1, 10) // [1,2,3,4,5,6,7,8,9,10]

Enumerable.Repeat("x", 5) // ["x","x","x","x","x"]

Guid: Generating unique IDs

Guid.NewGuid() // "3f8a4c3e-..."

Math: Numeric utilities

Math.Abs(-5) // 5

Math.Round(3.1415,2) // 3.14

Math.Max(1,10) // 10

JsonNode: JSON parsing and working with nodes

($.book.tags).AsArray().Count // 3

Regex: Pattern matching

Regex.IsMatch("abc123","[0-9]+") // true

Regex.Replace("abc123","[0-9]","x") // "abcxxx"

Object Members: Standard instance methods

42.Equals(42) // true

123.GetHashCode() // hash code of 123

Custom Helpers

ADF Helpers (Atlassian Document Format)

AdfHelper.BuildAdfParagraph("Hello World") // ADF paragraph node

AdfHelper.BuildAdfTable($.book.table) // ADF table node

Array Helpers

ArrayHelper.Append($.book.authors,"New Author")

// ["Andrew Hunt","David Thomas","New Author"]

ArrayHelper.Merge($.book.tags,$.book.moreTags)

// ["software","engineering","craft","best-practice","clean-code"]

Cast Helpers

Cast.Number($.book.price) // 42.5

Cast.String($.book.title) // "The Pragmatic Programmer"

Cast.MatchStrings(Regex.Matches($.book.isbn,"[0-9]"))

// ["9","7","8","0","2","0","1","6","1","6","2","2","4"]