Skip to content

Using Placeholders in Martini

Overview

Placeholders in Martini automatically inject values from external sources into your configuration files. Instead of hardcoding database passwords or API keys, you can reference them from environment variables, HashiCorp Vault, or other secure sources. This makes your applications portable across environments and keeps sensitive data out of your packages or Martini instances.

When to Use This

Use placeholders when you need to:

  • Keep database credentials and API keys out of configuration files.
  • Deploy the same application to development, staging, and production with different settings.
  • Store sensitive configuration in HashiCorp Vault or environment variables.
  • Avoid manually updating repetitive configuration values across environments.

Where You Can Use Placeholders

You can use placeholders in many Martini configuration features, including:

  • Triggers — Configure dynamic URLs and credentials for trigger endpoints that start workflows or services in Martini.
  • Database Connections — Securely manage connection details like host, username, and password.
  • Application Properties — Centralize and manage app-level settings.
  • Package Properties — Share and manage settings across multiple services and workflows.

Placeholders help you keep your configurations flexible, secure, and easy to maintain across all these areas.

Prerequisites

Setting Up Property Sources

Before using placeholders, you need to set up the external sources that contain your configuration values.

Getting Started

Choose from these property sources based on your security and deployment needs:

For sensitive data (recommended):

For application settings:

Generic Placeholders

Generic placeholders automatically search multiple property sources in order until a value is found, providing built-in fallback behavior for different deployment environments.

Generic Placeholder Syntax: ${propertyName}

Getting Started

Use generic placeholders when you want maximum flexibility across environments. Enter placeholders directly into any Martini configuration field. For example, in Database Connection settings:

Example: Using a placeholder in a database connection

  1. Open your Database Connection settings in Martini Designer.
  2. In the Host field, enter: ${database_host}
  3. In the Username field, enter: ${db_username}
  4. Save your configuration.

Expected result: Martini searches possible sources in order and uses the first match found. See How It Works - Search Order.

How It Works

When Martini encounters a generic placeholder, it performs a cascading search through configured property sources. The first matching value found is used, providing a fallback mechanism that adapts to different deployment scenarios.

Search Order:

  1. Environment Variables - Values set in the operating system environment
  2. System Properties - JVM system properties passed at startup
  3. Package Properties - Properties defined within Martini packages
  4. Override properties - Runtime configuration overrides
  5. Application Properties - Default values in application configuration files

Important: Vault properties are not included in the generic placeholder search order. If you need to use a value from Vault, you must use a specific placeholder with the Vault prefix, such as ${vault1:propertyName} or ${vault2:propertyName}. For details, see Specific Placeholders.

Why It Matters

Generic placeholders eliminate the need to modify configurations when moving between environments. Your development, staging, and production deployments can use identical configuration files while pulling values from environment- appropriate sources.

Troubleshooting

Problem Detection Cause Fix Affected Versions
Property not resolved Placeholder appears as literal text (e.g., ${database_host}) Property doesn't exist in any searched source Add the property to one of the sources or use a specific placeholder v2.0+

Managing Placeholders Across Environments

Generic placeholders (like ${myPropertyName}) are designed for seamless environment switching. You can use the same placeholder in your configuration files for development, staging, and production, and Martini will resolve the value from the appropriate property source (environment variable, override property, or application property) based on the environment. This means you do not need to change the placeholder when moving between environments.

Note: Vault is not included in the generic placeholder search order. If you need to retrieve values from Vault, you must use a specific placeholder (e.g., ${vault2:database/host}), which requires updating your configuration for each environment and does not provide the same flexibility as generic placeholders.

Getting Started

To manage placeholder values per environment, configure each environment with its own property sources:

  1. Development:
    • Set database_host as a property in your Martini Package's package.properties on your development server 
      1
      database_host=dev-db.local
  2. Staging:
    • Add database_host=staging-db.internal to your staging override properties file (e.g., /martini-designer-workspace/conf/override.properties) or set it as an environmental variable.
  3. Production:
    • Add database_host=prod-db.internal to your production override properties file or set it as an environmental variable.

