Session filters are query expressions for session properties. They can be used to address a set of sessions based on their session properties. For example, it is possible to send a message to all sessions that satisfy a specified filter. Session filters are parsed and evaluated at the server.

A session filter expression consists of either a single clause, or multiple clauses connected by the binary operators and and or. The and operator takes precedence over or but parentheses can be used to override the precedence. For example:

Department is "Accounts"
hasRoles ["operator" "trading desk"]
Department is "Payroll" and Status is "Closed"
(Department is "Accounts" or Department is "Payroll") and Status is "Closed"

The unary not operator can be used to negate the following clause or an expression within parentheses:

not Department is "Payroll"
not (Department is "Payroll" or Department is "Accounts")

An equality clause has the form key operator value where key is the name of a session property and value is the property value. The supported operators are is or eq, both of which mean "equals", and ne which means "does not equal". Values are strings enclosed within single or double quotes. Special characters ('"', ''' or '\') can be included within the value by preceding with the escape character '\'. The utility function PTDiffusionEscape can be used to insert escape characters into a value.

The all operator matches all sessions.

hasRoles is a special operator for querying the $Roles session property. A hasRoles clause has the form hasRoles ["role1" "role2" ... "roleN"]. The clause will match sessions that have all the specified authorisation roles. Each role is a string enclosed within either single or double quotes. Roles can be space or comma separated.

The $Roles session property can also be queried with an equality clause, for example, $Roles eq '"admin","client"', but the hasRoles clause is usually more convenient. An equality clause will match sessions that have exactly the listed roles. In contrast, a hasRoles clause will match any sessions with the listed roles, regardless of whether they have other roles. The equality clause requires the value to be in the canonical form produced by the PTDiffusionStringFromRoles utility method.

The in operator allows for the querying of a specific session property to see if it exists in a defined set. An example of this would to be filter all sessions from a set of countries, say Germany, France, and the UK. The query would be `$Country in 'UK' 'DE' 'FR'`.

The has operator can be used to check if a property is present. This is useful for determining if user-defined properties or optional fixed propereties have been set.

All operators are case insensitive.

The lists provided to in and hasRoles can optionally use square brackets and commas as delimiters. For example `$Country in ['UK','DE','FR']`.

Examples

The following are further examples of valid session filter expressions:

$Principal is "Alice"
Department is "Accounts" and $Country ne "US"
$Language EQ "en" and $Country NE "US"
not (Department is "Accounts" or Department is "Payroll") and $Country is "FR"
Text is "xyz\"\\"
hasRoles ["operator"]
$Transport is "wss" and hasRoles ["accountancy" "administrator"]
hasRoles ["operator"] and not hasRoles ["administrator"]
hasRoles "operator" and not hasRoles "administrator"
has Department
all