Mediation Flow editor

The Mediation Flow editor is a graphical programming environment that you use to visually create and manipulate mediation flows.

You can visually compose a mediation flow by defining the source and target operations in the Operation connections section, and then visually adding and wiring mediation primitives in the flow section. You then add properties for the primitives in the properties view. Here is an image of a mediation flow that is opened in the Mediation Flow editor, showing the different sections of the editor:

Picture of Mediation Flow editor

These are the sections of the Mediation Flow editor:
These are the editors that are launched from the Properties view of the Mediation Flow editor:

Operation connections

This section is used to identify the operations that will be invoked in the mediation flow by a source operation. Typically , these are connected operations between a source interface and target references; however, a flow can also be defined for a source operation that is not connected to a target. In this case, the message returns to the source after processing is complete. You must define either a source operation, or a connection between source and target operations before you can create a flow. Here is an image showing a source interface's operation connected to the operations of two target references:

Picture of operations connection section

These are the elements in the Operation connections section:
  1. Toolbar
    • The toolbar is the collection of icons at the top. Drag an interface icon Interface icon or a reference icon Reference icon to the canvas to add a source interface or target reference.
  2. Source interface
    • One or more source interfaces that allow service requesters to access the mediation flow. These interfaces must match those of the exports that will be wired to the mediation flow component in the mediation module. Source interfaces are always created on the left side of the editor. A mediation flow must have a source interface.
  3. Target references
    • Zero or more target references that allow a mediation flow component to access a service provider through an import in the mediation module. The reference specifies the interface that is used by the import to invoke the service. Target references are always created on the right side of the editor. Service references of custom mediation primitives are shown as unconnected target references.
  4. Import interfaces
    • The target references contain the interfaces that are used by the imports to invoke the services.
  5. Connections
    • Connections between the operations of a source interface and one or more target interfaces, shown as wires in the editor. The source operation in the connection invokes the target operation and sends the message as a parameter to the target operation. The target operation returns the message as a response to the source operation. The source and target operations define the end points of the mediation flow.

Mediation flow

This section is used to build a flow for the operation definition created in the top section of the editor. Once you define an operation connection, empty request and response flows are generated by the Mediation Flow editor, depending on the way that you defined the operation. A request flow is always generated for a source operation. If the source is expecting a response from a target operation, a response flow is also generated. The generated flows include nodes that are end points in the flow. These nodes are derived from the operation connections. You build your flow by adding mediation primitives between these nodes and wiring them together.

The following image shows a request flow for a source operation that can invoke two target operations. You can switch between the request and response flows by clicking on the tabs below the canvas. If a source operation is not connected to a target, you will only see a request flow.
Request flow

Request flow

The input, callout, input response and input fault nodes of a mediation flow are created by the editor, based on the source and target operations defined in the operations connection section of the editor. The flow is represented from left to right. These are the elements in the request flow section of the editor:
  1. Input node The first element on the left in the request flow view, derived from the source operation. This is the starting point for the request flow, and sends the message into the request flow. A flow can have only one input node.
  2. Callout node An end point in the request flow, derived from the target operations. It sends the processed message to the target operation. There is one callout node for each target operation.
  3. Input response node If a source operation is not wired to a target, the request flow typically ends with this node, which returns the processed message as a response to the source operation.
  4. Input fault node If a source operation has WSDL fault messages, the input fault node appears in the flow. This node is an end point in the request flow. It has an input terminal for each fault message type defined in the source operation. Any message propagated to an input fault node will result in a WSDL fault message being returned from the source operation.
  5. Mediation primitives process the message. They are wired sequentially in the flow between the input and callout nodes
  6. Connections Messages are propagated through connections, which represent the path of the message from the previous node or primitive to the next node or primitive in the flow. Connections are shown as wires in the flow.

The following image shows a response flow for a source operation that can invoke two target operations. You can switch between the request and response flows by clicking on the tabs below the canvas. If a source operation is not connected to a target, you will only see a request flow.


Response flow

Response flow

The callout response, callout fault, input fault, and input response nodes of a mediation flow are created by the editor, based on the source and target operations defined in the operations connection section of the editor. The return flow from target to source is represented from left to right. These are the elements in the response flow section of the editor:
  1. Callout response 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.
  2. Callout fault node A starting point for the response flow. It has an output terminal for each fault message type defined in the target operation. When a WSDL fault occurs, the callout fault node propagates the message to the primitive or node to which it is wired.
  3. Input response node An end point in the response flow. It returns the processed message as a response to the source operation.
  4. Input fault node If a source operation has fault messages, the input fault node appears in the response flow. This node is an end point in the response flow. It has an input terminal for each fault message type defined in the source operation. Any message propagated to an input fault node will result in a WSDL fault of the source operation.
  5. Mediation primitives process the message. They are wired sequentially in the flow between the callout response and input response nodes
  6. Connections Messages are propagated through connections, which represent the path of the message from the previous node or primitive to the next node or primitive in the flow. Connections are shown as wires in the flow.

