Appian Data Types

Overview

The data (process variables, node inputs, node outputs, rule inputs, data store entities, or constants) used by Appian must conform to certain data types.

Appian data types can be one of the system types or a custom data type built from an XML Schema Definition (XSD), Java object, or imported from a WSDL by the Call Web Service smart service.

See Also: Conversion Functions

Any Type

The Any Type is a generic data type only available for use as an expression input for rules and certain expression functions, such as the if() function. It accepts data of any data type.

Data is stored in variables of this type by mapping an existing variable, rule, constant, or expression to its value.

Primitive System Data Types

A system data type is a required format for data stored in Appian and includes primitive types and complex types. Each system data type can be used to store either a single value or a list of values.

The following primitive system data types are available.

Boolean

Values include True / False.

  • 1 is accepted as a literal value meaning Yes.
  • 0 is accepted as a literal value meaning No.

The default value is null, which appears as [Empty Value] in a process variable. The output of an empty boolean value in an expression depends on the function used.

You can populate the value using results from the true() or false() functions.

The toboolean() function can be used to convert true/false and 0/1 values into a Boolean data type value.

See also: Casting

Date

Data in a date format can be created using the date(year, month, date) function. Variables that have a date data type do not accept text string input.

The default value for a date is [Empty Value]. The minimum value is 1/1/1000, and maximum value is 12/31/9999. Dates values are not adjusted to a different time zone when saved or displayed.

Numerical and text values can be converted to a date value using the todate() function.

Date and Time

Variables that hold a Date and Time data type refer to a point in time that is the same for all users. Date and time variables do not accept text strings as input.

A Date and Time value is saved in Greenwich Mean Time (GMT) then converted to the end-user's time zone (accounting for daylight saving time) when displayed.

GMT is the default time zone used when evaluating expressions that include Date and Time values. You can specify a different time zone in your process model properties. The time zone used for display can be the user's preferred time zone, a globally specified time zone, or the time zone context.

If a function expects a Date and Time value, and you pass it a date, the date is automatically converted to a Date and Time value, using 12:00 am for the time component.

The Date and Time value is only converted to the end user's time zone when it is displayed in the following manner. (Use separate date values and time values if you do not want this conversion to take place.)

  • As a user input
  • When used in a calendar function
  • When cast to a string

See also Time Zone Context

Date and Time format data can be created using the datetime(year, month, date, hour, minute, second) function.

Numerical and text values can be converted to a Date and Time value using the todatetime() function.

See also: Appian Functions, Internationalization Settings

Encrypted Text

This type is used to store an Encrypted Text value. An Encrypted Text value can be created in one of the following ways:

  • Entered by a user in a EncryptedTextField component
  • Generated in a plug-in using the EncryptionService public Java API

An Encrypted Text value is only decrypted when displayed as the value in an EncryptedTextField or within a plug-in using the EncryptionService public API.

A value of type Encrypted Text cannot be cast to any other type and no other type can be cast to it.

An encrypted value is larger than the corresponding plaintext value. Specifically, the value stored in memory or on disk will be the lowest multiple of 16 bytes that is greater than the size of the corresponding plaintext value in bytes.

An Encrypted Text value remains encrypted when stored on disk. The encryption key is unique to each installation.

The data type does not provide any additional access controls. Encrypted text entered by one user may be decrypted and displayed to another user if that other user has permission to view the interface in which the value is displayed.

See also: Encrypted Text Component

Number (Decimal)

Holds numeric data stored as double precision floating-point decimal numbers. The default value is 0.0.

Decimal numbers can be created from text strings using the todecimal() function.

For forms, use one of the following Text Functions to display a decimal number as a default value to avoid rounding.

  • fixed()
  • text()

Also for forms, use one of the following currency functions to display a decimal number as a default currency value.

  • dollar()
  • euro()
  • pound()
  • yen()
  • currency()

See also: Text Functions

For PVs, if you enter a number that exceeds the maximum number of digits supported by double precision floating-points, the number is truncated down to the maximum number of digits when you save the process model. It does not provide you with a warning message if this occurs.

Number (Integer)

Integer numbers can range from -2,147,483,647 to 2,147,483,647 (or from -231+1 to 231-1 in scientific notation).

The default value is 0 and the null value is -2\^31.

Integer numbers can be created from text strings using the tointeger() function.

When an arithmetic operation (such as an expression) creates a Number (Integer) value that exceeds the type's limits, the value wraps.

  • 2147483647 + 10 = -2,147,483,639
  • 2147483647 + 1 = -2147483648 - interpreted as null. When looking in the user interface at a process variable changed to this value, an [Empty Value] result is displayed.

