Collection stage

For an overview of the use of collections, see the collections help page; this page is a practical guide to completing the properties form of a collection stage. The collection properties dialog has a number of fields to fill in.

Name

The name that you enter identifies the collection, it will be displayed on the process diagram.

Description

The additional description field allows a lengthier narrative to be entered.

Fields

Add fields to the collection using one of two methods.

• Using data from a business object – To add fields using a business object click the Import Fields button. For further help on this option, see the Importing fields from an action.
• Manually – To manually add fields click the Add Field button as many times as the number of fields that you require. After each press of the button a field will be added to the collection. Next choose a datatype for each field using the dropdown menus

Adding fields to nested collections

A collection can contain other collections – in order to define the fields in these 'nested' collections manually, add a field and choose the datatype 'Collection'. A label appears under the Fields column indicating that the new collection's fields are Not Defined. Select the row and click on the link to define the fields for this collection.

When the fields of a nested collection are being defined, a 'breadcrumb trail' appears indicating which collection's definition is currently being edited. To return to parent collections, their name can be clicked in the breadcrumbs.

The first name in the breadcrumb trail is the name of the collection itself. Clicking this will return to the basic stage configuration in which the stage's other attributes can be modified too.

Single Row

A Single Row Collection has exactly one row – you can set a collection (the primary one defined in the stage or a nested collection) to be single row by ticking the checkbox in the Fields tab.

If you have added rows for the collection, they will be removed until only one remains when this tickbox is checked. Conversely, if the collection currently has no rows, one will be added.

Add Initial Values

Optionally you can give the collection a set of initial values. To add an initial value click the initial values tab. To add new rows to the collections initial value click the Add Row button. Each click of the button creates a new row. After a row has been added the values can be set by clicking the cells within the row.

Populating nested collections in the values

If the collection contains other collections, their values can be set by selecting the row within the value to be edited and clicking on the hyperlink representing the collection.

If the collection has no data, the link will say No Data; if it is empty, ie. it is a collection with no rows, it will say Empty. If it has any rows it will say Row m of n, where 'm' represents the current row of the collection and 'n' represents the total number of rows.

When the row is selected, a button labelled Clear will be available. This button will remove the collection, ie. reset it to say No Data.

When the values of a nested collection are being edited, a 'breadcrumb trail' appears indicating which level the values are being modified on. To return to parent collections, their name can be clicked in the breadcrumbs.

The first name in the breadcrumb trail is the name of the collection itself. Clicking this will return to the basic stage configuration in which the stage's other attributes, such as the structure of the collection and its nested collections, can be modified too.

When the dialog is currently navigating the value (initial or current value) of a nested collection, the fields tab is available for viewing, but the fields are not editable from here. In order to edit the fields, the stage itself must be navigated to by clicking on the first name in the breadcrumb trail.

Importing fields from an action

If an action accepts a collection as input, or emits a collection as output, the fields defined in that action can be imported into a collection stage, by clicking on the Import Fields button in the stage properties dialog.

When activated, a dialog opens which lists all available business objects with actions which have defined collections in their parameters.

When an object is chosen, its applicable actions are listed. On choosing an action, the parameters with defined collections are shown.

On selecting a parameter, a preview of the fields defined in that parameter is displayed. Pressing OK causes the field definitions to be transferred to the currently open collection definition.

Note that a collection definition can be imported into any nested collection – not just the topmost collection, so, for example, it is possible to have a "web service" collection with the name and URL of the web service, and an 'input' collection field with its definition imported from the web service business object, and a separate output collection with its definition imported from the outputs of the same web service business object.