N1 Service Provisioning System 4.1 Reference Guide

Types of Variables Available for Substitution

When you create or edit a component, you can use predefined variable definitions or you can create custom ones to suit your needs.

The syntax to use when defining variable substitutions is:

:[variable]

where variable is the parameter you want to substitute the host-specific value for.

There are four basic kinds of variables you can define within a component:

Simple substitution variables
External component substitution variables
Session variable substitution
Target substitution variables

Simple Substitution Variables

You use simple substitution to define variables that you then reference later in the same component.

Simple substitution variables use the following syntax:

:[variable]

where variable is one of the following:

Local variable name - You can use local variable names in steps within a plan and in steps within a component's install, uninstall, and control service blocks.
Parameter name - You can use parameter names in steps within a plan and in steps within a component's install, uninstall, and control service blocks.
Predefined component variable name - You can only use predefined component variables in input sources associated with a component, but not for plans.

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. From an accessibility standpoint, predefined component variables are treated as public variables.

The predefined component variable names are listed in Predefined Substitution Variables for Components and Configuration Files.
Dynamic component variable name - You can only use dynamic component variables in input sources associated with a component, but not for plans.

A dynamic component variable name is a variable name declared by the associated component of the target component. In this case, the value to be substituted for the variable reference is either the associated override variables settings value, or else the default value defined by the component The value of this variable will be expanded before it is substituted.

External Substitution Variables

A variable setting value may include any number of external component substitution references. An external component substitution reference is one of the following:

:[primary-component:varname]
:[primary-component:secondary-component-list:varname]

Note –

An external component substitution reference does not include any white space.

Above, primary-component is one of the following:

	explicit-external-component
	secondary-component

And secondary-component is one of the following:

	nested-component
	toplevel-component
	dependee-component

The secondary-component-list is a sequence of one or more colon-separated secondary-components.

The varname is either a predefined substitution variable name, or a dynamic substitution variable name 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 at a particular location, and has the component resolution semantics of the <installedComponent> installed component targeter described in Chapter 2, “Installed Component Targeter” section. It has the following syntax:

	component-target:explicit-component-reference

Above, component-target specifies the host on which the desired component is installed, and is one of the following:

component
component(host-redirect)

The first variant specifies the current target host in the generation context. The second variant refers to the ROX host named by host-redirect, as specified in the host redirects section.

Above, explicit-component-reference is a reference to a component already installed on the target host specified by component-target. explicit-component-reference minimally includes the installed component name, but may 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}

Above, full-component-name is an absolute or relative reference to the desired component. Relative references are expanded relative to the plan or component that contains the explicit-component-reference. And path is either an absolute path name representing the install path of the desired component, or a substitution variable reference that, when expanded, represents the absolute install path of the desired component. If the former includes the "}" character, it must be escaped using the sequence "}}".

Nested Component Expansion

A nested-component specifies the component that is referenced by a nested component reference declared by the current component, and has the component resolution semantics of the <nestedRef> installed component targeter described in Chapter 2, "Installed Component Targeter" section. It has the following syntax:

	nestedRef:component-reference-name

Above, component-reference-name is the name of a <componentRef> element with "NESTED" installMode within the current component.

A nested-component may only be used when the current component is a composite component, and may only be used as a primary-component when the external component substitution reference appears within a composite component. When used as a primary-component, it may not be used as the default value of a component variable or override variable setting, as the referenced component will not yet have been installed when the variable is evaluated.

Toplevel Component Expansion

A toplevel-component specifies the component that is referenced by a toplevel component reference declared by the current component, and has the component resolution semantics of the <toplevelRef> installed component targeter described in Chapter 2, "Installed Component Targeter" section. It has one of the following formats:

toplevelRef:component-reference-name
toplevelRef:component-reference-name@{path}
toplevelRef(host-redirect):component-reference-name
toplevelRef(host-redirect):component-reference-name@{path}