When values that exceed the Number(Integer) range are passed through a user interface, the excessive value is changed.

  • In most cases, this is changed to a null value.

When a value that exceeds the Number(Integer) range is converted to Number(Integer) from a string in an engine server (such as when you convert text to an integer using the tointeger() function), the excessive value is changed to the maximum value.

On task forms, the Number Form Component prevents entry of values outside of the valid range.

  • If an expression is entered for a value and the Number Form Component is not mapped to a node input, any values that exceed 7 digits display in standard formatting with 7 digits of precision. For example, 2147483647 displays as 2147483000.

For PVs, if you enter a value that exceeds the Number(Integer) range, the integer will be replaced with a null value when you save the model. The Modeler does not provide you with a warning message if this occurs.

Text

This type is used to store any UTF-8 text string. Numerical values can be entered into the text data type; however, data manipulation cannot be performed on the text data type (except for report aggregations). The default value is [Empty Value].

To display text, enclose it within double quotation marks ("").

Time

Time data can be created using the time(hour,minute,second) function. Variables that have a time data type do not accept text string input.

Time values are not adjusted to a different time zone when saved or displayed.

Complex System Data Types

The following complex system types are made available in the system to support smart services.

These types cannot be edited or deleted. Their XML structure is not guaranteed to remain the same from release to release.

ApplicationTestResult

The ApplicationTestResult data type is designed to hold test result information for all expression rules in an application. This type also includes execution statistics for an individual application.

See also: ApplicationTestResult and Automated Testing for Expression Rules

DataSubset

The DataSubset data type is designed to hold the data returned by a query rule configured with a paging parameter.

It contains the following fields:

  • startIndex - This field holds a single Number(Integer) record.
  • batchSize - This field holds a single Number(Integer) record.
  • sort - This field holds multiple SortInfo records.
  • totalCount - This field holds a single Number(Integer) record.
  • data - This field holds multiple Any Type records.
  • identifiers - This field holds multiple Any Type records.

EntityData

The EntityData data type lets you define a target data store entity and the values to store in the target entity as an input value for the Write to Multiple Data Store Entities Smart Service.

It contains the following fields:

  • entity - This field holds a single Data Store Entity value in which the data to be updated is stored.
  • data - This field holds multiple Any Type values to store in the entity.

For example, a value of type EntityData where the entity and data values are stored as process variables could resemble the following when using the dictionary syntax:

{entity:pv!ENTITY_OPPORTUNITIES, data:{pv!RadiationOpp, pv!NewBusinessOpp}}

See also: Data Store Entity Data Type and Write to Multiple Data Store Entities Smart Service

EntityDataIdentifiers

The EntityDataIdentifiers data type lets you define a target data store entity and the values to delete from the target entity as an input value for the Delete from Data Store Entities Smart Service.

It contains the following fields:

  • entity - This field holds a single Data Store Entity value in which the data to be deleted is stored.
  • identifiers - This field holds multiple Any Type values for the primary key values of the data to be deleted.

For example, a value of type EntityDataIdentifiers where the entity and data values are stored as process variables could resemble the following when using the dictionary syntax:

{entity:pv!ENTITY_OPPORTUNITIES, identifiers:{pv!RadiationOpp.id, pv!NewBusinessOpp.id}}

NOTE: Make sure to use the primary key value IDs for the data rather than CDT values (for example, pv!opportunities.id rather than pv!opportunities). Using a CDT value will result in a casting error.

See also: Data Store Entity Data Type and Delete from Data Store Entities Smart Service

LabelValue

The LabelValue data type is designed to hold event labels and a nested hierarchy of sub-event labels for use by the Post Event to Feed Smart Service and the Post System Event to Feed Smart Service.

It contains the following fields:

  • label - This field holds a single Text record.
  • value - This field holds multiple Any Type records.

LabelValueTable

The LabelValueTable data type references the LabelValue type.

It contains the following field:

  • LabelValue - This field holds multiple LabelValue records.

ListViewItem

Data type used to define the record list view for record types.

It contains the following fields:

  • image - This field of type Document or User defines the image to appear in the list view next to each item.Value must be entered as an expression. If left null or empty, the first two letters of the record title display. For image file types, a thumbnail of the document displays. For user values, the user's avatar displays.
  • title - This field of type Text defines the name or short text description of the item.
  • details - This field of type Text defines a longer text description of the item.
  • timestamp - This field of type Date and Time indicate the creation modification timestamp of the item. Valid values include variables for timestamp fields of the record such as creation timestamp, a last modified timestamp, or other timestamp.

See also: a!listViewItem()

