External Functions Available to DataWeave

In addition to the built-in DataWeave functions, Mule Runtime and some modules, connectors, and Core components provide functions that you can use in DataWeave scripts. The functions are specific to the modules, connectors, and components that provide them. Before you begin, note that 2.x versions of DataWeave are used by Mule 4 apps. For DataWeave in Mule 3 apps, refer to the DataWeave version 1.2 documentation. For other Mule versions, you can use the version selector in the DataWeave table of contents.

Mule Runtime Functions

These functions are injected by the Mule Runtime:

p
lookup
causedBy

Starting in Mule 4.1.4, DataWeave incorporated the Mule Runtime functions into its Mule function module.

MuleSoft recommends that you start using the Mule namespace when using these functions in Mule apps that are running on Mule Runtime 4.1.4 or later. To use them, you simply prepend the namespace to the function name, for example, Mule::p('http:port'), instead of p('http:port').

In addition to its continued support for the use of Mule Runtime functions in your DataWeave scripts and mappings, the Mule module also enables you to use Mule Runtime functions in your custom DataWeave modules.

Mule apps running on Mule Runtime versions prior to version 4.1.4 cannot use the Mule namespace or use Mule Runtime functions in custom modules, only in DataWeave scripts and mappings.

For DataWeave runtime properties, see the DataWeave functions props and prop.

Accessing Properties (p Function)

The p function provides access to properties, whether these are:

Mule property placeholders
System properties
Environment properties

For more on configuring properties and how they are handled, see Configure Properties.

The following example logs the value of the property http.port.

Example: Property Function Usage for Mule 4.1.4 and Later

<flow name="simple">
  <logger level="INFO" doc:name="Logger"
    message="#[Mule::p('http.port')]"/>
</flow>

Note that you can also use the function when defining a DataWeave variable or function. This example uses the p function in the myVar definition. You can do the same thing with pre-4.1.4 runtimes simply by omitting the Mule:: namespace.

<flow name="simple">
  <logger level="INFO" doc:name="Logger"
    message="#[var myVar = Mule::p('http.port') --- myVar]"/>
</flow>

Example: Property Function Usage for Mule 4.1.3 and Earlier

<flow name="simple">
  <logger message="#[p('http.port')]"/>
</flow>

See also, the p function introduced in the Mule function module in Mule 4.2.

Execute a Flow (lookup Function)

Similar to the Flow Reference component, the lookup function enables you to execute another flow within your app and to retrieve the resulting payload. It takes the flow’s name and an input payload as parameters. For example, lookup("anotherFlow", payload) executes a flow named anotherFlow.

The function executes the specified flow using the current attributes, variables, and any error, but it only passes in the payload without any attributes or variables. Similarly, the called flow will only return its payload.

Note that lookup function does not support calling subflows.

Parameters

Name Description

Name	Description
`flowName`	A string that identifies the target flow.
`payload`	The payload to send to the target flow, which can be any (`Any`) type.
`timeoutMillis`	Optional. Timeout (in milliseconds) for the execution of the target flow. Defaults to `2000` milliseconds (2 seconds) if the thread that is executing is CPU_LIGHT or CPU_INTENSIVE, or 1 minute when executing from other threads. If the lookup takes more time than the specified `timeoutMillis` value, an error is raised.

flowName

A string that identifies the target flow.

payload

The payload to send to the target flow, which can be any (Any) type.

timeoutMillis

Optional. Timeout (in milliseconds) for the execution of the target flow. Defaults to 2000 milliseconds (2 seconds) if the thread that is executing is CPU_LIGHT or CPU_INTENSIVE, or 1 minute when executing from other threads. If the lookup takes more time than the specified timeoutMillis value, an error is raised.

This example shows XML for two flows. The lookup function in flow1 executes flow2 and passes the object {test:'hello '} as its payload to flow2. The Set Payload component (<set-payload/>) in flow2 then concatenates the value of {test:'hello '} with the string world to output and log hello world.

