1. Using Processes in Oracle Integration Generation 2
  2. Developer Tasks
  3. Manage Application Data
  4. Define Data

Define Data

To use data in your application, you must first define how it’s structured and stored.

Topics:

Typical Workflow for Defining the Data Used Within a Business Process

Defining how data is stored and manipulated is part of the overall design and development of an application.

Use the following typical workflow to define the data used within your process application. The first three tasks are required; complete the remaining tasks as needed.

Task Description
Define the business types Business types, such as business objects, business exceptions, and Enum objects, define the data structures used within your application.
Create data objects Data objects store the information used within your business process. Associate each activity with your business process with the data objects it requires.
Configure data associations and transformations Data associations define how information is passed between the flow elements in your business process.
Define expressions Expressions manipulate the data used in your business process.
Create business indicators Business indicators store the key performance information used in your business process.
Define input and output arguments The flow events that you use to define your business process operations allow you to define input and output arguments. These input and output arguments define the process input and output.

What You Can Do on the Business Types Page

The Business Types page provides the tools required to create and manage business types (business objects, enumeration (enum) objects, business exceptions), and also separately manage the life cycle of XML Schema Definition (XSD) files. You can use the business types in any process created for the selected application.

The Business Types page is divided into two sub views:

  • Business Types

  • Schema Files

Use the view option to alternate between views.


Description of bus-type-view.png follows
Description of the illustration bus-type-view.png

Business Types View

Use the Business Types view to perform the following tasks:

  • Create business objects.

  • Create business exceptions.

  • Create enum objects.

  • Import business objects.

  • Click Views Views icon to view the business types in Grid or List format. Grid view is the default.

    Each business type displays: its name, type (Business Object, Enum Object, Business Exception), schema, and file name.
    Description of bus-object-grid-view.png follows
    Description of the illustration bus-object-grid-view.png

    The business type is also identified by an image:

    • Business Object icon Manually created business objects

    • Form Business Object icon Form business objects

    • Import Business Object icon Imported business objects

    • Auto-generated icon Auto-generated business objects

    • Enum Object icon Enum objects

    • Business-exception icon Business exceptions

  • Click the business type name to edit it in the Business Types Editor. Click the file name to view the file details.

  • Select Include Auto-Generated to view the auto-generated business types.

    The number of auto-generated business objects that exists in the application display in parentheses.

    Include Auto-generated check box
  • Delete manually created business types.

    Note:

    The Delete icon only appears for manually created business types. You can’t delete business types that are being referenced by other artifacts.

Schema Files View

Use Schema Files view to perform the following tasks:

Work with Business Objects

Business objects let you group related types of data together to define the data structure required for your process applications. Create business objects manually or base them on a XML Schema Definition (XSD). After defining business objects, you can use them to define data objects to store the data within your application.

When manually creating business objects, you can define the hierarchical relationship between modules and objects, and the attributes used in the business object.

Note that you can’t modify XSD-based business object properties. However, if you manually create a business object with an attribute pointing to another XSD-based business object, then you can modify the property values of that attribute.

Note:

If you create a business object based on a XSD, any changes made to the XSD (modify, add, delete elements) aren’t reflected in the business object. After importing the modified XSD, you must delete the existing business object and then create a new business object on the modified XSD.

You can’t create business objects based on in-line types defined in a WSDL file. However, read-only business objects are automatically created from the WSDL file when you create a web service connection. You can create data objects based on these read-only business objects.

Want to learn more about WSDL files and web service connections? See Creating a Web Service Connection.

  • Modules

    Modules are containers that enable you to create a hierarchical structure. Each business object must be contained in a module. When you create a new business object, it’s automatically created within the BusinessData module. You can create additional business objects within a module or create additional modules.

  • Business objects

    Within a module you can define one or more business objects. A business object can contain other business objects.

  • Attributes

    Attributes define particular pieces of process data that are stored and can be shared among process activities. Attributes represent a characteristic of a real-world concept. For example, a business object that represents a person typically has firstname and lastname attributes.

You can also add documentation to your business objects and attributes. Adding documentation makes your data structures more understandable to other users who are collaborating on your application.

The following image shows an example of the hierarchical structure for the modules, business objects, and the business object attributes defined for an application.


Description of bus-obj-structure.png follows
Description of the illustration bus-obj-structure.png

