Chapter 3 The N1 Service Provisioning System Software Plan Schema

This chapter describes the XML schema for N1 Service Provisioning System software plans.

For an overview of the provisioning software's XML schema architecture, see Chapter 1.

The executionPlan Element

The entire plan is enclosed by the <executionPlan> element.

In the following tables, the “Config” column indicates whether or not a specific attribute may include substitution variable references in the form “:[varName]”.

executionPlan Element attributes

executionPlan child elements

Plans are either simple or composite. Simple plans do not contain or call other plans. A simple plan is a sequential list of steps that will be executed on a particular set of target machines. Composite plans are composed solely of other subplans. Composite plans are not directly targeted, as each simple subplan they recursively contain has a different set of targets.

The Plan paramList Element

The plan <paramList> element is a child of the <executionPlan> element and is used to declare a list of parameters for use by the steps contained in the plan and any components they reference. When this plan is run as a top-level plan, the caller will be prompted to enter values for all parameters declared in this list. When this plan is invoked as the result of an <execSubplan> step in another plan, the calling plan must explicitly pass values for all non-default parameters declared in the <paramList>.

Plan paramList Element child elements

The Plan param Child Element

The plan <param> element is a child of the plan <paramList> element and is used to declare a parameter for use within the plan.

Plan param Child Element attributes

The Plan varList Element

The plan <varList> element is a child of the <executionPlan> and <inlineSubplan> elements and is used to declare a list of variables for use by the steps contained in the plan and any components they reference. The values of the variables are defined at the point of declaration, and cannot be redefined.

Plan varList Element

The Plan var Child Element

The plan <var> element is a child of the plan <varList> element and is used to declare a plan variable including name and value.

Plan var Child Element attributes

The simpleSteps Element

The <simpleSteps> element is a child of the <executionPlan> and <inlineSubplan> elements and contains one or more “shared” or “simple plan only” steps. The presence of a <simpleStep> element indicates that the plan is a simple (as opposed to composite) plan. When run, the steps within this element will be sequentially executed on a set of logical target hosts chosen by the caller.

simpleSteps Element attributes

The simpleSteps limitToHostSet Attribute

The limitToHostSet attribute of the <simpleSteps> element specifies the name of the host set containing the hosts that are considered valid targets for this plan. If unspecified, all hosts are considered valid targets. Otherwise, the targets specified by the client must be a subset of the hosts contained in the named host set. If the targets include a host not contained in the named host set, it is a plan run time error. It is also a plan run time error to specify a name that does not correspond to an existing host set. The plan run time errors described here are reported during validation before preflight starts.

Child Elements of the simpleSteps Elements

The <simpleSteps> element children consist of one or more “shared” or “simple plan only” steps. These steps may include references to plan parameters and variables.

See Simple Plan-only Steps for details.

The compositeSteps Element

The <compositeSteps> element is a child of the <executionPlan> and <inlineSubplan> elements and contains one or more “composite plan-only” steps. The presence of a <compositeStep> element indicates that the plan is a composite (as opposed to simple) plan. The <compositeSteps> element does not contain any attributes.

Child Elements of the compositeSteps Element

The <compositeSteps> element children consist of one or more “composite plan- only” steps. These steps may include references to plan parameters and variables.

See Simple Plan-only Steps for details.

Child Elements of the compositeSteps Element

The <compositeSteps> element children consist of one or more “composite plan- only” steps. These steps may include references to plan parameters and variables.

See Simple Plan-only Steps

Shared Steps

This section lists steps that may be used in either a component or a simple plan. These steps include:

• <call> (described in call Step)

• <checkDependency> (described in CheckDependency Step)

• <execJava> described in execJava Step

• <execNative> (described in execNative Step)

• <if> described in if Step)

• <pause> (described in pause Step)

• <processTest> (described in processTest Step)

• <raise> (described in raise Step)

• <reboot> )(described in reboot Step)

• <retarget> (described in retarget Step)

• <sendCustomEvent> (described The sendCustomEvent Step)

• <transform> (described in transform Step)

• <try> (described in try Step)

• <urlTest> (described in urlTest Step)

In the following tables, the “Config” column indicates whether or not a specific attribute may include substitution variable references in the form “:[varName]”.

