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 Compute, JavaCompute, .NETCompute, and Mapping nodes.

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 also define a UDP at the level of the integration server, by updating the server.conf.yaml configuration file.

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.
  • From a .NETCompute node, by calling the GetUserDefinedProperty method.

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.

You can also change the behavior of a message flow at run time by using the administrative REST API to modify the values of user-defined properties on the message flow. For more information, see Setting message flow user-defined properties at run time by using the administration REST API.

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.
  • If a node within a subflow accesses a UDP and if the subflow does not define the UDP, the parent flow is searched for a definition of the UDP at run time. If the parent flow does not define the UDP and it is also a subflow, the parent of this subflow is searched for a definition of the UDP. The search process continues in this recursive manner upwards through the chain of subflows and parent flows until the UDP definition is found, or until the top-level flow is reached.
To have a value that is available to both the main and subflow, define UDPs in one of the following ways:
  • Define UDPs in the subflow and then promote them to the main flow. Set the value in the main flow.
  • Define UDPs in the main flow only and allow the subflow to locate the UDP value in the main flow at run time.

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 administration REST 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.

If User-defined properties that are defined in subflows are renamed during promotion, and you want to override them at runtime by using the IBM App Connect Enterprise web user interface, you might need to do so for the different names.

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 information about how to use the REST API to control user-defined properties at run time, see Setting message flow user-defined properties at run time by using the administration REST API. For more information about the administration REST API, see Managing resources by using the administration REST API.

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 administration REST 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. A user-defined property override is set to Gold by using the administration REST API. After successful completion of this method, the value of ProcessClasses is Gold.
  3. The integration node or server is shut down and restarted. The value of ProcessClasses reverts to All because the REST API update is not persistent.
  4. A user-defined property override is set to Gold by using the administration REST API. After successful completion of this method, the value of ProcessClasses is Gold.
  5. The original flow BAR file is redeployed. After deployment, the value of ProcessClasses is All.