WSO2 ESB - Property Mediator

Property Mediator

Properties are name value pairs. Properties are a way to convey information across different processing units. For example user may need to set a transport property from the message mediation. Or user may need to remove a property which is set by the transport. This mediator sets or removes properties for a particular message.

Property mediator has no direct impact on the message but rather on the message context flowing through Synapse. The properties set on a message can be later retrieved through the synapse:get-property(prop-name) XPath extension function. If a scope is specified for a property, the property could be set as a transport header property or an (underlying) Axis2 message context property, or as a Axis2 client option. If a scope is not specified, it will default to the Synapse message context scope. Using the property element with action specified as "remove" you can remove any existing message context properties.

There are some well-defined properties that you can get/set on the Synapse message context scope:

Name Values Meaning
RESPONSE true 'true' means the message is to be marked as a response message
OUT_ONLY true 'true' means the message is to be marked as an out-only message that does not expect a response
ERROR_CODE String this is set to any error message code encountered during a fault
ERROR_MESSAGE String this is set to any error message text encountered during a fault
ERROR_DETAIL String this is set to any error message detail text encountered during a fault
ERROR_EXCEPTION String this is set to any Java Exception encountered during a fault

There are some Axis2 and module properties that are useful which are set at scope="axis2"

Name Values Meaning
MercurySequenceKey integer can be an identifier specifying an Mercury internal sequence key, and
MercuryLastMessage true 'true' will make this the last message and terminate the sequence

There are some Axis2 client side properties/options that are useful which are set at scope="axis2-client"

Name Values Meaning
FORCE_HTTP_1.0 true forces outgoing http/s messages to use HTTP 1.0 (instead of the default 1.1)

The synapse:get-property() XPath extension function

The get-property() function allows any XPath expression used in a configuration to look-up information from the current message context. It is possible to retrieve properties previously set with the property mediator, and/or information from the Synapse or Axis2 message contexts or transport header. The function accepts the scope as an optional parameter as shown below:

synapse:get-property( [(axis2 | axis2-client | transport),] <property_name> [,<dateformat>] )

Some useful properties from the Synapse message context follows:

Name Meaning
SYSTEM_DATE Returns the current date as a String. Optionally a date format as per standard date format may be supplied. e.g. synapse:get-property("SYSTEM_DATE", "yyyy.MM.dd G 'at' HH:mm:ss z") or get-property('SYSTEM_DATE')
SYSTEM_TIME Returns the current time in milliseconds. (i.e. the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC)
To, From, Action, FaultTo, ReplyTo, MessageID the message To and Action and WS-Addressing propertie
MESSAGE_FORMAT returns the message format - i.e. returns pox, get, soap11 or soap12
OperationName returns the operation name for the message

In addition to the above, one may use the get-property() function to retrieve Axis2 message context properties or transport headers. e.g. synapse:get-property('transport', 'USER_AGENT')

SynapseXpath variables

There are a set of predefined XPath variables when writing XPaths in the Synapse Configuration. Those are as follows;

Name Meaning
body The SOAP 1.1 or 1.2 body element For example; expression="$body/getQuote" refers to the first getQuote element in the SOAP body regardless of whether the message is SOAP-11 or SOAP-12
header The SOAP 1.1 or 1.2 header element For example; expression="$header/wsa:To" refers to the addressing To header regardless of whether this message is SOAP-11 or SOAP-12Further there are some variable prefixes defined in Synapse XPaths which can be usefull in writing the configurations;
ctx Prefix for Synapse MessageContext properties For example; expression="$ctx:RESPONSE" gives the value of the Synapse message context property with name 'RESPONSE'
axis2 Prefix for Axis2 MessageContext properties For example; expression="$axis2:messageType" gives the value of the axis2 message context property with name 'messageType'
trp Prefix for the transport headers For example; expression="$trp:Content-Type" gives the value of the 'Content-Type' transport header, which is going to be the Content-Type of the current message

Syntax

 <property name="string" [action=set|remove] (value="literal" | expression="xpath") [scope=transport|axis2|axis2-client]/>

UI Configuration

Property Mediator Screenshot

You have the following configuration under the property mediator.

Example

  <property name="symbol"
                    expression="fn:concat('Normal Stock - ', //m0:getQuote/m0:request/m0:symbol)"
                    xmlns:m0="http://services.samples/xsd"/>

  <log level="custom">
      <property name="symbol" expression="get-property('symbol')"/>        
  </log>    

In this example we are setting the property symbol and later we are logging it using the log mediator.