An Enum object (enumeration) is a special type of business object that enables a data object to contain a set of predefined constants, such as one that includes the names of the days of the week (Sunday, Monday, Tuesday, and so on). See Creating an Enum Object.

Business exceptions convey unexpected situations that can occur while running a business process. You can use Process to define business exceptions for your application. See Creating a Business Exception.

Create a Business Object

Create new business objects (complex data types) manually. When creating your business objects you define the hierarchical relationship between modules and business objects, and the attributes used in the business object.

Note:

You can also import business objects based on XML schema (XSD) files. See Import a Business Object from XML.
To create a business object:
  1. On the Application Home tab, click Business Types.
  2. Click New Business Type New Business Type icon, then select New Business Object to manually create a business object.
  3. In the Create Business Object dialog box, enter a name for the business object or use the default name, select or add a parent module, and then:
    • Click Finish to create your new business object.
    • Click Next to add attributes.
  4. Click Add Attribute Add Attribute icon to add attributes. Enter a name, click Change Type to change the data type from the default value String, click Add. Click Finish after you add all your attributes.

Import a Business Object from XML

You can import business objects (complex data types) that are based on an XML Schema (XSD) file. During the process you define the hierarchical relationship between modules and business objects.

To import a business object:
  1. On the Application Home tab, click Business Types.
  2. Click New Business Type New Business Type icon, select Import Business Object, and then select From XML Schema.
  3. In the Import Business Object from XML Schema dialog box, enter a name for the business object (or use the default), select or add a parent module, and select an element or type defined in a schema file, or click Import Schemas from File Import Schemas from File icon to import an XSD or ZIP file. You can then highlight the required element or type from the list of elements and types.

    Note:

    Primitive types as top level elements is not supported.
  4. Click Import to create a business object based on an XSD file.

Import a Business Object from JSON

You can import business objects (complex data types) that are based on a JSON instance or schema. During the process you define the hierarchical relationship between modules and business objects.

To import a business object from JSON:
  1. On the Application Home tab, click Business Types.
  2. On the Business Types page, click Create , select Import Business Object, then From JSON.
  3. In the Import Business Object from JSON dialog box, enter a name and JSON for the business object, or click Import from File Import from File icon to import a JSON file and the definitions contained within it.
  4. Click Next to analyze and generate the JSON schema or instance, then make changes to it as needed. (Note that generation makes best guesses based on JSON contents.)
  5. Click Import to create a business object based on the JSON instance or schema.

    The following are the limitations while creating business objects using JSON schemas:

    • Imported JSON Schemas can contain references only to the definitions contained within it. External references aren't allowed.

    • Only one file or JSON schema is accepted at a time.

    • The use of required in the JSON schema doesn't impact the Not Null property of the resulting business object.

    • Imported JSON cannot have fields that are not NCName compliant, for example, they cannot contain special characters like @ $ % & / + , ; , whitespace characters, or different parenthesis. Furthermore a JSON field cannot begin with a number, a dot, or a minus character although they can appear later in the field.

    • Process doesn’t currently support JSON natively. The JSON schema is converted to an XML Schema before generating the business object.

      Note:

      Because JSON isn’t supported natively, the conversion to XML Schema must be valid. The field names (which are translated to XML Schema element names) must be compliant with XML Schema. For example, you can’t use names like some:name because the colon conflicts with the namespace prefix declaration.
    When converting a JSON schema to an XML schema, the following conventions are used:

    • All valid JSON schema blocks must define either a type, enum, or $ref keywords. JSON schema blocks not identified as type, enum or $ref are ignored.

    • The root JSON schema block can only be object type, or an enum block.

    • Only root definitions are taken into account.

    • Local definitions must be referenced by #/definitions/<local_name>.

    • Keywords allOf, anyOf, oneOf in the JSON schema map to xs:anyType in the resulting XML schema.

    • The not keyword isn't supported.

The following is an example of a JSON schema:

