Configuration Access Guide

Access environment variables and application properties using env

When to Use Configuration Access

Use the env variable to:

Read environment variables for API keys and secrets
Access application configuration properties
Support different configurations per environment (dev/staging/prod)
Enable feature flags and conditional behavior
Configure plugin behavior without code changes

The env variable provides read-only access to Spring’s Environment, including system properties, environment variables, and application configuration files.

Quick Start


// MVEL - Get configuration with defaults
apiUrl = env.getProperty("plugin.api.url", "http://localhost:8080");
apiKey = env.getProperty("API_KEY"); // Environment variable
timeout = env.getProperty("plugin.timeout", Integer.class, 30);
 
if (env.containsProperty("plugin.feature.enabled")) {
    featureEnabled = env.getProperty("plugin.feature.enabled", Boolean.class);
}


// Java - Get configuration with defaults (environment() from the PluginContext)
var env = context().environment();
String apiUrl = env.getProperty("plugin.api.url", "http://localhost:8080");
String apiKey = env.getProperty("API_KEY"); // Environment variable
Integer timeout = env.getProperty("plugin.timeout", Integer.class, 30);
 
if (env.containsProperty("plugin.feature.enabled")) {
    Boolean featureEnabled = env.getProperty("plugin.feature.enabled", Boolean.class);
}

Core Concepts

Configuration Sources

The env variable can access configuration from multiple sources (in priority order):

System Properties - JVM system properties (-Dproperty=value)
Environment Variables - OS environment variables (export API_KEY=secret)
Application Properties - application.properties or application.yml
Profile-specific Properties - application-{profile}.properties
Config Files - Additional configuration files in the config directory

Property Naming Conventions

Source	Example	Access Method
Environment Variable	`API_KEY`	`env.getProperty("API_KEY")`
System Property	`-Dapi.key=secret`	`env.getProperty("api.key")`
Application Property	`plugin.webhook.url`	`env.getProperty("plugin.webhook.url")`
Spring Convention	`PLUGIN_WEBHOOK_URL`	`env.getProperty("plugin.webhook.url")`

Spring automatically maps environment variables: PLUGIN_WEBHOOK_URL → plugin.webhook.url

API Reference

Core Methods

MVEL


// Get property as string
value = env.getProperty("property.name");
 
// Get with default value
value = env.getProperty("property.name", "default");
 
// Get as specific type
port = env.getProperty("server.port", Integer.class);
enabled = env.getProperty("feature.enabled", Boolean.class, false);
 
// Check if property exists
if (env.containsProperty("api.key")) {
    // Property is defined
}
 
// Get required property (throws if missing)
requiredKey = env.getRequiredProperty("api.key");
 
// Get active profiles
profiles = env.getActiveProfiles();

JavaScript


// Get property as string
const value = env.getProperty("property.name");
 
// Get with default value
const value = env.getProperty("property.name", "default");
 
// Get as specific type
const port = env.getProperty("server.port", java.lang.Integer.class);
const enabled = env.getProperty("feature.enabled", java.lang.Boolean.class, false);
 
// Check if property exists
if (env.containsProperty("api.key")) {
    // Property is defined
}
 
// Get required property (throws if missing)
const requiredKey = env.getRequiredProperty("api.key");
 
// Get active profiles
const profiles = env.getActiveProfiles();

Python


# Get property as string
value = env.getProperty("property.name")
 
# Get with default value
value = env.getProperty("property.name", "default")
 
# Get as specific type
port = env.getProperty("server.port", java.lang.Integer)
enabled = env.getProperty("feature.enabled", java.lang.Boolean, False)
 
# Check if property exists
if env.containsProperty("api.key"):
    # Property is defined
    pass
 
# Get required property (throws if missing)
required_key = env.getRequiredProperty("api.key")
 
# Get active profiles
profiles = env.getActiveProfiles()

Java


var env = context().environment();
 
// Get property as string
String value = env.getProperty("property.name");
 
// Get with default value
String defaultValue = env.getProperty("property.name", "default");
 
// Get as specific type
Integer port = env.getProperty("server.port", Integer.class);
Boolean enabled = env.getProperty("feature.enabled", Boolean.class, false);
 
// Check if property exists
if (env.containsProperty("api.key")) {
    // Property is defined
}
 
// Get required property (throws if missing)
String requiredKey = env.getRequiredProperty("api.key");
 
// Get active profiles
String[] profiles = env.getActiveProfiles();

Type Conversion

The env variable automatically converts property values to the requested type:


// MVEL - Type conversion examples
stringVal = env.getProperty("name");                          // String (default)
intVal = env.getProperty("port", Integer.class);              // Integer
longVal = env.getProperty("timeout", Long.class);             // Long
boolVal = env.getProperty("enabled", Boolean.class);          // Boolean
doubleVal = env.getProperty("rate", Double.class);            // Double
 
