Custom Data Types (CDTs)

A custom data type (CDT) is a designer-defined data structure that represents a logical grouping of related data, such as Employee and Contract. CDTs can be used to read from and write to a database table, to store information within a process, or to define inputs or outputs of a web service or Appian plug-in.

All CDTs can be downloaded and imported as XML Schema Definition (XSD) files. For information about XSDs, see the Supported XSD Elements and JPA Annotations page.

The life cycle of a CDT depends on where the authoritative data structure for your application is designed. See the diagram below for a high-level overview of the most common data type life cycle patterns.

Properties

The table below describes the properties for data types.

Property Name Description
Name Names must start with a letter or an underscore, and may contain only letters, numbers, hyphens, periods, and underscores, e.g., COB_Customer. Used in the UUID to uniquely identify the data type across environments and in object references, and therefore must not be changed.
Namespace Formatted as a URI, e.g., urn:com:appian:types:COB Used in the UUID to uniquely identify the data type across environments and in object references, and therefore must not be changed.
Description Displayed in data type pickers in the process modeler
Last Modified Updated when the data type is created, and every time that the data type is modified
Source Indicates how the data type was created or last modified:
  • XSD Import
  • Data Type Designer
  • Web Service Node
Visibility
  • Makes the data type available for use by other objects, e.g. pickers, process variables, etc.
  • Data types created from WSDL are hidden by default.
  • Controlled by the Available for selection in data type pickers checkbox in the Data Type Properties dialog.
Field Names Field names are case sensitive, and must be unique within one data type
Field Types Fields can be of the following types: primitive, custom. Other Appian types are not available.

Note: When using multiple application servers, the data type visibility is only updated in the cache of the application server you are logged into. The cache of any other application server is updated upon the next restart. To avoid restarting your application servers, log into each application server individually as this updates the data type visibility in each application server's cache.

Create

Users in the designer role can create data types in the following ways:

  • In an application, use the New menu to create a new data type using one of the following options:
    • Create from scratch: Use this option to create a completely new data type and configure it using the data type designer. If the CDT will be used to read data from or write data to a database table, Appian can generate the database table for you.
    • Duplicate existing data type: Use this option when you need to make a CDT that is similar to another CDT. All existing configuraitons on the original CDT, including any JPA annotations, will be duplicated. For example, if the original data type is mapping to a database table called Employee using the @Table annotation, the new data type will also map to the Employee table. If the CDT will be used to read data from or write data to a database table, Appian can generate the database table for you.
    • Create from database table or view: Use this option when you have an existing table or view in the database and need to create a CDT in order to read from and write to that table within Appian. A CDT will be created for you with all the configurations necessary to automatically map to that table.
    • Import XSD: Use this option if you already have an XSD file that defines your CDT. You may also create or edit multiple data types at once by importing a single XSD file that contains multiple data type definitions. If the CDT will be used to read data from or write data to a database table, Appian can generate the database table for you.
  • Import an XSD defined using a Java object as part of an Appian Plug-in
  • Import data types from a web service definition language file (WSDL) using the Call Web Service Smart Service or webservicequery() function

CDTs are identified by their combined name and namespace. When creating new data types from scratch, an existing CDT (duplicating), or a database table, the name and namespace must be unique. If you create a CDT by importing an XSD file or through a WSDL or Appian plug-in, the name and namespace do not have to be unique. This allows you to update existing CDTs in the system through these methods without having to delete them first.

Note: If you think that you could be accidentally replacing a deleted data type by using the same name and namespace, run impact analysis on the data type after creation to see if any objects depend on a previously deleted data type with the same name and namespace.

Edit

Custom data types are edited in different ways based on how they were created, how they are configured, and what they are used for. The following table links to reference information for each scenario.

Method or Usage How to Edit
Mapped to a database table See here if making changes in the database first or here if using Appian to update the table
Generated by WSDL See the update section on the Call Web Service Smart Service page
Generated by Appian plug-in See the edit section on the Custom Data Types from Java Object page
Imported with multiple types from an XSD After making the desired edits in the XSD file, navigate to the application. From there, click "New", then "Import XSD."

