Chapter 4 Plan Schema

This chapter describes the XML schema for the N1 Grid Service Provisioning System plans. The chapter covers these topics:

• <executionPlan> Element

• Plan-Only Steps for Composite Plans

• Plan-Only Steps for Simple Plans

Unless indicated, attributes described in this chapter cannot reference component-scoped substitution variables.

For an overview of the XML schema architecture, see Chapter 1, XML Schema Overview.

<executionPlan> Element

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

Plans are either simple or composite. A simple plan is a sequential list of steps that are executed on a particular set of target servers. A simple plan does not contain or call other plans. A composite plan is composed solely of other subplans. A composite plan is not directly targeted because each simple subplan can run on a different set of targets.

The <executionPlan> element has the following child elements, which must appear in the order shown. These child elements might have their own child elements, attributes, or both.

• <paramList> Element

• <varList> Element

• <simpleSteps> Element

• <compositeSteps> Element

Attributes for the <executionPlan> Element

The <executionPlan> element has the following attributes:

• xmlns – A required string that has the following value:

  http://www.sun.com/schema/SPS

• xmlns:xsi – A required string that has the following value:

  http://www.w3.org/ 2001/XMLSchema-instance

• xsi:schemaLocation – An optional string that has the following recommended value:

  http://www.sun.com/schema/SPS plan.xsd

• name – A required attribute of type entityName, which is the name of the execution plan.

• path – An optional attribute of type pathName, which is the absolute path of the execution plan. If this attribute is omitted, the root path (/) is used. The value must name a folder that exists at the time that the plan is saved.

• description – An optional attribute that is a string that describes the execution plan.

• version – A required attribute of type schemaVersion, which is the version of the plan schema that is being used. The only value currently permitted is 5.0.

<paramList> Element

The <paramList> element is an optional child of the <executionPlan> element. This element is used to declare a list of parameters for use by the steps contained in the plan and any components that they reference. If specified, this element can only appear one time.

When this plan is run as a top-level plan, the caller is 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 parameters that are declared by <paramList> that do not have default values.

The <paramList> element has one required child element, <param>, which is a plan parameter declaration. The declaration includes a name, a prompt, and a default value. You can specify one <param> element for each parameter that you want to declare.

<param> Element

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

Attributes for the <param> Element

The <param> element has the following attributes:

• name – A required attribute of type identifier, which is the name of the plan parameter. The name must be unique among all top-level plan parameters and variables.

• prompt – An optional attribute that is a string that is displayed in the user interface when prompting for the value of the parameter. If this attribute is omitted, the value of name is used.

• default – An optional attribute that is a string that is the default value of the parameter. The default value can include references to session variables.

• displayMode – An optional attribute that specifies the display mode of the parameter. The following legal values are permitted:

  • PASSWORD – The user-specified value is hidden, which means that the password is not shown or is replaced by asterisks.

  • BOOLEAN – The parameter is specified by means of a check box.

  • CLEAR – The value is displayed as entered.

  If the value is CLEAR or BOOLEAN, the value can be safely displayed as entered. If the attribute is omitted, the value is CLEAR.

<varList> Element

The <varList> element is an optional child of the <executionPlan> element and the <inlineSubplan> step. For information about the latter element, see <inlineSubplan> Step. The <varList> element 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. If specified, this element can only appear one time.

The <varList> element has one required child element, <var>, which is a plan variable declaration. A declaration includes a name and a value. Specify a <var> element for each variable that you want to declare.

<var> Element

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

Attributes for the <var> Element

This element has the following attributes:

• name – A required attribute of type identifier, which is the name of the local variable. The name must be unique among every variable in the containing <varList>. Variables associated with the top-level <executionPlan> must also be unique among the plan parameters.

• default – A required attribute that is a string that is the default value of the plan variable. This value can include references to other plan variables that have been declared earlier, to session variables, and to plan parameters. If this plan is a simple plan, you can include references to target host attributes and to installed component variables.

<simpleSteps> Element

The <simpleSteps> element is an optional child of the <executionPlan> element and the <inlineSubplan> step. For information about the latter element, see <inlineSubplan> Step. The <simpleSteps> element contains one or more “shared” or “simple plan only” steps. The presence of a <simpleSteps> element indicates that the plan is a simple, not composite, plan. If specified, this element can only appear one time.

When run, the steps within this element are sequentially executed on a set of logical target hosts that are chosen by the caller. These hosts are called the initial target hosts. While this plan executes, its steps can be redirected to execute on a host other than the initial host. The host on which the plan actually executes is known as the current target host. If a step is not redirected, the current host and the initial host are the same. The initial host can be either virtual or physical, as can the current host. The physical host is the root parent host of the current host, which is the same as the current host if the current host is physical.

The <simpleSteps> element children consist of one or more “shared” or “simple plan only” steps. These steps can include references to plan parameters and variables. See Plan-Only Steps for Simple Plans.

Attributes for the <simpleSteps> Element

The <simpleSteps> element has the following attributes:

• executionMode – An optional attribute that indicates whether the contained steps should be executed in a series or in parallel over the target hosts. The legal values are as follows:

  • PARALLEL

  • SERIES

  If this attribute is omitted, the value is PARALLEL.

