Structured Data Types

• Background
• Defining Structured Data Types
• Composite Types
• Using Referenced Structured Data Definition
• Type Definition for Enumeration
• Type Definition for Patterned
• Importing Types
• Exporting Types
• Copying Structured Data Types
• Deleting Structured Types
• XPDL Representation of Structured Data
• Using Structured Data For Process Data
• Mapping XSD Types
• Data Mappings for Structured Data
• Using Structured Data in WebService Applications
• Structured Data and Java Type Applications
• Data Structure Annotations and Field Annotations
• Using Structured Data as Descriptors
• Structure Data Storage
• XSD Schema Validation
• Structured Types and GUI Generation
• Setting Up Transition Conditions for Structured Data

Background

The Stardust Workflow Execution Perspective supports a variety of data technologies such as

1. Primitive data,
2. Serializable Java classes,
3. Entity Beans,
4. Classes persisted via the Hibernate O/R mapper or
5. XML data.

All the above are encapsulating "dereferentiation behavior" - how to obtain specific details from data represented in these technologies and also how these data are stored and loaded during the execution of business processes.

To describe structured data - e.g. a person with a first name, a last name and an address, while the address has a street name, a number a city and a ZIP code -, a data technology out of 2. to 5. can be used. However all these technologies require additional programming skills in Java or XML.

Structured data types provide mechanisms to define and work with structured data without programming skills in Stardust.

Having defined such data types in the modeling environment of Stardust, these can be used for data definitions and Stardust will take care of their persistence in and their efficient retrieval from the Audit Trail database.

Defining Structured Data Types

Structured data are defined on the Structured Types element in the outline view of the model.

Figure: Structured Types in the Outline View

Two categories of structured data types can be defined

• Composite Types and
• Enumeration Types.

Additionally you can import Types, see section Importing Types.

The Structured Types tree contains a table tree structure with all defined structured types:

Figure: Structured Types Subtree

Composite Types

Composite types are data types with fields of the following types

• primitive data (integer, string, boolean),
• enumerations (see below),
• other composite types and
• lists of all of the above.

for example to describe a person or order data.

To create a new composite type:

• In the outline view right-click the Structured Types entry.
• Choose New Composite.

Figure: Create a New Composite Type.

The name of the new composite type can be specified in the General properties settings.

Using the Visibility Public option, you can specify whether you want to import type definition by reference when referenced in another model. By default, the Visibility Public checkbox is selected. For more information, please refer to Multi Package Modeling Preferences section of Setting Process Manager Preferences chapter.

Figure: Composite Type - Visibility Public

The target namespace of the schema contained by a type declaration is selected by default. This namespace is used in creating and parsing XML documents based on this type declaration schema. A type declaration uses two fields, the location which specifies the id of the other model and the Xref which specifies the id of the type declaration in the other model.

To edit the new composite type, open its properties page with a double-click on its entry in the Structured Types tree.

Figure: Structured Type tree

Data fields can be specified in the Structured Type Definition field.

To create a new data field, select the <new> table cell, type in a name for the data field to be created and press the TAB key. An entire row representing the new data field will be displayed and can be edited by selecting the corresponding table cells:

Figure: Structured Type Definition

Note that when using structured data that has cardinality zero or more in scoped data, the data path must be set accordingly. If the data path of structured data is not set according to cardinality a validation warning is displayed. For example, if the cardinality is defined as Zero or more then the data path should be set as structured data[0]. The following screenshot displays the warning message:

Figure: Structured Data with Cardinality - Validation Warning

Types

In the Type column you can select xsd types as well as all other composite and enumeration types - except the current composite type to avoid recursion.

Figure: Choose a Type.

Choice

Embedded Unions

Figure: Setting a Choice Type.

Anonymous substructures

Anonymous substructures can be defined within a structure in order to fully support XSD composite structures without defining the substructures as separate data structure definitions.

For example:

