Promoting a property

You can promote a node property to the message flow level to simplify the maintenance of the message flow and its nodes, and to provide common values for multiple nodes within the flow by converging promoted properties.

Before you start

To complete this task, you must have completed the following task:

To promote message flow node properties to the message flow level:

  1. Switch to the Broker Application Development perspective.
  2. Open the message flow for which you want to promote properties by double-clicking the message flow in the Navigator view. You can also open the message flow by right-clicking it in the Navigator view and clicking Open The message flow contents are displayed in the editor view.

    If this is the first message flow that you have opened, the message flow control window and the list of available built-in message flow nodes are also displayed, to the left of the editor view.

  3. In the editor view, right-click the symbol of the message flow node whose properties you want to promote, and click Promote Property. The Property Promotion dialog is displayed. The left side of the dialog lists all available properties for all the nodes within the message flow. The properties for the node that you highlighted are expanded.

    You can access all node properties from this dialog, regardless of the node that you selected when you first opened the dialog, by expanding the properties for all the other nodes in the flow (these are initially collapsed).

    The right side lists all the properties that are currently promoted to the message flow. If you have not yet promoted any properties, only the message flow name as the root of the promoted property tree is displayed on the right.

    The majority of message flow node properties are available for promotion, but you cannot promote:

    • A property group, but you can promote an individual property.
    • A property that you cannot edit (for example, the Fix property in the Validate group of properties for the MQInput node).
    • The description properties (Short Description and Long Description).
  4. Create new groups and properties for promotion. Above the list of promoted properties on the right, three icons are displayed: the new group icon (on the left), the new property icon (in the middle), and the delete icon (on the right):

    When you create a new promoted property, the name that you enter is the name by which the property is known within the system, and must meet certain Java and XML naming restrictions. These are enforced by the dialog, and a message is displayed if you enter a name that includes a non-valid character. For example, you cannot include a space or the double quote symbol.

    1. Click the new group icon The new group icon (representation of the properties dialog with a group of small colored boxes imposed on it) to add a new group to the promoted properties. The group is added below the message flow root and is given the default name Group1 (unless you have already created groups that have default names, in which case the new group name has the next highest number).

      The name field is highlighted; type over it to rename the group when it is created. You can also rename the group at any later time by double-clicking the name.

    2. Click the new property icon The new property icon (representation of the properties dialog with a small green box imposed on it) to add a new promoted property under the currently selected group (or following the currently-selected property). The property is added below the highlighted group and is given the default name Property1 (unless you have already created properties that have default names, in which case the new property name has the next highest number).

      The name field is highlighted; type over it to rename the property when it is created. You can also rename the property at any time by double-clicking the name.

    3. Click the delete icon The delete icon (a red cross) to delete the currently-selected group or property. If you delete a group, all promoted properties within the group are deleted from the list on the right. There is no confirmation of the delete action. The deleted promoted properties are, however, returned to the list on the left, where they are again available for promotion.
  5. Select the property that you want to promote to the message flow level from the list of available properties on the left of the Property Promotion dialog. The list on the left initially shows the expanded list of all available properties for the selected node. If you have already promoted properties from this node, they do not appear on the left, but on the right.

    The list on the left also includes the remaining nodes in this message flow. You can expand the properties listed under each node and work with all these properties at the same time. You do not have to close the dialog and select another node from the editor view to continue promoting properties.

  6. Drag its entry from the list on the left of the Property Promotion dialog to the list on the right, to promote a property from a message flow node to the message flow:
    1. You can drop the property in an empty space. A new group is automatically created for the message flow, and the property is placed within it, with the original name of the property and the name of the message flow node from which it came displayed beneath the property entry.

      The new group is given a name that defaults to Group1. If the group Group1 already exists, the next default name is Group2, and so on. Rename the group by double-clicking it and entering new text.

    2. You can drop it onto a group that already exists, to group together related properties from the same or different nodes in the message flow. For example, you might want to group all promoted properties that relate to database interactions.
    3. You can drop it onto a property that already exists, to converge related properties from the same or different nodes in the message flow (this is further described in Converging multiple properties) For example, you might want to create a single promoted property that overrides the property on each node that defines a data source.
    You can rename the promoted property (see Renaming a promoted property), but you cannot update its original identification. This ensures that you can always determine the specific node or nodes that are the origin of each promoted property, regardless of the name of the promoted property.
  7. When you have selected the properties that you want to promote to the message flow, click OK Your updates are committed, and the dialog is closed. If you click Apply, this commits the changes but leaves the Property Promotion dialog open.

    When you have promoted a property, you can no longer make any changes to that property through the node properties dialog. You can only update its value at the message flow level.

The message flow node properties are now promoted to the message flow. If you want to confirm this, right-click the message flow in the Navigator view, or right-click the editor view, and select Properties.

The Properties dialog of the message flow is displayed, showing the message flow node properties that you have promoted, organized in the groups that you have created. If you now set a value for one of these properties, that value appears as the default value for the property whenever the message flow is itself included in other message flows.

When you select an embedded message flow within another message flow (a subflow) and view its properties, you see the promoted property values. If you look inside the embedded flow (that is, if you select Open Subflow), you see the original values for the properties. The value of a promoted property does not replace the original property, but it takes precedence when you deploy the message flow.

Promoting mandatory properties

If you promote a property that is mandatory (that is, an asterisk appears beside the name in the properties dialog of the message flow node), the mandatory characteristic of the property is preserved. You must always set a value for every mandatory property at the node level, even if you intend to promote that property to the message flow level and thereby override it.

Promoting properties through a hierarchy of message flows

You can repeat the process of promoting message flow node properties through several levels of message flow. You can promote properties from any level in the hierarchy to the next level above, and so on through the hierarchy to the top level. The value of a property is propagated from the highest point in the hierarchy at which it is set down to the original message flow node when the message flow is deployed to a broker. The value of that property on the original message flow node is overridden.

Related concepts
Promoted properties
Message flow application deployment

Related tasks
Defining promoted properties
Renaming a promoted property
Converging multiple properties
Removing a promoted property
Editing configurable properties

Related reference
Built-in nodes