User-defined properties

A user-defined property (UDP) is a property that is defined when you construct a message flow by using the Message Flow editor. This property can be used by the ESQL or Java™ program inside message flow nodes, such as a Compute node.

The advantage of UDPs is that their values can be changed by operational staff at deployment and run time. You do not need to change your application programs. For example, if you use the UDPs to hold data about your computer center, you can configure a message flow for a particular computer, task, or environment at deployment time, without having to change the code at the message node level.

When you launch the Message Flow editor to either create a message flow or modify an existing message flow, as well as deciding which nodes are required in the message flow, you also have the option (provided by the tab) of defining and giving initial values to some user-defined properties. Use the User Defined Properties tab at the bottom of the edit window. See Message Flow editor for more information.

You can access UDPs in the following ways:
  • From a Mapping node within a Graphical Data Map. Use the iib:getUserDefinedProperty("propertyname") custom XPath function; see Accessing user-defined properties from a Mapping node. You can also access UDPs from custom ESQL that is invoked from a map.
  • From a JavaCompute node, by calling the getUserDefinedAttribute method.
  • From a Compute node, by using a DECLARE statement with the EXTERNAL keyword, which can also provide a default.

See the DECLARE statement for details of the DECLARE statement, and see Accessing message flow user-defined properties from a JavaCompute node for more information about how to use a UDP in a JavaCompute node.

If you use ESQL to access your UDP, the value that you give to a UDP when you define it in a message flow overrides the value of that variable in your ESQL program.

You can also modify the value of a UDP at deployment time by using the Broker Archive editor to edit the BAR file. This value overrides the value that was set when you defined the message flow.

The value of the UDP is set at the message flow level, and is the same for all eligible nodes that are contained in the flow. An eligible node is a node that supports UDPs and is within the scope of the declaration that declares the UDP to your application. For example, if you use the Message Flow editor to change the value of a user property called timezone, which is declared in a schema called mySchema, in a message flow called myFlow, the UDP is available at run time to all the nodes in myFlow that support UDPs and that fall within mySchema.

  • If you use the Message Flow editor to change the value of a user-defined property in a subflow, the newly edited property is available to all the nodes in the subflow that support UDPs, and that are within the scope of the declaration. The property is not available, for example, to nodes in the parent flow.
  • Nodes in the subflow do not see a UDP value that is set on the main flow.
To have a value that is available to both the main and subflow, define UDPs in the subflow and then promote them to the main flow. Set the value in the main flow.

Controlling user-defined properties at run time

User-defined properties can be queried, discovered, and set at run time to dynamically change the behavior of a message flow. You can use the IBM Integration API to manipulate these properties, which can be used by a systems monitoring tool to perform automated actions in response to situations that it detects in the monitored systems.

For example, a message flow contains a Route node, which is used to differentiate between the classes of customer that are defined in the message. The Route node has a user-defined property called ProcessClasses, which is set with an initial value of All. When ProcessClasses is set to All, the node routes messages from all classes of customer to its first terminal for immediate processing.

When certain conditions are detected (for example, the monitoring system detects that the request load is causing the service level agreement to fall below its target), the Route node must be set to pass requests from only "Gold" class customers for immediate processing, while other customer requests are sent to another output terminal, which queues them for later batch processing. Therefore, the monitoring application sets ProcessClasses to Gold, so that the Route node routes the less critical messages to the second terminal.

To make it easier to know what a user-defined property does, and what values it can have, adopt a suitable naming convention. For example, a user-defined property named property01, with an initial value of valueA is not as useful as a property named RouteToAorB with an initial value of RouteA.

For more information, see Setting message flow user-defined properties at run time by using a custom integration application.

Precedence of UDP value overriding

You can define a user-defined property in the following ways:
  • In the ESQL code
  • In the Message Flow editor
  • Through a BAR file override before BAR file deployment
  • By using the IBM Integration API

A BAR file override takes precedence over changes in the Message Flow editor, and changes in the Message Flow editor take precedence over changes in the ESQL code.

The precedence of the values for user-defined properties is shown in the following sequence:
  1. The user-defined property ProcessClasses is set to All in a message flow BAR file. After deployment of the BAR file, the value of ProcessClasses is All.
  2. The same user-defined property (ProcessClasses ) is set to Gold by using the IBM Integration API to issue the call setUserDefinedProperty("ProcessClasses", "Gold"). After successful completion of this method, the value of ProcessClasses is Gold.
  3. The integration node is shut down and restarted. The value of ProcessClasses is still Gold.
  4. The original flow BAR file is redeployed. After deployment, the value of ProcessClasses is All.
You can find more information about defining user-defined properties in the following related topics.