Above, component-reference-name is the name of a <componentRef> element with "TOPLEVEL" installMode within the current component.

Above, path and host-redirect are the location and host, respectively, at which the referenced component is expected to be installed. host-redirect has syntax as specified in the host redirects section.

A toplevel-component may only be used when the current component is a composite component, and may only be used as a primary-component when the external component substitution reference appears within a composite component. When used as a primary-component, it may not be used as the default value of a component variable or override variable setting unless 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, and has the component resolution semantics of the <dependee> installed component targeter described in Chapter 2, "Installed Component Targeter" section. It has the following syntax:

	dependee:dependency-name

Above, dependency-name is the name of a dependency created by the current component.

A dependee-component may only be used as a primary-component when the external component substitution reference appears within a component. When used as a primary-component, it may not be used as the default value of a component variable or override variable setting, as the dependency will not yet have been created when the variable is evaluated.

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, and has the component resolution semantics of the <systemService> installed component targeter described in Chapter 2, "Installed Component Targeter" section. It has the following syntax:

systemService:system-service-name

System Type Component Expansion

A system-type-component specifies the component derived from a given component type that is most recently installed on a particular host at a particular location, and has the component resolution semantics of the <systemType> installed component targeter described in Chapter 2, "Installed Component Targeter" section. It 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}

Here, path is optional, and if specified, indicates the path in which the desired component is installed. The host-redirect is also optional, and indicates the host on which the desired component is installed, as described in the host redirects section.

Container Component Expansion

A container-component specifies the component that contains the current component as a nested reference. It has the following syntax:

	container

A container-component may only be used as a primary-component when the external component substitution reference appears within a component that has been installed as a nested component by another "container" component.

External Component Substitution Reference Resolution

The value of an external component substitution reference is computed by first resolving the component referenced by primary-component. If a secondary-component is used as a primary-component, then the component containing the external component substitution reference serves as the initial current component used when resolving the primary-component. The component resolved by primary-component becomes the new current component. Then, each secondary-component in the secondary-component-list is resolved using the last resolved component as the current component. Finally, we lookup and return the variable named varname in the last resolved component.

The value of an external component substitution reference is computed based on the value of the named variable within the referenced component as of the time it was installed. It is an error to reference a variable name that is not declared by the installed component, or to reference a component that is not installed on the target host. It is also an error to reference a variable that is not accessible to the component or plan that declares the external component substitution reference. The variable is accessible if and only if the variable is declared with an accessible access mode, and the component declaring the component is accessible, and each of the primary and secondary components traversed to get to that component are accessible.

Note –