{
    "id": "http://some.site.somewhere/entry-schema#",
    "$schema": "http://json-schema.org/draft-04/schema#",
    "description": "schema for an fstab entry",
    "type": "object",
    "required": [ "storage" ],
    "properties": {
        "storage": {
            "type": "object",
            "oneOf": [
                { "$ref": "#/definitions/diskDevice" },
                { "$ref": "#/definitions/diskUUID" },
                { "$ref": "#/definitions/nfs" },
                { "$ref": "#/definitions/tmpfs" }
            ]
        },
        "fstype": {
            "enum": [ "ext3", "ext4", "btrfs" ]
        },
        "options": {
            "type": "array",
            "minItems": 1,
            "items": { "type": "string" },
            "uniqueItems": true
        },
        "readonly": { "type": "boolean" }
    },
    "definitions": {
        "diskDevice": {
            "properties": {
                "type": { "enum": [ "disk" ] },
                "device": {
                    "type": "string",
                    "pattern": "^/dev/[^/]+(/[^/]+)*$"
                }
            },
            "required": [ "type", "device" ],
            "additionalProperties": false
        },
        "diskUUID": {
            "properties": {
                "type": { "enum": [ "disk" ] },
                "label": {
                    "type": "string",
                    "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
                }
            },
            "required": [ "type", "label" ],
            "additionalProperties": false
        },
        "nfs": {
            "properties": {
                "type": { "enum": [ "nfs" ] },
                "remotePath": {
                    "type": "string",
                    "pattern": "^(/[^/]+)+$"
                },
                "server": {
                    "type": "string",
                    "oneOf": [
                        { "format": "host-name" },
                        { "format": "ipv4" },
                        { "format": "ipv6" }
                    ]
                }
            },
            "required": [ "type", "server", "remotePath" ],
            "additionalProperties": false
        },
        "tmpfs": {
            "properties": {
                "type": { "enum": [ "tmpfs" ] },
                "sizeInMB": {
                    "type": "integer",
                    "minimum": 16,
                    "maximum": 512
                }
            },
            "required": [ "type", "sizeInMB" ],
            "additionalProperties": false
        }
    }
}

The resulting business object in Process appears as follows:

Description of bo.png follows
Description of the illustration bo.png

In certain business cases, you may need to update a JSON (either by updating it directly or importing a newer version) with changes that are incompatible with the current JSON. An incompatible JSON can include changes like:

  • some elements or types have been removed
  • some attributes in complex type have been updated to new type
  • some attributes in complex type have been removed

While updating a JSON with incompatible changes, warning messages are displayed indicating the impact of the changes. For example, you may be notified that some business objects have to be modified or removed from the application to support the changes.

Import XML Schema Files

Import and store XML Schema (XSD) files, and then use its complex types or elements to create business objects. You can also update the root XSD and all its dependencies.

Note:

Updating your schema files using this import feature is different from the update feature in the XSD details view where you can only update the current schema file. Want to learn more about how to update the current schema file? See Upload a New Version of an XML Schema File.
To import a XSD file:
  1. On the Application Home tab, click Business Types.
  2. On the Business Types page, click the Schema Files option, and then click Import Schema Files Import Schema Files icon.
  3. In the Upload Schema File dialog box, select one of the following, and then click Validate.
    • Upload from file: Click Browse to browse for a XSD or ZIP file.
    • Use URL: Provide the URL for your XSD or Zip file.
    A summary of the files to be added are shown if the validation is successful.

    Note:

    If validation is unsuccessful, the validation errors or warnings are displayed. Validation warnings occur if some of the files that you want to upload override exiting ones. In this case, you can upload and override existing files. Whenever an unexpected error occurs, the error is logged in the server log and the upload is cancelled. You can’t import files that fail validation.
  4. Optionally, click Update to update the root XSD and all its dependencies.
  5. Click Upload to import your XSD file.

Upload a New Version of an XML Schema File

Process lets you upload and validate new versions of existing XML schema (XSD) files.

To upload a new version of an XSD file:
  1. On the Application Home tab, click Business Types.
  2. Click Schema Files.
  3. Click the name of the schema file to open it.
  4. Click Menu Menu icon and select Upload New Version.
  5. In the Upload New Version dialog box, select one of the following options:

    • Upload from file: Click Browse to browse for your XSD file.

    • Use URL: Provide the URL for your XSD file.

  6. Click Validate.

    A summary of the files to be added are shown if the validation is successful.

    Note:

    If validation is unsuccessful, then validation errors or warnings are displayed. Validation warnings occur if some of the files that you want to upload override exiting ones. In this case, you can upload and override existing files. Whenever an unexpected error occurs, the error is logged in the server log and the upload is cancelled. You can’t upload files that fail validation.
  7. Click Upload to update your XSD file.

    In certain business cases, the XSD you're trying to upload may contain changes that are incompatible with the current XSD. An incompatible XSD can include changes like:

    • some elements or types have been removed
    • some attributes in complex type have been updated to new type
    • some attributes in complex type have been removed

    While uploading an XSD with incompatible changes, you get warning messages in the Upload New Version dialog box to indicate the impact of the changes. For example, you may be notified that some business objects in the application were deleted or modified to support the incompatible changes.

