Scripting Module Reference

Mule Runtime Engine versions 3.5, 3.6, and 3.7 reached End of Life on or before January 25, 2020. For more information, contact your Customer Success Manager to determine how you can migrate to the latest Mule version.

The scripting module provides facilities for using scripting languages in Mule. Any scripting languages that support JSR-223 can be used inside Mule. Scripts can be used as implementations of components or transformers. Also, scripts can be used for expression evaluations, meaning message routing can be controlled using script evaluations on the current message. You can even configure Mule instances from scripts.

Component

Defines a script component backed by a JSR-223 compliant script engine such as Groovy, JavaScript, or Ruby. Scripting allows you to either directly embed your script inside the XML config or reference a script using Spring’s dynamic language support: http://static.springframework.org/spring/docs/2.5.x/reference/dynamic-language.html.

Table 1. Attributes of <component…>
Name	Type	Required	Default	Description
script-ref	string	no		A reference to a script object bean, that is, a `<script:script …>` definition.

Table 2. Child Elements of <component…>
Name	Cardinality	Description
script	0..1	A script to be executed by a JSR-223 compliant script engine such as Groovy, JavaScript(Rhino), Python, Ruby, or Beanshell.
java-interface-binding	0..*	A binding associates a Mule endpoint with an injected Java interface (this is like using Spring to inject a bean, but instead of calling a method on the bean a message is sent to an endpoint). Script bindings will only work with Java-based scripting languages. Right now there is no validation on when languages support Java bindinngs because there are so many scripting languages.

Configuring an In-line Script

The following example demonstrates how to configure a Groovy script component with an in-line script:

<mule xmlns="http://www.mulesoft.org/schema/mule/core"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:script="http://www.mulesoft.org/schema/mule/scripting"
      xmlns:vm="http://www.mulesoft.org/schema/mule/vm"
      xsi:schemaLocation="
       http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
       http://www.mulesoft.org/schema/mule/scripting
       http://www.mulesoft.org/schema/mule/scripting/current/mule-scripting.xsd
       http://www.mulesoft.org/schema/mule/vm http://www.mulesoft.org/schema/mule/vm/current/mule-vm.xsd">

    <vm:connector name="vmConnector"/>

    <script:script name="myScript" engine="groovy">
        return "$payload Received"
    </script:script>

        <flow name="inlineScript">
            <vm:inbound-endpoint path="vm:in1"/>
            <script:component>
                <script:script engine="groovy">
                    return "$payload Received"
                </script:script>
            </script:component>
            <vm:outbound-endpoint path="out1"/>
        </flow>
...

Message Flows Using Bindings

The following example demonstrates how to orchestrate message flows using bindings. The example calls out to two different flows and passes the results on to the outbound router:

<flow name="scriptWithBindings">
            <inbound>
                <inbound-endpoint ref="client_request"/>
            </inbound>
            <script:component>
                <script:script engine="groovy">
                    msg = CalloutService.doSomething(payload)
                    return CalloutService.doSomethingElse(msg)
                </script:script>
                <script:java-interface-binding interface="org.mule.components.script.CalloutService" method="doSomething">
                    <outbound-endpoint ref="callout_1" synchronous="true"/>
                </script:java-interface-binding>
                <script:java-interface-binding interface="org.mule.components.script.CalloutService" method="doSomethingElse">
                    <outbound-endpoint ref="callout_2" synchronous="true"/>
                </script:java-interface-binding>
            </script:component>
            <outbound>
                <pass-through-router>
                    <outbound-endpoint ref="client_response"/>
                </pass-through-router>
            </outbound>
        </flow>

        <flow name="Callout1">
            <inbound>
                <inbound-endpoint ref="callout_1"/>
            </inbound>
            <test:component appendString=" Received by #[mule:context.serviceName]"/>
        </flow>

        <flow name="Callout2">
            <inbound>
                <inbound-endpoint ref="callout_2"/>
            </inbound>
            <test:component appendString=" Received by #[mule:context.serviceName]"/>
        </flow>

Scripting Module

The scripting module provides facilities for using scripting languages in Mule. Any scripting languages that supports JSR-223 can be used inside Mule. Scripts can be used as implementations of service components or transformers. Also, scripts can be used for expression evaluations, meaning message routing can be controlled using script evaluations on the current message. You can even configure Mule instances from scripts.

