Setting properties in mediation flows

Mediation primitives accept and process messages to let you change their format, content or the target service provider. Mediation primitives have properties that determine how a message will be processed. When you wire a flow in the Mediation Flow editor, you can modify the properties of nodes and mediation primitives.

Tip: Wire the input and output terminals of a mediation primitive before you set its properties. This will make your input and output message types known to the editor, and will save you time when setting the properties.

This topic describes the properties of mediation primitives and nodes. This topic does not discuss marking properties for promotion. For information on promoted properties, see Changing the value of mediation flow properties at runtime.

Input node

The Input node propagates the message to the primitive or node to which it is wired. The properties to be stored in the message context are specified in the details page of the input node's properties view. These properties can be accessed by mediation primitives later in the flow.


Input node

Here is an image of the input node's details page properties:


Input details

  • Correlation context specifies the business object that is persisted through the duration of the request and response flows. The correlation context is specified in the input node in the request flow and is used for passing values from the request flow to the response flow. Click Browse to select a business object, or Reset to clear the field.
  • Transient context specifies the business object that is available for the duration of the current flow (either the request flow or the response flow). The transient context is specified in the input node in the request flow, and is used to pass values between mediation primitives in the same flow. Click Browse to select a business object, or Reset to clear the field.
For more information, see Storing and using properties in the message context

Callout node

The callout node receives the message and invokes the requested service and operation. There is a callout node for each connected target operation in the mediation flow.


Callout node

Here is an image of the callout node's details page properties:


Callout details

Dynamic routing is enabled by default. This means that the callout will invoke the endpoint that is set in the target element of the SMOHeader in the message. If no endpoint exists in this location, the callout will invoke the endpoint defined in the import's binding. For more information, see Selecting endpoints dynamically

Callout response node

The callout response node is a starting point for the response flow. It forwards the message received from the target operation into the response flow. There is one callout response node for each target operation. Errors that are not defined as WSDL fault messages are propagated to the fail terminal of the callout response node.


Callout node

Here is an image of the callout response node's details page properties:


Callout response details

Select the check box to include the original request message if you want to propagate the complete message to the fail terminal in the event of a failure. If you don't select the check box, the message information that is propagated includes the failure information (in the failinfo element) and some context information.

Event Emitter

The Event Emitter primitive emits custom base events at a significant point in the message flow.


XSL Transformation node

Here is an image of the Event Emitter primitive's details page properties.


Event emitter details

  • Label specifies a unique identifier for the event. This maps to the extension name of the common business event, and is the name given to an event definition generated from WebSphere® Integration Developer. Use a meaningful name in this field that is specific to the business event that will be emitted. The default value is MediationModule_MediaitonFlow_Req.
  • Root specifies the part of the message to be included in the common base event.
    • / includes the complete message.
    • /body includes the body section of the message.
    • /headers includes the message headers.
    • /context includes the message context.
    • Custom XPath launches theXPath Expression Builder , where you can specify your own XPath expression.
  • Transaction mode specifies the transaction within which the event is sent to the CEI server. This property overrides the transaction mode that is configured on the CEI emitter.
    • Default uses the default setting in the CEI emitter.
    • Existing the event is sent to the CEI server within the current transaction
    • New the event is sent to the CEI server outside the transaction. If the mediation flow component is configured to run inside a global transaction, the transaction mode on the event emitter primitive must be New.
For more information, see Emitting common base events and Event Emitter primitive reference

Message Element Setter

The Message Element setter primitive sets, copies or deletes the value of message elements as the message passes through a mediation flow.

Message Element Setter

Here is an image of the Message Element Setter's detail page properties.


Message Element Setter Properties

Message Elements Each row in the table represents an update operation.
  • Target describes the location of the element to update.
  • Type the type of the element value. If you are setting a constant value in the target element, type must be a simple Java™ type or String. Use the type copy if you are copying the value from another element in the message. Use the type delete if you are deleting the value of an element.
  • Value A String value to be placed in the target element, or an XPath 1.0 expression that identifies the location of the element whose value is to be copied to the target element.

Select the Validate input check box to enable input message validation to ensure it matches its type definition at runtime. Deselect this check box to disable validation if performance is a concern.

Tip: Promote this property so that you can enable validation at runtime to help you debug a problem.

For more information, see Message Element Setter primitive reference.

Endpoint Lookup

The Endpoint Lookup mediation primitive queries the WebSphere Service Registry Repository and retrieves service endpoints. The endpoints retrieved are based on the search criteria defined in the Details page, and the retrieved endpoints are placed in the primitiveContext element in the message context. The retrieved endpoints can then be used to dynamically invoke a service, depending on the match policy specified.

