HOCON Substitution Variables

< Previous		Next >

Overview

This article describes the use of HOCON substitution variables.

Substitution Variables

Configuration files provide substitution variable support, where the substitution variable values come from (in priority order):

The substitutions= parameter of the epadmin install node or epadmin load configuration commands.
A substitution file specified using the substitutionfile= parameter of the same two epadmin commands.

For example, if the same substitution variable value is specified in a substitution file using the install node substitutionfile= parameter and also in the substitutions= parameter, the value specified in the substitutions= parameter is used.

There is no support for using an environment variable value as a substitution variable value. This is different behavior than standard HOCON, which allows environment variable values to be used as a substitution variable value.

Substitution variables must follow these rules:

Defined using ${variable-name[:-default-value]}. This defines a substitution variable named variable-name with an optional default value of default-value.
variable-name can only contain characters specified by this regular expression [a-zA-Z0-9\\.-_]+.
variable-name cannot contain the HOCON escape character (\).
Substitution variable values, and default-value expressions, cannot contain unescaped newlines. Escaped newlines (\\n) are permitted, and will result in a newline character appearing in the substituted value.
Closing braces (}) in substitution variable values must be escaped. For example:
```
roleSearchFilter = "${ROLESEARCHFILTER:-member={1\}}"
```
Nested substitution variables are not allowed (these are allowed by standard HOCON). For example:
```
foo = bar 
bar = biz 
bar = biz ${${foo}} // returns an error instead of the value biz
```
Substitution variables are supported anywhere in a configuration file, including the left-hand side of an assignment. This is an extension to standard HOCON.
Substitution variables on the left-hand side of an assignment that contain the "." character must be surrounded with double quotes to prevent the value from being interpreted as a HOCON path. This is an extension to standard HOCON.
Substitution variables are supported in quoted strings. This is an extension to standard HOCON.

Substitution Variable Example

The following is an example of a substitution variable in the configuration file header as well as in the body of the file.

Note

When using the HOCON Editor in StreamBase Studio, substitution variables MUST be specified with default values in order to pass Studio typechecking. Nevertheless, configuration files like the sample below (without default values) can be run as shown from the epadmin command line.

//
// Setting substitution variables on command line
//
epadmin load configuration source=my.conf substitutions=
  "NODE_NAME=A.X,PROJECT_VERSION=1.0"

//
// Use substitution variable in configuration file header
//
name     = "integration-test-application"
version  = ${PROJECT_VERSION}
type     = "com.tibco.ep.dtm.configuration.node"
configuration =
{
  NodeDeploy =
  {
    nodes =
      {
        //
        //  Use substitution variable on left-hand side
        //  of an assignment in a quoted string
        //
        "${NODE_NAME}" = { ... }
      }
  }
}

Default Substitution Variable Value Example

The following example shows a configuration file that specifies a default for its substitution variable using the colon-hyphen (:-) syntax.

Note

When using the HOCON Editor in StreamBase Studio, substitution variables MUST be specified with default values in order to pass Studio typechecking. Nevertheless, configuration files without default values can be successfully run from the epadmin command line.

configuration =
{
  ApplicationDefinition =
  {
    execution
    {
      dataTransport =
        {
          //
          //    Default value of 10 if not specified
          // 
          nodeActiveTimeoutSeconds = ${TIME_OUT_VALUE:-10}
        }
     }
  }
}

Built-in Substitution Variables

Built-in substitution variables are available. You can use built-in substitution variables anywhere in a configuration file where a standard substitution variable can be used. Built-in substitution variables do not need to specified. Built-in substitution variables include:

EP_NODE_NAME — node name.

The EP_NODE_NAME variable makes it easier to create elastic node deployment files such as:

name = "MyApplication"
version = "2.0"
type = "com.tibco.ep.dtm.configuration.node"
configuration = {
  NodeDeploy = {
    nodes = {
      "${EP_NODE_NAME}" = {
      }
    }
    availabilityZones = {
      zone1 = {
        dataDistributionPolicy = "dynamic"
      }
    }
  }
}