This documentation is for WSO2 ESB version 4.5.0. View documentation for the latest release.

Script Mediator

Synapse supports Mediators implemented in a variety of scripting languages such as JavaScript, Python or Ruby. There are two ways of defining the Script Mediators:

WSO2 ESB uses Rhino engine to execute JavaScripts. Rhino engine converts the script to a method inside a Java class. Therefore, when processing large JSON data volumes, the code length must be less than 65536 characters, since the Script mediator converts the payload into a Java object. However, you can use the following alternative options to process large JSON data volumes.

  • Achieve the same functionality via a Class mediator.
  • If the original message consists of repetitive sections, you can use the Iterate mediator to generate a relatively small payload using those repetitive sections. This will then allow you to use the Script mediator.

1. With the script program statements stored in a separate file, referenced via the Local or Remote Registry entry.

 2. With the script program statements embedded inline within the Synapse configuration.

Synapse uses the Apache Bean Scripting Framework for scripting language support. Any script language supported by BSF may be used to implement the Synapse Mediator. With the Script Mediator, you can invoke a function in the corresponding script. With these functions, it is possible to access the Synapse predefined in a script variable named "mc." The "mc" represents an implementation of the MessageContext, named ScriptMessageContext.java,}}which contains the following methods that can be accessed within the script as "{{mc.methodName".

  • public Object getPayloadXML() - Gets the XML representation of SOAP Body payload.
  • public void setPayloadXML(Object payload) - Sets the SOAP body payload from XML.
  • public void addHeader(boolean mustUnderstand, Object content) - Adds a new SOAP header to the message.
  • public Object getEnvelopeXML() - Gets the XML representation of the complete SOAP envelope
  • public void setTo(String reference)
  • public void setFaultTo(String reference)
  • public void setFrom(String reference)
  • public void setReplyTo(String reference)

Implementing a Mediator with a script language has advantages over using the built-in Synapse Mediator types or implementing a custom Java class Mediator. The Script Mediators have the flexibility of a class Mediator with access to the Synapse MessageContext and SynapseEnvironment APIs. Also, the ease-of-use and dynamic nature of scripting languages allow rapid development and prototyping of custom mediators. An additional benefit of some scripting languages is that they have very simple and elegant XML manipulation capabilities, which make them very usable in the Synapse mediation environment. For example, JavaScript E4X or Ruby REXML.

For both types of script mediator definitions, the MessageContext passed into the script has additional methods over the standard Synapse MessageContext to enable working with XML natural to the scripting language. Example are when using JavaScript getPayloadXML and setPayloadXML, E4X XML objects and when using Ruby, REXML documents.



Syntax

Script Mediator Using a Script of the Registry
<script key="string" language="js" [function="script-function-name"]/>

The attributes of of the <script>:

  • "key" - The registry key to load the script.
  • "language" - Specifies the scripting language of the script code (e.g. "js" for Javascript, "rb" for ruby, "groovy" for Groovy, "py" for Python).
  • "function"  - Optional attribute defining the name of the script function to invoke. If not specified, it defaults to a function named "mediate." The function is passed a single parameter, which is the Synapse MessageContext. The function may return a boolean. If it does not, then the value "true" is assumed and the script mediator returns this value.
Script mediator using a In-lined script
<script language="js"><![CDATA[...script source code...]]><script/>

UI Configuration

Script Type

  • #Inline - Specifies the script inline.
  • #Registry - Stores the script in registry and refers it using the key.

If Inline Selected

The following options are available:

  • Language - Chooses from a variety of scripting languages supported:
    • JavaScript
    • Groovy
    • Rooby
  • Source - If inline is selected as the Script type, specify the source.

If Registry is Selected

Following options are available:

  • Function - Function of the script language to execute.
  • Key Type - Specifies whether to use Static or Dynamic Keys.
  • Key - Registry location of the source. You can click on the "Configuration Registry" or "Governance Registry" links to choose the source from the "Registry Tree". Refer to more information in Namespace.
  • Include Keys - Script sources to be included.

Note

You can configure the Mediator using XML. Click on "switch to source view" in the "Mediator" window.


Example

1.

<script language="js"><![CDATA[mc.getPayloadXML()..symbol != "IBM";]]><script/>

The above configuration is an example of an inline mediator using JavaScript/E4X which returns false if the SOAP message body contains an element named symbol, which has a value of IBM.

2.

<script language="js"
    key="repository/conf/sample/resources/script/test.js"
    function="testFunction"/>

In the above example, script is loaded from the registry by using the key repository/conf/sample/resources/script/test.js. The script is written in Java script. The function to be invoked is testFunction. An example of test.js is shown bellow:

3.

function testFunction(mc) {
     var symbol = mc.getPayloadXML()..*::Code.toString();
     mc.setPayloadXML(
        <m:getQuote xmlns:m="http://services.samples/xsd">
           <m:request>
              <m:symbol>{symbol}</m:symbol>
           </m:request>
        </m:getQuote>);
}