Component

Table 3. Attributes of <component…>
Name	Type	Required	Default	Description
script-ref	string	no		A reference to a script object bean, that is, a `<script:script …>` definition.

Table 4. Child Elements of <component…>
Name	Cardinality	Description
script	0..1	A script to be executed by a JSR-223 compliant script engine such as Groovy, JavaScript(Rhino), Python, Ruby, or Beanshell.
java-interface-binding	0..*	A binding associates a Mule endpoint with an injected Java interface (this is like using Spring to inject a bean, but instead of calling a method on the bean a message is sent to an endpoint). Script bindings will only work with Java-based scripting languages. Right now there is no validation on when languages support Java bindinngs because there are so many scripting languages.

Script Context Bindings

When run inside Mule, scripts have a number of objects available to them in the script context. These are:

Name	Description
log	a logger that can be used to write to Mule’s log file.
muleContext	a reference to the MuleContext object.
eventContext	A reference to the eventcontext. This allows you to dispatch events progammatically from your script
message	the current message.
originalPayload	the payload of the current message before any transforms.
payload	the transformed payload of the current message if a transformer is configured on the service. Otherwise this is the same value as originalPayload.
src	same as payload, kept for backward compatibility.
service	a reference to the current service object.
id	the current event id.
result	a placeholder object where the result of the script can be written to. Usually it’s better to just return a value from the script unless the script method doesn’t have a return value.

Name

Description

log

a logger that can be used to write to Mule’s log file.

muleContext

a reference to the MuleContext object.

eventContext

A reference to the eventcontext. This allows you to dispatch events progammatically from your script

message

the current message.

originalPayload

the payload of the current message before any transforms.

payload

the transformed payload of the current message if a transformer is configured on the service. Otherwise this is the same value as originalPayload.

src

same as payload, kept for backward compatibility.

service

a reference to the current service object.

the current event id.

result

a placeholder object where the result of the script can be written to. Usually it’s better to just return a value from the script unless the script method doesn’t have a return value.

Transformer

Runs a script to perform transformation on the current message.

Table 5. Attributes of <transformer…>
Name	Type	Required	Default	Description

Table 6. Child Elements of <transformer…>
Name	Cardinality	Description
script	0..1	A script to be executed by a JSR-223 compliant script engine such as Groovy, JavaScript(Rhino), Python, Ruby, or Beanshell.

Filter

Runs a script to perform filter on the current message.

Table 7. Attributes of <filter…>
Name	Type	Required	Default	Description

Table 8. Child Elements of <filter…>
Name	Cardinality	Description
script	0..1	A script to be executed by a JSR-223 compliant script engine such as Groovy, JavaScript(Rhino), Python, Ruby, or Beanshell.

Script

Represents a script that can be used as a component for a service or a transformer. The script text can be pulled in from a script file or can be embedded inside this element. A script can be executed by any JSR-223 compliant script engine such as Groovy, JavaScript(Rhino), Python, Ruby, or Beanshell.

Table 9. Attributes of <script…>
Name	Type	Required	Description
name	string	no	The name used to identify this script object. This is used when you want to reference this script object from a component or transformer.
engine	string	no	The name of the script engine being used. All scripting languages that support JSR-223 have a script engine name such as groovy, ruby, python, etc. If this value is not set, but a script file is configured, Mule will attempt to load the correct script engine according to the script file’s extension.
file	string	no	The script file to load for this object. The file can be on the classpath or local file system.

Table 10. Child Elements of <script…>
Name	Cardinality	Description
text	0..1	Used for embedding script code inside the XML. This is useful for simple scripts where you are just mocking up a quick application.

Groovy refreshable

A wrapper for a component object that allows the underlying object to be reloaded at runtime. This makes it possible to hot-deploy new component logic without restarting.

Table 11. Attributes of <groovy-refreshable…>
Name	Type	Required	Description
name	string	yes	The name for this refreshable groovy bean wrapper.
refreshableBean-ref	string	no	The reference to a `groovy.lang.Groovy` object to use for this component.
methodName	string	no	The entrypoint method to invoke when a message is received for the object.

Table 12. Child Elements of <groovy-refreshable…>
Name	Cardinality	Description

Lang

This element allows the http://www.springframework.org/schema/lang namespace to be embedded. Within this element developers can include the Spring lang namespace.