<xs:complexType name="PaymentTypeInformation1">
   <xs:sequence>
      <xs:element name="InstrPrty" type="Priority2Code"/>
         <xs:choice>
          <xs:element name="SvcLvl" type="ServiceLevel2Choice"/>
        <xs:element name="ClrChanl" type="ClearingChannel2Code"/>
      </xs:choice>
      <xs:element name="LclInstrm" type="LocalInstrument1Choice"/>
      <xs:element name="CtgyPurp" type="PaymentCategoryPurpose1Code"/>
   </xs:sequence>
</xs:complexType>

Selecting the <xsd:anonymous> type sets the type of the new field to <New Composition> and creates an indented line to enter subfields for this composition.

The <new> entry appears as the last node whenever the node is expanded.

Figure: Selecting the Anonymous Type.

Figure: Subtree of Anonymous Type.

If the type of the field of the anonymous composition is changed to another type later, the subfields are deleted.

Attribute type

In case you intend to export a schema file containing XML attribute types, use the <attribute> type, e.g.:

Figure: Selecting the Attribute Type.

An attribute type is displayed with an attribute icon on the left side of the name:

Figure: Attribute Type displayed in Structured Type Definition.

If you import a schema file containing XML attribute types, these types will be mapped as <attribute> type. Note that attribute types can have the cardinality Optional, Prohibited or Required as shown in the above figure.

For example importing a schema file containing:

...
  <xsd:complexType name="Product">
    <xsd:sequence>
      <xsd:element name="Name" type="xsd:string"/>
      <xsd:element name="Synopsis" type="xsd:string"/>
      <xsd:element name="State" type="xsd:string"/>
    </xsd:sequence>
    <xsd:attribute name="Analysis" type="xsd:string" use="required"/>
  </xsd:complexType>
  <xsd:element name="Product" type="pro:Product"/>
...

will result in the following structured data definition:

Figure: Imported Type Example.

Cardinality

In the Cardinality column, you can specify, how many times the selected type should occur. The following cardinalities can be selected:

• Exactly One
• Zero or One
• Zero or More
• One or More

Figure: Choose Cardinality.

The One or More cardinality provides a list-like behavior.

For Attribute Type, following cardinalities can be selected:

• Optional
• Prohibited
• Required

Order of keys

You can change the order of the keys by using the Move Up and Move Down buttons.

! Tip:

You can create your entire structure just by using the TAB key, typing in names and selecting types and cardinalities with the UP/DOWN keys.

Annotation Field

At the bottom of the composite property page, a table tree view is added to modify predefined annotations. Please refer to the section Data Structure Annotations and Field Annotations for more information on the usage of annotations.

Storage

Optionally set the values for Indexing and Persistence in the Property column. By default all data fields in the structure are persisted and indexed.

Indexing: choose between Indexed and Not Indexed.

A field being indexed results in the creation of a corresponding row for the field's value in the table STRUCTURED_DATA_VALUE in the audit trail database. By setting some fields to Not Indexed the size of the table can be kept effectively smaller. Thus, to keep the table size small, only fields that are the basis for descriptors or are candidates for DataFilters in queries should be indexed.

Persistence: choose between Persistent and Transient.

Please note that setting Persistence to Transient overrules the Indexing setting. A field that is transient is never indexed and never saved. It allows your structured data to conform to existing XSDs while optimizing the footprint of the structure in the audit trail database.

To delete values set for Indexing or Persistence, right-click on the field and select Delete, as shown in the following screenshot:

Figure: Clearing a Value.

Edit in Structure

To add an additional column Indexing in the structured table with indexing information to the attributes pane, enable the checkbox in the Edit in Structure column as shown in the following screenshot:

Figure: Enable Indexing for Edit in Structure.

The additional column vanishes as soon as the checkbox is disabled or a field is selected which does not have the property set.

To add an additional column Persistence in the structured table with persistence information to the attributes pane, enable the checkbox in the Edit in Structure column as shown in the following screenshot:

Figure: Enable Persistence for Edit in Structure.

The additional column vanishes as soon as the checkbox is disabled or a field is selected which does not have the property set.

Change all

In case Change all is selected, changing one entry for Persistence or Indexing either in the Value column or in the according structured table columns, will change the value for all fields.

Figure: Enable Change all to reflect value on all entries.

Defining Field Level Presentation for Structure Data

