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 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.
  4. Select Promote Property.

    The Promote Property dialog is displayed.

    The Promote Property dialog

    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 the properties for all the nodes in the open message flow 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 of the dialog lists the name of the open message flow and 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. In the image shown the message flow contains no promoted properties so only the name of the message flow is displayed.

    The majority of message flow node properties are available for promotion, but you cannot promote the following properties:
    • The properties that name Mapping modules.
    • 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).
  5. Select the property that you want to promote to the message flow. 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 other nodes in the open 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.

    You can select multiple properties to promote by selecting a property, holding down Ctrl, and selecting one or more other properties.

    If you have you selected multiple properties to promote, all the properties you have selected must be available for promotion. If one or more of the selected properties is not available for promotion, the entire selection becomes unavailable for promotion, and the Promote button in the right-hand pane is grayed out.

  6. Click the Promote button to promote the property or properties

    Clicking the Promote button invokes the Target Selection dialog:

    The Target Selection dialog

    The Target Selection dialog displays only the valid targets for the promotion of the previously selected property or properties and allows you to create a new target for the promotion, such as to a new group or to a new property.

  7. In the Target Selection dialog, select the destination group or property for the property or properties you want to promote. You can group together related properties from the same or different nodes in the message flow by dropping the selected property or properties onto a group or property that already exists. Alternatively, you can click New Group or New Property to create a new target for the promotion. You can rename groups and properties by selecting them and clicking Rename, or by double-clicking on the group or property.
  8. Click OK to confirm your selections.
    Note: If you create a new group or property using the Target Selection dialog, the changes persist even if you select Cancel in the dialog. When the dialog closes, groups or properties that you have created using the Target Selection dialog will appear in the Promote properties dialog.
  9. When you have selected the properties that you want to promote to the message flow, click OK Your updates are committed, and the Promoted Property dialog is closed. If you click Apply, this commits the changes but leaves the 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.

Note: You can also promote properties from the Promote property dialog by dragging the selected property or properties from the left-hand pane of the Promote Property dialog to the right-hand pane:
  1. Select the property you want to promote. You can select multiple properties to promote by selecting a property, holding down Ctrl, and selecting one or more other properties.
  2. You can drop the selected property or properties into the right-hand pane using the following methods:
    1. Drop the selected property or properties 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 name of the first group created defaults to Group1. If a group called Group1 already exists, the group is given the name Group2, and so on. You can rename the group by double-clicking it and entering new text or by selecting the group in the Promoted properties pane and clicking Rename.
      Note:

      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.

      If you are developing a message flow within a user-defined project that will be delivered as an Eclipse plug-in, you can add translation for the promoted properties that you have added. Translated names can contain characters, such as space, that are restricted for system names. The option to provide translated strings for promoted properties is not available if you are working with a message flow within a message flow project.

    2. Drop the selected property or properties 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. You can change the groups that promoted properties belong to at any time, by selecting a property in the Promoted properties pane and dragging it onto a different group.

    3. Drop the selected property or properties onto a property that already exists, to converge related properties from the same or different nodes in the message flow.

      For example, you might want to create a single promoted property that overrides the property on each node that defines a data source.

      For more information on converging properties, see Converging multiple properties.

The message flow node properties are now promoted to the message flow. 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 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.

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. When a mandatory property is promoted, its value does not need to be set at the node-level. If the flow containing the mandatory promoted property is included as a subflow within another flow, then the property has to be filled in for the subflow node.

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 reference
Built-in nodes