call Step

You can use the <call> step to execute a control block associated with a component installed on the target host.

call Step attributes

call Step child elements

The argList Child Element

The <argList> element is a child of the <call>, <install>, <uninstall>, <execSubplan>, and <addSnapshot> steps. It specifies a list of variables to be passed as arguments to the called service. The called service declares the variables that it expects using a <paramList> element. The variables within the <argList> and the called <paramList> need not be the same. However, for any variable in the called <paramList> that does not have a default value, there must be a variable with the same name in the <argList>, or a preflight error is raised at plan runtime. For each variable in the called <paramList> for which there is a corresponding variable in the <argList>, the value of the variable in <paramList> will obtain the value of corresponding variable in <argList> for the duration of the execution of the called service.

Variables in <argList> that do not correspond to a variable in the called <paramList> will be silently ignored. This permits services to be redefined with additional parameters, while still allowing for backward compatibility such that one plan can call both old and new versions of the service.

The arguments of the <argList> element are expressed as attributes. For example, the following <argList> declares two arguments, “password” and “path”:

<argList password=”:[password]”
path=”/tmp”/> 

Order is not important.

argList Child Element attributes

The <argList> element must have at least one attribute. Each attribute is treated as a named variable to be passed to the called service. The name of each attribute must be an identifier without substitution variable references, and should correspond to the name of a parameter in the called service. The value of each attribute is an arbitrary string which may include references to variables in the enclosing scope, but not other arguments within the <argList>.

CheckDependency Step

You can use <checkDependency> to verify that a particular component has been installed on the target host. If an appropriate component has not been installed, the step fails and execution stops.

The dependency is checked using the contained component targeter. If the targeter successfully resolves a component, the dependency is considered satisfied. Otherwise, it is considered failed.

checkDependency Step child elements

execJava Step

A step used to execute a Java^TM Executor instance on the target host. If the executor instance raises an exception, the step fails and execution stops.

The <execJava> step is an advanced feature intended only for internal use.

execJava Step attributes

When an execJava step is contained within a component, it typically calls classes which are contained within one or more resources deployed by that component. When contained within a plan, the classes called are already resident on the agent, either as a system class of the agent itself, or more probably as a resource that was deployed with an existing component.

execJava Child elements

execNative Step

The <execNative> step is used to execute a native command on the target host. If the command produces an unexpected result, the step fails, and execution stops.

execNative Step attributes

execNative can have nested elements to specify the:

• Environment variables

• Background execution

• Command standard output file

• Command error output file

• Command input

• Command to execute

• Step success criteria

execNative Element child elements

1 Both <outputFile> and <errorFile> must be specified if <background> element is specified.

2 inputText and inputFile elements are optional. Only one of them may be specified at a time.

3 One of exec or shell elements must be specified. It is illegal to have both exec and shell elements in an execNative element.

The <inputText> and <inputFile> elements are optional. Only one of them may be specified at a time.

One of exec or shell elements must be specified. It is illegal to have both exec and shell elements in an execNative element.

The env Child Element

The <execNative> element may optionally have <env> elements to specify environment variables for the command. You can use <env> to supply new variables for the command's environment or to over-ride existing variables.

The set of the command's environment variables will be a union of the set of Remote Agent's environment variables and the variables supplied using the <env> tags.

env Element attributes

background element

The <background> element is a child of the <execNative> element and, when present, specifies that the command should be executed as a background process. It has no attributes or child elements.

For an <execNative> with a <background> element, the following constraints apply.

• <successCriteria> need not be specified. The step will succeed if there were no issues starting off the background process. If specified, the <successCriteria> is tested against the script that is used to run the command as a background process.

• No standard output or error output will be captured for the executed command. Clicking on details will show exist status as 0 and the empty output and error output. However in case there were problems starting the native command in background, you will see a different exit status, depending on the nature of the error and diagnostic output.

• The <outputFile> and <errorFile> elements must be specified. If the specified files already exist, they will be overwritten.

outputFile element

The outputFile element is used to specify the path to a local file on the agent in which the standard output of the command being executed should be stored. The path to the local file is specified through the name attribute in the outputFile element. Relative paths are interpreted relative to the command"s working directory.

The outputFile element must be specified if the background element is specified.

