Casting in Appian

All variables in Appian are strongly typed, so a value sometimes needs to be cast from one data type to another. For example, the Number (Decimal Precise) value 123.45 can be cast to a Number (Integer), which drops the fractional part to produce 123.

Some casts lose information (such as 123.45 to 123), while others preserve all information (123 to 123.0). In general, the casts that are supported are intended to provide ease of use while acting in an expected manner. Casts that never make sense for a type are disallowed and will issue an error message during evaluation of the expression.

Casting happens consistently throughout Appian, except for nested arrays, which flatten only when saved to a process variable. For example, if you store a decimal result in a process variable defined as a Number (Integer), Appian casts the value as though you ran it through the tointeger() function. The same applies when you pass a decimal to a rule, function, or type constructor that expects a Number (Integer).

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.

All arithmetic operations

The following combinations apply to all arithmetic operations:

Addition, subtraction, and multiplication

These operations also support the following combinations:

Addition, subtraction, and division

These operations also support the following combinations:

Subtraction and division

These operations also support the following combinations:

Division

In addition to the combinations under All arithmetic operations, division returns different results for the following combinations:

General casting

Each of the following sections lists a supported target type. Within each section, the bulleted list shows the source types you can cast from, along with any special behavior.

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. In this page, all Appian object types other than users are treated as Integer Keys.

If a casting rule is not listed, it is not supported and will issue an error. If no behavior is noted for a source type, 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 in the following sections.

Cast to Password

• From Binary
• From Text

Cast to Text

• From Binary
• From Integer: The decimal base format of the number (for example, 123 as "123").
• From Number (Decimal Floating): The decimal base format of the number, with a decimal point (for example, 123.45 as "123.45"). Large values may appear in scientific notation.
• From Number (Decimal Precise): The exact value is preserved.
• From Duration: Days::Time.
• From Integer Key: [typename:integer value]. All Appian object types other than users are handled as Integer Keys, including Knowledge Centers and Documents.
• From Email Address
• From Password: * appears in place of each password character, without necessarily matching the number of characters in the password.
• From Boolean: Yes or No.
• From Date: Local date format.
• From Time: Local time format.
• From Date and Time: Local date and time format.
• From User: The username.
• From List: Comma-separated values.
• From User or Group: As a user or group Integer Key.
• From Document or Folder: As a Document or Folder Integer Key.
• From Custom Data Type: Each record can be stored as text.
• From Safe URI: The underlying text string does not change.

Cast to Integer

• From Number (Decimal Floating): The value is rounded.
• From Number (Decimal Precise): The value is rounded using HALF_EVEN rounding.
• From Text: If the text string includes a minus sign (-), the number is negative. Any data after the decimal point is dropped, and the remaining digits (0-9) form the number.
• From Duration: The value is truncated.
• From Boolean: 0 for False, 1 for True.
• From Date: Serial date value (number of days since January 1, 2035).
• From Date and Time: Serial date value (number of days since January 1, 2035).
• From Integer Key: The Integer ID number.
• From List: The head of the list is cast to an Integer.

Cast to Number (Decimal Floating)

• From Integer: The number as a Number (Decimal Floating) value.
• From Text: Similar to casting a text string to an Integer, except it retains data after the decimal point.
• From Duration: Number of days, with time as fractional days.
• From Boolean: 0.0 for False, 1.0 for True.
• From Time: Fraction of a day, where precision may be lost.
• From Integer Key: The Integer ID number as a Number (Decimal Floating) value.
• From Number (Decimal Precise): Precision can be lost because the value is stored as a floating-point number.
• From List: The head of the list is cast to a Number (Decimal Floating) value.

Cast to Number (Decimal Precise)

• From Integer: The exact value is preserved.
• From Text: The exact value is preserved. If the text string contains non-numeric characters, the cast returns an error.
• From Number (Decimal Floating): The value is rounded at 15 significant digits.
• From Time: Fraction of a day, with exact precision preserved.

For source types not listed here, Number (Decimal Precise) follows the same casting behavior as Number (Decimal Floating).

When an operation or comparison combines a Number (Decimal Precise) value with another numeric type, Appian normalizes the values first:

• With Number (Decimal Floating): The Number (Decimal Precise) value is cast to Number (Decimal Floating), and the result is Number (Decimal Floating).
• With integer: The integer is cast to Number (Decimal Precise), and the result is Number (Decimal Precise).
• With text: In both comparisons and numerical operations, the text value is cast to Number (Decimal Precise).

Cast to Duration

• From Integer: The number as a Number (Decimal Floating) value, representing a number of days.
• From Number (Decimal Floating): The number as a Number (Decimal Floating) value, representing a number of days; any fractional component becomes a fraction of a day.
• From Text: Similar to casting a text string to a Number (Decimal Floating) value.
• From Boolean: 0.0 days for False, 1.0 days for True.
• From Time: The fraction of a day as a Duration.
• From List: The head of the list is cast to a Duration.

Cast to Integer Key

• From Integer: The Integer ID of the correct form.
• From Number (Decimal Floating): Rounded to an Integer ID.
• From List: The head of the list is cast to an Integer Key. One form of Integer Key cannot be cast directly to another form (for example, you cannot convert a Page to a Group). To do this, first cast to Integer and then to the desired form of Integer Key. This is rarely useful.

Cast to User

• From Text: The user with the given username.
• From User or Group: The user, if the value represents a user; otherwise null.
• From List: The head of the list is cast to a user.

Cast to Boolean

• From Integer: False if 0, otherwise True.
• From Number (Decimal Floating): False if 0.0, otherwise True.
• From Text: True if the first character is 1, t, T, y, or Y; otherwise False.
• From List: The head of the list is cast to a Boolean.

Cast to Date

• From Text: Date in local format. This is discouraged and intended only for user input.
• From Integer: Serial date value (number of days since January 1, 2035).
• From Number (Decimal Floating): Truncated serial date value (number of days since January 1, 2035).
• From Date and Time: Truncated serial date value (number of days since January 1, 2035).
• From List: The head of the list is cast to a Date. Time is explicitly disallowed, because a value like "2pm on a Tuesday" doesn't provide useful data.

Cast to Time

• From Text: Time in local format. This is discouraged and intended only for user input.
• From Date and Time: The time component of the date and time.
• From Number (Decimal Floating): The fractional component of a date and time.
• From Duration: The fractional component, as a fraction of a day.
• From Date: Midnight.
• From Integer: Milliseconds after midnight, up to one day.
• From List: The head of the list is cast to a Time.

Cast to Date and Time

• From Text: Date and time in local format. This is discouraged and intended only for user input.
• From Date: Midnight on the given date.
• From Integer: Serial date value (number of days since January 1, 2035).
• From Number (Decimal Floating): Truncated serial date value (number of days since January 1, 2035).
• From List: The head of the list is cast to a Date and Time.

Cast to User or Group

• From User
• From Group

Cast to Document or Folder

• From Document
• From Folder

Cast to a list

• From a list of another type: Each element is cast individually. Elements that cast successfully are included in the final list; elements that fail are ignored, so a miscast list can yield an empty list.

Cast to Safe URI

• From Text: The underlying text string does not change. If the URI is not considered safe, the system produces an error.

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:

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

Feedback