As a developer you are familiar with the use of variables. You use them to store temporary information, count a number of occurrences and so on. Within the WSO2 Micro Integrator (and of course Enterprise Integrator) you can also use properties. Not only for the purposes mentioned before but also to make changes to the message context, e.g., switch from XML to JSON and vice versa. This is done using the property mediator which doesn’t directly change the message context but allows you to change certain properties related to it.

There are quite a few different properties available that you can use and set. Some examples:

• Generic Properties like OUT_ONLY (no response is expected)
• HTTP Transport Properties like FORCE_SC_ACCEPTED (a 202-status code is generated)
• SOAP Headers like To and From
• Axis2 Properties like the CacheLevel for JMS objectsSynapse Message Context Properties like SYSTEM_DATE or MESSAGE_FORMAT

You can use these properties for instance in the MAIN sequence to log in a user-friendly way when a non-existing proxy was called (the main sequence will gather all calls to the Micro Integrator where there is no proxy defined, e.g., wrong service name).  For a complete list of properties see the WSO2 documentation.

Client Case WSO2

An Insurance Company Chooses WSO2 to displace MuleSoft

Download now

Property Mediator

The property mediator is used to set or remove properties. Below you will find the syntax of this mediator. The type is not limited to string, but also integer, Boolean and so on. More information can be found online. Keep in mind what scope you need to use. Some properties are defined on the axis2 scope, meaning that you define them for instance on an inSequence like a messageType

The general syntax is as follows:

<property name="string" [action=set|remove] [type="string"] (value="literal" | expression="xpath") [scope=default|transport|axis2|axis2-client] [pattern="regex" [group="integer"]]>
    <xml-element/>?
</property>

However the what we see from the documentation is that the list of scopes is bigger than described in the syntax.

Integration Studio also does not allow all these scopes to be selected in the properties view. We have submitted an issue in the github repository.

We will not describe all the possible use cases but focus on the setting and reading of properties in the registry and on the message flow (default / synapse scope and axis2 scope).

In the example below the value of the TestValue Axis2 is retrieved and logged to the console.

<log level="custom"> 

<property expression="get-property('axis2','TestValue Axis2')" name="SETProperty Axis2"/>

</log>

From the perspective of the Properties of the Property Mediator the Testvalue Axis2 looks like this

There is even the possibility to set and retrieve values stored in the conf and governance registries which, in case of the Micro Integrator, are file based registries and therefor easier to access. For completeness, the Enterprise Integrator has a database in which registry data is stored in a number of tables. However, from the perspective of development and deployment, there is little difference. Just the way the data is stored and configuration is governed is different.

Here is the design view of the Test proxy. When you switch to source you see this code stores a value in the governance registry and puts the value on the console.

<?xml version="1.0" encoding="UTF-8"?>
<proxy name="Test" startOnLoad="true" transports="http https" xmlns="http://ws.apache.org/ns/synapse">
    <target>
        <inSequence>
            <property name="gov:myvalues/value.txt" scope="registry" type="STRING" value="Testing"/>
            <log level="custom">
                <property expression="get-property('registry','gov:myvalues/value.txt')" name="Value"/>
            </log>

            <respond/>
        </inSequence>
        <outSequence/>
        <faultSequence/>
    </target>
</proxy>

The Log mediator displays the value on the console.

But we have even more possibilities. This code also create a registry resource but the value after the @ is consider the key of a key-value pair.

<?xml version="1.0" encoding="UTF-8"?>
<proxy name="Test" startOnLoad="true" transports="http https" xmlns="http://ws.apache.org/ns/synapse">
    <target>
        <inSequence>
            <property name="gov:myvalues/value.txt@key" scope="registry" type="STRING" value="Testing"/>
			<log level="custom">
                <property expression="get-property('registry','gov:myvalues/value.txt@key')" name="Value"/>
            </log>
            <respond/>
        </inSequence>
        <outSequence/>
        <faultSequence/>
    </target>