If outputFile is not specified and the successCriteria element does not specify an outputMatches, the respective output of the command will not be stored and will be lost. If outputMatches is specified, the standard output will be stored in a temporary file and that will be deleted after command is done executing.

outputFile Attributes

errorFile element

The errorFile element is used to specify the path to a local file on the agent in which the error output of the command being executed should be stored. The path to the local file is specified through the name attribute in the errorFile element. Relative paths are interpreted relative to the command"s working directory.

The errorFile element must be specified if the background element is specified.

If errorFile is not specified and the successCriteria element doesn"t specify an errorMatches, the respective output of the command will not be stored and will be lost. If errorMatches is specified, the error output will be stored in a temporary file and that will be deleted after command is done executing.

errorFile Attributes

The inputText Child Element

The <inputText> element is a child element of <execNative>. The <inputText> element specifies any arbitrary text that should be fed into the command's standard input. The text is specified as contents of this element.

You can use <inputText> to enclose input in CDATA sections, preserving the formatting of the input and avoiding parse errors that might be caused by input containing the characters `& and `<'.

For example:

<execNative>
		<inputText> 		  ls –l |fgrep `*test*'|sort –u >file.out 
	</inputText> 		<command exec=”sh”/> </execNative> 

If the <inputText> is specified, it will always be enclosed within a CDATA section when generating XML for the <execNative> step. All the characters within inputText are fed as it is to the command being executed. If inputText contains only white spaces, those white spaces will be fed, exactly as they are specified, into the standard input of the command being executed.

The contents of <inputText> are config-generated.

The <inputText> element has no attributes.

inputFile Child Element

The <inputFile> element is a child element of <execNative>. The <inputFile> element specifies the path to a local file on the Remote Agent whose contents should be fed into the standard input of the command being executed. The path to the local file is specified through the name attribute in the <inputFile> element.

The <inputFile> element cannot be used with the <inputText> element in an <execNative> command.

inputFile Element attributes

The exec Child Element

An <execNative> step can contain exactly one <exec> element. The <exec> element specifies the details of the native command to be executed.

The <exec> element contains:

• an attribute, cmd, that specifies the name of the command to execute

• a set of nested arg elements that specify each of the arguments for the command specified with cmd.

<execNative> executes the command specified in cmd directly with the arguments in the order they are specified.

For example, the <execNative> step below:

<execNative>
	<exec cmd=”ps”>
		<arg value=”-fu”/>
		<arg value=”sps”/>
	</exec>
</execNative> 

will execute the command: ps –fu sps.

exec Element attributes

exec Element child elements

arg Child Element attributes

The shell Child Element

The <shell> element is a child element of <execNative>. The <shell> element specifies the command to be executed as its content. The command to be executed is interpreted using an interpreter specified using the cmd attribute. The command thus specified is executed using sh –c `command' syntax for the platform. In this form the cmd attribute has to be specified to indicate the shell command to use to execute the command.

For example:

<execNative>
	<shell cmd=”/usr/bin/bash -c”>
		ls –l |fgrep `*test*'|sort –u >file.out
	</shell>
</execNative> 

This code executes the command:

/usr/bin/bash –c `ls –l |fgrep `*test*'|sort –u >file.out' 

To preserve formatting and to avoid XML parsing problems, the text contents of the command will always be enclosed within a CDATA element when generating XML representation from the <execNative> step.

It is illegal for command string to be empty or have only white space characters. The command string is supplied exactly as it is specified (with surrounding white space) to the shell.

The contents of the <shell> element are config-generated.

Attributes of the shell Element

The successCriteria Element

The <successCriteria> element is a child element of <execNative>. The <successCriteria> element specifies the criteria to be used to evaluate whether or not an <execNative> step executed successfully. If this element is not specified, the default value is:

<successCriteria status=”0”/> 

The successCriteria is ignored if an empty successCriteria is specified. If you specify the tag:

<successCriteria/> 

The step will always succeed no matter what output or exit code the command generated.

successCriteria Element attributes

If the inverse attribute is set to true, it negates each of the conditions specified within <successCriteria>.

For example, an <execNative> step with the following successCriteria

<successCriteria status=”1” outputMatches=”bin” errorMatches=”none” inverse=”true”/> 

will succeed if status is not 1 and output does not match `bin' and error does notmatch `none'.

