All custom data types (CDTs) in Appian are defined using an XML Schema Definition (XSD) file. This page contains information about which XSD elements and Java Persistence API (JPA) annotations are supported.
Many of the configurations that are described on this page are not required in the typical workflow. For example, the basic XSD is generated for you when creating a data type through the data type designer or from a database table. Any JPA annotations that are required for specifying a primary key or defining table relationships are also automatically added for you. You can also specify CDT relationships from the data type designer.
However, if you need to use more advanced XSD elements or JPA annotations, or you are troubleshooting a data type created from a WSDL, this page provides reference information about what elements and annotations are supported in Appian and how they can be used.
The following are basic requirements for all XSDs:
http://www.appian.com/ae/types/*
.namespace
.name
attribute, or where the name attribute holds an empty value.schemaLocation
attribute that includes valid XSD defining the imported types.xsd:list
types that extend an xsd:list
type are not permitted.The following XSD elements are supported and can be used:
Element | Attribute(s) | Description |
---|---|---|
<xsd:all> | When an all data type is imported, the fields are defined in the order indicated by the all compositor. | |
<xsd:annotation> <xsd:documentation> |
The description of the custom type is taken from the contents of the first 1000 characters of the documentation element. | |
<xsd:annotation> <xsd:appinfo source="appian.jpa"> |
Indicates that JPA annotations can be used. The source attribute of the appinfo tag must be set to "appian.jpa" – those with any other source attribute values are ignored. |
|
<xsd:any> | When creating a custom data type, any elements become a string field in the custom data type. These fields are named @any. If multiple any elements occur within the same custom data type, each element name has a number appended to it, starting at 1. | |
<xsd:anyType> <xsd:anySimpleType> |
When possible, the anyType or anySimpletype elements are converted to the Any Type system data type or an existing custom data type. If the data type cannot be mapped to an existing system or custom data type, the element is converted to a string. At runtime, any data contained in a data type that cannot be mapped to a system or existing custom data type is cast to a string data type, except when it is an Appian system object (such as a document, page, user, or group).
|
|
<xsd:attribute> | name type ref form use=prohibited |
Attributes become fields in an attribute-nested item. The defined attributes become fields of an attribute-nested item named @attributes.
|
<xsd:attributeGroup> | Attributes in an attributeGroup element can be used within any data type that references it. The attributeGroup is not created as a standalone data type. | |
<xsd:choice> | If an imported schema contains the choice element, an error is returned and no data types are created; unless the choice contains a single item. When the schema defines a choice group with only a single item in it (without an actual choice) the choice is ignored and treated as the sequence compositor. Custom data types are created and no errors are returned. | |
<xsd:complexContent> | complexContent contains either restriction or extension subelements, which are handled in the same manner as restriction or extension elements. Restrictions are ignored. Extension relies on existing (already defined) data types. | |
<xsd:complexType> | name mixed=true |
A custom data type is created for each complexType defined in the schema. |
<xsd:element> | name type nillable minOccurs maxOccurs |
A field is created for each element, if it is a child of a custom data type (unless maxOccurs=0). If it is a global element, a type is created. The name attribute designates the element as it appears in the system. @Column annotation.id is not the same as ID .The type attribute lists the data type that is assigned to the element. Only the name, type, ref, and form attributes of the element declaration are supported. |
<xsd:extension> | You can import schemas that extend the set of elements, using the extension element. The custom data types that are created rely on existing (already defined) data types. | |
<xsd:group> | minOccurs maxOccurs |
Elements in a group data type can be fields of any custom data type.
|
<xsd:import> <xsd:include> |
You can import or include referenced schemas from an http URI (not https). Additional imported schemas are handled in the same manner as the primary schema, when the URL is accessible. If the schema referenced in the import/include statement cannot be retrieved, the import of the primary schema can still proceed only if the data types already exist or can be mapped to Appian system data types. | |
<xsd:list> | maxOccurs | List types are converted to Appian system data types with single or multiple values, taking the name attributed to the list.
|
<xsd:schema> | xmlns:xsd xmlns:tns targetNamespace elementFormDefault |
xmlns:xsd="http://www.w3.org/2001/XMLSchema" sets the namespace prefix "xsd" to the standard namespace in which all XSD elements are defined.
For both the xmlns:tns and targetNamespace attributes, list a URN with your organization's name, such as: "urn:com:appian:types:example" </br>
"http://www.example.org/documentation ". |
<xsd:sequence> | minOccurs maxOccurs |
If an imported schema contains a sequence, the fields are defined in the order indicated by the sequence. Sequence declarations with minOccurs or maxOccurs attributes that contain values greater than 1 are not supported. |
<xsd:simpleContent> | If simpleContent elements with attributes are encountered, the attributes are supported as string fields in the custom data type. These fields are named @value (similar to any elements). | |
<xsd:simpleType> | name | A custom data type is created for each simpleType defined in an imported schema, based on the matching Appian system data type.
|
<xsd:union> | You cannot create data types that contain a union data type directly, but it is valid for a data type defined by a WSDL to contain one. Data types that contain a union data type can not be used outside of the inputs and outputs of the Call Web Service Smart Service node, but you can save data from a field that is defined using a union type into a process variable of type text. |
The following XSD elements are not used within Appian. While data types with some of these elements will fail to import, others will import successfully but ignore the unsupported elements. The table below describes the exepcted behavior for each element.
Element | Behavior |
---|---|
<xsd:anyAttribute> | XSD imports successfully, but attributes are ignored and the data is discarded at runtime. |
facets such as the following: <simpleType name='celsiusBodyTemp'> <restriction base='decimal'> <totalDigits value='4'/> |
A warning is displayed upon import, and all facets are ignored. |
<xsd:key> <xsd:keyRef> |
XSD imports successfully, but key and keyRef elements are ignored. |
<xsd:restriction> | XSD imports successfully, but restriction elements are ignored. |
<xsd:redefine> | An error is displayed on import |
<xsd:unique>
<xsd:selector> <xsd:field> |
XSD imports successfully, but unique elements are ignored. |
When used with Data Stores, a custom data type can be used to map data to a relational database. Your custom data types can use JPA annotations in the XSD to map types and their fields to tables and columns within a database.
Many of the supported JPA annotations are automatically added for you when creating a CDT from a database table or when defining CDT relationships in the data type designer. Should you need to add additional JPA annotations to your XSD, this section contains the list of all supported annotations.
The following annotations are supported:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
@Table
@SecondaryTable
@SecondaryTables
@UniqueConstraint
@Column (with additional attributes: uniqueKey and index)
@JoinColumn
@JoinColumns
@Id
@GeneratedValue
@AttributeOverride
@AttributeOverrides
@AssociationOverride
@AssociationOverrides
@IdClass
@Transient
@Version
@Basic
@Lob
@Temporal
@Enumerated
@ManyToOne (with additional value of NONE for cascade attribute; default value of cascade is MERGE, PERSIST, REFRESH)
@OneToOne
@OneToMany (default value of cascade is ALL, which includes deleting orphans)
@JoinTable
@ManyToMany
@OrderBy
@Inheritance
@PrimaryKeyJoinColumn
@MappedSuperclass
@SequenceGenerator
@TableGenerator
See also: Section 9 of the JPA Specification for Syntax Documentation
NOTE: Name attributes for the @Table
and @Column
annotation are used exactly when referencing the data type for a data store. The letter casing will not change and the name length will not truncate. If you do not specify a name in the JPA annotation, the name attribute for <xsd:complexType>
or <xsd:element>
is used and a naming strategy is applied to it, which will make it lowercase and truncate it as needed.
Schema attributes for the @Table
annotation are lowercase when referencing the data type for a data store. If the lowercase schema attribute value doesn't match the casing of the schema in Oracle, the entity for the data store won't map correctly.
The following is an example of a typical XSD file:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:tns="urn:com:appian:types:example"
targetNamespace="urn:com:appian:types:example">
<xsd:complexType name="Employee">
<xsd:sequence>
<xsd:element name="id" nillable="true" type="xsd:int">
<xsd:annotation>
<xsd:appinfo source="appian.jpa">
@Id
@GeneratedValue
</xsd:appinfo>
</xsd:annotation>
</xsd:element>
<xsd:element name="firstName" type="xsd:string" />
<xsd:element name="lastName" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
Supported XSD Elements and JPA Annotations