Palette

You can pick a mediation primitive from the palette and add it to the canvas. The palette is the same for both request and response flows. The following image shows the palette with its mediation primitives:
Picture of the mediation primitives in the palette

For ease of access, primitives in the palette are contained groups. Click on the arrow beside the primitive icon to view and select a primitive from the group, as shown below:
Expanded group in the palette
These are the primitives in the palette:

  • The Event Emitter primitive Event Emitter primitive in the palette emits a common base event at a point significant in the mediation flow.
  • The Message Element Setter primitive sets, copies, or deletes the content of message headers or bodies.Message Element Setter primitive in the palette
  • The Endpoint Lookup mediation primitive queries the WebSphere® Service Registry and Repository and retrieves service endpoints, which it places in the message context. The retrieved endpoints can then be used to dynamically invoke a service. Endpoint Lookup mediation primitive
  • The Message Logger primitive Message Logger primitive in the palette logs messages to a database.
  • The Message Filter primitive Message Filter primitive in the palette conditionally routes messages based on the results of pattern evaluation. A pattern is evaluated against the message, and if the result is true, the message is propagated to a terminal associated with the pattern.
  • The Database Lookup primitive Database Lookup primitive in the palette enriches the message using data retrieved from a database.
  • The Stop mediation primitive Stop primitive in the palette silently stops the execution of the current path in the flow. This is an expected termination , and is not caused by an execution failure in the primitive.
  • The Fail mediation primitive Fail primitive in the palette stops the execution of the flow and throws an exception when there is a known execution failure in the primitive. You can define your own exceptions for the Fail primitive.
  • The Custom Mediation primitive Custom Mediation primitive in the palette allows you to implement your own mediation logic using Java™ code, or to call an import in the same mediation module.
  • The XSL Transformation primitive XSL Transformation primitive in the palette transforms message formats between source and target operations, or changes the content of a message. The primitive uses an XSL style sheet to map between the source and target message types.

Properties view

When working with the Mediation Flow editor, you use the Properties view to modify properties of the selected node or mediation primitive on the canvas.

Note: Detailed context-sensitive help is available for the properties in the Properties view. Use the mouse or Tab key to focus on the field or button and then press the F1 key (for Linux®, press Ctrl+F1) to display the help text.

Properties of nodes and mediation primitives are grouped into description, terminal, details, and promoted properties.

  • Description properties

    Description properties provide information about the name and description of the node or mediation primitive.

  • Terminal properties

    The following image shows the Properties view displaying the terminal properties of a Message Logger primitive:

    Terminal properties in the Mediation Flow editor
    A tree view lists the terminals of primitives and nodes. There are three types of terminals:
    • Input terminal receives the incoming message. Each primitive has one input terminal.
    • Output terminal propagates the outgoing message. Some primitives such as Message Filter allow you to add output terminals.
    • Fail terminal sends the input message and exception information when there is an execution failure in the primitive.

    You can change the terminal type by selecting the terminal and clicking the change button.

  • Details properties

    Mediation primitives have properties that determine how a message will be processed. These properties are set in the details view. Some properties can be set using the XPath Expression Builder, or the XML Mapping Editor. Buttons that launch these editors are available from the details properties view. The following image shows the details properties of a Message Logger primitive. The Custom XPath button launches the XPath Expression Builder, which displays the input message in a tree view and allows you to visually build an XPath 1.0 expression.

    Details properties page

  • Promoted properties

    Mediation primitives have properties that can be promoted, so that their value can be changed from the administrative console at runtime. These properties are listed in the promoted properties page.

    You can view the Promoted properties page from the Operations connection section at the top of the mediation flow editor, or from the editor's canvas as well. You can filter and sort the list to control the list display. The list of properties that you see on this page depends on the context:
    • If you click on the canvas of the Operations connections section, all the promotable properties of all the wired operations in the mediation flow appear in the Promoted properties page.
    • If you click on the canvas of the request flow or response flow, all the promotable properties of all the primitives and nodes in the flow appear in the Promoted properties page.
    • If you make a selection, such as an operation or primitive, the Promoted properties page will display all the promotable properties of that selection.
    Note: A property that is in a table (such as the Filters table in the Message Filter) will appear in this list only if it has a value.

    The following image shows the a partial list of promoted properties viewed from the Operations connections section. By default, all of the promotable properties of the connected operations are listed here. This view includes the column flow:


    Promoted properties view

    The following image shows the list of properties from the canvas of the request flow. The properties have been sorted by primitive.


    Promoted properties of a request flow

    In the Details page, a promoted property is indicated by the marker Promoted property icon.