Facet

Data type produced when defining user filters using expressions.

It contains the following fields:

  • name - A Text value defining the name of the user filter that displays to end users.
  • options - An array of FacetOption values defining the list of options that a user can select from. See below: FacetOption

See also: a!facet()

FacetOption

  • id - An Integer value defining the unique identifier for the filter option.
  • name - A Text value defining the name of the option.
  • filter - The QueryFilter value that will be sent by the framework when this filter option is selected. See below: QueryFilter
  • dataCount - An optional integer value defining how many items in the data set will be selected if this filter option is chosen.

See also: a!facetOption()

ObjectTestResult

The ObjectTestResult data type is designed to hold data for each of the expression rules with test cases.

See also: ObjectTestResult and Automated Testing for Expression Rules

PagingInfo

The PagingInfo data type is designed to hold the paging configuration passed as a parameter to query rules and the Paging Grid component.

It's used primarily as an argument for the todatasubset() and a!gridField() functions.

To create a value of type PagingInfo, use the a!pagingInfo() function.

See also: todatasubset() and a!pagingInfo()

ProcessInfo

The ProcessInfo data type is designed to hold information about a running process. It contains three fields.

  • pp - A dictionary containing the properties of the process: id, name, priority, initiator, designer, start time, deadline, and timezone
  • pm - A dictionary containing the properties of the process' model at the time the process was started: id, name, description, version, creator, and timezone
  • pv - A dictionary containing the process variables of the process

See also: Process Model Properties, Process Variables

Query

The Query data type defines the grouping, aggregation, filtering, paging, and sorting configuration to be applied when querying record data. To do so, you use it as an input to the queryrecord function to return a DataSubset value containing query results and must be created ad-hoc via a type constructor. The DataSubset can then be applied to an interface component, such as a grid, pie chart, or stacked bar chart.

NOTE: Process variables cannot be created as a Query data type.

It contains the following fields:

  • selection|aggregation (Selection or Aggregation) - This optional field determines the selections or grouping and aggregations for the query. Only one Selection or Aggregation value can be used. If neither are provided, all fields of the record type are returned.
  • logicalExpression|filter|search (LogicalExpression, QueryFilter, or Search) - This optional field determines the filtration to apply to the query. Similar to the selection|aggregation field, only one value can be used. To include more than one filter, use the LogicalExpression data type with the AND operator. If none of them are provided, no filters will be applied.
  • pagingInfo - This required field holds a PagingInfo data type value and determines the paging configuration to use.

Validation of the Query data type occurs when it is evaluated with the queryrecord() function.

See also: a!query(), Record Design, and queryrecord()

Selection

Data type accepted in the selection|aggregation field of the Query data type. It can contain one or more Column data types and should be used instead of an Aggregation data type when you just want to select the columns, rather than group them together or apply an aggregation function.

See also: a!querySelection()

Column

The Column data type is only used in conjunction with the Selection data type.

It contains the following fields:

  • field - The field of the data type you want to retrieve. The fields available depend on the source of the data and the data type of that source. Fields that are children of a multiple cannot be selected. If the alias is not provided and the field name collides with another existing alias, the field name will be suffixed with an incremented digit appended to the end when returned in the result.
  • alias - (Optional) The short name by which the result of the Column value can be referenced in other areas of the query value. Values are case-sensitive. If no alias is given, the alias for the column will be inferred as the field value.
  • visible (Boolean) - (Optional) Determines whether the column should be visible to end users. If false, the data for the column will not be retrieved, but it can be used for sorting. Default value true.

See also: a!queryColumn()

Aggregation

Data type accepted in the selection|aggregation field of the Query data type. It can contain one or more AggregationColumn data types and should be used instead of a Selection data type when you want to perform a function on the selected columns. The following aggregation functions are supported: COUNT, SUM, AVG, MIN, and MAX.

See also: a!queryAggregation()

AggregationColumn

The AggregationColumn data type is only used in conjunction with the Aggregation data type.

It contains the following fields:

  • field - The dot-notation to the field of the data, such as a record type, you want to group together and/or aggregate. The fields cannot be complex or multiple values.
  • alias - The short name by which the result of the AggregationColumn value can be referenced in other places of the Query value. Values are case-sensitive.
  • visible (Boolean) - (Optional) Determines whether the grouping or aggregation column should be visible to end users. If false, the data for the column will not be retrieved, but it can be used for sorting. Default value is true.
  • isGrouping (Boolean) - (Optional) Determines whether the field should be grouped. Default value is false.
  • aggregationFunction - The function to use when aggregating the field. Valid values include COUNT, SUM, AVG, MIN, and MAX. This value is required when isGrouping is set to false.
  • groupingFunction (Text): A function that can be applied on the selected field. Valid values are YEAR and MONTH. This parameter can only be used with Date and Date and Time data types. Requires isGrouping to be true.