// With defaults
port = env.getProperty("server.port", Integer.class, 8080);
timeout = env.getProperty("timeout.ms", Long.class, 30000L);


// Java - Type conversion examples
var env = context().environment();
String stringVal = env.getProperty("name");                          // String (default)
Integer intVal = env.getProperty("port", Integer.class);              // Integer
Long longVal = env.getProperty("timeout", Long.class);               // Long
Boolean boolVal = env.getProperty("enabled", Boolean.class);          // Boolean
Double doubleVal = env.getProperty("rate", Double.class);            // Double
 
// With defaults
Integer port = env.getProperty("server.port", Integer.class, 8080);
Long timeout = env.getProperty("timeout.ms", Long.class, 30000L);

Common Patterns

1. API Configuration


// JavaScript - Configure external API client
function getApiClient() {
    const config = {
        baseUrl: env.getProperty("external.api.url", "https://api.example.com"),
        apiKey: env.getProperty("EXTERNAL_API_KEY"),
        timeout: env.getProperty("external.api.timeout", java.lang.Integer.class, 30),
        retryCount: env.getProperty("external.api.retries", java.lang.Integer.class, 3)
    };
 
    if (!config.apiKey) {
        console.error("EXTERNAL_API_KEY not configured");
        return null;
    }
 
    return config;
}
 
// Use configuration
const apiConfig = getApiClient();
if (apiConfig) {
    const response = http.retry(
        () => http.getWithBearerToken(apiConfig.baseUrl + "/data", apiConfig.apiKey),
        apiConfig.retryCount,
        1
    );
}


// Java - Configure external API client (http(), environment() from the PluginContext)
record ApiConfig(String baseUrl, String apiKey, int timeout, int retryCount) {}
 
ApiConfig getApiClient() {
    var env = context().environment();
    String baseUrl = env.getProperty("external.api.url", "https://api.example.com");
    String apiKey = env.getProperty("EXTERNAL_API_KEY");
    int timeout = env.getProperty("external.api.timeout", Integer.class, 30);
    int retryCount = env.getProperty("external.api.retries", Integer.class, 3);
 
    if (apiKey == null) {
        System.err.println("EXTERNAL_API_KEY not configured");
        return null;
    }
    return new ApiConfig(baseUrl, apiKey, timeout, retryCount);
}
 
// Use configuration
ApiConfig apiConfig = getApiClient();
if (apiConfig != null) {
    var http = context().http();
    var response = http.retry(
        () -> http.getWithBearerToken(apiConfig.baseUrl() + "/data", apiConfig.apiKey()),
        apiConfig.retryCount(),
        1
    );
}

2. Environment-specific Behavior


// MVEL - Different behavior per environment
profile = env.getActiveProfiles().length > 0 ? env.getActiveProfiles()[0] : "default";
 
if (profile == "production") {
    // Production settings
    batchSize = env.getProperty("plugin.batch.size", Integer.class, 1000);
    logLevel = "ERROR";
} else if (profile == "development") {
    // Development settings
    batchSize = env.getProperty("plugin.batch.size", Integer.class, 10);
    logLevel = "DEBUG";
} else {
    // Default settings
    batchSize = 100;
    logLevel = "INFO";
}
 
log.info("Running in " + profile + " mode with batch size: " + batchSize);


// Java - Different behavior per environment
var env = context().environment();
String[] profiles = env.getActiveProfiles();
String profile = profiles.length > 0 ? profiles[0] : "default";
 
int batchSize;
String logLevel;
switch (profile) {
    case "production" -> {
        batchSize = env.getProperty("plugin.batch.size", Integer.class, 1000);
        logLevel = "ERROR";
    }
    case "development" -> {
        batchSize = env.getProperty("plugin.batch.size", Integer.class, 10);
        logLevel = "DEBUG";
    }
    default -> {
        batchSize = 100;
        logLevel = "INFO";
    }
}
 
log.info("Running in {} mode with batch size: {}", profile, batchSize);

3. Feature Flags


# Python - Feature flag management
def is_feature_enabled(feature_name):
    flag_key = f"plugin.feature.{feature_name}.enabled"
 
    # Check if explicitly set
    if env.containsProperty(flag_key):
        return env.getProperty(flag_key, java.lang.Boolean)
 
    # Check global feature flag
    global_enabled = env.getProperty("plugin.features.enabled", java.lang.Boolean, True)
 
    # Check if in beta features list
    beta_features = env.getProperty("plugin.features.beta", "")
    if feature_name in beta_features.split(","):
        return env.getProperty("plugin.features.beta.enabled", java.lang.Boolean, False)
 
    return global_enabled
 
