Casting

Overview

All variables in Appian are strongly typed. In some cases, when using the Expression Editor, a variable's value must be cast from one data type to another. For instance, the value 123.45 has a decimal floating point number data type. This value can be cast to an integer number as the number 123. Similarly, 123 can be cast to a decimal type as 123.0.

See also: Data Types

Casting is done consistently throughout the application (except for nested arrays that only flatten when saved to a process variable).

For example, if a process variable is defined as an integer, and a decimal result of an expression is stored in the process variable, then the result will be the same as if running the data through the tointeger() function.

Also, if you pass a value of type decimal to a rule, function, or type constructor that expects a value of type integer, the value that passes would be the same as if running it through the tointeger() function first.

Operator casting

Comparison operators

Before performing a comparison with a comparison operator, the left and right sides of an expression are normalized to the same type automatically (where possible) according to the following rules:

Arithmetic

Before performing arithmetic operations, the left and right sides are normalized to the same type where possible. Arithmetic operations on combinations not listed here are disallowed. For the sake of consistency, expressions that have the same data type on each side are also listed.

Addition, subtraction, and division operations also support the following combinations (combinations specific to just subtraction or division appear in more tables below):

Subtraction and division operations also support the following combinations (combinations specific to just division appear in table after this):

Only division operations support the following combinations in addition to the other arithmetic combinations mentioned above:

General casting

The casting rules for each data type are listed in the following format:

A null is a special value, an absence of value, or term indicating that a value is not applicable. Any null of any type may be cast to any other type. All nulls are considered the same null. Null is excluded from consideration below.

Types are often based on other types or categorized as entirely within a given type. For instance, Knowledge Center and Document data types are both Integer Keys. They are listed only as Integer Keys below. (All Appian object types other than users are treated as Integer Keys for this page.)

If a casting rule is not listed, it is not supported and will issue an error. If no comment is given, then the casting rule is that the entire value is retained. For instance, a text string of abc cast to a password is still abc.

Types are always castable to themselves without change. This is known as the "identity" cast and is not listed below.

Casting custom data

One custom data type (CDT) can be cast to another CDT, when the field names match.

For example, given the following CDTs:

1
2
3
4
5
HRName 
	|
	|-lastname (text)
	|
	|-firstname (text)

— AND —

1
2
3
4
5
PayrollName 
	|
	|-lastname (text)
	|
	|-firstname (text) 

Casting HRName to PayrollName maps firstname to firstname and lastname to lastname as records with the PayrollName data type.

• General casting rules apply to types used by fields in the CDT. (Casting may fail if the fields are of different, uncastable types.)
• Fields in a CDT do not have to have a common origin to allow casting, only a common structure (field names).

See above: General Casting Rules

Casting record data

A record data type can be cast to a dictionary, map, CDT, or string. You can cast the record fields and use the relationships defined in the record type to cast related record fields. You cannot cast fields that have been excluded by a query, or were not mapped from the record type's data source.

Let's look at some examples of how to cast record data. See Casting related record data for examples of how to use your relationships to case related record fields.

Casting a record to a CDT

In the first example, we will cast the Employee record, which has four record fields: firstName, lastName, age, and phoneNumber to the Person CDT.

When casting a record to a CDT, general casting rules apply to data types used by fields in the record.

1
2
3
4
5
6
7
8
9
cast(
  type!Person,
  recordType!Employee(
    recordType!Employee.fields.firstName: "Jane",
    recordType!Employee.fields.lastName: "Doe",
    recordType!Employee.fields.age: "31",
    recordType!Employee.fields.phoneNumber: "540-234-8975"
  )
)

The expression output will result in the record field values cast to the Person CDT:

Since the age field does not exist on the Person CDT, this field was dropped.

Casting a record to a map

In this example, we'll cast the Employee record to a map.