Promote Schema Types and Elements to Business Objects

You can quickly create business objects (complex data types) that are based on specific XML Schema (XSD) types or elements by using the Promote feature available in the Schema Files — Details view.

To promote a schema type or element to a business object:
  1. On the Application Home tab, click Business Types.
  2. Click Schema Files to switch to the Schema Files view, which lists all schema files in the application.
    Description of schema-files-option.png follows
    Description of the illustration schema-files-option.png
  3. Click the name of the required schema file to view its details.
    Description of schema-subview.png follows
    Description of the illustration schema-subview.png

    This view shows the details of the schema file including:

    • User-defined business types

    • Auto-generated business types

    • Types and Elements with no business object defined

    You can create business objects based on the types and elements that aren’t already used for other business objects, as well as on the auto-generated business types because they’re not explicitly created by the user.

  4. Click Promote for the type or element you want to base your new business object.
    The Promote to Business Object dialog box opens.
    Description of promote-bus-obj.png follows
    Description of the illustration promote-bus-obj.png
  5. Enter a name for the new business object.
    The field is populated with the name of the selected business type or element, such as BusinessAddressType. You can use this name or change it.
  6. Select a parent module from the drop-down list or click New to create a new module and then click OK to create your business object.

Manage Business Types

After you create a business object, click its name to go to the Business Types — Data Structure page. From this page, you can add or change the type of a business object’s attributes or add documentation. You can also add modules, business objects, business exceptions, Enum objects and Enum items, and import business objects to the data structure.

The business types and related items you can add are based on what you have highlighted in the hierarchy.


Description of add-bus-type.png follows
Description of the illustration add-bus-type.png

When you highlight a business type or related item in the hierarchy, its details appear in the pane on the right. You can edit the details or add documentation. For imported business objects, the type behind the business object and the file where that type is defined is also displayed.


Description of manage-bus-types.png follows
Description of the illustration manage-bus-types.png

Right-click a business type or related item in the hierarchy to delete it, move it, or collapse a section of the hierarchy.

Think before you delete. You can’t recover a business object, module, or attribute that has been deleted. When you delete a business object or module that contains other related items, they’re also deleted. However, if the deleted business object or module contains an attribute based on a business object, that business object isn’t deleted.

Work with Data Objects

Data objects are, in general, the variables used to store the information used by your business processes. They’re defined during the design and implementation stage of a process. To complete a process application, you must ensure that you have associated each activity with the data objects it requires.

At runtime, data objects contain information that might be altered as users interact with your business process. Running processes can store, access, and manipulate data. The values stored within a data object can also be used to determine the branch that a process takes.

Process supports data objects that are based on either simple or complex data types. Which type of data type you base your data object on depends on the type of data it must handle.

  • Based on Simple Data Types

    Data objects can be based on simple data types. These are the core data types common in most programming languages. The following table lists the basic data types supported by Process.

    Type Description
    Bool Represents the logical values True or False.
    Int Represents an integer. For example: 23, –10, 0.
    Decimal Represents a number that can be expressed in decimal notation. For example: 3.14, 62, 0.023.
    Real Represents a floating-point numeric value. For example: 2e-1, 2.3E8.
    String Represents a sequence of characters. For example: This text is a string.
    Time Represents a specific time expressed as: year-month-day hour:minute:second. For example: 2014–12–14 13:20:28.
    Interval Represents a duration of time expressed as a number in years, months, days, hours, minutes, and seconds. For example: 1d3h30m.
    Binary Used to store binary data, including images or videos.

  • Based on Complex Data Types (Business Objects)

    Data objects based on complex data types (business objects) lets you create data structures that group different types of data. Business objects allow you to create data structures from data objects based on simple data types.

    For example, you can create a business object called employee that contains different types of data for employee such as id, name, and age. The relationship between data objects based on simple data types and data objects based business objects is similar to the relationship between classes and instances in the Java programming language. The following tables show this relationship.

    Data Object Simple Data Type
    id Int
    name String
    age Int
    sku Int
    price Decimal
    brand String
    type Int
    Data Object Structure
    Employee

    • id (Int)

    • name (String)

    • age (Int)
    Product

    • sku (Int)

    • brand (String)

    • type (Int)

    • price (Decimal)

    Before creating a complex data object, you must first define the business object that defines the data structure.

