Mule Configuration File

All Mule applications, domains, and policies are configured through an XML domain-specific language (DSL). This XML file specifies the resources that compose the artifact, including dependencies needed to run the Mule application.

Although you can write the XML file manually, it is more common to use the graphical user interfaces in Anypoint Design Center or Anypoint Studio to structure and define the behavior of your Mule app. While you use either of these GUIs, the underlying XML is provided for you. In Studio, the XML is also available for viewing and editing.

Overview

A Mule configuration file is a tree.
Each of the elements sets up a configuration object within Mule, for example:

Mule Global Configuration
Global settings, such as the default transaction time-out, that apply to the entire Mule configuration.
Properties
Configuration Properties, message properties, and system properties.
Flows
Combine components to define a message flow.
Sources (Endpoints)
Trigger a flow. Sources are sometimes called Endpoints in Studio.
Connectors and Modules Configurations
Declare configurations for any connectors and modules components used.
Routers
Control the flow execution.
Operations
Apply specific actions within a flow.

XML Schema

Schemas define the configurable attributes of these resources that are referenced in the XML Configuration file. This is how a Mule artifact both validate and define its functional components and their configuration.

XML schemas are used to validate functional components in a Mule artifact. They are specified in the header.

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
      xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
        xmlns:jms="http://www.mulesoft.org/schema/mule/jms"
        xmlns:file="http://www.mulesoft.org/schema/mule/file"
        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/jms http://www.mulesoft.org/schema/mule/jms/current/mule-jms.xsd
        http://www.mulesoft.org/schema/mule/file http://www.mulesoft.org/schema/mule/file/current/mule-file.xsd">

Mule domains feature the mule-domain tag instead of mule.

Be sure to specify all the necessary schema files. This can be time-consuming when setting up the configuration file by hand, but importing schema files provides the following time-saving benefits:

Auto-completion and context-specific help in Anypoint Studio
Design-time configuration validation
Typed properties

Schemas in Mule 4 are autogenerated dynamically according to the artifact dependencies. The HTTP schema, for example, will only be available if the HTTP connector is part of the artifacts dependencies. Therefore, to specify the schemas you will also need to have the correct dependencies declared. In the example above which requires the JMS and File schemas you would need the following dependencies in the artifact’s pom.xml file, for example:

<dependencies>
  ...
  <dependency>
      <groupId>org.mule.connectors</groupId>
      <artifactId>mule-jms-connector</artifactId>
      <version>1.3.2</version>
      <classifier>mule-plugin</classifier>
  </dependency>
  <dependency>
      <groupId>org.mule.connectors</groupId>
      <artifactId>mule-file-connector</artifactId>
      <version>1.2.1</version>
      <classifier>mule-plugin</classifier>
  </dependency>
  ...
</dependencies>

Anypoint Studio will add the required schemas and dependencies as components are introduced.

Namespaces

Each Mule module or connector has its XML schema, including Mule core for its community and enterprise versions. When you import a schema, it has its namespace.

To use the standard Mule elements, import the Mule Kernel (CE) and Mule runtime engine (EE) namespaces:

http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/ee/core http://www.mulesoft.org/schema/mule/ee/core/current/mule-ee.xsd

Default Namespace

Typically, you set the Mule core schema as the default namespace for your configuration file. This means that any XML element without a prefix will come from the Mule core schema. To set the default namespace schema, specify xmlns immediately followed by the URL of the Mule schema, without the colon or namespace prefix you set in the previous example (e.g., xmlns instead of xmlns:jms):

<mule xmlns="http://www.mulesoft.org/schema/mule/core"
    xsi:schemaLocation="http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd">
   ...config...
</mule>

Merging Configuration Files

If you have multiple configuration files, you can import them into one configuration file so that you only have to specify one configuration. This is useful to extract connector configurations or other global elements. For example:

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns=http://www.mulesoft.org/schema/mule/core ....>

    <import file="global-prod-configurations.xml" />
    <import file="global-error-handler.xml" />
...

These imports can also be dynamic when combined with properties:

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns=http://www.mulesoft.org/schema/mule/core ....>

    <import file="global-${env}-configurations.xml" /> (1)
...

1	The `env` property in the example cannot be set by a global property. To define the `env` value, you can configure either a system property or an environment property.

Because of the hierarchy in which Mule runtime engine loads the properties, you cannot make imports depend on an application or a global configuration property. See the properties hierarchy page for more information.