# Usage
if is_feature_enabled("new_algorithm"):
    use_new_algorithm()
else:
    use_legacy_algorithm()


// Java - Feature flag management
boolean isFeatureEnabled(String featureName) {
    var env = context().environment();
    String flagKey = "plugin.feature." + featureName + ".enabled";
 
    // Check if explicitly set
    if (env.containsProperty(flagKey)) {
        return Boolean.TRUE.equals(env.getProperty(flagKey, Boolean.class));
    }
 
    // Check global feature flag
    Boolean globalEnabled = env.getProperty("plugin.features.enabled", Boolean.class, true);
 
    // Check if in beta features list
    String betaFeatures = env.getProperty("plugin.features.beta", "");
    if (java.util.Arrays.asList(betaFeatures.split(",")).contains(featureName)) {
        return Boolean.TRUE.equals(
            env.getProperty("plugin.features.beta.enabled", Boolean.class, false));
    }
 
    return globalEnabled;
}
 
// Usage
if (isFeatureEnabled("new_algorithm")) {
    useNewAlgorithm();
} else {
    useLegacyAlgorithm();
}

4. Service Configuration


// JavaScript - Dynamic service configuration
function getServiceConfig() {
    const config = {
        url: env.getProperty("plugin.service.url", "http://localhost:8080"),
        username: env.getProperty("plugin.service.username"),
        password: env.getProperty("plugin.service.password"),
        maxConnections: env.getProperty("plugin.service.max-connections", java.lang.Integer.class, 10)
    };
 
    // Validate configuration
    if (!config.url) {
        throw new Error("Service URL not configured");
    }
 
    return config;
}


// Java - Dynamic service configuration
record ServiceConfig(String url, String username, String password, int maxConnections) {}
 
ServiceConfig getServiceConfig() {
    var env = context().environment();
    String url = env.getProperty("plugin.service.url", "http://localhost:8080");
    String username = env.getProperty("plugin.service.username");
    String password = env.getProperty("plugin.service.password");
    int maxConnections = env.getProperty("plugin.service.max-connections", Integer.class, 10);
 
    // Validate configuration
    if (url == null) {
        throw new IllegalStateException("Service URL not configured");
    }
    return new ServiceConfig(url, username, password, maxConnections);
}

5. Webhook Configuration


// MVEL - Configure webhooks from properties
webhookConfig = [:];
 
// Check if webhooks are enabled
if (env.getProperty("plugin.webhooks.enabled", Boolean.class, false)) {
    webhookConfig["enabled"] = true;
    webhookConfig["urls"] = [];
 
    // Support multiple webhook URLs
    for (i = 1; i <= 10; i++) {
        urlKey = "plugin.webhook.url." + i;
        if (env.containsProperty(urlKey)) {
            url = env.getProperty(urlKey);
            authKey = "plugin.webhook.auth." + i;
 
            webhook = ["url": url];
            if (env.containsProperty(authKey)) {
                webhook["auth"] = env.getProperty(authKey);
            }
 
            webhookConfig["urls"].add(webhook);
        }
    }
 
    webhookConfig["retries"] = env.getProperty("plugin.webhook.retries", Integer.class, 3);
    webhookConfig["timeout"] = env.getProperty("plugin.webhook.timeout", Integer.class, 10);
}
 
// Use configuration
if (webhookConfig["enabled"]) {
    for (webhook : webhookConfig["urls"]) {
        sendWebhook(webhook["url"], data, webhook["auth"]);
    }
}


// Java - Configure webhooks from properties (environment() from the PluginContext)
var env = context().environment();
List<Map<String, String>> webhookUrls = new ArrayList<>();
 
if (Boolean.TRUE.equals(env.getProperty("plugin.webhooks.enabled", Boolean.class, false))) {
    // Support up to 10 webhook URLs
    for (int i = 1; i <= 10; i++) {
        String urlKey = "plugin.webhook.url." + i;
        if (env.containsProperty(urlKey)) {
            String url = env.getProperty(urlKey);
            String authKey = "plugin.webhook.auth." + i;
            Map<String, String> webhook = new HashMap<>();
            webhook.put("url", url);
            if (env.containsProperty(authKey)) {
                webhook.put("auth", env.getProperty(authKey));
            }
            webhookUrls.add(webhook);
        }
    }
}
int retries = env.getProperty("plugin.webhook.retries", Integer.class, 3);
int timeout = env.getProperty("plugin.webhook.timeout", Integer.class, 10);
 
// Use configuration
for (Map<String, String> webhook : webhookUrls) {
    sendWebhook(webhook.get("url"), data, webhook.get("auth"));
}

