Docs/Developer SDK/Properties & Configuration

Properties & Configuration

Externalize customer and environment configuration without editing workflow code.

Configuration split

File	Purpose
`config/sdk.properties`	Local SDK runtime settings: input/output mode, FHIR endpoint and SDK directories.
`scripts/script.properties`	Customer-specific workflow configuration injected into scripts.

@ScriptProperty

Values from script.properties are injected into annotated script fields. Common target types include strings, booleans, sets and maps.

@ScriptProperty("hospitalName")
String hospitalName

@ScriptProperty("enable_debug")
boolean debugEnabled

@ScriptProperty("vital_list_noloinc")
Set<String> noLoincVitalList

@ScriptProperty("map_patient_classes")
Map<String,String> patientClasses

Validate configuration that is mandatory for the workflow during onStartup(), before message processing begins.

@Override
void onStartup() {
    if (!hospitalName || hospitalName.trim().isEmpty()) {
        throw new IllegalStateException("script.properties: hospitalName is required")
    }
}

Environment variables

Property values may resolve operating-system environment variables, which keeps deployment-specific and sensitive values outside the Groovy source.

property.name=${ENV_VARIABLE:defaultValue}

hospitalName=${HOSPITAL_NAME:St. Joseph Clinic}
defaultTimezone=+0200
apiToken=${API_TOKEN}

The default value after : is optional. If no default is provided, the environment variable must supply the value required by the workflow.

Protect credentials

Do not hardcode passwords, API tokens, authentication credentials, or customer secrets in Groovy scripts or committed property files. Use environment variables or the deployment environment's approved secret-management system.

Guidelines

Use properties for facility names, allow lists, timezones, endpoints and feature flags.
Keep safe fallback defaults only where a default is operationally valid.
Validate required properties in onStartup().
Keep business validation in semantic rules rather than encoding it in configuration values.