Before updating a data type, do the following:

  1. Use the Dependents view to determine the locations where the data type is used. Assess the impact of your changes on the related interfaces, process models, expressions, and other design objects.
  2. If the data type is used in a production system, consider any issues with backwards compatibility. The easiest way to do this is to only add fields and not change or remove existing fields.
  3. If the data type is mapped to an RDBMS through a data store, update the associated RDBMS object to reflect the data type change or check the Automatically update database schema box on the data store's designer page.

The name and namespace of the data type cannot be changed as they form the data type's universally unique identifier (UUID). Deleted types can be replaced from the application when creating a type from scratch or duplicating an existing type.

After updating the data type, a new version is created unless the only change is to the data type description or its visibility in data type pickers. When a new version of a data type is created, all objects (excluding running processes) immediately begin using the new version of the data type.

Deploying a new version of a plug-in data type will only replace the existing active data type if the plug-in version number is greater than the currently deployed plug-in version.

Updating Data Stores

Data stores that include the updated data type will also immediately begin using the new version. This means that data stores can be negatively affected even if you only add fields, unlike rules and interfaces. To ensure that you do not accidentally invalidate a dependent data store's mapping to the database, you will receive a warning dialog when you attempt to update data types through the following means:

  • Clicking "Save" from the Data Type Designer
  • Importing an XSD to create a new version from the Data Type Designer
  • Importing an XSD to create a new version from the Appian Designer

Back-end data type updates (importing an XSD in a patch or application and updating data types through an Appian plug-in) provide logs detailing the effect on dependent data stores, rather than a warning dialog.

If a deleted data type is updated by creating a new data type with the same name and namespace, you will NOT receive a warning about dependent data stores. The data store will immediately begin using the new data type structure, but the underlying database schema will not be automatically updated (even if the Automatically update database schema option is enabled).

Delete

When a data type is deleted, it is retained in the system so that objects can continue to function correctly even if referenced data types are deleted. Deleted types, however, will no longer appear in the Appian Designer or as choices in type pickers.

Upon deleting a data type, references to that data type will have a version number appended in the form of a caret (^) + version number. For example: myCDT^1, myCDT^2.

Objects that use a deleted data type can be exported and on import, will attempt to reference the most recent version of the data type. If the most recent version of the data type is deleted, import of the dependent object will still succeed. If no data type exists on the destination environment, import of the dependent object will fail.

Appian recommends that you use the Outdated Type References Metrics Log to find all objects that reference deleted data types and remove those references.

Create New Version from XSD

There are some configurations for CDTs that cannot be accessed through the data type designer. If you need to modify those configurations, you can download the XSD for the data type and re-import it to create a new version of the data type.

To download the XSD file for a data type, click Download XSD in the settings menu of the data type designer. The following types cannot be downloaded as XSD:

Once you have made the necessary changes to the file, click Create New Version from XSD in the settings menu and upload the new version of the XSD.

Import

When deploying data type edits to a production environment, all design objects will be updated to use the latest version of the data type when it is imported. Dependents of data types only need to be included in the import package if you have made changes to their definitions.

When a package containing data types is imported, only data types that have been changed or depend on a data type that has been changed will be updated.

See also: Deploying Data Types

Casting

For details on how data type data are cast, see Casting Custom Data

Variables of simple custom types that extend other simple custom types can be saved into each other because they both extend from a simple system type (like Text).

Variables of custom types that extend other custom types often cannot be successfully used to save data into each other, because of the mismatch of fields. At runtime, any fields of a derived data type that are not present in the parent data type cannot be mapped. If the parent data type is an abstract custom type with no fields, no data can be saved into it. Therefore, it is best to avoid abstract data types and extending data types.

Security

A data type does not have individual security settings. Only users in the designer role can perform any action on a data type.

The following actions can be completed by each user type in the designer role:

Actions System Administrator Basic User
Create Yes Yes
Edit Yes Yes
View Yes Yes
Download XSD Yes Yes
Delete Yes No

Usage Considerations

  • When a process variable of a data type is updated, the whole data type value is written to process history. Process history does not highlight which fields changed.
  • The typename of a custom type is the name as defined in the XSD that was used to create it. When a variable is marked as a multiple, ?list is appended to the typename to indicate that it holds multiple values. This is different than system data types which have a typename of the form List of <the type> when they are multiple. Be aware of this when using the typename() expression function with data types.
FEEDBACK