<successCriteria> element that contains only the inverse attribute will be saved without the inverse attribute. That is if you specify

<successCriteria inverse=”true”/> 

It will be stored as:

<successCriteria/> 

The result will be that <successCriteria> is ignored.

if Step

A step used conditionally execute a block of steps. It has no attributes, and children consist of a <condition>, <then>, and <else> element.

If the content of the <condition> element evaluates to true, then the steps of the <then> block are executed, otherwise the steps of the <else> block are executed, if present.

if Step Child Elements

if Step Example

The following is an example of an <if> step used to conditionally restart.

<if>
	<condition><istrue value=":[restart]"/></condition>
	<then>
		<call blockName="restart"/>
	</then>
</if> 

condition Element

A child element of the <if> step that specifies a boolean expression. It has no attributes, and must contain exactly one boolean operator child element. See the Boolean Operators section for details of the permitted boolean operators.

then Element

A child element of the <if> step that specifies the steps to execute if the associated condition is true. It may contain any number of steps that are permitted within the scope of the block containing the <if> step.

else Element

A child element of the <if> step that specifies the steps to execute if the associated condition is not true. It may contain any number of steps that are permitted within the scope of the block containing the <if> step.

pause Step

The <pause> step pauses the execution of a plan for a specified amount of time. You can use <pause> to make a plan wait for required services to come online after being started.

pause Step attributes

processTest Step

The <processTest> step is used to verify that a particular process is running on the target host. If the desired process does not exist, the step fails and execution stops.

This step is intended for use with UNIX systems.

processTest Step attributes

raise Step

A step that always fails (though it may be caught and handled in a <try> step). It contains a single attribute "message", and has no children.

The <raise> step is used to indicate a failure condition without having to construct an artificial step to do so. It most often appears within a <catch> block to propagate an error condition after cleaning up.

raise Step attributes

raise Step Example

The following example shows how the <raise> step is used to repropagate an error condition from within a <catch> block, after noting the error in a log.

<control blockName="default">
	<try>
		<block>
			<!-- some arbitrary processing here -->
		</block>
		<catch>
			<!-- note error in log -->
			<execNative>
				<exec cmd="appendLog"> <arg value="an error occurred"/> </exec>
			</execNative>
			<!-- rethrow error -->
			<raise/>
		</catch>
	</try>
</control> 

reboot Step

A step that causes the agent to reboot before proceeding with the rest of the plan. It may only be used on windows based platforms. If encountered on a non-windows platform, an error is raised. It is also an error to reboot an agent that resides on the same host as the master server. The errors discussed here are preflight errors.

reboot Step attributes

retarget Step

A step that changes the execution target for a set of steps. Retarget steps may be nested.

retarget Step attributes

retarget Step Child Elements

retarget Step host Attribute

The "host" attribute is used in the <retarget> step, as well as in various component targeter elements. Its value is the name of a host, which may include substitution variable references. It may also include symbolic names "/" to reference the root physical host of the current execution target, or "..(/..)*" to reference a parent host of the current execution target. The complete syntax supported is specified in the "host redirects" section of Chapter 16.

When a host attribute is specified within a component targeter, it is semantically equivalent to enclosing the containing step within a retarget step.

retarget Step Execution Semantics

When a <retarget> step is encountered, we first evaluate the "host" attribute in the context of the current host of the caller.

If the value of the "host" attribute is different from the name of the current host, then the following steps are taken:

1. We resolve the host name to an actual host. If no such host exists, an error is raised.

2. We verify that the current user has "plan run" permission on the the given host. If not, an error is raised.

3. We verify that the root physical host of the host contains an RA, can be connected to, and is updated and prepared. If not, an error is raised.

4. We obtain a lock on the host, while retaining locks on all previously visited hosts. If the current execution thread already locks the host, this operation is effectively a no-op. If the host is already locked by another execution thread, this operation will block until the host is unlocked. If the request for a lock would result it a deadlock, then an error is raised.

5. The host becomes the new "current" host. The "physical" host is reset based on the new "current" host. The "initial" host does not change.