See also: a!queryAggregationColumn()

LogicalExpression

Data type that determines the filtration to apply.

It contains the following fields:

  • operator - Determines the operation to apply to the set filters in the logicalExpression|filter|search value. Currently the only valid values are AND and OR.
  • logicalExpression|filter|search (LogicalExpression, QueryFilter, or Search) - Nested LogicalExpression or QueryFilter values that will be operated on based on the operator value.

See also: a!queryLogicalExpression()

QueryFilter

This data type is required to configure the filter options for a expression-backed record or filter a queryrecord() function call before any grouping or aggregation is computed.

It contains the following fields:

  • field - The dot notation to the field that you want to apply the filter to.
  • operator - The operator to apply to the filter. Valid values include =, <>, >, >=, <, <=, between, in, not in, is null, not null, starts with, not starts with, ends with, not ends with, includes, not includes.
  • value - The value to compare to the given field using the given operator. Optional if the operator value is is null or not null. If the operator value is between, the value must be a list of only two elements with the lower bound as the first element and the upper bound as the second.

See also: a!queryFilter(), queryrecord()

Data type that indicates a user's search term. Used in the logicalExpression|filter|search field of a Query or LogicalExpression data type.

It contains a single field:

  • searchQuery - The text value to look for.

SortInfo

The SortInfo data type is referenced by the PagingInfo and DataSubset types and determines how data is sorted in a subset.

To create a value of type SortInfo, use the a!sortInfo() function.

See also: a!sortInfo(), PagingInfo, and DataSubset

TestCaseResult

The TestCaseResult data type is designed to hold data for each of the test cases in an object.

See also: TestCaseResult and Automated Testing for Expression Rules

TestRunResult

The TestRunResult data type is designed to hold test statistics for a test run across all applications being tested.

See also: TestRunResult and Automated Testing for Expression Rules

Writer

The Writer data type is a special data type returned by expression functions that intend to modify data. The modification of data must not happen during expression evaluation, so these functions return a Writer, which is then handled in a special way during the phase of an interface evaluation where saving into variables takes place. The Writer data type has no impact during expression evaluation - no data is written by the function that returns a writer until a variable created with the bind function is saved into in an interface.

It contains the following fields:

  • name - The name of the function that returned the writer
  • parameters - The parameters that will be used when the writer executes the data update

See also: bind() and Writer Functions

Appian Object Data Types

An Appian Object data type is a required format for objects specific to the Appian system. Similar to primitive and complex system types, each can be used to store either a single value or a list of values.

Appian Object data types are only recognizable within the Appian system.

Application

Holds an integer ID number that represents an Appian application. It can be used as a rule input to expression rules or interfaces; it can also be used as a constant and referenced from interfaces, web APIs, and process models; and finally used as a process variable from the process modeler, or as inputs to the Start Rule Tests (Applications) - Smart Service. Custom data types cannot use this data type.

Connected System

Holds an integer ID number that represents a connected system. A connected system represents an external system that is integrated with Appian.

See also: Connected System Objects

Data Store Entity

Holds an integer ID number that represents a data store entity. Data store entities are named, typed storage units within a data store. They can map to one or more tables in an external database.

It can only be applied to process variables and cannot be used to save form data from a mobile form. Data store entity IDs are not reused if the entity is deleted.

See also: Data Stores

Document

Holds an integer ID number that represents a document in Document Management. It can be used to save form data selected from a dropdown, radio button, or checkbox field input on a mobile form.

If the ID number of a document is known, you can convert it to this data type using the todocument() function. Document IDs are not reused if the document is deleted.

See also: Document Management

Document Management Community

Holds an integer number that represents a Document Management Community ID.

If the ID of a Community is known, you can convert it to this data type using the tocommunity() function. Community IDs are not reused if the community is deleted.

It cannot be used to save form data from a mobile form.

Document or Folder

Holds an integer ID number that represents a document or a folder that exists within Document Management. Document or folder IDs are not reused if the object is deleted.

It cannot be used to save form data from a mobile form.

Email Address

Holds data formatted as an email address. Variables that hold it do not accept text strings as direct input.

Email address data can be created from text strings using the toemailaddress() function.

Use the email recipient data type if you are sending email from a process.

It cannot be used to save form data from a mobile form.

Email Recipient

Email address data must be converted to email recipient data for use by the Send Email smart service.