Create a Data Object

You can create a data object based on a simple data object type or on a business object (complex data type). If you’re creating a data object on a business object, you must create the business object first.

To create a data object:
  1. On the Application Home tab, select a process, and then click Data Objects.
  2. In the Data Objects dialog box, click Add.
  3. Enter a name for your data object or use the default name, select a simple data object type or a data object based on a business object, click Create, then click Close.

Note:

A default process data object with the name TaskOutcomeDataObject is automatically created for the human task outcome when a human task is created. The Edit and Delete links are disabled for this data object.
In the Data Objects dialog box, you can also edit or delete a data object. After editing or deleting a data object, validate your application to verify that there are no references to the changed or deleted data object.

See Work with Data Objects.

Edit or Delete a Data Object

You can edit or delete data objects.

To edit or delete a data object:
  1. Go to the Application Home tab and make sure you’re in Edit mode if you’re editing a shared application.
  2. Open the business process where you want to edit or delete a data object.
  3. Click Data Objects and expand the list of data objects for your business process.
  4. Select the specific data object.
    This step activates the Edit and Delete icons.
    Description of data-object-dialog.png follows
    Description of the illustration data-object-dialog.png
    • To edit the data object, click Edit, then change the name or data type as necessary.
    • To delete the data object, click Delete.
  5. Click Close.
After editing or deleting data objects, validate your application to verify that there are no references to the changed or deleted data objects.

After editing a data object, you must ensure that all references to it are still valid. For example, if you change a data object type from an integer to a string, you must verify that all of the expressions that use the data object still function correctly. If they don’t function correctly, the application doesn’t validate.

After deleting a data object, you must ensure that all references to it are removed. This includes any data associations and expressions that use the data object. If you don’t remove references to the deleted data object, the application doesn’t validate.

Create a Business Exception

Business exceptions are used to convey unexpected situations that can occur while running a business process. Define business exceptions for your application and use them in an error end event that is triggered under a certain condition, such as an invalid Id or poor credit rating.

To create a business exception:
  1. On the Application Home tab, click Business Types to open the Business Types page.
  2. Click New, then select New Business Exception to open the Create Business Exception dialog.
  3. Enter a name for the new business exception.
    The field is populated with a default name, such as BusinessException, BusinessException1, and so on. You can use this name or change it.
  4. Click Change Type if you want to change the type. The default value is String.
  5. Select a parent module from the drop-down list, and then click Create to create your new business exception.
    The parent module is BusinessData in most cases. If you’re an advanced user, you can click New and create a new parent module.

Create an Enum Object

You can manually create Enum objects for your application. An Enum object (enumeration) is a special type of business object that enables a data object to contain a set of predefined constants, such as one that includes the names of the days of the week (Sunday, Monday, Tuesday, and so on).

To create an Enum object:
  1. On the Application Home tab, click Business Types to open the Business Types page.
  2. Click New, then select New Enum Object to open the Create Enum Object wizard.
  3. Enter a name for the new Enum object.
    The field is populated with a default name, such as EnumObject, EnumObject1, and so on. You can use this name or change it.
  4. Click Change Type if you want to change the data type of the Enum items. The default value is String.
  5. Select a parent module from the drop-down list.
    The parent module is BusinessData in most cases. If you’re an advanced user, you can click New and create a new parent module.

    You now have two options:

    • Click Finish to create your new Enum object.
    • Continue to the next step to add Enum items.
    Perform the following steps to add Enum items.
  6. Click Next to open the Enum Items dialog.
  7. Click New to add an Enum item. Enter the name and value, then click OK.
    Continue adding as many new Enum items as required.
  8. Click Finish to create your new Enum object.