Once the above has completed, variables of the <varList> element are evaluated in the context of the new current host. Local variables may hide variables of enclosing scopes. Then each of the steps is executed in the context of the new current host.

Finally, if the retarget operation changed the current host, then it is unlocked as appropriate and the current host is reset to the current host of the caller. Note that if the host was locked previously in the current execution thread, then it remains locked until the block that first acquired the lock completes.

An empty <retarget> block is still useful as a mechanism to prevalidate that the current user has appropriate permissions, and that the host is properly prepared.

retarget Step Example

The following is an example of a "restart" control service one might expect to find on a WebLogic managed server. It is implemented by calling a control on the admin server to "stop" the managed server, and then making a call on the local machine to start the server.

The "adminHostName" variable is evaluated on the current host of the caller (which is assumed to be the vhost containing the managed server). The domainName variable is evaluated on the retargeted host (which is assumed to be the vhost containing the admin server). The ADMIN_SERVER component is also resolved on the retargeted host.

<control name="restart">
	<varList>
		<var name="adminHostName" default=":[target:adminHostName]"/>
	</varList>
	<retarget host=":[adminHostName]">
		<varList>
			<var name="domainName" default=":[target:domainName]"/>
		</varList>
		<call blockName="stopServer">
			<argList serverName=":[serverName]"
domainName=":[domainName]"/>
			<installedComponent name="ADMIN_SERVER"/>
		</call>
	</retarget>
	<call blockName="start"/>
</control> 

The sendCustomEvent Step

The <sendCustomEvent> step is used to generate a custom event with a particular message. This step can be used in conjunction with the notification rules module to send an email any time this step is encountered on a particular host.

sendCustomEvent Step attributes

transform Step

The <transform> step is used to perform a text-based transformation on a file contained on the target host. Currently, Perl5 and XSLT based transforms are supported.

transform Step attributes

The input and output attributes can reference the same or distinct files. The value of the input and output attributes is a generalized path that can include zip archives (or zip derivatives such as JAR, etc.) as directory elements, e.g. webapp/myapp.jar/Configurablexml.

transform Element child elements

The <transform> element children specify the transformation to be applied to the input file. The child elements can be any one of the following:

• A single <stylesheet> element defining an XSLT transform to apply on the input source.

• One or more <subst> elements defining Perl5-based substitution patterns to apply sequentially on the input source.

• A single <source> element naming an external file that contains the transform.

• Empty, meaning the content of the input file is copied directly to the output file. This is useful for extracting from or writing to zip archives.

The stylesheet transform Child Element

The <stylesheet> element is a child of the <transform> step, and specifies an XSLT transform to apply on the input source. At most one <stylesheet> element may appear as a child of a particular <transform> element, and they may not be used in conjunction with any other child elements.

The <stylesheet> element is an XSLT version 1.0 element as defined by the namespace “http://www.w3.org/1999/XSL/Transform”. Please see the XSLT specification at “http://www.w3.org/TR/xslt” for details. Note that only the XSLT <stylesheet> element is accepted as a child of the transform element. In particular, neither the XSLT synonym <transform> nor the simplified XSLT transform syntax described in section 2.3 of the XSLT specification are supported as children of the transform element.

The stylesheet element body may include substitution variable references so long as the body is still considered valid XSLT without first undergoing variable substitution.

When a <stylesheet> element is used as a transform, it is assumed that the input file is written in XML.

Example of the stylesheet Element

The following is an example of an XSLT transform.

<transform output="/etc/hosts">
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:template match="/">
<xsl:for-each select="a" >
<xsl:value-of select="b"/>
</xsl:for-each>
</xsl:template>
</xsl:stylesheet>
</transform> 

The subst transform Child Element

The <subst> element is a child of the <transform> step, and specifies a Perl5-based substitution pattern to apply as a transform. Multiple <subst> elements may appear as children of the <transform> elements, but they may not be used in conjunction with any other child elements. When more than one <subst> elements appear, they are applied sequentially.

All occurrences of the pattern in the input file are replaced, including multiple occurrences within a line.

The details of the supported syntax can be found in the Oro documentation (class org.apache.oro.text.regex.Perl5Substitution).

subst Element attributes

An Example of the subst Element

The following transform converts all occurrences of the string 127.0.0.xxx into 10.10.0.xxx within the file /etc/hosts:

<transform output=”/etc/hosts”>
 		<subst match=”127\.0\.0\.(\d+)” replace=”10.10.0.$1” />
</transform>

The source transform Child Element

The <source> element is a child of the <transform> step, and specifies an external file on the target host which contains the transform to be applied to the input file. At most one <source> element may appear as a child of a particular <transform> element, and they may not be used in conjunction with any other child elements.

No config generation is performed on the named source file as part of the <transform> step. However, the named source file may be a config-type resource file deployed as part of a component install, in which case substitution variables contained in the source file would have been substituted when the file was deployed.

source Element attributes

The type Attribute of the source Element

The “type” attribute of the <source> element specifies the type of transformation contained in the named file.

A value of “PERL” indicates a Perl5-based transform similar to that of the <subst> element. In this case, the named file should have format similar to the following:

<?xml version='1.0'?>
<transform>
	<subst match=”127\.0\.0\.(\d+)” replace=”10.10.0.$1” />
</transform> 

Perl-type external transform files may contain any number of <subst> elements.

A value of “XSLT” indicates an XSLT transform. In this case the named file contains a standard XSLT version 1.0 transform as defined by the namespace “http://www.w3.org/1999/XSL/Transform”. Note that unlike inline transforms which only allow the XSLT <stylesheet> element, XSLT transforms contained in external source files may include any valid top-level XSLT transform element including <stylesheet>, <transform>, and simplified XSLT syntax as described in section 2.3 of the XSLT specification.

try Step

The <try> step is used to specify typical error handling and cleanup logic for a block of steps. It has no attributes, and children consist of a <block>, <catch>, and <finally> element.

The <try> step is executed as follows:

• The steps in the <block> element are executed in order until all have completed or a step fails (as per the plan executor"s definition of failure for each step).

• If and only if a <catch> element is defined and the execution of the block element terminated with a step failure other than plan abort or plan timeout, then the steps in the <catch> element are executed in order until all have completed or a step fails.

• If a <finally> element is defined, its steps are executed in order until all have completed or a step fails. This happens regardless of the success of the previous two elements unless either of the two previous elements failed due to plan abort or plan timeout.

• A corollary of the above rules is that if any contained step fails due to plan abort or plan (not step) timeout, then no other contained steps are executed, and execution of the <try> step ends with a failure.

The <catch> element is used to suppress and recover from errors encountered in the <block> element. The <finally> element is used to unconditionally perform some cleanup, regardless of whether typical errors were encountered.

The <try> step either succeeds or fails as follows:

• If the <try> step contains just a <finally> element (but no <catch>), then it fails if the execution of either the <block> or the <finally> element fails.

• If the <try> step contains just a <catch> element (but no <finally>), then it fails if and only if

  • the <catch> element executes and fails, or

  • the <block> element fails due to plan abort or plan timeout

• If the <try> step contains both a <catch> and a <finally> element, then it fails if and only if

  • the <catch> or the <finally> element executes and fails,

  • the <finally> element executes and fails, or

  • the <block> element fails due to plan abort or plan timeout

The critical point of the above is that failures in the <block> element are suppressed by the presence of a <catch> element.

try Step Child Elements

try Step Examples

Suppose you have a component whose installation consists of resource deployment followed by a restart. In this case, the component is really considered installed after its resources are deployed, and a failure during restart should not affect its installed state. Typical errors can be suppressed during the restart as follows:

<installSteps blockName="default">
	<deployResource/>
	<try>
		<block>
			<call blockName="restart"><thisComponent/></call>
		</block>
		<catch/><!-- suppress all typical errors -->  
	</try>
</installSteps> 

Try blocks can also be used to model intelligent auto-upgrades. Suppose you are working with version 1.1 of a component, and you have two different install routines depending on whether version 1.0 was previously installed or not (fresh install versus upgrade install). On can model this in a single install block, as follows:

<installSteps blockName="default">
	<try>
		<block>
			<checkDependency>
				<installedComponent name="foo" version="1.0"/>
			</checkDependency>
			<!-- 1.0 install exists, do upgrade -->
		</block>
		<catch>
			<!-- 1.0 install doesn"t exist, do fresh install -->
		</catch>
	</try>
</installSteps> 

The <finally> block is most often used to cleanup temporary resources. The following example creates a temp file, processes it and then removes it.

<control blockName="default">
	<varList>
		<var name="file" default="/tmp/file.txt"/>
	</varList>
	<execNative outputFile=":[file]">
		<exec cmd="ls"><arg value="-l"/></exec>
	</execNative>
	<try>
		<block>
			<!-- process file in some way -->
		</block>
		<finally>
			<execNative>
				<exec cmd="rm"><arg value=":[file]"/></exec>
			</execNative>
		</finally>
	</try>
</control> 

block Element

The <block> element is a child element of the <try> step that specifies the primary steps executed by the <try> step. It contains one or more steps that are permitted within the scope of the block containing the <try> step.

catch Element

The <catch> element is a child element of the <try> step that specifies the steps to execute in the event that a typical error occurs while executing the steps of the <block> element. It may contain any number of steps that are permitted within the scope of the block containing the <try> step.

The <catch> element serves both to suppress typical errors of the <block> element, and to define typical error recovery actions. Note that it may be empty, in which case it serves only to suppress typical errors.

finally Element

A child element of the <try> step that specifies the steps to execute regardless of whether a typical error occurred earlier within the <try> or <catch> steps; typical errors comprise plan abort or plan timeout, in which case the steps of the <finally> element are skipped altogether. It may contain any number of steps that are permitted within the scope of the block containing the <try> step.

The <finally> element is used primarily to specify steps to clean up and release resources, when the cleanup should be triggered regardless of other typical error conditions.

urlTest Step

The <urlTest> is a step used to verify that the contents of a particular URL match an expected pattern. If the desired pattern is not matched, the step fails and execution stops.

Attributes of the urlTest Step

Composite Plan-only Steps

This section lists steps that may only be used within a composite plan. Note that steps contained within a plan may include references to plan variables and parameters.

execSubplan Step

The <execSubplan> step is a step used to execute another plan. The <execSubplan> step may only appear as the child of the <compositeSteps> element.

execSubplan Step attributes

execSubplan Step child elements

inlineSubplan Step

The <inlineSubplan> step is a step used to execute a sequential series of steps. This step may only appear as the child of the <compositeSteps> element.

An <inlineSubplan> step is similar to an <execSubplan> step except that the <execSubplan> steps names an external plan to execute, whereas the <inlineSubplan> step directly contains the plan to execute as a child element. The primary difference between an inline subplan and a top-level plan is that inline subplans are not saved as distinct named entities, and therefore may not be externally referenced by <execSubplan> steps, whereas top-level plans are distinct named entities and therefore can be referenced from <execSubplan> steps. Inline subplans are useful in cases where the subplan content is concise and directly tied to the context and logic of the calling plan, and does not otherwise make sense as a stand-alone plan. In these cases, having all steps in one self-contained unit can facilitate maintenance and readability for the plan.

Unlike top-level plans, inline subplans may not declare parameters. They implicitly inherit the parameters and variables of all enclosing plans. They may declare additional variables local to the inline subplan, which may hide variables and parameters of the enclosing plans. A subplan variable hides the variable of an enclosing plan if both have the same name. In this case, only the value of the variable declared by the innermost subplan is available for use by its steps.

inlineSubplan Step attributes

inlineSubplan Element child elements

The <inlineSubplan> element consists of an optional <varList> followed by one additional child element, which is either <simpleSteps> or <compositeSteps>, depending on whether the inline subplan is a simple or composite plan.

Simple Plan-only Steps

This section lists steps that may only be used within a simple plan.

Steps contained within a plan can reference any variables declared by that plan, plus any unhidden variables and parameters of all enclosing plans.

install Step

The <installStep> is a step used to install the resources of a component onto the target host. This causes the steps of the named <installSteps> element of the associated component to be executed. This step may only appear as the child of the <simpleSteps> element.

install Step attributes

install Step child elements

uninstall Step

The <uninstallStep> is a step used to uninstall the resources of a component currently installed on the target host. This causes the steps of the named <uninstallSteps> element of the associated component to be executed. This step may only appear as the child of the <simpleSteps> element.

uninstall Step attributes

uninstall Step child elements