</proxy>

As you can see below, the value.txt is now a properties file and the @key created a key value pair. The Log mediator displays the value on the console.

Scopes

The way to get the value of a property is with the get-property command. It takes two commands, the scope, and the property name. If the scope is omitted, the default scope (Synapse) is presumed.

Because you define a property with a scope. The default scope is Synapse, that allows the value to be persisted as long as message handling is running within the particular message context. Such kind of properties are only visible to the current message context and do not affect other messages. A variable defined on the axis2 scope will only persist in the In, Out or Fault sequence depending on where it has been defined.

If a scope is used where there is no property defined with that name, a null value is returned. Defining a property on the wrong scope does not work, for instance setting a header on anything other than the transport scope will not deliver the required result.

This is the source code of the above code that was written for Enterprise Integrator (it uses a standard Echo service):

<?xml version="1.0" encoding="UTF-8"?>
<proxy name="TestProxy" startOnLoad="true" transports="http https" xmlns="http://ws.apache.org/ns/synapse">
    <target>
        <inSequence>
            <property name="TestValue Axis2" scope="axis2" type="STRING" value="GOING IN"/>
            <property name="TestValue Synapse" scope="default" type="STRING" value="GOING IN"/>
            <log level="custom">
                <property name="Value IN" value="Static value"/>
                <property expression="get-property('axis2','TestValue Axis2')" name="SETProperty Axis2"/>
                <property expression="get-property('TestValue Synapse')" name="SETProperty Synapse"/>
            </log>
            <send>
                <endpoint>
                    <address uri="http://localhost:8280/services/echo">
                        <suspendOnFailure>
                            <initialDuration>-1</initialDuration>
                            <progressionFactor>1</progressionFactor>
                        </suspendOnFailure>
                        <markForSuspension>
                            <retriesBeforeSuspension>0</retriesBeforeSuspension>
                        </markForSuspension>
                    </address>
                </endpoint>
            </send>
        </inSequence>
        <outSequence>
            <log level="custom">
                <property name="Value OUT" value="Static value"/>
                <property expression="get-property('axis2','TestValue Axis2')" name="SETProperty Axis2"/>
                <property expression="get-property('TestValue Synapse')" name="SETProperty Synapse"/>
            </log>
            <send/>
        </outSequence>
        <faultSequence/>
    </target>
</proxy>

If you want to try it out on the Micro Integrator, you need to either change the endpoint to a service that gives a response or create the simplest proxy of all: only a respond mediator.

<?xml <?xml version="1.0" encoding="UTF-8"?>
<proxy name="EchoProxy" startOnLoad="true" transports="http https" xmlns="http://ws.apache.org/ns/synapse">
    <target>
        <inSequence>
            <respond/>
        </inSequence>
        <outSequence/>
        <faultSequence/>
    </target>
</proxy>
version="1.0" encoding="UTF-8"?>

This of course because Micro Integrator does not have the Echo service on board.

Brochure Integration solutions with WSO2

A vendor summary

Download now

An example

To make this clear we created a simple proxy that calls the Echo axis2 service of the EI. We set two variables in this proxy, TestValue Axis2 and TestValue Synapse, each on the scope that is indicated by the name. We deploy this proxy to the Enterprise Integrator as a CAR file. Using SoapUI we call the deployed TestProxy. The response is a simple echo of the message that we send to the proxy, but the interesting things are actually happening on the console.

The two log statements will put the actual value of the variable to the console.

As you can see, the value defined at the Synapse level is available in both the In- and Outsequence. The Axis2 defined variable is null in the Outsequence.

When you use a call mediator in the In Sequence, the axis2 value is also cleared, even though you are still in the inSequence.

Properties are handy to store variables as well as change the context of the message. If you want to change the content of a message, look at our blog about the PayloadFactory mediator.

If you are interested in learning how to develop and deploy proxies like this, take a look at our training pages.