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

Using Substitution Variables

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

Parent Element

Substitutable Attribute

<component>

<toplevelRef>

host

Example 6–5 Using Substitution Variables

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.