You can define certain properties to control each field of structured data. For example, if you define a Read Only property for a the field Customer ID then in the Stardust Portal the user cannot edit the Customer ID field.

Figure: Structured Data - Field Level Properties

You can define following field level properties for a structured data:

For more information, please refer to the section Manual Activity Panel for Structured Data with Field Level Properties of the Activities Execution View of The Workflow Execution Perspective .

Using Referenced Structured Data Definition

Once the file connection is established, the referenced structured data definition can be referred in another model. Note that the structured types from the referenced model are read only. You cannot edit the referenced structured types. To refer the structure data in the referencing model:

In the referencing model, drag and drop the structure data from the Outline view > External Model Information > File Connection

Figure: Drag Referenced Structured Data

Double-click on the dragged structured data in the diagram canvas. The structured data properties get displayed.

Click on the Structured Data Definition. The declared types are displayed. If you select the check box Display Imported Model Elements as Groups then the references for the declared types are also displayed.

Figure: Referenced Declared Type

Type Definition for Enumeration

The Stardust Structured data type supports two flavors of the xsd simple types that are enumerations and patterned. The Enumeration type means that the data object will be of type string and it will accept values from the list of values defined in the enumeration. Enumeration types are lists of enumeration keys, e.g. to describe salutations, titles or countries.

To create a new enumeration type:

• In the outline view right-click the Structured Types entry.
• Choose New Enumeration.

Figure: Create a New Enumeration Type.

To edit the properties of the enumeration type, double-click its entry in the structured types tree.

Select the <new> cell, type in an enumeration key and press the TAB key.

Optionally you can enter a Minimum Length and a Maximum Length for the enumeration field.

To change the order of enumeration keys use the Move Up and Move Down buttons.

Type Definition for Patterned

The Patterned type means that the data object is of type string and it accepts values conforming to the defined pattern. Patterned types are series of values. You can define exact sequence of characters that are acceptable. For example, you can define series of numbers [0 - 9] and letters [a - z], gender [male - feamale] where you can give choice.

To create a new patterened type:

• In the outline view right-click the Structured Types entry.
• Choose New Enumeration.
• Select Patterned from the Structured Type Definition

Figure: Patterened Type

Select the <new> cell, type in an enumeration key and press the TAB key.

Figure: Patterened Type Values

Optionally you can enter a Minimum Length and a Maximum Length for the enumeration field.

To change the order of enumeration keys use the Move Up and Move Down buttons.

Importing Types

XSD files describing one or more data structure definition can be imported. The corresponding data structure definitions will be created.

To import an xsd file select Structured Types > Import Types in the Outline view:

Figure: Import Types

A dialog opens where you can choose if you want to select the schema from:

• Workbench projects or
• HTTP

Figure: Choose where to select the Schema from.

Selecting from Workbench Projects

In case you chose to select from workbench project, the next dialog offers to import appropriate files. Select Import Files... to open the file import dialog.

Figure: Import Files

Now browse to the import resource in your local file system.

Figure: Browse to File.

Now select Finish to accept the files you selected. Select the schema file from the projects and click Next.

Figure: Select an XML Schema File.

Choose the types you want to import and select Finish to close the dialog.

Figure: Choose the Types to be imported.

Selecting from HTTP

To select the schema from HTTP:

1. Choose HTTP and click Next.
2. In the Select an XML schema file from HTTP dialog, type in the URL for your XML schema and select Load to load this URL, e.g.:

Figure: Enter a URL for your schema.

3. After a successful load of the URL, select Next.
4. You can optionally save the resource in your current project.

Figure: Using the Loaded Schema

5. In the next dialog select the types you like to import.
6. You can optionally save the original schema in the model to make the imported structured data editable.

Figure: Select the Types to be imported.

7. Finish the dialog.

Now the imported type is added to your model. You can see it in the structured types tree of the Outline view, e.g.:

Figure: Imported Structured Type

Note
Please note that there will be no warning in case the imported types have the same name or Id like existing structured types. You need to rename them explicitly.

Exporting Types

