N1 Grid Service Provisioning System 5.0 Plan and Component Developer's Guide

Types of Variables Available for Substitution

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

Simple Substitution Variable References

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.

Predefined Component Variable Names

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.

Escape Sequences for Substitution 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.

Substitution Variable Expansion

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.

Simple Substitution Variable Reference Expansion

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.

Example 6–1 Using Simple Substitution Variables

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

External Component Substitution Variable References

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.

Explicit External Component Expansion

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.

System Service Component Expansion

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.

System Type Component Expansion

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.

`targetableComponent` Component Expansion

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.

Secondary Component Expansion

Nested Component Expansion

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.

Top-Level Component Expansion

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.

Dependee Component Expansion

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.

Container Component Expansion

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.

Resolving External Component Substitution References

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.

Example 6–2 Using External Component Substitution Variable References

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 Substitution Variable References

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.

Predefined Session Variables

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.

Target Substitution Variable References

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.

Predefined Host Substitution Shorthands

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 ;

Host Redirects

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.

Example 6–3 Using Target Substitution Variable References

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]

Predefined Host Variable Names

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

Example 6–4 Using Host Substitution Variable References

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

Dynamic Host Variable Names

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.