3.1 Custom Data Types (CDTs) & Schema Design

3.1 Custom Data Types (CDTs) & Schema Design

Understanding Custom Data Types (CDTs) and XSD Architecture

Custom Data Types (CDTs) are one supported way to define and pass structured business data in Appian; modern record types provide another data-modeling approach. A CDT is a developer-defined, structured data object that groups logically related attributes into a single cohesive entity. For example, a Customer CDT might bundle customer identification numbers, first and last names, corporate email addresses, credit limits, and account status flags into one unified composite variable.

Under the hood, every Custom Data Type is defined by an XML Schema Definition (XSD). The XSD file governs the structure, data typing, XML namespace, field names, and relational persistence rules for the CDT. When developers create or modify CDTs through the Appian Designer interface, Appian generates and maintains this XSD automatically. However, developers can also download the raw XSD, edit it directly in a code editor, and re-import it into Appian—a capability that becomes critical when implementing advanced object-relational mapping (ORM) annotations not exposed in the visual builder.

A CDT represents data in memory across various Appian design objects:

• Process Models: Used as process variables to pass complex business entities between workflow nodes, script tasks, and user input tasks.
• Interfaces: Used as rule inputs (ri!) to display and capture structured form data entered by end users in SAIL components.
• Expression Rules & Integrations: Passed into rules as parameters for validation, calculation, or JSON serialization for REST web APIs.
• Data Stores: Mapped directly to relational database tables through Data Store Entities (DSEs) for persistent storage.

---

CDT Creation Methods: Scratch, Database Tables, and XSD Imports

Appian provides three primary workflows for creating Custom Data Types:

When reverse-engineering a CDT from an existing database table or view, Appian inspects the relational catalog metadata. It converts SQL types (such as VARCHAR, INT, DATETIME) into corresponding Appian types and preserves primary key indicators. Conversely, when starting from scratch, developers define fields visually in Appian Designer, publish the CDT through a Data Store, and allow Appian to generate the physical database tables automatically.

---

Data Type Mapping: Appian Primitives vs. RDBMS Types

A CDT field can store either an Appian primitive type or another complex CDT (nested type). Appian maps primitive data types to standard XSD datatypes, which subsequently correspond to standard relational column definitions:

---

Java Persistence API (JPA) Annotations in XSD

Appian uses the Java Persistence API (JPA) specification (via Hibernate) to bridge in-memory CDTs with relational database tables. These annotations reside within the <xsd:annotation><xsd:appinfo source="appian.jpa"> metadata block of the XSD.

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns:tns="urn:com:appian:types:ORDER"
            targetNamespace="urn:com:appian:types:ORDER">
  <xsd:complexType name="PurchaseOrder">
    <xsd:annotation>
      <xsd:appinfo source="appian.jpa">
        @Table(name="purchase_order")
      </xsd:appinfo>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="orderId" type="xsd:int">
        <xsd:annotation>
          <xsd:appinfo source="appian.jpa">
            @Id
            @GeneratedValue
            @Column(name="order_id", nullable=false)
          </xsd:appinfo>
        </xsd:annotation>
      </xsd:element>
      <xsd:element name="orderNumber" type="xsd:string">
        <xsd:annotation>
          <xsd:appinfo source="appian.jpa">
            @Column(name="order_number", length=50, nullable=false)
          </xsd:appinfo>
        </xsd:annotation>
      </xsd:element>
      <xsd:element name="customerId" type="xsd:int">
        <xsd:annotation>
          <xsd:appinfo source="appian.jpa">
            @Column(name="customer_id", nullable=false)
          </xsd:appinfo>
        </xsd:annotation>
      </xsd:element>
    </xsd:sequence>
  </xsd:complexType>
</xsd:schema>

Essential JPA Annotations

1. @Id: Identifies the primary key attribute. Every CDT mapped to a relational table through a Data Store Entity must have exactly one primary key field marked with @Id.
2. @GeneratedValue: Instructs the database engine to assign the primary key automatically (such as an auto-increment column in MariaDB/MySQL or an identity sequence in Oracle/PostgreSQL).
3. @Table(name="..."): Overrides the default table name to match database naming conventions (e.g., lower snake_case).
4. @Column(name="...", length=..., nullable=...): Customizes the physical column name, maximum text length, and nullability constraints.
5. @JoinColumn(name="..."): Defines the physical foreign key column that links two entities.

---

Entity Relationships: 1:1, 1:N, and Many-to-Many