This is done with the toemailrecipient() function, which accepts email address data, user data, or group data.

It cannot be used to save form data from a mobile form.

Folder

Holds an integer ID number that represents a folder that exists within Document Management. It can be used to save form data selected from a dropdown, radio button, or checkbox field input on a mobile form.

If the ID number of a folder is known, you can convert it to this data type using the tofolder() function. Folder IDs are not reused if the folder is deleted.

Group

Holds an integer ID number that represents a group within the system.

It can be used to save form data selected from a dropdown, radio button, or checkbox field input on a mobile form.

If the ID of a group is known, you can convert it to this data type using the togroup() function. A group ID may be reused if the group is deleted.

See also: Creating Groups

Knowledge Center

Holds an integer ID number that represents a Knowledge Center in Document Management.

If the ID number of a Knowledge Center is known, you can convert it to this data type using the toknowledgecenter() function. Knowledge Center IDs are not reused if it is deleted.

It cannot be used to save form data from a mobile form.

Process

Holds the integer ID number of an instance of a process model.

Process Model

Holds the integer ID number of a process model. Each time a process model is launched, it runs as separate process.

A process model ID may be reused if the process model is deleted.

Record Identifier

Holds the definition of a record.

You can only create constants of this data type. Process variables cannot be created of this type, and custom data types cannot be saved as this type.

To create a value of type Record Identifier, use the a!toRecordIdentifier function. To create a value of type Record Identifier for a User record, use the a!userRecordIdentifier function.

See also: a!toRecordIdentifier() and a!userRecordIdentifier()

Values of type Record Identifier are used as inputs for the Post Event to Feed Smart Service and Post System Event to Feed Smart Service to specify the record tags for an event.

See also: Post Event to Feed Smart Service and Post System Event to Feed Smart Service

RecordType

Holds the definition of a record type.

You can only create constants of this data type. Process variables cannot be created of this type, and custom data types cannot be saved as this type.

Constants of type RecordType are commonly used as parameter values for functions related to records, such as queryrecord() and urlforrecord().

See also: queryrecord(), urlforrecord(), Constants, and Record Design

Report

Holds an integer ID number that represents a report within the system.

Constants of type Report are commonly used as parameter values for report links.

SafeURI

Holds a URI value and enforces security rules during casting.

When casting from Text, the string will fail verification if it contains any of the following:

  • Any scheme other than http, https, ftp, and mailto
  • Invalid URI characters if not already escaped
  • Empty text string

The string does not change when cast to or from a Text data type.

This data type can not be used in expressions for events or process reports.

See Also

Safe Link: Link type that accepts SafeURI values to create an external link.

Task

Holds the integer ID number of a process task.

It can be used to add a link to the Paging Grid component that opens a process task in Tempo.

See also: Paging Grid

Task Report

Holds an integer ID number that represents a task report within the system.

Constants of type Task Report are commonly used as parameter values for report links.

User

Holds an Appian user account ID number.

It can be used to save form data selected from a dropdown, radio button, or checkbox field input on a mobile form.

User or Group

Holds an Appian user account or group. It is sometimes referred to as a People data type.

It can be used to save form data selected from a dropdown, radio button, or checkbox field input on a mobile form.

Custom Data Types (CDTs)

Designers can create or import their own custom data types (CDTs). These organize data into a structure that represents a logical grouping of related data, such as Employee and Contract.

For more information about creating and editing data types, see Custom Data Types (CDTs)

Mapping Data

Careful attention must be paid to data types when passing the values from one variable to another (also called mapping data).

The variables used at the node level are called node inputs and node outputs. (A node is often referred to as an activity. A node input or output can also be called an Activity Class.) These variables can be mapped into process variables, enabling process modelers to access the variables in other nodes within the process model and pass the data to other processes and sub-processes. The following properties must be taken into consideration when mapping node inputs/outputs to process variables.

  • Appian does not support a direct mapping of data from one type into another, regardless of whether the data values are compatible. You can use an expression to cast a variable from one type into another and then save the result into a new variable.

  • Appian allows you to map variables that only store single values into variables that can store multiple values using a custom output on the output tab, but not when using results listed on the output tab. Results must match according to data type and whether the data type holds multiple values (its cardinality).

  • Mapping scalars (single values) to vectors (multiple values) is only applicable when mapping process variables. Therefore, vector values cannot be set as default values in a scalar variable. For example, a variable cannot be given the default value {1,6,9,8} if the variable does not support multiple values.

Data types also apply to rule inputs and constants, but data from a node input or a process variable cannot be mapped to a rule input or a constant.

See also: Casting

FEEDBACK