• limitToHostSet – An optional attribute that specifies the name of the host set that contains the hosts that are considered to be valid targets for this plan.

  If this attribute is omitted, all hosts are considered to be valid targets. Otherwise, the targets that you specify must be a subset of the hosts that are contained in the named host set. If the targets include a host that is not contained in the named host set, the plan issues a runtime error. The plan also issues a runtime error if you specify a name that does not correspond to an existing, supported host set. If the specified host set is defined by a plug-in, pluginName must be prefixed to the host set name, such as pluginName#hostSetName. These plan runtime errors are reported during validation before the preflight starts.

<compositeSteps> Element

The <compositeSteps> element is an optional child of the <executionPlan> element and the <inlineSubplan> step. For information about the latter element, see <inlineSubplan> Step. The <compositeSteps> element contains one or more “composite plan-only” steps. The presence of a <compositeSteps> element indicates that the plan is a composite plan. The <compositeSteps> element does not have any attributes. If specified, this element can only appear one time.

The <compositeSteps> element children consist of one or more “composite plan-only” steps. These steps can include references to plan parameters and variables. See Plan-Only Steps for Composite Plans.

Plan-Only Steps for Composite Plans

This section describes the steps that can only be used within a composite plan. The attributes of some of the steps that are contained within a composite plan can include references to plan variables and parameters.

<execSubplan> Step

The <execSubplan> step executes another plan. The <execSubplan> step can only appear as the child of the <compositeSteps> element.

The <execSubplan> step has an optional child element, <argList>, which is a list of arguments to pass to the called plan. For each parameter in the <paramList> section of the called plan for which no default value is declared, a corresponding argument must be declared by this <argList>. See <argList> Element. If specified, this element can only appear one time.

Attributes for the <execSubplan> Step

The <execSubplan> step has the following attributes:

• planName – A required attribute of type entityName, which is the name of the plan to execute. When this step is run, a corresponding top-level <executionPlan> with this name must be specified. This name cannot reference an inline subplan.

• planPath – An optional attribute of type pathReference, which is the path of the plan to execute. If this attribute is omitted, the path of the containing plan is assumed.

• planVersion – An optional attribute of type Version, which is the version of the plan to execute. If this attribute is omitted, the latest version of the named plan is executed.

<inlineSubplan> Step

The <inlineSubplan> step executes a sequential series of steps. This step can only appear as the child of the <compositeSteps> element.

An <inlineSubplan> step is similar to an <execSubplan> step. However, while the <execSubplan> steps names an external plan to execute, 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 distinctly named entities. Thus, inline subplans cannot be externally referenced by <execSubplan> steps. Top-level plans are distinctly named entities and can be referenced from <execSubplan> steps.

Inline subplans are useful when the content is concise, 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 plan maintenance and readability.

Unlike top-level plans, inline subplans cannot declare parameters. They implicitly inherit the parameters and variables of all enclosing plans. They can declare additional variables that are local to the inline subplan, which can 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 that is declared by the innermost subplan is available for use by its steps.

The <inlineSubplan> step consists of an optional <varList> followed by one additional child element, either <simpleSteps> or <compositeSteps> depending on the type of inline subplan: simple or composite.

The <inlineSubplan> step has the following child elements:

• <varList> – An optional element that is a list of plan variables for use within the inline subplan. If specified, this element can only appear one time.

• <simpleSteps> – An optional element that contains a list of simple steps. Only one <simpleSteps> or <compositeSteps> element can be present. If specified, this element can only appear one time.

• <compositeSteps> – An optional element that contains a list of composite steps. Only one <compositeSteps> or <simpleSteps> element can be present. If specified, this element can only appear one time.

Attributes for the <inlineSubplan> Step

The <inlineSubplan> step has the following attributes:

• planName – A required attribute of type entityName, which is a name used to identify the inline subplan. This name is used primarily for display purposes, and need not be distinct from names of other plans (inline or top-level).

• description – An optional attribute that is a string description of the inline subplan. This attribute is useful for documentation purposes.

Plan-Only Steps for Simple Plans

This section describes steps that can only be used within a simple plan. Steps that are contained within a plan can reference any of the variables that are declared by that plan. The steps can also reference any of the unhidden variables and parameters of all of the enclosing plans.

<install> Step

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

The <install> step has the following child elements:

• <argList> – An optional element that is a list of arguments to pass to the <installSteps> block. If specified, this element can only appear one time. See <argList> Element.

• Repository component targeter – A required element that identifies the component to install. See Repository Component Targeters.

Attributes for the <install> Step

The <install> step has one required attribute of type entityName, blockName, which is the name of the install block to execute within the target component.

<uninstall> Step

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

The <uninstall> step has the following child elements:

• <argList> – An optional element that is a list of arguments to pass to the <uninstallSteps> block. If specified, this element can only appear one time. See <argList> Element.

• Installed component targeter – A required element, which identifies the component to uninstall. See Installed Component Targeters.

Attributes for the <uninstall> Step

The <uninstall> step has one required attribute of type entityName, blockName, which is the name of the uninstall block to execute within the target component.