6. Secrets Management


// JavaScript - Secure secret handling
function getSecrets() {
    const secrets = {};
 
    // Try environment variables first (preferred for secrets)
    secrets.apiKey = env.getProperty("API_KEY") ||
                     env.getProperty("plugin.api.key");
 
    secrets.password = env.getProperty("APP_PASSWORD") ||
                       env.getProperty("plugin.password");
 
    // Validate required secrets
    const required = ["apiKey"];
    for (const key of required) {
        if (!secrets[key]) {
            console.error(`Required secret '${key}' not configured`);
            console.error("Set via environment variable or application properties");
            return null;
        }
    }
 
    // Never log secrets!
    console.log("Secrets loaded successfully");
    return secrets;
}


// Java - Secure secret handling
record Secrets(String apiKey, String password) {}
 
Secrets getSecrets() {
    var env = context().environment();
 
    // Try environment variables first (preferred for secrets)
    String apiKey = env.getProperty("API_KEY");
    if (apiKey == null) apiKey = env.getProperty("plugin.api.key");
 
    String password = env.getProperty("APP_PASSWORD");
    if (password == null) password = env.getProperty("plugin.password");
 
    // Validate required secrets
    if (apiKey == null) {
        System.err.println("Required secret 'apiKey' not configured");
        System.err.println("Set via environment variable or application properties");
        return null;
    }
 
    // Never log secrets!
    System.out.println("Secrets loaded successfully");
    return new Secrets(apiKey, password);
}

Configuration File Examples

application.properties


plugin.api.url=https://api.example.com
plugin.api.timeout=30
plugin.api.retries=3
 
plugin.webhooks.enabled=true
plugin.webhook.url.1=https://webhook1.example.com
plugin.webhook.url.2=https://webhook2.example.com
plugin.webhook.retries=3
 
plugin.features.enabled=true
plugin.features.beta=feature1,feature2
plugin.features.beta.enabled=false
 
plugin.batch.size=100
plugin.db.max-connections=10

Environment Variables


# Secrets (preferred method)
export API_KEY="your-secret-api-key"
export APP_PASSWORD="secure-password"
export EXTERNAL_API_KEY="external-service-key"
 
# Configuration overrides
export PLUGIN_API_URL="https://api.production.com"
export PLUGIN_BATCH_SIZE=1000
export PLUGIN_FEATURES_ENABLED=true

Security Considerations

Never log sensitive configuration values! Always mask or omit secrets in logs.


// Safe logging of configuration
console.log("Configuration loaded:");
console.log(`  API URL: ${env.getProperty("plugin.api.url")}`);
console.log(`  API Key: ${env.containsProperty("API_KEY") ? "***configured***" : "missing"}`);
console.log(`  Timeout: ${env.getProperty("plugin.timeout", "30")}s`);


// Java - Safe logging of configuration (never log raw secrets)
var env = context().environment();
log.info("Configuration loaded:");
log.info("  API URL: {}", env.getProperty("plugin.api.url"));
log.info("  API Key: {}", env.containsProperty("API_KEY") ? "***configured***" : "missing");
log.info("  Timeout: {}s", env.getProperty("plugin.timeout", "30"));

Troubleshooting

Common Issues

Property not found: Check spelling and naming conventions
Wrong type: Ensure property value can be converted to requested type
Environment variable not visible: Restart application after setting
Profile-specific properties not loading: Verify active profile is set

Debugging Configuration


// List active profiles
console.log("Active profiles:", env.getActiveProfiles());
 
// Check multiple property sources
const propertyName = "plugin.api.url";
console.log(`Checking property: ${propertyName}`);
console.log(`  Exists: ${env.containsProperty(propertyName)}`);
console.log(`  Value: ${env.getProperty(propertyName, "not set")}`);
 
// Check both environment variable and property formats
console.log(`  As env var: ${env.getProperty("PLUGIN_API_URL", "not set")}`);
console.log(`  As property: ${env.getProperty("plugin.api.url", "not set")}`);


// Java - Debugging configuration (environment() from the PluginContext)
var env = context().environment();
 
// List active profiles
log.info("Active profiles: {}", java.util.Arrays.toString(env.getActiveProfiles()));
 
// Check multiple property sources
String propertyName = "plugin.api.url";
log.info("Checking property: {}", propertyName);
log.info("  Exists: {}", env.containsProperty(propertyName));
log.info("  Value: {}", env.getProperty(propertyName, "not set"));
 
// Check both environment variable and property formats
log.info("  As env var: {}", env.getProperty("PLUGIN_API_URL", "not set"));
log.info("  As property: {}", env.getProperty("plugin.api.url", "not set"));