Data structure definitions can be exported to XSD for single data structures or for all data structure definitions in a process model. To export a structured data type:

1. In the Outline view right-click the data and select Export Schema.

2. The Export XML schema dialog opens.
3. In case the type depends on other structured types, you have to select in a list the types to be exported.

4. Select folder where you like your schema to be located.

Now the exported types appear as xsd files in the selected folder, e.g.:

Figure: Exported Schema Files

Copying Structured Data Types

When copying a structured data to another model or project, the structured type is created automatically. In case a structured type with this name already exists, a dialog opens to enter a new name:

Figure: Enter a New Name

Copying structured data with imported XSD files

Note that in case you copy structured data types, which use an imported XSD file, between different projects, you have to copy the according XSD file to the target project first. Otherwise a warning dialog opens to remind you to copy this file, e.g.:

Figure: XSD Copy Warning Dialog

Deleting Structured Types

To delete a type, right-click it in the Outline view and select Delete Element. When a structured data type is deleted, which is used in process data, appropriate validation warnings are created, but entries concerning the type are left unchanged.

XPDL Representation of Structured Data

Structured data are stored in the TypeDeclarations section of an XPDL file according to the XPDL standard.

<xpdl:TypeDeclaration Id="Address" Name="Address">
   <xpdl:SchemaType>
        <xsd:schema xmlns:Cou="http://www.infinity.com/bpm/model/NewWorkflowModel/Country"
            xmlns:tns="http://www.infinity.com/bpm/model/NewWorkflowModel/Address" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                targetNamespace="http://www.infinity.com/bpm/model/NewWorkflowModel/Address">
            <xsd:complexType name="Address">
                <xsd:sequence>
                    <xsd:element name="Street" type="xsd:string"/>
                    <xsd:element name="Number" type="xsd:string"/>
                    <xsd:element name="City" type="xsd:string"/>
                    <xsd:element name="Country" type="xsd:string"/>
                </xsd:sequence>
            </xsd:complexType>
            <xsd:element name="Address" type="tns:Address"/>
        </xsd:schema>
    </xpdl:SchemaType>
</xpdl:TypeDeclaration>

Using Structured Data For Process Data

Select Structured Data as the data type for process data from the modeler palette or from the New Data option for the pop-up menu for the model node in the outline and select one of the structured data types defined for the process model as described above on the Structured Data Definition property page.

Figure: Create a Data with Type Structured Data.

Figure: Property Page of Data Type Structured Data.

Mapping XSD Types

Some XSD types specified in structured data will be converted to JavaScript types when used for Message Transformation applications or in transition conditions. For Java representations like Map, List or Object, they have to be converted to Java types. The following table displays the mapping performed for the XSD types:

XSD:anyType

When the actual type is not defined for any element or attribute, the xsd:anyType is the default type for that. The values for elements or attributes of type xsd:anyType are persisted with the Java type String. If the value of an xsd:anyType element is another element, the persisted value is the corresponding xml fragment as String. For example, <some_element>...content (can be mixed - complex element)...</some_element>. Serialization of a structured data containing xsd:anyType elements via MessageSerializationApplication creates a valid xml with the xml fragment correctly embedded in the document.

Behavior of XSD:date Field

The XSD:date fields are not localized. Because the Server Time Zone and Client Time Zone may not match. It means, if you map the XSD:date field and try to view it in Stardust Portal, the date value is displayed irrespective of Client Time Zone. To view date and time, use XSD:dateTime field.

Comparing Decimal XSD Types

Please note that decimal xsd types are mapped as String values and thus are compared like Strings in transition conditions. To avoid this, use a Number typecast, e.g.:

Number(StructData1.decimal) > Number(StructData2.decimal)

Data Mappings for Structured Data

Data in process data of structured type can be obtained or modified via XPath-like dereferentiation paths. However, defining such dereferentiation paths does not require any XPath skills.

• Defining the Data Mappings
• Transform Structured Data to DOM object
• XOM Conversion Not Supported
• Behavior for IN and OUT Data Mappings

Defining the Data Mappings

Create IN/OUT data mappings between an activity and a data of structured type as described in chapter Specifying Data Mappings:

After opening the data mapping dialog

and selecting the Browse button, the data path browser will open and show the top level of the data structure, e.g.

By selecting one cell in the Next Element column, you navigate to this element:

until you have reached an atomic data as shown in the following figure:

Please refer to the section Transform Structured Data to DOM Objects for a detailed description of the DOM option visible in the above screenshot.

If the selected field has a list type, you need to specify, whether you intend to retrieve the entire list, e.g.:

or a single element, e.g.:

Note, that you can access lists of lists as results of the dereferentiation this way.

The Back and Next buttons allow you to step back and forth in the dereferentiation path.

The path created in the path browser can be stored in the data mapping via the Finish button.

Transform Structured Data to DOM object

The DOM options, which you can set in the data path dialog, allow you to transform the structured data type to DOM objects. Using DOM() converts the Structured Data into a data of type org.w3c.dom.Element.

If you have an activity and you have connected a data of type structured data to it, you can set these options in the Access path browser on the corresponding property page of the activity (datamappings). For application activities, take care to add the correct return type to your application class methods depending on the used object. The following application class gives an example class, which is called in an application activity using DOM() in a data path:

import org.w3c.dom.Element;

public class DOMApplication {

	private Element myElement;
	
	public Element complete(Element aEle) {
		System.out.println(aEle);
		return aEle;
	}

	public void setMyElement(Element myElement) {
		this.myElement = myElement;
	}