Here is an image of the Endpoint Lookup primitive's details page properties, where you specify the properties to include in your query of the registry.


Endpoint Lookup details page

Port Type (Interface) is the WSDL port type which is an interface in WebSphere Integration Developer. You can specify these properties for the port type:
  • Name is the port type or interface name. Click Browse to select an existing interface and its namespace.
  • Namespace is the namespace of the port type or interface. You can specify any valid namespace such as URI or URN.
  • Version is the version of the port type in the registry.
  • Registry name is the registry that you wish to search. Leave this field blank to use the runtime default registry.
  • Match Policy specifies the result if more than one matching endpoints are found.

Here is an image of the advanced details page of the Endpoint Lookup primitive


Endpoint lookup advanced details

  • Classifications objects that match a particular classification. The WSRR classifies objects using the ontology classification system (OWL), in which each classifier is a class and has a URI. Enter an OWL URI for this property, for example, enter http://www.ibm.com/xmlns/prod/serviceregistry/6/0/governance/DefaultLifecycle#Approve to specify an object that is classified as DefaultLifecycle#Approve.
  • User Properties properties that are defined on the services in the registry. The type can be either String or XPath.
For more information, see Selecting endpoints dynamically and Endpoint Lookup primitive reference.

XSL Transformation

The XSL Transformation primitive transforms messages, or changes message content according to an XSL style sheet that maps between the source and target message types.


XSL Transformation node

Here is an image of the XSL Transformation primitive's details page properties.

XSL Transformation details

In the Mapping file field:

Select the Validate input check box to enable input message validation to ensure it matches its type definition at runtime. Deselect this check box to disable validation if performance is a concern.

Tip: Promote this property so that you can enable validation at runtime to help you debug a problem.

The Regenerate XSL button only appears on those XSL Transformation primitives that were created in a previous version of WebSphere Integration Developer. Click Regenerate XSL to synchronize the XSL style sheet with the XML map, and to optionally enable the capability to automatically generate the associated XSL style sheet. Once you enable this capability, the XSL and XMX files will automatically stay synchronized.

For more information, see Creating mappings for the XSL Transformation primitive and XSL Transformation primitive reference.

Message Logger

The Message Logger primitive logs a copy of the message to a database for future retrieval or audit.


Message Logger node

Here is an image of the Message Logger primitive's details page properties


Message Logger details
  • Data source name the JNDI name of the data source that defines where the data will be logged. The default data source is jdbc/mediation/messageLog.
  • Root specifies the part of the message to be logged. The message to be logged is converted to XML from the point specified in the root field. Select one of the following options:
    • / logs the complete message.
    • /body logs the body section of the message.
    • /headers logs the message headers.
    • /context logs the message context.
    • Custom XPath launches theXPath Expression Builder. , where you can specify your own XPath expression.
  • Transaction mode defines the transaction within which the changes to the database will be committed. This property only takes effect within a global transaction. By default, transactions of mediation flow components are not global. To set the transaction of the mediation flow component to global, set the qualifier property in the component's Implementation page in the assembly editor. Select one of the following options:

    • Same logs the message within the transaction of this flow instance. If a failure occurs later on in the flow, the logs will not be committed to the database. Request and response flows each have their own transaction.
    • New logs the message within a new transaction. The flow's transaction is suspended and a new transaction is created to store the message. The new transaction is then committed and the flow's transaction resumed. If a failure occurs later on in the flow, the message logging is not rolled back.

For more information, see Message Logger primitive reference

Message Filter

The Message Filter primitive compares the content of the message to XPath 1.0 expressions that you configure, and routes the message to the next mediation primitive based on the result. You can add output terminals and associate them with the XPath expression that you configured.


Message Filter node

Terminals

You can add an output terminal to Message Filter in one of the following ways
  • Select the primitive in the Mediation Flow editor's canvas, right-click, and select Add Output Terminal, as shown below:
    Message Filter: Add Output Terminal from primitive's context menu
  • Switch to the Terminals page of the properties view. Select Output terminal from the list of terminals, right-click and select Add Output Terminal, as shown below:
    Message Filter: Add Output terminal from properties view
:

Details

We will use an example to illustrate the use of the properties in the details page of the properties view for the Message Filter primitive. In the example, if the value of the subscriptionLevel field in the message body is premium, the input message will be propagated to the terminal named realtime. The following image shows the properties that are set for the example:


Message Filter details

In the Filters table, define the filtering performed by the mediation primitive. Each row in the table represents a filter object that associates a pattern with a terminal name.

Note: The order of the filters can be changed using the up and down buttons. You can control the pattern matching behavior by using the distribution mode property.

