The N1 Grid Service Provisioning System software enables you to customize the deployment of any component by using substitution variables and variable settings.
This chapter covers the following topics:
You can model an application as a component so that it can be customized to run in different environments.
For example, suppose that you use a database application to manage your online catalog business. Before you deploy the application to the production environment, you test it in a test environment. These two environments run the same application but are configured differently. When the application is deployed to the test environment, it uses a test database. When the application is deployed to the production environment, it uses the production database.
You can store configuration information about the application, such as which database to use, in configuration files. To support each environment, these files must be customized. These configuration files can include substitution variables that are replaced by variable setting values when you deploy the component.
Not only can you use substitution variables in configuration files, but also in plans and components. For example, you might use them to specify the directory in which to install the application. The provisioning system enables you to define and manage distinct variable settings for each deployment environment.
A substitution variable reference in a configuration file, plan, or component can obtain the following kinds of values:
User-defined value
Component-specific value, such as a name or label
Target host-specific value, such as an IP address
User-defined value that is specific to a host in the provisioning system
Value of a session variable
Value associated with a component that has already been installed
The provisioning system uses a configuration generation engine to replace substitution variable references with the appropriate variable setting values. This engine interacts with the host repository and component repository to resolve values any time that you run a plan to deploy a component.
The provisioning system has a repository for storing variable settings so you can reuse them at a later time. You can view the variable settings that have been used to install components and to run plans to determine the state of the variables. This repository is also used to determine the state of substitution variables when running a comparison with an installed component.
When you run a plan that deploys an application to more than one host, you can use configuration generation to automatically replace substitution variables with appropriate values for each host.
To do this, you add substitution variable definitions to your components. These can be used, for example, as a way to configure the directory into which an application is installed. Using the provisioning system, you can define and manage different variable settings for application deployments on each of your target hosts, as follows:
Each version of a component can declare its own variable definitions.
Each version of a component has its own variable settings (possibly imported from a previous version).
Each component can be installed using any of its variable settings.
The values that the provisioning system substitutes when you install an application can be any of the following:
Value that you specify
Component-specific value, such as a name or a label
Value that is associated with a previously installed component
Value of a session variable
Value that is specific to a target host, such as an IP address or a user-defined host variable
Variable substitution happens when a target step is run on a target host. The step can be in a plan or in a component being installed or already installed on the target host. If there is a state associated with the target host and component, it is used to determine the value of a particular substitution variable. The state can include the following:
Target component – The component on which to perform operations
Target host – The current host on which the target step is executing
Target variable settings source – A collection of name-value pairs that override the the default values defined in the component when it is being installed
Local variables – Any variables in the target step itself, such as those that you have declared in the enclosing block or plan
The variable substitution engine operates on any text-based input source in the form of a String or Reader. In practice, however, only these entities are used as input sources:
Configuration-type resource files
Input to CLI commands that perform variable substitution on demand
Some of the component and plan attributes, such as the defaultInstallPath attribute of the <installSteps> element and the command attribute of the <execNative> step
See Chapter 2, Shared Schema Used by Components and Simple Plans, in N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide, Chapter 3, Component Schema, in N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide, and Chapter 4, Plan Schema, in N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide.
You can refer to the following types of variables from within components, plans, variable settings, and configurable resources:
Simple substitution variables
External component substitution variables
Session substitution variables
Target substitution variables
The input source can contain any number of simple substitution variable references. A simple substitution variable has the following syntax:
:[variable] |
variable is one of the following:
Local variable name. You can reference local variable names in plan steps and in steps that are in a component's install, uninstall, snapshot, and control service blocks.
Parameter name. You can reference parameters in plan steps and in steps that are in a component's install, uninstall, snapshot, and control service blocks.
Predefined component variable name. You can only use predefined component variable names in input sources that are associated with a component, but not with a plan.
Predefined component variable names are always resolved relative to the actual component that is (or is being) installed, even if the variable reference occurs in a base component. From an accessibility standpoint, predefined component variables are treated as PUBLIC variables.
See Predefined Component Variable Names for a list of names.
Dynamic component variable name. A component can reference both locally declared and inherited variables. The value that will be substituted for the reference is either the override value of the associated variable settings source or the variable's default value. The value that is used is expanded before it is substituted.
A dynamic component variable name is declared or inherited by the component associated with the target component. In this case, the value to be substituted for the variable reference is either the associated override variable settings value or the default value defined by the component. The value of this variable is expanded before it is substituted.
These predefined component variable names refer to the associated component attributes of the generation context:
sys.name – Component name
sys.description – Component description
sys.label – Label of the component
sys.softwareVendor – Software vendor that wrote the application that is modeled by the component
sys.author – Creator of the component
sys.path – Path of the component
The sys.path variable is like the path attribute of the component, but it includes a trailing slash (/). sys.path can be directly combined with the sys.name variable to create the full name of the component.
:[sys.path]:[sys.name] |
sys.rsrcInstallPath – Location where the component resource is installed
The sys.rsrcInstallPath variable is in the file format of the remote agent on which the component is, or is being, installed. You can only use this variable for simple components. Since the value of this variable might require other dynamic component variables to be computed, you cannot use sys.rsrcInstallPath in a component variable default value or variable settings override value. This variable also cannot be used as the value of the <component> installPath attribute or in the <resourceRef>/<installSpec> element attributes. These restrictions prevent the possibility of circular references.
sys.targetRefName – Name of the associated component targeting host
The sys.targetRefName variable is only defined for targetable components. The component targeting host is defined by the resolved value of the hostName attribute of the targetable component's <targetRef> element. It cannot appear as a simple substitution variable in a component variable value because component variables might be used to compute the sys.targetRefName value. This variable is most often used with the <retarget> step to install or manipulate components that are in a targetable component.
Predefined component variables are always resolved relative to the actual component that is, or is being, installed even if the variable reference occurs in a base component. Predefined component variables are treated as PUBLIC variables.
If you want to include :[ in input source, you must escape it by using :[[ instead. The configuration generator replaces occurrences of :[[ with :[.
For example, to literally include the text :[box] without the provisioning system substituting a value for box, use :[[box].
When the input source is an attribute of a component that is authored in XML, the value is subject to the following rules for XML-based escape sequences:
To get the quote character (""), use the " sequence.
To get the apostrophe character ('), use the ' sequence.
To get the less-than character (<), use the < sequence.
To get the greater-than character (>), use the > sequence.
To get the ampersand character (&), use the & sequence.
These escape rules do not apply to override values input via the provisioning system's browser interface, configuration resource files, or input to the configuration generation CLI commands.
When a substitution variable reference is replaced by a variable setting value, the value is recursively expanded before being substituted. This expansion is necessary because the value itself might contain references to simple substitution variables. To prevent the substitution of values, escape input sources with :[[.
You can only use host and external component substitution references in default or override substitution values, parameter default values, and local variable default values. Such references are not permitted in other input sources.
The syntax for a simple substitution variable reference in a variable setting value is the same as for input sources:
:[varname] |
In this case, the variable name that is referenced must be a variable that has been declared before the variable that contains the reference. This restriction prevents circular references.
For derived components, variables that are inherited from the base component are first expanded in the order of declaration in the parent. Then, local non-override variables are expanded in the order of declaration. Local variables that override inherited variables are expanded in place of the inherited variable in the same order that the inherited variable would have been expanded. Therefore, override variables can only refer to other inherited and override variables that have already been declared. For example, base component A declares variables x and y. Then derived component B declares variables z and y. The order of evaluation of variables in component B is x, which is inherited from component A, then y, which is overridden by component B, and finally z, which is local to component B.
The following table shows examples of substitution variables, as well as their expanded and unexpanded values.
Variable Name |
Unexpanded Value |
Expanded Value |
---|---|---|
foo |
silly |
silly |
bar |
:[foo] |
silly |
baz |
a :[foo] :[bar] example |
a silly silly example |
badFrob |
:[frob] |
Error – forward reference |
frob |
:[[foo] |
:[foo] |
compName |
:[sys.name] |
Name of the target component |
badFoz |
:[foz] |
Error – foz has not been declared |
A variable setting value can include one or more external component substitution references. An external component substitution reference is one of the following:
:[primary-component:varname]
:[primary-component:secondary-component-list:varname]
Note that an external component substitution reference does not include any white space.
primary-component is one of the following:
explicit-external-component
system-service-component
system-type-component
targetable-component
secondary-component
secondary-component is one of the following:
nested-component
toplevel-component
dependee-component
container-component
secondary-component-list is a sequence of one or more colon-separated secondary-components.
varname is either a predefined substitution variable name or a dynamic substitution variable name that is declared by the referenced component.
An explicit-external-component explicitly specifies a component that is expected to be installed on a particular host in a particular location. It has the component resolution semantics of the <installedComponent> installed component targeter. See Installed Component Targeters in N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide.
explicit-external-component has the following syntax:
component-target:explicit-component-reference |
component-target specifies the host on which the specified component is installed and is one of the following:
component – Specifies the current target host in the generation context
component(host-redirect) – Refers to the host named by host-redirect (see Host Redirects)
explicit-component-reference is a reference to a component that is already installed on the target host that is specified by component-target. The explicit-component-reference minimally includes the installed component name, but can also include a version and an install path, as follows:
full-component-name full-component-name#version full-component-name@{path} full-component-name#version@{path} |
full-component-name is an absolute or relative reference to the specified component. A relative reference is expanded relative to the plan or component that contains explicit-component-reference.
path is the absolute install path name of the specified component, or a substitution variable reference that, when expanded, represents the absolute install path of the specified component. If path includes the } character, it must be escaped using the }} sequence.
A system-service-component specifies a system service component that is expected to be installed on the root physical host of the current target. It has the component resolution semantics of the <systemService> installed component targeter. See Installed Component Targeters in N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide.
system-service-component has the following syntax:
systemService:system-service-name |
If the system service is defined by a plug-in, system-service-name must be prefixed with the name of the plug-in that defines it.
A system-type-component specifies the component that is derived from a specified component type that is most recently installed on a particular host in a particular location. It has the component resolution semantics of the <systemType> installed component targeter. See Installed Component Targeters in N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide.
system-type-component has the following syntax:
systemType:component-type-name systemType:component-type-name@{path} systemType(host-redirect):component-type-name systemType(host-redirect):component-type-name@{path} |
path is optional. If specified, path is the absolute install path name of the specified component or a substitution variable reference. The reference, when expanded, represents the absolute install path of the specified component. If path includes the } character, it must be escaped using the }} sequence.
host-redirect is also optional and indicates the host on which the component is installed. See Host Redirects.
If the component type is defined by a plug-in, component-type-name must be prefixed with the name of the plug-in that defines it.
A targetable-component references variables that are associated with a targetable component and is similar to the <targetableComponent> targeter. See Installed Component Targeters in N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide.
targetable-component has the following syntax:
targetableComponent
targetableComponent(host-redirect)
host-redirect is the name of a component targeting host. If unspecified, the host on which the plan is currently executing is used. These constructs resolve to the targetable component that is associated with a particular component targeting host. See Host Redirects.
A nested-component specifies the component that is referenced by a nested component reference that is declared by the current component. It has the component resolution semantics of the <nestedRef> installed component targeter. See Installed Component Targeters in N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide.
nested-component has the following syntax:
nestedRef:component-reference-name |
component-reference-name is the name of a <componentRef> element where installMode=NESTED for the current component.
nested-component can only be used when the current component is a composite component. It can only be used as a primary-component when the external component substitution reference appears in a composite component. When used as a primary-component, it cannot be used as the default value of a component variable or override variable setting. This is because the referenced component will not yet have been installed when the variable is evaluated.
A toplevel-component specifies the component that is referenced by a top-level component reference that is declared by the current component. It has the component resolution semantics of the <toplevelRef> installed component targeter. See Installed Component Targeters in N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide.
toplevel-component has the following syntax:
toplevelRef:component-reference-name toplevelRef:component-reference-name@{path} toplevelRef(host-redirect):component-reference-name toplevelRef(host-redirect):component-reference-name@{path} |
component-reference-name is the name of a <componentRef> element where installMode=TOPLEVEL for the current component.
path is the absolute install path name of the specified component, or a substitution variable reference. The reference, when expanded, represents the absolute install path of the specified component. If path includes the } character, it must be escaped using the }} sequence.
host-redirect is the host on which the referenced component is expected to be installed. The syntax for host-redirect is described in Host Redirects.
toplevel-component can only be used when the current component is a composite component. It can only be used as a primary-component when the external component substitution reference appears in a composite component. When used as a primary-component, it cannot be used as the default value of a component variable or an override variable setting. This is because the referenced component has already been installed.
A dependee-component specifies the component on which the current component depends as a result of a dependency created by a <createDependency> step. dependee-component has the component resolution semantics of the <dependee> installed component targeter. See Installed Component Targeters in N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide.
dependee-component has the following syntax:
dependee:dependency-name |
dependency-name is the name of a dependency that is created by the current component.
dependee-component can only be used as a primary-component when the external component substitution reference appears in a component. When used as a primary-component, it cannot be used as the default value of a component variable or an override variable setting. This is because the dependency will not yet have been created when the variable is evaluated.
A container-component specifies the component that contains the current component as a nested reference.
container-component has the following syntax:
container |
container-component can only be used as a primary-component when the external component substitution reference appears in a component that has been installed as a nested component by another “container” component.
The value of an external component substitution reference is computed first by resolving the component that is referenced by primary-component. If secondary-component is used as a primary-component, the component that contains the external component substitution reference serves as the initial current component that is used when resolving the primary-component. The component that is resolved by primary-component becomes the new current component. Then, each secondary-component in secondary-component-list is resolved by using the last resolved component as the current component. Finally, the provisioning system looks up and returns the variable, varname, in the last resolved component.
The value of an external component substitution reference is computed based on the value of the specified variable in the referenced component at the time the component was installed. You cannot refer to a variable that is not declared by the installed component or to a component that is not installed on the target host. You also cannot refer to a variable that is not accessible to the component or plan that declares the external component substitution reference. The variable is accessible only if it is declared with an accessible access mode, the declaring component is accessible, and each primary and secondary component that is traversed to get to that component is accessible.
External component substitution references are computed at the time that they are encountered during a plan run, not at the start of the run. Thus, an actual installed component that is being referenced might change based on the steps executed earlier in the plan. Furthermore, references to components that are installed on a host other than the current target host might be affected by other plans that are running concurrently on the other host. For predictable results, only refer to hosts that are included in the target set of the current plan run because they are guaranteed to be locked. Also, synchronize any <install> or <uninstall> operations on an externally referenced host in the plan by using retargeting or series execution mode.
The following are examples of external component substitution variable references that use explicit-external components:
:[component:installApache:sys.label] :[component:jdk#1.3:classpath] :[component:webApp#2.4@{/usr/local}:bannerColor] |
In the following example, the provisioning system resolves the component that is installed on the root physical host of the current target host:
:[component(/):IIS global settings:install_path] |
In this example, webAppPath is resolved as the name of a simple substitution variable that is set in the associated component of the generation context. It is not a variable that is defined in the externally referenced component.
:[component:webApp@{:[webAppPath]}:bannerColor] |
The following examples show external component substitution variable references that use targetable-component:
:[targetableComponent:hostName] :[targetableComponent(host1):port] |
The following are examples of external component substitution variable references that use nested-component and toplevel-component:
:[nestedRef:ref1:sys.label] :[toplevelRef:ref2:sys.name] :[toplevelRef(/):ref3@{/usr/local}:var1] |
The following are examples of external component substitution variable references that use system-type-component and system-service-component:
:[systemService:com.sun.windows#Windows SS:classPath] :[systemType:com.sun.weblogic#WL Target Type:serverName] :[systemType(..):MyType@{/tmp}:var1] |
The following is an example of an external component substitution variable reference that uses dependee-component:
:[dependee:app2domain:domainName] |
The following is an example of an external component substitution variable reference that uses container-component:
:[container:sys.installPath] |
The following is an example of a chained component reference. This reference assumes that the current target component is installed as a nested component of another container component. The container: part resolves to the component that contains the current component, which for this example is called X. The nestedRef:ref1 part resolves to the component that is referenced by component X by using its component reference named ref1, which is component Y. The toplevelRef:ref1 part resolves to the component that component Y refers to by using its component reference ref1, which is component Z. Finally, the provisioning system resolves and uses the value of the label attribute that is defined by component Z.
:[container:nestedRef:ref1:toplevelRef:ref1:sys.label] |
Session variables enable you to enter data, such as your WebLogic credentials, one time per user session. You can also securely save the contents of these variables and not have to re-enter data each time you log in. Session variables are integrated at the modeling level by using substitution variables.
A session substitution variable reference has the following syntax:
:[session:varname] |
varname is the name of a session variable.
A session substitution variable reference resolves to the value of the session variable in the current user's session. An attempt to resolve a session variable that is not defined in the current user's session results in an error. When a failure to generate a session variable is encountered, an attempt is made to add the session variable, with an empty value, to the user's current session variable set.
A session variable can be used anywhere that a simple substitution variable reference can be used. However, a session variable cannot be used in the value of another session variable.
sys:sessionID is a predefined session variable that resolves to the ID of the current user session. The system sessionID variable enables you to write steps that call back into the master server through the CLI by using the same credentials as the user who ran the plan. The system sessionID variable can only be resolved in the context of certain hosts, per the config.allowSessionIDOnHosts configuration variable. Thus, the system sessionID variable can only be resolved if the target host of the current generation context is included within the hosts named by the config.allowSessionIDOnHosts configuration variable.
When configuring a CLI for use in callbacks during plan execution, a Remote Agent and CLI Client must be installed on the same server. For maximum security, you should install the CLI Client and the Remote Agent on the same server as the Master Server. In this scenario, plans and components that want to make a callback through the CLI would use a <retarget> step to redirect execution to the single host that contains the CLI. In addition, the system sessionID variable would be resolved after the <retarget> step, and the config.allowSessionIDOnHosts configuration variable would name only the master server host.
You can use target substitution variables to obtain values directly from a particular host.
Target substitution variable references use the following syntax:
:[target:varname] :[target(host-redirect):varname] |
A variable name that begins with target refers to the logical host on which a plan is currently being run.
varname represents an attribute value that is specified in the target host's definition for the application that you install. Two types of host variables can be referenced: predefined and dynamic. See Predefined Host Variable Names and Dynamic Host Variable Names.
If you also specify host-redirect, the value for varname is retrieved from that particular host. That host can be a host other than the host on which the plan is currently being run. You can also specify another substitution variable for hostname that, when expanded, resolves to the name of a host. The syntax for host-redirect is described in Host Redirects.
You can use these predefined host substitution shorthands anywhere that a host substitution reference can be used:
:[/] – Expands to the operating system-specific file separator, which is based on the root physical host of the current target host
UNIX systems – :[/] expands to /
Microsoft Windows systems – :[/] expands to \
:[:] – Expands to the operating system-specific path separator, which is based on the root physical host of the current target host
UNIX systems – :[:] expands to :
Microsoft Windows systems – :[:] expands to ;
Target host substitution variable references and external component substitution variable references can optionally include a host redirect. This means that the host on which the variable or component lookup occurs is the specified host rather than the current target. host-redirect has one of the following forms:
parent-ref
hostname
hostname/parent-ref
hostname is either the name of a host or a substitution variable reference that, when expanded, resolves to the name of a host.
parent-ref is one of the following:
/ – The root parent host of the specified host, or the current target host if hostname is omitted
A series of one or more slash-separated ..s – The nth parent of the specified host, or current target host if hostname is omitted, where n is the number of ..s that appear
The parent-ref operators are used primarily for virtual hosts, but they can also be used for physical hosts. Applying either operator to a physical host is a no-op.
This example shows how to look up variable var1 on host myHost:
:[target(myHost):var1] |
This example shows how to look up variable var1 on the host specified by substitution variable hostName:
:[target(:[hostName]):var1] |
This example shows how to look up variable var1 on the logical host on which the plan is currently running:
:[target:var1] |
These predefined host variable names refer to the associated attribute of the referenced host:
sys.hostName – Target host name
sys.description – Target host description
sys.hostType – Host type of the target host
sys.ipAddress – IP address of the remote agent on the target host
sys.portNumber – Port number of the remote agent on the target host
sys.raHomeDir – Absolute path of the remote agent home directory on the target host
sys.raDataDir – Absolute path of the remote agent data directory on the target host
sys.raTmpDir – Absolute path of the remote agent temporary directory on the target host
sys.raConfigDir – Absolute path of the remote agent configuration directory on the target host
The following are examples of host substitution variable references and their values:
:[target:sys.ipAddress] – IP address of the current host
:[target:var1] – Dynamic variable var1 of the current host
:[target(host1):var1] – Dynamic variable var1 of host host1
:[target(:[hostNameVar]):var1] – Dynamic variable var1 of the host whose name is the value of the hostNameVar substitution reference
:[target(/):var1] – Dynamic variable var1 of the root parent host of the current host
:[target(host1//):var1] – Dynamic variable var1 of the root parent host of the host named host1
:[target(../..):var1] – Dynamic variable var1 of the second parent host of the current host
:[target(host1/../..):var1] – Dynamic variable var1 of the second parent host of the host named host1
A dynamic host variable name is any attribute name that is declared by the host type of the referenced host. In this case, the value to be substituted for the variable reference is the corresponding value of the attribute that is defined by the referenced host. The value must be expanded prior to substitution, if applicable.
You can use simple substitution variables in any input source, including configuration files. You can use external component and target substitution variables in a number of places, including <varList>/<var> default values of the <installSteps>, <uninstallSteps>, <controlService>, and <executionPlan> elements.
Simple substitution variable references of the form :[varname] can be used in any input source, including configuration files and configurable component attributes. However, host substitution references (:[target:varname]) and external component substitution references (:[component:compRef:varname]) can only be used in variable setting values.
Variable setting values include the default attribute of the <var> element and values in the variable setting overrides, but not configuration files or other configurable component attributes. This limitation ensures that all variables used in a component and in the configuration files that it references are explicitly declared and validated by the <varlist> element of the component.
Following are all substitution variables that can be used in particular input sources. The elements and attributes listed are the input source, and the sublist contains the types of variables that are permitted.
<component>/<varList>/<var>/ default attribute:
Variable settings override value:
Component substitution references, excluding sys.rsrcInstallPath and sys.targetRefName
Host substitution references
External component substitution references, excluding nested-component and dependee-component as primary components
Session variable references
<component>/<installList>/<installSteps>/<paramList>/<param>/ default attribute:
<component>/<uninstallList>/<uninstallSteps>/ <paramList>/<param>/default attribute:
<component>/<controlList>/<control>/<paramList>/<param>/default attribute:
<component>/<snapshotList>/<snapshot>/<paramList>/<param>/ default attribute:
Component substitution references
Host substitution references
External component substitution references
Session variable references
<component>/<installList>/<installSteps>/<varList>/<var>/ default attribute:
<component>/<uninstallList>/<uninstallSteps>/<varList>/<var>/ default attribute:
<component>/<controlList>/<control>/<varList>/<var>/default attribute:
<component>/<snapshotList>/<snapshot>/<varlList>/<var>/default attribute:
Local variable substitution references that have been previously declared
Parameter substitution references
Component substitution references
Host substitution references
External component substitution references
Session variable references
<component>/<installList>/<installSteps>/child steps:
<component>/<uninstallList>/<uninstallSteps>/child steps:
<component>/<controlList>/<control>/child steps:
<component>/<snapshotList>/<snapshot>/<prepare>/child steps:
<component>/<snapshotList>/<snapshot>/<capture>/child steps:
<component>/<snapshotList>/<snapshot>/<cleanup>/child steps:
Local variable substitution references
Parameter substitution references
Component substitution references
<component>/<resourceRef>/<installSpec>:
<component>/installPath attribute:
Component substitution references, excluding sys.rsrcInstallPath
<component>/<diff>/<ignore>:
<component>/<componentRef>/<argList>:
Configuration files:
Component substitution references
<component>/<targetRef>:
<component>/<targetRef>/<agent>:
Component substitution references, excluding sys.targetRefName and sys.rsrcInstallPath
<executionPlan>/<paramList>/<param>/ default attribute:
Session variable references
<executionPlan>/<varList>/<var>/ default attribute:
<executionPlan>/*/<inlineSubplan>/<varList>/<var>/ default attribute:
Session variable references
Local variable substitution references that have been previously declared
Unhidden local variable substitution references of enclosing plans
Unhidden parameter substitution references
Host substitution references for simple plans and subplans only
External component substitution references for simple plans and subplans only, but excluding container, nested, top-level, and dependee as primary component
<executionPlan>/*/child steps:
Local variable substitution references
Unhidden local variable substitution references of enclosing plans
Unhidden parameter substitution references
hostAttributes
Session variable references
The following configuration attributes of a component can include substitution variable references.
Parent Element |
Substitutable Attributes |
---|---|
<capture>/<addFile> |
displayName, path |
<component> |
installPath |
<diff>/<ignore> |
path |
<installSpec> |
name, path, permissions, user, group, deployMode, diffDeploy |
<paramList>/<param> |
default |
<targetRef> |
hostName |
<targetRef>/<agent> |
connection, ipAddr, port, params |
<varList>/<var> |
default |
The following step attributes that are in a component or a plan can include substitution variable references.
Parent Element |
Substitutable Attributes |
---|---|
<argList> |
Attributes of the <argList> element, which are free form |
<execJava> |
className, classPath |
<execNative> |
dir, userToRunAs |
<execNative>/<ouputFile> |
name |
<execNative>/<errorFile> |
name |
<execNative>/<env> |
name, value |
<execNative>/<exec> |
cmd |
<execNative>/<exec>/<arg> |
value |
<execNative>/<shell> |
cmd, <body> |
<execNative>/<successCriteria> |
outputMatches, errorMatches |
<execNative>/<inputFile> |
name |
<execNative>/<inputText> |
<body> |
<if>/<condition>/<equals> <if>/<condition>/<istrue> <if>/<condition>/<matches> |
value1, value2 value value, pattern |
<processTest> |
processNamePattern, user |
<raise> <retarget> <retarget>/<varList>/<var> |
message host default |
<sendCustomEvent> |
message |
<transform> |
input, output |
<transform>/<source> |
name |
<transform>/<stylesheet> |
<body> |
<transform>/<subst> |
match, replace |
<urlTest> |
url, pattern |
The following plan attributes can include substitution variable references.
Parent Element |
Substitutable Attribute |
---|---|
<paramList>/<param> |
default |
<varList>/<var> |
default |
The following attributes of installed component targeters can include substitution variable references.
Parent Element |
Substitutable Attributes |
---|---|
<installedComponent> |
installPath, host |
<systemType> |
installPath, host |
<targetableComponent> |
host |
<toplevelRef> |
installPath, host |
The following attributes of repository component targeters can include substitution variable references.
Parent Element |
Substitutable Attribute |
---|---|
<component> <toplevelRef> |
host host |
The following example lists the variables that are defined in a component for the Apache web server:
<varList> <var name="domainname" default=":[target:domainname]"/> <var name="name" default="apache"/> <var name="installPath" default="/opt/apache"/> <var name="execNativeShutdown" default=":[installPath]/bin/apachectlstop"/> <var name="execNativeStartUp" default=":[installPath]/bin/apachectlstart"/> </varList> |
This component specifies the following:
The domain name must be dynamically retrieved from the target host.
The default value of name is apache.
The variable called installPath has a value of /opt/apache.
The value of installPath is used in the definition of two <execNative> variables.
Although you cannot use a target substitution variable in a configuration file, you can reference a host-specific value from a configuration file. You can do this because the value of the variable that you reference can be computed as a host-specific value. For example, you might have the following variable defined in the <varList> section of the component:
<var name="box" value=":[target:room]"> |
You can then reference :[box] from a configuration file. When :[box] is substituted, it is substituted with the value of the room variable that is defined by the target host.