Declaring Multiple Configurations

You can also keep your files separate as long as you declare them as part of your application configurations. This is useful when each configuration file is relatively unrelated to the others. Configurations are declared on the application descriptor file, mule-artifact.json, within the configs section. For example, four configuration files are declared here:

{
  "configs": [
    "http-api.xml", "jms-messaging-api.xml", "monitoring-tools.xml", "core-functionality.xml"
  ],
  "redeploymentEnabled": true,
  "name": "retail-api",
  "minMuleVersion": "4.1.1",
  "requiredProduct": "MULE_EE",
  "classLoaderModelLoaderDescriptor": {
    "id": "mule",
    "attributes": {
      "exportedResources": []
    }
  },
  "bundleDescriptorLoader": {
    "id": "mule",
    "attributes": {}
  }
}

Anypoint Studio will handle the application descriptor automatically.

Full Application Example

Following is an example of a simple Mule configuration file for an application:

<mule xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:db="http://www.mulesoft.org/schema/mule/db"
      xmlns:email="http://www.mulesoft.org/schema/mule/email"
      xmlns:http="http://www.mulesoft.org/schema/mule/http"
      xmlns:tls="http://www.mulesoft.org/schema/mule/tls"
      xmlns="http://www.mulesoft.org/schema/mule/core"
      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/db http://www.mulesoft.org/schema/mule/db/current/mule-db.xsd
        http://www.mulesoft.org/schema/mule/email http://www.mulesoft.org/schema/mule/email/current/mule-email.xsd
        http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
        http://www.mulesoft.org/schema/mule/tls http://www.mulesoft.org/schema/mule/tls/current/mule-tls.xsd">

    <http:listener-config name="http.listener.config" basePath="mule">
        <http:listener-connection host="0.0.0.0" port="${http.port}" protocol="HTTP"/>
    </http:listener-config>

    <http:request-config name="http.request.config" basePath="mule">
        <http:request-connection host="127.0.0.1" port="${http.port}"/>
    </http:request-config>

    <email:smtp-config name="email.config">
        <email:smtp-connection host="${email.host}" port="${email.smtp.port}"/>
    </email:smtp-config>

    <flow name="integration-routing-contentFlow">
        <http:listener config-ref="https.listener.config" path="routing/main"/>
        <logger level="INFO" message="#[attributes.headers]"/>

        <choice>
            <when expression="#[attributes.headers.'content-type' contains 'application/json']">
                <http:request config-ref="http.request.config" path="routing/http" method="POST"/>
            </when>
            <otherwise>
                <set-payload value="Error: Unexpected unmapped choice element when trying to route the request."/>
                <email:send config-ref="email.config" subject="Email routing">
                    <email:to-addresses>
                        <email:to-address value="routing@mulesoft.com"/>
                    </email:to-addresses>
                    <email:body contentType="text/plain">
                        <email:content>#[payload]</email:content>
                    </email:body>
                </email:send>
            </otherwise>
        </choice>
    </flow>

</mule>

Full Policy Example

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns:http="http://www.mulesoft.org/schema/mule/http"
     xmlns:http-policy="http://www.mulesoft.org/schema/mule/http-policy"
     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/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
              http://www.mulesoft.org/schema/mule/http-policy http://www.mulesoft.org/schema/mule/http-policy/current/mule-http-policy.xsd">

   <http-policy:proxy name="policy-example">
       <http-policy:source>
           <http-policy:execute-next/>
           <logger level="INFO" message="#[payload]"/>
       </http-policy:source>
   </http-policy:proxy>
</mule>

Full Domain Example

<?xml version="1.0" encoding="UTF-8"?>
<domain:mule-domain
        xmlns:http="http://www.mulesoft.org/schema/mule/http"
        xmlns="http://www.mulesoft.org/schema/mule/core"
        xmlns:domain="http://www.mulesoft.org/schema/mule/ee/domain"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:doc="http://www.mulesoft.org/schema/mule/documentation" 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/ee/domain http://www.mulesoft.org/schema/mule/ee/domain/current/mule-domain-ee.xsd
http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd">

    <!-- configure here resource to be shared within the domain -->

    <http:listener-config name="HTTP_Listener_config" doc:name="HTTP Listener config" doc:id="e252ad6a-220d-4c1f-865b-d7aec30bfc30" basePath="/api" >
          <http:listener-connection host="0.0.0.0" port="8081" />
      </http:listener-config>

</domain:mule-domain>