1
2
3
4
5
6
7
8
9
cast(
  typeof(a!map()),
   recordType!Employee(
    recordType!Employee.fields.firstName: "Jane",
    recordType!Employee.fields.lastName: "Doe",
    recordType!Employee.fields.age: "31",
    recordType!Employee.fields.phoneNumber: "540-234-8975"
  )
)

The expression output will result in the record field values cast to a map:

Casting a record type to a dictionary works the same way as casting a record type to a map. A map retains the type of each value while a dictionary wraps a variant AnyType around each value in the dictionary.

Casting a map to a record

Now let's use the cast() function to cast in the opposite direction. We'll cast a map of four field values to the Employee record. In this expression, we'll use the recordType! domain to specify the Employee record.

1
2
3
4
5
6
7
8
9
cast(
  recordType!Employee,
  a!map(
    firstName: "Jane",
    lastName: "Doe",
    age: "31",
    phoneNumber: "540-234-8975"
  )
)

The expression output will result in the following map cast to the Employee record:

Casting a record to text

In the last example, we will cast the Employee record to text.

1
2
3
4
5
6
7
8
9
cast(
  3 /* Type number (Text) */,
  recordType!Employee(
    recordType!Employee.fields.firstName: "Jane",
    recordType!Employee.fields.lastName: "Doe",
    recordType!Employee.fields.age: "31",
    recordType!Employee.fields.phoneNumber: "540-234-8975"
  )
)

The expression output will result in the following record field values cast to a text string:

Casting related record data

You can use the relationships defined in the record type to cast related record fields to a nested CDT, a map, or a dictionary.

Let's take a look at a few examples.

Casting a related record to a nested CDT

In this example, we'll cast a record from the Case record type to the Case CDT. The Case record type has two fields: Id and title, and has a many-to-one relationship with the Customer record type. Similarly, the Case CDT has the fields Id, title, and customer, where customer uses a nested CDT as the data type.

When casting a related record to a nested CDT, the relationship name must match the nested CDT field name. General casting rules also apply to data types used by fields in the related record type.

1
2
3
4
5
6
7
8
9
10
11
cast(
  type!CSA_Case,
  recordType!Case(
    recordType!Case.fields.id: 1,
    recordType!Case.fields.title: "Case 1",
    recordType!Case.relationships.customer: recordType!Customer(
      recordType!Customer.fields.id: 1,
      recordType!Customer.fields.name: "John Doe"
    )
   )
  )

The expression output will result in the record field values cast to the Case CDT.

Casting a related record to a map

In this example, we'll cast a record from the Case record type to a map.

1
2
3
4
5
6
7
8
9
10
11
cast(
  typeof(a!map()),
  recordType!Case(
    recordType!Case.fields.id: 1,
    recordType!Case.fields.title: "Case 1",
    recordType!Case.relationships.customer: recordType!Customer(
      recordType!Customer.fields.id: 1,
      recordType!Customer.fields.name: "John Doe"
    )
   )
  )

The expression output will result in the record field values cast to a map:

Casting a related record type to a dictionary works the same way as casting a related record type to a map. A map retains the type of each value while a dictionary wraps a variant AnyType around each value in the dictionary.

Casting a map to a related record

Now we'll cast in the opposite direction. We'll cast a map of two record field values and two related record field values to the Case record type. In this expression, we'll use the recordType! domain to specify the Case record type.

1
2
3
4
5
6
7
8
9
10
11
cast(
  typeof(recordType!Case()),
  a!map(
    id: 1,
    title: "Case 1",
    customer: a!map(
      id: 1,
      name: "John Doe"
    )
  )
)

The expression output will result in the following map cast to the Case record type:

Casting a nested CDT to a related record

In the last example, we will cast values from the Case CDT and the nested Customer CDT to the Case record type.

1
2
3
4
5
6
7
8
9
10
11
cast(
  typeof(recordType!Case()),
  type!Case(
    id: 1,
    title: "Case 1",
    customer: type!Customer(
      id: 1,
      name: "John Doe"
    )
  )
)

The expression output will result in the following map cast to the Case record type:

Feedback