Relational modeling requires defining how entities relate to each other. In Appian, these relationships are expressed in the CDT's XSD using JPA relationship annotations:

1. One-to-One (1:1)

A single parent record corresponds to exactly one child record (e.g., Employee and EmployeeParkingPass). Annotated using @OneToOne with a @JoinColumn on the owning side.

2. One-to-Many (1:N) & Many-to-One (N:1)

The most common enterprise pattern (e.g., one Department has many Employees, or one PurchaseOrder has many OrderLineItems). In the parent CDT, the child field is configured as an array of child CDTs and annotated with @OneToMany. A flat child foreign-key field can avoid a cyclic nested type structure; use only relationships supported by Appian's type designer and XSD rules.

3. Many-to-Many (M:N)

For example, Students and Courses. Direct @ManyToMany JPA mappings in Appian CDTs are strongly discouraged because they introduce complex Hibernate session caching issues, fragile cascade lifecycles, and difficult querying semantics. Instead, the architectural standard is to create an explicit junction CDT (e.g., CourseEnrollment) that resolves the M:N relationship into two distinct One-to-Many relationships (Student 1:N CourseEnrollment, and Course 1:N CourseEnrollment).

---

Cascade Behaviors: Power and Pitfalls

When defining nested CDT relationships, developers can specify cascading rules using the cascade attribute inside @OneToMany or @OneToOne annotations:

• CascadeType.ALL: Propagates all operations (persist, merge, remove, refresh) from the parent entity to child entities.
• CascadeType.PERSIST / CascadeType.MERGE: Automatically saves or updates child records when the parent record is written.
• CascadeType.REFRESH: Re-reads child entities from the database when the parent is refreshed.

---

Architectural Comparison: Flat CDTs vs. Nested CDTs

In enterprise applications, developers choose between two structural patterns:

Appian best practices favor flat CDTs for high-volume transactions and enterprise workflow processes to protect process execution memory engines from bloat.

---

Primary Key Design: Surrogate vs. Natural Keys

Choosing the right primary key strategy is critical for database longevity and Appian performance:

• Surrogate Keys (Recommended): An artificial, non-business value—typically an auto-incrementing 32-bit integer within the supported Appian identifier range generated by the database engine. Surrogate keys never change, have zero business dependencies, ensure optimal B-tree indexing, and seamlessly integrate with Appian's @GeneratedValue convention.
• Natural Keys (Discouraged): Real-world business identifiers such as Social Security Numbers (SSNs), email addresses, or Vehicle Identification Numbers (VINs). Natural keys frequently change due to business reorganizations, typos, or privacy regulations, creating severe update cascades across foreign key tables.
• Composite Keys (Strongly Discouraged): Primary keys consisting of two or more columns. Do not assume arbitrary JPA @IdClass or @EmbeddedId mappings are supported in Appian CDTs. Use a supported single identifier for the CDT persistence design; modern record-type composite-key support is a separate feature.

---

Real-World Scenario: Healthcare Patient Intake

A health network designs an intake application where an IntakeEncounter record has multiple VitalSignLog records and multiple PrescriptionRequest records. Initially, the developer nests both child types inside IntakeEncounter using CascadeType.ALL. During high-volume testing, nurse stations report interface sluggishness. Process monitoring reveals that whenever a nurse logs a single blood pressure reading, the entire patient encounter, all historical vitals, and all prescriptions are loaded into the process variable and re-persisted to the database.

The lead architect refactors the design to flat CDTs. The VitalSignLog CDT stores a simple encounterId integer. Logging a vital now requires writing only a small, lightweight record to the database, reducing the data held and rewritten for that operation. Measure memory and database behavior with representative data rather than assuming a fixed reduction.

---

Exam Watchouts & Common Traps

• Missing @Id Annotation: If a CDT is mapped to a table without an @Id primary key annotation in its XSD, Data Store schema verification will fail immediately.
• Text Length Defaults: If you do not specify a @Column(length=...) annotation on a text field, Appian defaults the database column to VARCHAR(255). If user inputs exceed 255 characters, writes will fail with an SQL truncation exception.
• Modifying CDT Namespaces: Changing a CDT's target namespace in the XSD treats it as a brand-new data type, breaking dependencies across all interfaces, expression rules, and process models referencing the original type.
• XSD Upload Overwrites: When downloading an XSD, editing it, and re-uploading, always ensure that the complexType name and targetNamespace remain identical to update the existing CDT version rather than spawning a duplicate type.

Source checked 2026-10-18: Appian supported XSD/JPA mappings.