External component substitution references are computed at the time that they are encountered during a plan run (as opposed to at the start of the plan run). Therefore, actual installed component being referenced may change based on steps executed earlier in the plan. Furthermore, references to components installed on a host other than the current target host may be affected by other plans running concurrently on the other host. For predictable results, clients should only reference hosts included in the target set of the current plan run (so that they"re guaranteed to be locked), and should synchronize any install/uninstall operations on an externally referenced host within the plan using retargeting and/or series execution mode.

Here are some examples of external component substitution references, using explicit-external components:

:[component:installApache:label]
:[component:jdk#1.3:classpath]
:[component:webApp#2.4@{/usr/local}:bannerColor]
:[component(/):IIS global settings:install_path]
:[component:webApp@{:[webAppPath]}:bannerColor]

In the second to last example, the component is resolved that is installed on the root physical host of the current target host.

In the last line, webAppPath is resolved as the name of a simple substitution variable set in the associated component of the generation context, not a variable defined in the externally referenced component.

Here are some examples of external component substitution references, using nested and toplevel-components:

:[nestedRef:ref1:label]
:[toplevelRef:ref2:name]
:[toplevelRef(/):ref3@{/usr/local}:var1]

Here is an example of external component substitution references, using dependee-components:

:[dependee:app2domain:domainName]

Session Variables Substitution Variables

Session variables allow users to enter data, such as their WebLogic credentials, once during a login session. Also, users can securely save the contents of these variables so that they don't need to re-enter them each time they log in. Session variables are integrated at the modeling level using substitution variables. Session variables have the following syntax:

session:varname

Above, varname is the name of a session variable.

Note –

Session variable references of the form session:varname will resolve 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 that states that the session variable was not defined. When a failure to generate a session variable is encountered, an attempt will be made to add the session variable with an empty value to the user's current session variable set.

A session variable may be used anywhere a simple substitution variable reference may be used. However, a session variable cannot be used within the value of another session variable.

Target Substitution Variables

You can use target substitution variables to get values directly from a particular host

Target substitution variables use the following syntaxes:

:[target:varname]
:[target(hostname):varname]

Variable names that begin with target refer to the logical host upon which a plan is currently being run.

The varname parameter you add after the colon represents an attribute value that is specified in the target host's definition for the application you are installing.

If you specify a (hostname) right after target, the value for varname is retrieved from that particular host, which can be a different host than the host the plan is currently being run on. You can also specify another substitution variable for hostname that, when expanded, resolves to the name of a host.

Host Redirects

Host substitution references and external component substitution references may optionally include a host redirect, in which case the host on which the variable or component lookup will occur is redirected from the current target to a named host. A host redirect has one of the following forms:

parent-ref hostname hostname/parent-ref

Where hostname is either the name of a ROX host, or a substitution variable reference that, when expanded, resolves to the name of a ROX host.

And parent-ref is either "/", meaning the root parent host of the named host (or current target host if hostname is omitted), or a series of one or more slash-separated "..", meaning the nth parent of the named host (or current target host if hostname is omitted) where "n" is the number of ".." that appear. The parent-ref operators are meant primarily for use with virtual hosts, though they may be used with physical hosts as well. Applying either operator to a physical host is a no-op.

Here are some examples of using target substitution variables:

This example specifies to look up variable var1 on host myHost.

:[target(myHost):var1]

This example specifies to look up variable var1 on host named by substitution variable hostName

:[target(:[hostName]):var1]

This example specifies to look up variable var1 on the logical host on which the plan is currently running.

:[target:var1]

The following are variables predefined for target hosts:

name – the name of the target host
description – description of the target host
hostTypeName – the name of the host type of the target host
raIP –the IP address of the remote agent on the target host
raPort – port used by the remote agent on the target host
raHomeDir - absolute path of the remote agent home directory on the target host
raDataDir - absolute path of the remote agent data directory on the target host
raTmp Dir - absolute path of the remote agent temporary directory on the target host
raConfigDir - absolute path of the remote agent config directory on the target host

Note –
In addition to the predefined variables, you can also reference any host attribute declared by the host type of the target host.

The following is an example of the list of variables defined in a component for apache:

<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 that the domain name be dynamically retrieved from the target host, defines the default value of `name' to be `apache', and then specifies a variable installPath value to use in the definition of two execNative variables.

Although you cannot use a target substitution variable within a configuration file, you can reference a host-specific value from within a configuration file. This is because the value of the variable you reference may be computed as a host-specific value. For example, you might have the following variable defined within the <varList> section of the component:

<var name="pants" value=":[target:pie]">

and then reference :[pants] from within a configuration file. When :[pants] is substituted, it will be substituted with the value of the pie variable defined by the target host.

Predefined Host Substitution Shorthands

The shorthands :[/] and :[/] can be used anywhere a host substitution reference may be used.

The shorthand :[/] is expanded to the operating system specific file separator based on the root physical host of the current target host. For example, it is expanded to “/” on UNIX-based operating systems and “\” on Windows.

The shorthand :[:] is expanded to the operating system specific path separator based on the root physical host of the current target host. For example, it is expanded to “:” on UNIX-based operating systems and “;” on Windows.