Example: Using the lookup Function in Mule 4.1.4 or Later

<flow name="flow1">
  <http:listener doc:name="Listener" config-ref="HTTP_Listener_config"
    path="/source"/>
  <ee:transform doc:name="Transform Message" >
    <ee:message >
      <ee:set-payload ><![CDATA[%dw 2.0
output application/json
---
Mule::lookup('flow2', {test:'hello '})]]></ee:set-payload>
    </ee:message>
  </ee:transform>
</flow>
<flow name="flow2" >
  <set-payload value='#[payload.test ++ "world"]' doc:name="Set Payload" />
  <logger level="INFO" doc:name="Logger" message='#[payload]'/>
</flow>

Example: Using the lookup Function in Mule 4.1.3 and Earlier

<flow name="flow1">
  <http:listener doc:name="Listener" config-ref="HTTP_Listener_config"
    path="/source"/>
  <ee:transform doc:name="Transform Message" >
    <ee:message >
      <ee:set-payload ><![CDATA[%dw 2.0
output application/json
---
lookup('flow2', {test:'hello '})]]></ee:set-payload>
    </ee:message>
  </ee:transform>
</flow>
<flow name="flow2" >
  <set-payload value='#[payload.test ++ "world"]' doc:name="Set Payload" />
  <logger level="INFO" doc:name="Logger" message='#[payload]'/>
</flow>

Output

hello world

Always keep in mind that a functional language like DataWeave expects the invocation of the lookup function to not have side effects. As such, the internal workings of the DataWeave engine might cause a lookup function to be invoked in parallel with other `lookup`s, or not invoked it at all.

MuleSoft recommends that you invoke flows with the Flow Ref (flow-ref) component, using the target attribute to put the result of the flow in a var and then referencing that var from within the DataWeave script.

Matching Errors by Types (causedBy Function)

The causedBy function matches an error by its type, like an error handler does. This is useful when matching by a super type is required but specific sub-type logic is also needed or when handling a COMPOSITE_ROUTING error that contains child errors of different types.

The error to match against can be implicit, but the type is always a required parameter.

In the following example, a global error handler is set up to handle SECURITY errors in a general way, while specific actions are set up for HTTP:UNAUTHORIZED and HTTP:FORBIDDEN errors.

Example: Error Matcher Function Usage in Mule Runtime Version 4.1.4 and Later

<error-handler name="securityHandler">
  <on-error-continue type="SECURITY">
    <!-- general error handling for all SECURITY errors -->
    <choice>
      <when expression="#[error Mule::causedBy 'HTTP:UNAUTHORIZED']">
        <!-- specific error handling only for HTTP:UNAUTHORIZED errors -->
      </when>
      <when expression="#[Mule::causedBy('HTTP:FORBIDDEN')]">
        <!-- specific error handling only for HTTP:FORBIDDEN errors -->
      </when>
    </choice>
  </on-error-continue>
</error-handler>

Example: Error Matcher Function Usage in Mule Runtime Version 4.1.3 and Earlier

<error-handler name="securityHandler">
  <on-error-continue type="SECURITY">
    <!-- general error handling for all SECURITY errors -->
    <choice>
      <when expression="#[error causedBy 'HTTP:UNAUTHORIZED']">
        <!-- specific error handling only for HTTP:UNAUTHORIZED errors -->
      </when>
      <when expression="#[causedBy('HTTP:FORBIDDEN')]">
        <!-- specific error handling only for HTTP:FORBIDDEN errors -->
      </when>
    </choice>
  </on-error-continue>
</error-handler>

Notice that the error parameter is used both explicitly and implicitly.

Connector and Component Functions

When using connectors and components in a Mule app, you can inject functions. Unlike the Runtime functions, these functions require a namespace, which usually matches the component name.

For example, in an app using Batch you can use the following expression: #[Batch::isSuccessfulRecord()].