Example: Using a generic placeholder in database configuration

  • Open Martini Designer in the environment you want to configure (development, staging, or production).
  • For the Host field, enter: ${database_host} (generic placeholder)
  • Add values to other fields.
  • Save your configuration.

Expected result: Martini resolves ${database_host} to the correct value based on the environment's property sources and search order. You do not need to change the placeholder when switching environments.

For more details and step-by-step setup instructions, see Configuring Environment-Specific Properties.

How It Works

When you deploy your Martini package, the platform resolves each generic placeholder according to the property sources configured for the current environment. Generic placeholders are resolved by searching environment variables, system properties, package properties, override properties, and application properties in order. See Generic Placeholders - Search Order for more details.

This allows you to use the same configuration file across development, staging, and production, and Martini will automatically substitute the correct values based on where and how you deploy.

Specific Placeholders

Specific placeholders target exact property sources for faster lookup and predictable behavior.

Available placeholder syntaxes and their corresponding sources:

Syntax Source Example Usage
${env:propertyName} Environment variable ${env:DATABASE_URL}
${sys:propertyName} System property ${sys:java.home}
${vault1:propertyName} Vault v1 API ${vault1:secret/api-key}
${vault2:propertyName} Vault v2 API ${vault2:database/credentials}
${properties::/absolute/path/of/application/properties/file:propertyName} Application Properties ${properties::/martini-designer-workspace/conf/application.properties:db.password}
${properties::/absolute/path/of/custom/properties/file:propertyName} Use a custom properties file ${properties::/opt/configs/external.properties:db.password}

Getting Started

Use specific placeholders when you want to explicitly define the property source. For example, when configuring an AWS SQS trigger:

In AWS SQS Trigger properties:

  • Queue Name: ${env:SQS_QUEUE_NAME}
  • AWS Access Key ID: ${vault2:aws/access-key-id}
  • AWS Secret Key: ${vault2:aws/secret-key}
  • AWS Region: ${env:aws.region}

Expected result: Martini retrieves values directly from the specified sources without searching through other locations.

How It Works

Specific placeholders bypass the cascading search mechanism and query the designated source directly. This approach offers:

  • Performance benefits — No search overhead across multiple sources.
  • Predictable behavior — Values always come from the specified location.
  • Clear intent — Configuration explicitly shows where values originate.
  • Error isolation — Missing values fail fast with clear source identification.

Specifying Properties File in Placeholders

You can specify the exact properties file Martini should use by providing its path in the placeholder. This can be the default application.properties file or any other properties file you choose.

  • To use the default application properties file:

${properties::/martini-designer-workspace/conf/application.properties:propertyName}

  • To use a custom properties file:

${properties::/absolute/path/of/custom/properties/file:propertyName}

Why use a custom properties file?

  • The default application.properties is considered readonly and should not be modified.
  • The standard override.properties is intended for runtime overrides and general environment-specific values.
  • Use a custom properties file when you need a dedicated, organized set of properties for a specific purpose that cannot be satisfied by override.properties.
    Examples include team-specific settings, feature flags, third-party integration credentials, or modular configuration for different packages.
  • Collate custom values in one file while still using the defaults from application.properties.

Martini will look up the property value in the file you specify, instead of always using the default application properties.

Vault Integration

  • vault1: — Accesses HashiCorp Vault using KV Secrets Engine v1.
  • vault2: — Accesses HashiCorp Vault using KV Secrets Engine v2.
  • Requires vault connection configuration in Martini runtime.

For setup instructions and details on using Vault with Martini, see Configuring Vault.

Why It Matters

Specific placeholders give you precise control over configuration sources, improving application security by ensuring sensitive data only comes from approved locations like vault systems. They also provide better performance for frequently accessed properties.

Troubleshooting

Problem Detection Cause Fix Affected Versions
Property not resolved Placeholder appears as literal text (e.g., ${env:DB_HOST}) Source doesn't contain the property Verify property exists in specified source v2.0+
Vault connection failed Runtime error during startup Vault server unreachable or misconfigured Check vault connection settings and network connectivity v2.1+
Permission denied Error accessing vault property Insufficient vault permissions Update vault policies for the accessing token v2.1+

Helpful Resources