Child pages
  • Substitution Language

This is the documentation of the latest development version of automaIT. The documentation of the latest stable release can be found at AUTOMAIT.

Skip to end of metadata
Go to start of metadata

Variables are used to parametrize components and plans . This allows creating different component instances by using specific values or running plans with different behaviour.

Substitutions are used to resolve values of variables. Substitutions can be used for example in the variables of component models or plans, conditions etc.

 

Usage of substitution at the example "echo"
<echo message="You are installing component :[sys.path]/:[sys.name]." />

The model schema gives a complete overview which attributes support substitutions. Attributes that support substitutions are identified by the attribute types SubstitutionType and SubstitutionNonEmptyType.

Structure of a Substitution

The structure of a substitution is always similar, regardless of the special substitution being used. The expression term is enclosed by a colon and square brackets.

:[variableName]

All substitutions are case sensitive.

The literal term ":[" can be escaped by using a colon and two opening square brackets: :[[.

Substitution Types

The following substitution types are available. All possibilities are listed in the section Grammar.

Simple Substitution

This substitution resolves a variable that is declared in the current scope. Only the variable name is given in the square brackets:

:[databaseName]

Session Substitution (session)

This substitution resolves the value of a user specific session variable:

:[session:myVariable]

The following session variables are predefined:

SubstitutionDescriptionSample Output
session:sys.userReturns the user name of the current user.admin
session:sys.sessionIDReturns the session-id of the current user.f97c6099-fd47-4df7-a894-f261df960d2d

System Substitution (sys)

This substitution resolves the value of a system variable. There is a predefined set of variables to work with:

Global Variables
SubstitutionDescriptionSample Output
sys.serverAddressReturns the server's address.
The property server.address may be overwritten by the administrator to change the default name.
automait.example.com
sys.serverHttpPortReturns the server's http port.8080
sys.serverHttpsPortReturns the server's https port.8443
sys.serverContextPathReturns the server's context path.

For installations of automaIT in the default (root) context, this system variable returns an empty string, i.e. "".

/np-server
sys.serverHttpUrlReturns the server's URL using the protocol http.http://automait.example.com:8080/np-server
sys.serverHttpsUrlReturns the server's URL using the protocol https.https://automait.example.com:8443/np-server
Variables of the Target System
SubstitutionDescriptionSample Output
sys.hostNameReturns the host name. 
sys.descriptionReturns the description of the host. 
sys.hostTypeReturns the host type. If the host type is plug-in owned, the name of the host type starts with the plug-in name
followed by a '#' and the name of the host type. Otherwise it is only the name of the host type.
info.novatec.db2#db2client
sys.portNumberReturns the port number of the host.8080
sys.ipAddressReturns the ip address resp. dns name of the host.192.168.0.1
sys.OSVersionReturns the os version of the host.3.2.0-25-generic
sys.OSArchReturns the os architecture of the host.i386
sys.OSNameReturns the name of the os of the host.Linux
sys.gatewayNameReturns the name of the gateway of the host. If the host uses no gateway, it returns an empty string.gateway1

These substitutions can only be used in combination with the prefix target. By default the current host is used. See  Host Substitutions for details to the keyword "target" and how to address differing hosts.

Example
:[target:sys.hostName]
Variables of the Component

The following substitutions return information about components:

SubstitutionDescriptionSample Output
sys.nameReturns the name of the component.MyComponent
sys.pathReturns the path of the component with a trailing slash./examples/
sys.versionReturns the version of the component.1.0
sys.descriptionReturns the description of the component.Sample description.
sys.idReturns the identifier of the instance./example/default
sys.targetRefNameReturns the name of the target-ref of the instance.myproduct-instance
Example
:[sys.name]

These substitutions can be used in combination with the prefix component, too. To use the component substitution in plans, the component prefix must be used.

Example with component prefix
:[component:/examples/Echo:sys.name]

Variables of the Resource

The following system substitutions can be used with resource prefix:

SubstitutionDescriptionSample Output
sys.deployNameReturns the name of the resource.ExampleResource
sys.deployPathReturns the path of the resource with a trailing slash./opt/resourcePath
Example
:[resource:resourceName:sys.deployName]

The usage with an component prefix is also possible:

Example
:[component(exampleHost):/examples/component:resource:resourceName:sys.deployPath]

Host Substitutions

Target Substitutions (target)

Host substitutions can resolve values of predefined host variables (identified by the prefix "sys"):

:[target:sys.hostName]

Host substitutions can also resolve the values of host specific variables (identified by its variable name without prefix) defined in its host type:

:[target:serviceLevel]

Host Redirection in Substitutions

The following keywords support host redirection:

  • target
  • targetableComponent
  • component
  • toplevelRef

The following examples all use "target".

If no host is specified, the current host scope is used to retrieve the variable value:

:[target:serviceLevel]

Hosts can also be referenced (absolutely) by name which has to be given in round brackets. The host name can contain substitutions:

:[target(:[hostName]):serviceLevel]

The host can also be addressed relatively to the current host. Virtual parents are addressed by using '..' as often as needed. Each '..' will go up one level. Subsequent '..' after reaching the physical host will have have no further effect and be ignored silently. Physical host can also be referenced using '/'.

# 2 hosts above current host (parent of parent)
:[target(../..):serviceLevel]
# Root / physical host of current host
:[target(/):serviceLevel]

Absolute and relative host addressing can also be combined within one substitution:

# Parent host of :[hostName]
:[target(:[hostName]/..):serviceLevel]
# Root / physical host of :[hostName]
:[target(:[hostName]//):serviceLevel]

File Separator (/)

This substitution resolves the specific file separator for the current host. If the indicated host is a virtual host, then the file separator is taken from the underlying physical host. For Unix systems the value is '/'. Windows systems will resolve this variable to '\'.

Path Separator (:)

This substitution resolves the specific path separator for the current host. If the indicated host is a virtual host, then the path separator is taken from the underlying physical host. For Unix systems the value is ':'. Windows systems will resolve this variable to ';'.

Component Substitutions

These substitutions resolve values of variables of components.

Primaries

Primary component substitutions will refer to a component scope and therefore can be used everywhere regardless of the the current scope (e.g. not only in components, but also in any plan). The following component substitutions are supported:

 

TypeKey WordDescriptionAbility to specify host (*)
component substitutioncomponentResolves the variable of a given component.(tick)
system service substitutionsystemServiceResolves the variable of a component that is a system service.(error)
targetable component substitutiontargetableComponentResolves the variable of a component that is targetable.(tick)
thisComponent substitutionthisComponentResolves the variable of a component variable of the current component.(error)

(*) see syntax described in "Target Substitutions" above.

 

Example of a component substitution with the current host:

:[component:/examples/Component:variableName]

Example of a component substitution with an explicit host:

:[component(localhost):/examples/Component:variableName]

Components should be referenced by their full qualified name and their identifier:

:[component(..):/examples/Component@{:[identifier]}:variableName]

Secondaries

To address other components relatively, starting from a specific component, secondary component substitutions can be chained. First of all there has to be a single primary component substitution. It can be followed by one or many secondary component substitutions. It is also possible to start with a secondary component substitution, if the substitution is used in the scope of a component - otherwise the substitution will fail, e.g. in a plan. In this case the secondary substitution is prefixed implicitly by the "thisComponent" substitution and refers to the scope of the current component:

TypeKey WordDescriptionAbility to specify host (*)
nested substitutionnestedRefResolves the variable of a nested component.(error)
toplevel substitutiontoplevelRefResolves the variable of a top level component.(tick)
dependee substitutiondependeeResolves the variable of a dependee.(error)
container substitutioncontainerResolves the variable of container component. Can only be used for nested components, not for toplevel components.(error)

(*) see syntax described in "Target Substitutions" above.

The variable of a component which is referenced by a dependency can be accessed using the dependee keyword.

:[dependee:dependencyName:variableName]

An example for the chaining of substitution is the following. In this example, the variable installPath will be resolved. The primary component substitution component (which references the component "TomcatClusterMember" by path and name) is followed by the secondary component substitutions container and nestedRef (which references the component reference "tomcatClusterMember2Ref" by name).

:[component:/examples/TomcatClusterMember:container:nestedRef:tomcatClusterMember2Ref:installPath]

Complex example

The following diagram shows an example installation of several components and how to get their values with different substitutions.

example-diagram

Grammar

The following grammar specifies the general construction of the substitution language. All words written in upper case letters have to be resolved by the defined rules. Letters in lower case or characters like colons and square brackets cannot be resolved any more. Epsilon is the expression for "nothing". The arrow indicates the resolution possibilities.

Words like "varname" (enclosed in arrow brackets) have to be replaced by names (e.g. the variable name for varname).

Grammar
E -> TERM E
	| epsilon
TERM -> LITERALTERM
	| SUBSTITUTIONTERM
LITERALTERM -> <any string>
SUBSTITUTIONTERM -> :[SIMPLE]
	| :[SESSION]
	| :[SESSION_ID]
	| HOST
	| :[COMPONENT_SUBSTITUTION]
HOST -> :[TARGET]
	| :[:]
	| :[/]
SIMPLE -> <varname>
SESSION_ID -> session:sys.sessionID
SESSION -> session:<varname>
COMPONENT_SUBSTITUTION -> PRIMARY:<varname>
	| PRIMARY:SECONDARY_LIST:<varname>
PRIMARY -> COMPONENT
	| SYSTEM_SERVICE
	| TARGETABLE_COMPONENT_SUBSTITUTION
	| SECONDARY
SECONDARY_LIST -> SECONDARY:<varname>
	| SECONDARY:SECONDARY_LIST:<varname>
SECONDARY -> NESTED
	| TOPLEVEL
	| DEPENDEE
	| CONTAINER
TARGET -> target HOSTREDIRECT:<varname>
TARGETABLE_COMPONENT_SUBSTITUTION -> targetableComponent HOSTREDIRECT
COMPONENT -> component HOSTREDIRECT COMPONENT_REFERENCE
COMPONENT_REFERENCE -> COMPONENT_QUALIFIED_NAME
	| COMPONENT_QUALIFIED_NAME # COMPONENT_VERSION
	| COMPONENT_QUALIFIED_NAME @{ID}
	| COMPONENT_QUALIFIED_NAME # COMPONENT_VERSION@{ID}
COMPONENT_QUALIFIED_NAME -> PATH <componentName>
	| <componentName>
PATH -> /
	| RELATIVE_PATH/
	| /RELATIVE_PATH/
RELATIVE_PATH -> .
	| ..
	| ./RELATIVE_PATH
	| ../RELATIVE_PATH
	| <path>
	| <path>/RELATIVE_PATH
SYSTEM_SERVICE -> systemService:SYSTEM_NAME
SYSTEM_NAME -> <systemNameIdentifier>
	| PLUGIN_NAME#<systemNameIdentifier>
PLUGIN_NAME -> IDENTIFIER
	| IDENTIFIER.PLUGIN_NAME
NESTED -> nestedRef:COMPONENT_REFERENCE_NAME
COMPONENT_REFERENCE_NAME -> IDENTIFIER
TOPLEVEL -> toplevelRef HOSTREDIRECT:COMPONENT_REFERENCE_NAME @{ID}
	| toplevelRef HOSTREDIRECT:COMPONENT_REFERENCE_NAME
DEPENDEE -> dependee:DEPENDENCY_NAME
DEPENDENCY_NAME -> IDENTIFIER
CONTAINER -> container
HOSTREDIRECT -> epsilon | (E)
IDENTIFIER -> epsilon
	| <any string>
ID -> E
	| ([^}])
  • No labels