In the Distribution mode field, specify the desired behavior when more than one pattern evaluates to true.

If no terminal matches the message, it is propagated to the default terminal.

For more information, see Message Filter primitive reference

Database Lookup

The Database Lookup primitive searches values from a database and stores them in the message.


Database Lookup node
We will use an example to illustrate the use of the properties in the details page of the properties view for the Database Lookup primitive. In the example, assume the following:
  • The value of an employee's serialNumber, 049728, is passed into message body from the client application.
  • There is an employee record in the EmployeeDatabase with serialNumber = '049728' and salary = '$50,000'.
  • We want to retrieve the employee's salary from the database, using the serialNumber field of the message to locate the record in the database.
  • We then want to retrieve the value of the salary from the database and put it in the message body.
This is the corresponding SQL statement:

select SALARY from EMPLOYEE_TABLE where SERIAL_NUMBER = '049728'

The result, '50000' of type long will be stored in the salary field in the message body.


Database Lookup details

Specify these properties for the primitive in the Details page of the Properties view.

In the Data source name field, enter the JNDI name of the data source. In the example, jdbc/sample/EmployeeDatabase

In the Table name field, enter the name of the database table, including the schema name. In the example, myschema.EMPLOYEE_TABLE

In the Key column name field, enter the name of the database column to be used for the look up. In the example, this is SERIAL_NUMBER

In the Key path field, click Custom XPath to launch the XPath Expression Builder to build an XPath expression. The value returned from the XPath expression is used as the key into the database. In this case that is the value of the serialNumber (049728) from the message body.

Select the Validate input check box to enable input message validation to ensure it matches its type definition at runtime. Deselect this check box to disable validation if performance is a concern.

Tip: Promote this property so that you can enable validation at runtime to help you debug a problem.

In the Data elements table, define the database column from which the value will be retrieved, the type of information it is, and the place in the message where the retrieved value is to be stored. Each data element has three properties:
  • Value column name specifies the name of the database column from which to obtain the element value. In the example, this is SALARY.
  • Message value type specifies the type of the element value. In the example, the type is long.
  • Message element specifies an XPath 1.0 expression describing the path location of the message element where the database value is stored. The XPath expression must evaluate to a single element in the message. In the example, the salary value retrieved will be stored in the message body, in the salary field.

For more information, see Database Lookup primitive reference.

Custom Mediation

The Custom Mediation primitive allows you to implement your own mediation logic using Java code, or to call an import in the same mediation module.


Custom Mediation node

Starting with WebSphere Integration Developer 6.0.2, there has been a change in implementation of the custom mediation primitive. The custom code is now embedded in the primitive. Custom mediations created in previous versions will still run without any changes required, however you have the option to convert them to the new implementation. For more information on this change, see the topics in "Implementing custom mediation logic" in the related tasks at the bottom of thi

Here is an image of a Custom Mediation primitive's details page properties.


Custom Mediation details
  • The Root property specifies the parts of the message that are available to the custom mediation:
    • / specifies the entire message.
    • /body specifies the body section of the message, which contains only the application data or payload of the message.
  • Visual creates your custom code as a Visual snippet
  • Java to creates your custom code as a Java snippet.
  • Invoke invokes a service external to the mediation flow. This option leads to an interface where you specify a reference to the component that the primitive is calling, and the operation that will be invoked.

For custom mediation primitives created in a version prior to WebSphere Integration Developer 6.0.2, the details view will appear as shown below:

  • Convert to Embedded Snippet converts your custom code to embedded snippet code. You will need to manually delete the service reference in the operations connections section of the mediation flow editor, and delete the reference and Java component in the assembly editor. For more information on this, see "Migrating a custom mediation primitive" in the list of related task topics at the end of this topic.
  • Open Java Editor launches the Java editor. Note that selecting this option may impact the future use of the Java Snippet editor for this custom mediation.

For more information, see Implementing custom mediation logic and Custom mediation primitive reference

Stop

Use the Stop primitive to silently stop execution of the flow. This is an expected termination and is not caused by an exception.


Stop node

There are no properties to specify for this primitive. For more information, see Error handling in the mediation flow and Stop primitive reference.

Fail

The Fail primitive throws an exception and stops the execution of the flow when there is an execution failure in a mediation primitive.


Fail node

Specify the properties of the primitive in the details page of the properties view.

In the Error message field, enter the error message that is added to the exception.


Fail details

For more information, see Error handling in the mediation flow and Fail mediation primitive reference.

Related tasks
Defining source and target operations
Adding mediation primitives to the flow
Wiring a mediation flow
Building XPath expressions

Feedback
(C) Copyright IBM Corporation 2005, 2006. All Rights Reserved.