4.2 Configuration Property Files & Environment Management

4.2 Configuration Property Files & Environment Management

Hardcoding hostnames, port numbers, database credentials, timeouts, and resource paths inside Mule configuration files creates serious security vulnerabilities and prevents applications from seamlessly moving across development, testing, and production environments.

Mule 4 provides a standardized configuration property management framework that decouples environment-specific parameters from integration business logic. Mastering property declaration, syntax resolution, and runtime override precedence is essential for developing enterprise-ready Mule applications.

---

1. YAML vs. Properties File Formats

Mule 4 supports two primary formats for configuration property files stored under src/main/resources:

src/main/resources/
├── config-dev.yaml
├── config-test.yaml
├── config-prod.yaml
└── config-common.yaml

A. YAML Format (.yaml / .yml)

YAML (YAML Ain't Markup Language) uses hierarchical indentation, creating structured, human-readable configuration trees:

# src/main/resources/config-dev.yaml
http:
  port: "8081"
  timeout: "30000"
  
database:
  host: "dev-db.internal.corp"
  port: "5432"
  name: "orders_dev"
  user: "mule_app"

sfdc:
  authUrl: "https://test.salesforce.com/services/Soap/u/55.0"
  username: "developer@company.com.dev"

In Mule XML and DataWeave, nested YAML keys are resolved using dot notation: http.port, database.host, sfdc.username.

B. Properties Format (.properties)

Java properties files use flat, unnested key-value pairs:

# src/main/resources/config-dev.properties
http.port=8081
http.timeout=30000
database.host=dev-db.internal.corp
database.port=5432
database.name=orders_dev
database.user=mule_app
sfdc.authUrl=https://test.salesforce.com/services/Soap/u/55.0
sfdc.username=developer@company.com.dev

Format Comparison Matrix

[!TIP] MuleSoft Best Practice: Use YAML format (.yaml) for all new Mule 4 projects. YAML reduces key repetition and provides clear visual grouping of system configurations.

2. Declaring Configuration Property Files in Mule XML

To make property files accessible to the application, they must be registered using the <configuration-properties> global element, typically placed inside global.xml.

A. Static Declaration

Declares a single, static configuration file:

<configuration-properties file="config.yaml"/>

B. Dynamic Environment-Based Declaration

In enterprise deployments, the application dynamically loads the configuration file matching the target environment (dev, test, uat, prod):

<!-- Dynamically resolves config-dev.yaml, config-prod.yaml, etc. based on ${env} -->
<configuration-properties file="config-${env}.yaml"/>

C. Multi-File Configuration Pattern

A common architectural pattern separates shared properties (common to all environments, such as endpoint paths or business thresholds) from environment-specific properties (hosts, ports, credentials):

<!-- 1. Shared common properties across all environments -->
<configuration-properties file="config-common.yaml"/>

<!-- 2. Environment-specific overrides -->
<configuration-properties file="config-${env}.yaml"/>

+-----------------------------------------------------------------------------+
|                   DYNAMIC PROPERTY FILE RESOLUTION FLOW                     |
|                                                                             |
|   JVM Startup Argument: -Denv=prod                                          |
|         |                                                                   |
|         v                                                                   |
|   <configuration-properties file="config-${env}.yaml"/>                     |
|         |                                                                   |
|         v                                                                   |
|   Mule Runtime Engine resolves path: "src/main/resources/config-prod.yaml"  |
|         |                                                                   |
|         +--> Loads: db.host = "prod-cluster.db.internal"                    |
|         +--> Loads: http.port = "8082"                                      |
+-----------------------------------------------------------------------------+

3. Property Resolution Syntax: XML vs. DataWeave

A central topic on the Developer I exam is knowing when to use ${property.key} versus p('property.key').

+-----------------------------------------------------------------------------+
|                     PROPERTY RESOLUTION SYNTAX MATRIX                       |
|                                                                             |
|   CONTEXT             SYNTAX                      EVALUATION TIMING         |
|   ------------------  --------------------------  ------------------------  |
|   XML Attributes      ${property.key}             Application Initialization|
|   DataWeave 2.0       p('property.key')           Runtime Script Evaluation |
|   DataWeave 2.0 (Alt) Mule::p('property.key')     Runtime Script Evaluation |
+-----------------------------------------------------------------------------+

A. In XML Element Attributes: ${property.key}

Use the ${...} placeholder syntax inside Mule XML attribute definitions. These values are resolved by the configuration parser during application deployment/initialization:

<!-- HTTP Listener Configuration using property placeholders -->
<http:listener-config name="HTTP_Listener_config">
    <http:listener-connection host="0.0.0.0" port="${http.port}"/>
</http:listener-config>

<!-- Database Configuration using property placeholders -->
<db:config name="Database_Config">
    <db:my-sql-connection host="${database.host}" 
                           port="${database.port}" 
                           user="${database.user}" 
                           database="${database.name}"/>
</db:config>

B. In DataWeave 2.0 Expressions: p('property.key')

Inside DataWeave scripts, the ${...} syntax is invalid. Instead, you must use the built-in p('property.key') or Mule::p('property.key') function:

%dw 2.0
output application/json
---
{
    serviceEnvironment: p('env'),
    databaseHost: p('database.host'),
    // Coercing property string to Number for arithmetic/validation
    timeoutMs: p('http.timeout') as Number,
    // Coercing to Boolean
    isFeatureEnabled: p('features.newCheckout') as Boolean
}

<!-- Using p() inside an event processor attribute with inline DataWeave -->
<set-variable variableName="targetUrl" 
              value="#[p('crm.baseUrl') ++ '/v2/customers/' ++ payload.customerId]"/>

[!IMPORTANT] Key Exam Rule:

• XML Attributes: ${property.key}
• DataWeave Scripts / Expressions (#[...]): p('property.key') The p() function always returns a String. If you need an Integer, Float, or Boolean in DataWeave, you must explicitly cast it using as Number or as Boolean.

4. Runtime Environment Parameter Overrides & Deployment

To specify which configuration file to load dynamically (e.g., resolving ${env} in config-${env}.yaml), the property must be supplied to the JVM runtime at startup.

A. In Anypoint Studio (Local Development)

In Studio, open Run Configurations -> Arguments Tab -> VM Arguments and append the system property flag:

-Denv=dev

Multiple properties can be supplied:

-Denv=dev -Dencryption.key=MyStudioSecretKey123

B. On CloudHub 1.0 Deployments

In CloudHub 1.0, properties can be supplied via:

1. Runtime Manager UI: Go to Application -> Settings -> Properties tab and define key-value pairs (e.g., env = prod).
2. Mule Maven Plugin: Configured inside pom.xml under <cloudHubDeployment><properties>.
3. Command-Line Arguments: When deploying via CLI/API, system properties require the -M-D prefix:

-M-Denv=prod

C. On CloudHub 2.0 / Runtime Fabric (RTF) / Standalone On-Premises

• CloudHub 2.0 / RTF: Environment variables and properties are injected via Application Ingress / ConfigMaps through Runtime Manager UI or Anypoint CLI.
• Mule Standalone Runtime: Set in $MULE_HOME/conf/wrapper.conf:

wrapper.java.additional.1=-Denv=prod

---

5. Property Resolution Precedence Hierarchy

When a property key (e.g., database.host) is defined in multiple locations, Mule 4 resolves the value according to a strict order of precedence:

+-----------------------------------------------------------------------------+
|                     PROPERTY RESOLUTION PRECEDENCE                          |
|                                                                             |
|   HIGHEST PRECEDENCE                                                        |
|   [1] JVM System Properties                                                 |
|       Passed via -Dproperty.key=val or -M-Dproperty.key=val                 |
|         |                                                                   |
|         v                                                                   |
|   [2] OS Environment Variables                                              |
|       System-level variables (e.g., export DB_HOST="10.0.0.1")              |
|         |                                                                   |
|         v                                                                   |
|   [3] Application Configuration Properties (<configuration-properties>)      |
|       Loaded from YAML or .properties files (e.g., config-prod.yaml)        |
|         |                                                                   |
|         v                                                                   |
|   [4] Connector / Component Default Values                                  |
|       Fallback values defined in XML schemas (e.g., port="8081")            |
|   LOWEST PRECEDENCE                                                         |
+-----------------------------------------------------------------------------+

Multiple <configuration-properties> Precedence Rule

If multiple <configuration-properties> elements are defined in an application (such as config-common.yaml and config-dev.yaml) and both files contain the identical key (e.g., timeout: "5000" vs timeout: "10000"), the first loaded file takes precedence.

<!-- config-common.yaml is evaluated FIRST. Any key present here will NOT be overwritten by config-dev.yaml -->
<configuration-properties file="config-common.yaml"/>
<configuration-properties file="config-dev.yaml"/>

[!WARNING] To ensure environment-specific overrides take effect over default common properties, declare the environment-specific file first:

<configuration-properties file="config-${env}.yaml"/>
<configuration-properties file="config-common.yaml"/>