Table 13. Attributes of <lang…>
Name	Type	Required	Default	Description

Table 14. Child Elements of <lang…>
Name	Cardinality	Description

Script Configuration Builder (Deprecated, will be removed as of Mule 4.0)

The ScriptConfigurationBuilder allows developers to create a Mule instance from a JSR-223 compliant script. To load the manager from Groovy:

ConfigurationBuilder builder = new ScriptConfigurationBuilder("groovy", "../conf/mule-config.groovy");
                MuleContext muleContext = new DefaultMuleContextFactory().createMuleContext(builder);

Or to start the server from the command line:

mule -M-Dorg.mule.script.engine=groovy
-builder org.mule.module.scripting.builders.ScriptConfigurationBuilder
-config ../conf/mule-config.groovy

For more information about configuring a Mule instance from code or script see [Configuration Overview].

Script Context Bindings

When run inside Mule, scripts have a number of objects available to them in the script context:

Name Description

id

The current message ID.

log

A logger that can be used to write to Mule’s log file.

message

The current message.

muleContext

A reference to the MuleContext object.

originalPayload

The payload of the current message before any transforms.

payload

The transformed payload of the current message if a transformer is configured on the flow. Otherwise this is the same value as originalPayload.

result

A placeholder object where the result of the script can be written. Usually it’s better to just return a value from the script unless the script method doesn’t have a return value.

If your script needs to return null, you must set result=null instead of simply returning null.

service

A reference to the current service.

message properties

Any message properties can be used as variables for the script.

Script Configuration Builder

*Note*: Deprecated and will be removed in Mule 4.0.

The ScriptConfigurationBuilder lets you create a Mule instance from a JSR-223 compliant script.

To load the manager from Groovy:

ConfigurationBuilder builder = new ScriptConfigurationBuilder("groovy", "../conf/mule-config.groovy");
MuleContext muleContext = new DefaultMuleContextFactory().createMuleContext(builder);

Or to start the server from the command line:

mule -M-Dorg.mule.script.engine=groovy -builder org.mule.module.scripting.builders.ScriptConfigurationBuilder -config ../conf/mule-config.groovy

Transformer

Runs a script to perform transformation on the current message.

Table 15. Attributes of <transformer…>
Name	Type	Required	Default	Description

Table 16. Child Elements of <transformer…>
Name	Cardinality	Description
script	0..1	A script to be executed by a JSR-223 compliant script engine such as Groovy, JavaScript(Rhino), Python, Ruby, or Beanshell.

To use Groovy as an example, the following transformer configuration converts a comma-separated string of values to a java.util.List.

<script:transformer name="stringReplaceWithParams">
        <script:script engine="groovy">
            <property key="oldStr" value="l"/>
            <property key="newStr" value="x"/>
            <script:text>
                return payload.toString().replaceAll("$oldStr", "$newStr")
            </script:text>
        </script:script>
    </script:transformer>

Groovy refreshable

A wrapper for a component object that allows the underlying object to be reloaded at runtime. This makes it possible to hot-deploy new component logic without restarting.

Table 17. Attributes of <groovy-refreshable…>
Name	Type	Required	Description
name	string	yes	The name for this refreshable groovy bean wrapper.
refreshableBean-ref	string	no	The reference to a `groovy.lang.Groovy` object to use for this component.
methodName	string	no	The entrypoint method to invoke when a message is received for the object.

Table 18. Child Elements of <groovy-refreshable…>
Name	Cardinality	Description

Lang

This element allows the http://www.springframework.org/schema/lang namespace to be embedded. Within this element developers can include the Spring lang namespace.

Table 19. Attributes of <lang…>
Name	Type	Required	Default	Description

Table 20. Child Elements of <lang…>
Name	Cardinality	Description

Gartner names MuleSoft a Leader

Create connected experiences with AI

Future of connected AI agents

The world of AI is a world of APIs

Gartner names MuleSoft a Leader

Create connected experiences with AI

Future of connected AI agents

The world of AI is a world of APIs

Scripting Module Reference

Component

Configuring an In-line Script

Message Flows Using Bindings

Scripting Module

Component

Script Context Bindings

Transformer

Filter

Script

Groovy refreshable

Lang

Script Configuration Builder (Deprecated, will be removed as of Mule 4.0)

Script Context Bindings

Script Configuration Builder

Transformer

Groovy refreshable

Lang