See "Changing the value of mediation flow properties at runtime" and "Setting properties of mediation flows" in the related links for more information.

XPath Expression Builder

Most mediation primitives have properties that are specified using an XPath 1.0 expression; for example the root property takes an XPath 1.0 expression which specifies the part of the message that is available to the primitive for processing. The XPath Expression Builder provides a tree view of the message, and allows you to visually build an XPath 1.0 expression or to manually specify an XPath 1.0 expression.

The input message is displayed in the XPath Expression Builder's schema viewer, so the primitive's input terminal must be connected in order to launch the Expression Builder. If a primitive's input terminal is not connected, the builder will not launch because it does not know the message type to be displayed.

The XPath Expression Builder is typically launched by clicking the Custom XPath button in the details properties view of a node or mediation primitive. For properties that are set in a table, click on the end of an expression to see the button XPath Expression Builder launch button that launches the XPath Expression Builder.

The following image shows a message displayed in the XPath Expression Builder:


Picture of XPath Expression Builder

Schema viewer

The schema viewer shows a tree view of the message, with the following sections.
  1. context: is the message context where information that is unrelated to the payload is stored. The context has these elements.

    correlation
    makes the property persist throughout the duration of the request and response flows, and is used for passing values from the request flow to the response flow.
    transient
    makes the property available for the duration of the current flow (either the request flow or the response flow), and is used to pass values between mediation primitives in the same flow.
    failInfo
    contains exception information about execution failure in a mediation primitive; it contains the message exception chain, and identifies the primitive where the failure occurred. This information is propagated to the fail terminal.
    primitiveContext
    contains context information for primitives.
    • EndpointLookupContext contains the result of a WebSphere Service Registry and Repository query.
      • endpointReference contains the information needed to access the service endpoint.
      • registryAnnotations contains information for the user-defined properties.

  2. Headers contain header information associated with the message. These are the elements in the headers section:

    SMOHeader
    contains information that defines the message; such as the unique message id, message version and message type. An SMO header is always present in a service message object.
    • Target contains the dynamic endpoint used by the runtime if the Use dynamic endpoint property is set and there is a valid endpoint in the field.
      • address the address of the target.
    JMSHeader
    contains JMS headers, when a JMS import or export binding is used.
    SOAPHeader
    contains SOAP header information when a web services import or export binding is used.
    SOAPFaultInfo
    contains information about SOAP faults; fault code, fault string etc.
    Properties[]
    properties put in the message header by the application
    MQHeader
    contains WebSphere MQ header information, when an MQ binding is used.

  3. Body contains the application data in a business object. Application data is also known as the payload, or operation message type.

XPath location

The location path of the field that you selected in the schema viewer is displayed here.

Condition

Offers a drop down list of available fields, that you can use to filter or select by specifying a value. The XPath location and condition information is combined to create the complete expression.

Full XPath Expression

Displays the completed XPath expression.

Override

Allows you to manually type in your own XPath expression, or to edit the expression created visually.

XML Mapping editor

The XML Mapping editor is launched from the XSL Transformation primitive's properties view. The mapping editor is used to map between the input (source) and output (target) message, and produces an XML map, which is then used to generate an XSL style sheet. The XSL Transformation primitive uses this XSL style sheet to transform the format of the input message to that of the output message as defined in the XSL style sheet.

Here is a view of the XML Mapping editor:
XML Mapping editor

For more information see:
  • "Creating mappings for the XSL Transformation primitive" in topic "Building request and response flows" under related tasks for more information.
  • Rational® Application Developer topic Mapping between XML files
Related concepts
Mediation services overview
Related tasks
Creating a mediation flow
Opening the Mediation Flow editor
Building mediation flows
Emitting common base events
Creating mappings for the XSL Transformation primitive
Selecting endpoints dynamically
Implementing custom mediation logic
Storing and using properties in the message context
Changing the value of mediation flow properties at runtime
Testing and debugging mediation modules
Related reference
Error handling in the mediation flow
Considerations when refactoring mediation flow artifacts

Related information

Tutorial: Create a mediation flow
Samples: Mediation Flow editor
Contributing your own mediation primitive plug-in
Setting properties in mediation flows

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