Configuring Dynamic Values with HOCON

This guide shows how to configure dynamic variable values using HOCON (Human-Optimized Config Object Notation) files in a Spring Boot application.

Prerequisites

  • A Spring Boot application

  • MPS-generated code containing DynamicVariableLibrary classes

  • Maven, for dependency management

Steps

1. Add Maven Dependencies

Add the IPF Studio Configuration HOCON Spring Starter to your project:

<dependency>
    <groupId>com.iconsolutions.dsl</groupId>
    <artifactId>ipf-studio-configuration-hocon-spring-starter</artifactId>
    <version>${ipf-studio-configuration.version}</version>
</dependency>

This transitively includes:

  • ipf-studio-configuration-core - Core interfaces

  • ipf-studio-configuration-hocon - HOCON parser

  • ipf-studio-configuration-spring-starter - Spring Boot auto-configuration

  • com.typesafe:config - Typesafe Config library

2. Create HOCON Configuration File

Create an application.conf file in your src/main/resources directory:

ipf.studio = {
    models = [
        {
            name = "paymentService",
            configurable-values-global = {
                upperBound = 5000,
                minAmount = 10,
                allowedCurrencies = ["USD", "EUR", "GBP", "CHF"]
            }
            entities = []
        }
    ]
}

Key points:

  • Each entry in models array represents an MPS model

  • The name must match your MPS model name exactly

  • Keys in configurable-values-global are the variable names defined in DynamicVariableLibrary nodes within MPS

  • The composite key is formed automatically: {modelName}_{variableKey}

3. Verify Auto-Configuration

With the dependencies and configuration in place, Spring Boot auto-configuration will:

  1. Detect DynamicVariableLibrary beans (from your MPS-generated code)

  2. Create a HoconConfigurableValueSource from the Config bean

  3. Create a ConfigurableValuesManager that loads and registers values

The ConfigurableValuesManager validates that configuration values match the expected types defined in your DynamicVariable declarations and will throw an IllegalArgumentException at startup if there’s a type mismatch.

4. Entity-Scoped Configuration (Optional)

Entity-scoped configuration allows different processing entities to have their own values for dynamic variables, overriding the global defaults when the corresponding Processing Entity is in context.

Configuration Format

Extend your application.conf to include entity-specific overrides:

ipf.studio = {
    models = [
        {
            name = "paymentService",

            // Global defaults
            configurable-values-global = {
                upperBound = 1000,
                minAmount = 1,
                allowedCurrencies = ["USD", "EUR"]
            },

            // Entity-specific overrides
            entities = [
                {
                    name = "entity-1",
                    configurable-values = {
                        upperBound = 50000,
                        allowedCurrencies = ["USD", "EUR", "GBP", "CHF", "JPY"]
                    }
                },
                {
                    name = "entity-2",
                    configurable-values = {
                        upperBound = 5000
                    }
                },
                {
                    name = "entity-3",
                    configurable-values = {
                        upperBound = 100,
                        minAmount = 10
                    }
                }
            ]
        }
    ]
}

Key points:

  • Each entity has a name (string identifier)

  • Entity configurable-values override global values

Troubleshooting

Values Not Being Applied

  • Verify the model name in HOCON matches your MPS model name exactly

  • Check that the Config bean is available in the Spring context

  • Look for warning logs about unrecognized configuration keys

Unknown Configuration Keys Warning

If you see warnings like:

WARN ConfigurableValuesManager - Configuration key 'modelName_unknownVar' from source 'HoconConfigurableValueSource' does not match any known DynamicVariable

This means the HOCON file contains a key that doesn’t correspond to any defined DynamicVariable. Check for typos in the variable name.

Type Mismatch Errors

If a configuration value doesn’t match the expected type, you’ll see an error at startup:

java.lang.IllegalArgumentException: Type mismatch for configuration variable with key: 'paymentService_upperBound' - expected type java.lang.Integer but got java.lang.String

This indicates the HOCON value type doesn’t match the DynamicVariable type. For example, if upperBound is defined as Integer but configured as a string "5000" instead of numeric 5000.

Additional Resources