	public Element getMyElement() {
		return myElement;
	}
	

In the application, you can use the methods from this class in as access points. E.g.:

Figure: Using DOM in data path

Behavior for IN and OUT Data Mappings

The semantics of IN and OUT data mappings defined on structured data differ for different dereferentiation paths. The following table describes possible IN- and OUT- data mapping expressions for example schema:

Note, that the rule to decide if java.util.List or java.util.Map should be used: if all XPath parts can only return one element, java.util.Map will be used as Java type, otherwise java.util.List. The term "can only return one element" is true, if the element per definition has a maxOccurs=1 or a unique index is used ([last()], ([first()], [NUMBER]).

Using Structured Data in WebService Applications

To use structured data as input or output for WebService Applications, please refer to the section Structured Data as Input and Output of the chapter Integrating Synchronous Web Services for detailed information.

Structured Data and Java Type Applications

Details on how to use structured data types with Java application types (Java classes, Session Beans) can be obtained from the chapter Structured Data and Java Type Applications of the Programming Guide.

Data Structure Annotations and Field Annotations

Primitive fields of composite data structures and composite data structures themselves can have annotations.

Annotations are grouped in categories. The following categories are supported for leaf fields of composite data structures:

Annotation Editor

At the bottom of the composite property page, a table tree view is added to modify predefined annotations for all elements of the composite type:

For enumerations this table tree remains empty.

XPDL/XSD Representation

Global annotations are stored as XSD annotations in the following structure:

<xsd:schema xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:infinity="...">
   <xsd:element name="customer" type="Customer"> <xsd:annotation>
   <xsd:complexType>
    <xsd:sequence minOccurs="0">
     <xsd:element name="someString" type="xsd:string" maxOccurs="unbounded">
      <xsd:annotation>
       <xsd:appinfo>
        <infinity:storage>
         <infinity:indexed>false/infinity:indexed>
         <infinity:persistent>false</infinity:persistent>
        </infinity:storage>
       </xsd:appinfo>
      </xsd:annotation>
     </xsd:element>
    </xsd:sequence>
   </xsd:complexType>
  </xsd:element>
</xsd:schema>

Other formats may specify how to store their annotations in a corresponding XSD structure in the implementation of the Message Format extension point. For example combining upcoming SWIFT standards and global annotations from the Process Workbench, an XSD representation of a data structure definition would look like:

<xs:annotation>
   <xs:appinfo>
      <info:FinFormat value="16c"/>
   </xs:appinfo>
</xs:annotation>

<xsd:schema xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:infinity="http://www.carnot.ag/xpdl/3.1">
   <xsd:element name="customer" type="Customer">
   <xsd:complexType>
    <xsd:sequence minOccurs="0">
     <xsd:element name="someString" type="xsd:string" maxOccurs="unbounded">
      <xsd:annotation>
       <xsd:appinfo>

     <!--Stardust global annotations-->
        <infinity:storage> 
         <infinity:indexed>false</infinity:indexed>
         <infinity:persistent>false</infinity:persistent>
        </infinity:storage>
       </xsd:appinfo>
      </xsd:annotation>
     </xsd:element>
    </xsd:sequence>
   </xsd:complexType>
  </xsd:element>
</xsd:schema>

Extension Point

Annotations and categories can be dynamically added to the modeling environment with an Eclipse extension point, which:

• defines a category for the annotation editor (e.g. SWIFT),
• parses annotations for all relevant nodes of an XSD tree and creates annotation objects for the internal data structure model.
• generates annotations for all relevant nodes of an XSD tree based on the internal data structure model.
• defines label providers and optionally in-place editors for all annotations in the category specified by the extension type.

Select the following link to view the schema description of the applicationInfo extension point: applicationInfo schema

Using Structured Data as Descriptors

Primitive data retrieved from structured data can be used as descriptors for process definitions:

with the same dereferentiation path mechanisms as for Data Mappings of Structured Data:

Please refer to the section Descriptors of the chapter Working with Data Paths for general information on the usage of descriptors.

Structure Data Storage

Process data of structured type are stored in the tables in the Stardust Audit Trail Database. The storage layout is optimized for efficient access in queries.

See details about structured data storage in the chapter Structured Data Storage of the Operation Guide.

XSD Schema Validation

Per default, a strict xpath validation will be performed on XSD schemas. To change the validation behavior, you can set the property XPath.StrictEvaluation in your carnot.properties file.

If this property is set to true, which is the default value, strict XPath evaluation will be performed. Set to false, dereferentiation paths on structured data are invoked, even if the XSD schema has changed, provided the path is still compatible with the new schema. Otherwise invocation fails.

Structured Types and GUI Generation

The Stardust Workflow Execution Perspective supports the automatic generation of GUI forms to display and modify data of structured data types.

Manual Activities in the Stardust Portal

If Manual activities are activated in the JSF-based Workflow Execution Perspective a form is created at runtime for all data mappings whose endpoints return

• primitive
• and structured

data types.

For the primitive and structured data the following mapping rules are used

Data Mapping Endpoint Type	GUI Element
Integer, float or string type	Entry fields with corresponding validation rules. Readonly, when the data mapping is an IN path only.
Boolean type	Checkbox. Readonly, when the data mapping is an IN path only.
Enumeration type	Combo box with enumeration keys. Readonly, when the data mapping is an IN path only.
Composite data type	Titled boxes with GUI elements for all fields of the composite type
List of the above	Tables displaying the corresponding GUI elements for all list entries and GUI controls to add and remove list elements as well as collapse and expand the displayed GUI elements according to the following list collapse all list elements expand all list elements add new list element The add and delete button are missing when the data mapping is an IN path only.

For example, for the structure

and the following data mapping

whereby customer is of structured type Person, the following GUI form is generated:

Mapping of Enumerations

The combobox is created if direct mapping of enumeration is provided into activities or enumeration field is inside a composite type.

Setting Up Transition Conditions for Structured Data

To set up transition conditions with structured data expressions the Data ID has to be followed the XPATH expression. For example:

<DataID>.a.b.c == <value>

references the element denoted by XPath "a.b.c" in data "DataID".

<DataID>.a.b.c[1] == <value>

references the fist element of the list denoted by XPath "a.b.c" in data "DataID".

Note - Viewing Structured Data with XPATH in the Stardust Portal

When working with XPATH enabled sturctured data in the Stardust Portal, make sure that the correct input is provided in the field. If no value is provided or XPATH is null or inappropriate, then at the time of instantiation of the process or activity in the Stardust Portal, a warning message is displayed after expanding the data. To expand the data, click on the plus sign.

The warning message looks like as shown in the following screenshot:

For detailed information on setting transition conditions please refer to the section Setting Transition Conditions in the chapter Working with Transitions.