Substitution Variables
A substitution variable is a variable that you can reuse in resource, logging, and application configurations. Substitution variables enable late binding of property values to values set at administration time. For example, you can create an HTTP client resource template and bind its port property to a substitution variable that is set when the template is instantiated. The types of substitution variables are:
You can create substitution variables at design time and during administration. At design time, instead of explicitly setting property values, you can bind them to substitution variables. During administration, you set the substitution variables values to values supported by the resources available on the node on which the components and bindings are deployed.
A substitution variable is identified by a name. Names may not contain whitespace. When a property value is bound to a substitution variable, the property value is a string containing the substitution variable name surrounded by two pairs of percent signs.
Substitution Variable Scope
In Administrator, you can define and set enterprise, host, node, and environment substitution variables and can set application and application fragment substitution variables.
Using Substitution Variables
Substitution variables provide the ability to share common values, called generalization, or to introduce small variations in the configuration based on the node or machine, called specialization.
- In the resource template, application, or logging appender, type %%svar-name%% in any editable field instead of a fixed value such as 8080 for a port number. The svar-name is simply an identifier for the substitution variable and the %% is a mandatory prefix and suffix in a substitution variable. You can use multiple substitution variables as well as static text in a single value. For example, http://%%host-name%%/%%endpoint-uri%% can represent http://hostname/uri format.
- Define each substitution variable by assigning a type and value. For example, you can define substitution variables host-name and endpoint-uri at the environment level of type String and with a value venus and myservices/OrderService respectively. Do not use %% as prefix or suffix in the definitions. Also, do not use the values themselves as substitution variables.
- Design the resolution scheme for the substitution variables. If you are trying to generalize by sharing common values across multiple objects, define substitution variables at a broader scope, such as enterprise or environment. If you are trying to specialize by introducing small variations in the configuration, define substitution variables at a narrower scope such as application, node or host.
Example of Substitution Variable Usage
Let us say you created a HTTP Connector resource template and want to create two resource instances on two nodes. When you create this configuration, you want the flexibility to run the two nodes on the same machine or on two different machines. Entering a fixed port number such as 8080 in the HTTP Connector's port number field will not create a port conflict if the nodes run on different machines, however, will result in port conflict when the two nodes run on the same machine. To avoid a port conflict, use a substitution variable %%port%% in the port number field. Then define the substitution variable with name port, type Integer, and value 8080 at the node level for Node1, and also define the same substitution variable with a different port value, 8081 for Node2. Then, create resource instances on the two nodes and install them. ActiveMatrix Administrator will use port 8080 for Node1 and 8081 for Node2 which will avoid a port conflict. Thus, you have introduced a small variation in your HTTP Connector configuration at a node level.
A variation of the above case is that you can define the port substitution variable at the enterprise level with a value of 8082. Let us say you now add a Node3 to the system, however, forgot to define the substitution variable to the node level. Installing a resource instance on Node3 will succeed by using the port value 8082, which is treated as a default (fallback) value when no substitution variable is found at the node level for Node3.
Substitution Variable Resolution
A substitution variable defined at the node level will get a higher precedence than the one defined at the enterprise level. Enterprise level is the broadest scope at which you can define a substitution variable. A substitution variable defined at a specific node level is narrow in scope and is not visible to other nodes.
ActiveMatrix Administrator uses a resolution process based on fixed rules to determine which substitution variables should be considered to arrive at the final values to be replaced in a configuration property. The final value is sent to the runtime instead of the substitution variable. The value that is chosen depends on the type of the object and the scopes in which the substitution variables are defined.
The substitution variable resolution for each type is as follows:
Resource Templates
Substitution variables for resource templates are resolved when a resource instance from the resource template is installed or re-installed on a node.
For example, if a resource template using %%port%% substitution variable with a name port is defined at the node level, then its value is used and others ignored. If the host does not define port, then environment SVars are scanned for a match, and if there is no match, finally enterprise SVars are scanned. If no definitions are found, an error indicates that the substitution variable %%port%% was not found.
Application Properties
Substitution variables for application properties are resolved when deploying an application. The resolution order is the same as described for resource templates scoped at application level.
Logging Appenders
Substitution variables for logging appenders are resolved through logging configurations, that makes use of logging appenders, for a node, host or application. The resolution occurs when the logging configuration is deployed.
When used in logging configuration for an application, the resolution order for a substitution variable is the same as described for resource templates scoped at the application level.