Working with Components

Basic Concepts for Components

A Component is a logical grouping of source information (file(s) and/or directory structures or other components) that define an application and a set of instructions specifying how to handle the source information. A component can be a collection of files and directories, an autonomous archive such as a J2EE Enterprise Archive (EAR) or a COM component, a complete application such as BEA WebLogic, or an operating system-level update such as a patch or service pack. Components can also reference other components.

N1 Service Provisioning System software makes components more manageable by:

• Creating component models that include a carefully defined group of software resources for each component, along with information about how the component should be installed, configured, and analyzed

• Storing components in a repository with version control, so that you can retrieve any previous version of a component

• Making components available to plans, which perform data center operations in a step-by-step manner, taking advantage of the knowledge embedded in each component model

• Enabling components to be compared to one another as well as to installations of software

For an overview of how the N1 Service Provisioning System software manages components and plans, please see The N1 Service Provisioning System Software Object Model.

Modeling Components

The N1 Service Provisioning System software offers great flexibility in modeling components. Depending on the application that you are modeling, you may choose to use any of the following approaches:

• Fully automated modeling

• Extending built-in resource types with XML authoring

• Authoring component models in XML

Fully Automated Modeling

You can check in a component from a gold server or source code control system, have the provisioning software automatically generate a component model, and then use the component model for installation, configuration, and comparison procedures. You can do all this without ever viewing or editing the XML contents of the component model yourself.

We recommend this approach for modeling components in the Windows environment. The provisioning software's built-in resource types can be used to automatically model the most common resources that make up Windows application components. The resource type templates even include built-in procedures for basic operations such as installations, so that you can perform basic operations on common types of resources without even writing a plan.

For a complete list of resource types, see Built-in Components Types.

Extending Built-in Resource Types with XML Authoring

You can begin with an automatically generated component model, as described above, and then customize the component model by editing XML. You can edit a component model's XML by using the Advanced Edit feature on the component's Component > Details page. You can also edit the XML by downloading it to your local system and editing it with an XML-schema-validating editor, such as Turbo XML.

Editing XML enables you to:

• Customize the component with additional variables

• Add calls to extended control services, such as starting and stopping IIS or Windows services

Authoring Component Models in XML

You can write a component model from scratch, using an XML editor and the component schema described in this chapter. Note, though, that you still have to check the component's XML file and the component's resources into the repository in order for the model to be useful.

Overview of Modeling Components

Table 5–1 provides an overview of the steps for modeling components through the HTML user interface and through the CLI. These steps are described in further detail in the Procedures section of this chapter.

Table 5–1 Summary of Steps for Creating Components

HTML User Interface

Command Line Interface

Use the Components page to create a new component. On the Component > Details page, add the reference to components that make up the component. If a components has already been checked in, you add it as an existing component. Otherwise, check in the component as a new resource. Save the component. Saving the component creates a new version of the component with a specific name and version number. This new version of the component is associated with the specific versions of the resources that make it up.

Run the cdb.c.lo command to list the resources that make up the component you want to manage. Using an XML editor such as TurboXML, write the XML definition of the component. Run the cdb.rsrc.ci command to check in the resources that make up the component you want to manage.

Building a Component

A key in creating a useful component is building the component.

Building a component selects specific versions of specific resources for use in the component. It assigns a version number to the component, and ensures that version of the component is always associated with specific versions of the component's resources.

Components consist of the following attributes.

• Path - A user definable location to store components. Between the many built-in components and the ones you create, the number of components can become extremely large making it difficult to locate the one you want. To help locating and using components easier, the provisioning software allows you to organize them in a hierarchical filing system.

• Component - (Name) A user definable text string that identifies the component. In some pages the component (name) will include the associated path such as in the Component Details page. In other pages such as the Components page it does not.

• Type - A user definable name for an object (Component Type) that serves as a service that manages the acquisition and deployment of source objects such as files directories, and configurations. The component type object is just another component that is used to control how to handle source information.

  The N1 Service Provisioning System software comes with a large number of component types that support WebLogic and Windows, UNIX, and some generic models.

• Version - The provisioning software manages version control by assigning a new version number each time a component is modified. This version number has a major number—the number to the left of the decimal point—and a minor number—the number to the right of the decimal point. You have the option of incrementing the minor number or the major number.

• Platform - Specifies which operating system(s) are valid for hosts that are targets for deployment.

• Checked in - The date and time the component was checked in. When a component is checked in it time and date stamps the component.

• Checked in by - The provisioning software provides an audit trail by storing the user ID of the person checking in the component.

• Label - A user definable text string that is used to categorize or group components. Labels can be used as sorting criteria on the component page.

• Category - A user definable object that is used to filter the component list. Categories are created using the categories page accessed from the Administrative page. Categories are then applied to a component from the Components page. Categories can also be created by clicking in the “Apply Categories . . .” link. at the bottom of the components page.

• Description - An optional user defined text string that describes the component object. This attribute is not used by the provisioning software but can provide meaningful information to the user. The better a description is the more useful it is for the user.

• Source - Identifies where the component source information came from including the path. This may be an object to be deployed (simple component), other components consisting (composite component) each consisting of other components or of an object to be deployed.

• Component Variables - User definable containers that store values required to deploy a component resource. For more information on component variables see Component Variables.

• Procedures - A set of instructions that tells what to with the resources and variables.

• Hidden - A flag that marks a component for exclusion from lists. Hidden components are not included in lists unless specifically requests.

If you're using the HTML user interface to define a component, saving the component automatically builds it.

Once a component has been built, it is ready to be deployed at which point you can either:

• install the component on a single set of hosts, using the HTML user interface to directly run the install procedure

• write a plan to install the component on several sets of target hosts

Plans are described in Chapter 6, Plans.

Procedures

Component procedures contain the logic for how to install, uninstall, and control a component. A given component can define any number of procedures. For example, it can define more than one way to install or uninstall a component. An example of a control procedure might be some logic for starting and stopping a server.

The only way to add install, uninstall, and control procedures is through the advanced edit feature in the HTML user interface or through the XML check-in process using the CLI.

When you create a composite component, by default it will inherit a default install procedure and a default uninstall procedure. In general, components often inherit their procedures from their component type. For more details on inheritance see Component Inheritance.

Component Inheritance

Inheritance the characteristic of getting certain attributes from something else. For example, when a component is created, by default, it gets or inherits variables, snapshots, and/or procedures from its component type.

This makes the component model much more powerful and flexible. For example, if you have a thousand components that all extend the IIS Application Component Type and you need to add additional functionality to these components you do not need to add it a thousand times, you only need to add it to the base component type that all these components extend. All one thousand components will inherit the change from the component type.

Access Modes and Modifiers

Access modes and modifiers control how a component attributes can be used and by whom or what. Access modes and modifiers can effect contained components, component variables, procedures, and source data.

There are basically four access modes, public, private, path, and protected. While some access mode apply to all of the attributes others do not. There are two modifiers final and abstract.

---

Note –

Both the concept of inheritance and the access modes and modifiers function like their Java language counterparts. To understand either of these more fully, please refer to the "Plan and Component Language Specification" as well as the any books that explain these concepts for Java.

---

Component Access Modes and Modifiers

The access attribute for a component controls how a component can be deployed. There are two modes, path and public. If access is set to path, then the component can only be referenced by other components in the same path and cannot be directly installed by the user. If access is set to public, then no such restrictions apply. A component can be referenced by any other component regardless of its path and it can be deployed directly by a user. The default access mode for a component is public.

The modifiers, abstract and final, for a component effect deployment options. If the modifier is set to abstract then the component may not be installed. It serves only as a base component for other components to extend. Only abstract components may declare abstract child elements. If the modifier is set to final then the component may not be extended by another component. If the modifier is omitted, then the component may be extended and installed.

Component Variable Access Modes and Modifiers

The access attribute for a component variable controls what can access the variable. There are four access modes, public, private, path, and protected. If the access mode is set to public, then access to the variable is not restricted in any way. If the access mode is set to protected, then access to the variable is restricted to derived components and entities in the same path. If the access mode is set to path, then access to the variable is restricted to entities in the same path. If the access mode is set to private, then access to the variable is restricted to the component containing the variable. The default access mode for a component is public.

The modifiers, abstract and final, for a component variable effect the default values and overrides for a component variable. If the modifier is set to abstract then the variable default attribute is omitted and must be specified by non-abstract derived components. Variables can only be declared abstract if the component is also declared abstract. Abstract variables may not be private. Non-abstract variables must declare a default value. If the modifier is set to final then the variable may not be overridden by derived components. If the modifier is omitted, then derived components can choose whether or not to override the variable.

Component Source Access Modes and Modifiers

The access attribute for a component source is not supported and therefore is implied to be public.

The modifiers, abstract and final, for a component source effect the overrides for the component source location. If the modifier is set to abstract then the source location is omitted and must be specified by non-abstract derived components. The source location for a component can only be declared abstract if the component is also declared abstract. If the source location is declared non-abstract then the source location must be specified. If the modifier is set to final then the source location may not be overridden by derived components. If the modifier is omitted, then derived components can choose whether or not to override the location for the source data.

The Component Schema

The <component> Tag

The <component> tag is the basic tag for defining a component. The <component> names the component, specifies its version number, and includes optional information such as the software vendor that create the application modeled by the component.

Other Component Tags

Within the opening <component> tag and the closing </component> tag in the component's XML file are a number of other tags that define:

• the list of resources that make up the component

• what to install (by default, all the resources) in the component

• what to remove when un-installing the component (by default, all the resources that were installed)

By editing the XML definition of the component, you can add other tags that define:

• configuration variables for the component

• additional procedures that can be called to manage the component

• content that should be included or excluded when the component is analyzed

  <component attributes> component_contents </component>

Table 5–2 describes the XML tags that you can use to modify or extend a component.

Table 5–2 XML Tags for the Component Schema

Schema Tag	Required/Optional	Description
resourceList	Required	A list of the resources that make up the component. If you define the component through the HTML user interface, this list will include each resource that you have added to the component.
varList	Optional	Contains a list of configuration variables for the component. Each variable is assigned a name and, optionally, a default value.
installList	Required.	Includes one or more installSteps tags, each of which includes a grouped block of installation instructions. By default, installList includes a single installSteps block which includes a single command: deployAllResources.
uninstallList	Required	Includes one or more uinstallSteps tags, each of which includes a grouped block of instructions for un-installing (removing) the component. By default, uninstallList includes a single installSteps block which includes a single command: deployAllResources.
controlList	Optional	Defines one or more higher-level procedures, such as start and stop, that can be called to control the component.
snapShotList	Optional	Defines what should be included in a snapshot. Each snapshot can be assigned a name, a list of files to be included, and operations (such as console commands) to be performed before or after the snapshot is taken.
diff	Optional	Defines what should be excluded during snapshots.

For details about each of these tags, please see N1 Service Provisioning System 4.1 Reference Guide.

Component Variables

Components support the use of variables, which are user definable containers that store values used during deployment. The purpose of component variables is to make parts of the component accessible and configurable external to the component. For example, a component may have a variable named installPath that is overridden on a per host basis that defines where to install each component.

The value of the component variable can be a reference to other component variables, including variables that are defined by the component's container. When a nested component is added to a container component, the HTML user interface verifies that the referenced variable is defined within the container. If the variable is not defined within the container component, the HTML user interface automatically adds the referenced variable to the container's variable list. As an example, it is typical for simple components to define their installPath variable to have the value of the container component's installPath variable. In this example, the syntax of the referenced variable is :[container:installPath]. For more information on variable substitution, see Chapter 16, Configuration Generation in N1 Service Provisioning System 4.1 Reference Guide.

Component variables are evaluated and assigned a value at the time the component is deployed. They can be used to define host names, IP addresses, paths, or any other piece of information that is required to implement a deployment.

Variable Sets

A variable set is a list of component variables with alternate values for one or more of the variables overriding their default value. This allows the user to specify different values for component variables based on which variable set is used.

An example of using a variable set is when a component is deployed into different environments such as a production environment and a development environment. If the variables defined in a component allow for the differences between both environments then you can use different variable sets based on where the component will be installed. At plan run time, the user simply chooses which variable set to use based on which environment the component will to be installed.

Variable Overrides

Variable overrides only pertain to composite components and are not used with simple components.

When a component contains other components (children components), a variable set only effects the top-level parent component. All children components use the default values for their variables.

The way to override the defaults values for children components is to set the variable override variables when creating a component that contains children components. Each referenced component will have a set of variable overrides that you can use.

Component Reports

The N1 Service Provisioning System software provides a number of lists that provide useful information about components. It is possible to list all the places where a specific component has been installed, the resources included in a specific component, all the versions of a specific component (the component's version history).

The Components User Interface

The Components Page

The Components page allows you to list components, view component details, create components, and edit components. This page also contains controls for filtering the component list and selecting sort criteria. You can change the sort criteria for the components list by clicking on one of the sort arrows in the header area. Click either the ascending or descending arrow selects that column for sorting and the sort order.

Path

Allows you to specify where to look for or store components. Click on change path to specify a different path.

Show

Allows you to list either components or plans. If you select plans the HTML user interface displays the plans page as though you had click on the plans option in the left-hand navigation menu.

You can also narrow the list by selecting a category from the category pull down menu.

(Check Box)

Marks a component for inclusion when one of the actions are clicked in the Actions for Checked components area. When clicked, Actions for Checked components will either delete, check in, or categorize a component.

Component

A user definable text string that names the component object. By default, the components are listed in alphabetical order by component name. You can sort the components list by the items in this column by clicking on one of the sort arrows in the header area for this column. Click either the ascending or descending arrow selects this column for sorting and the sort order.

Type

A user definable object that is used to control how to handle resources.

For more information on component types see Building a Component.

Version

Displays the revision number of the component. Each time a component is modified, its version number is incremented.

You can sort the components list by the items in this column by clicking on one of the sort arrows in the header area for this column. Click either the ascending or descending arrow selects this column for sorting and the sort order.

Label

A optional user definable text string that can be used to further group components together.

You can sort the components list by the items in this column by clicking on one of the sort arrows in the header area for this column. Click either the ascending or descending arrow selects this column for sorting and the sort order.

Description

An optional user defined text string that describes the component object. This attribute is not used by the provisioning software but can provide meaningful information to the user.

Action

Links that take you to other component related pages to either create a new component, view more information about a specific component, or edit components.

Actions for Checked Component

From this area you can either delete, check in, or apply categories to the checked components.

The Components Details Page

The Component Details page allows you to view Component information and attributes. This page is organized into several general informational and functional sections and also contains buttons that allow you to show where the component is uninstalled, delete the component, go to the Component Edit page, and download XML files.

General Information

This section of the Components Details Page displays general information about the component.

Component

The name of the component. By default, the components are listed in alphabetical order by component name. You can sort the components list by the items in this column by clicking on one of the sort arrows.

Type

The name of the component type.

A user definable object that is used to control how to handle resources.

For more information on component types see Building a Component.

Version

Displays the revision number of the component.

Platform

Displays the operating system(s) that are valid targets for component deployment.

Checked In

Displays the date and time when the component was checked in. That is, created or modified.

Checked In By

Displays the user ID of the one who checked in the component. That provides an audit trail when trying to troubleshoot problems or inconsistencies.

Label

A user definable text string that can be used to control the sorting on the components page.

Category

A user definable object that is used to filter the component list. Categories are created using the categories page accessed from the Administrative page. Categories are then applied to a component from the Components page. Categories can also be created by clicking in the “Apply Categories . . .” link.

Description

An optional user defined text string that describes the component object. This attribute is not used by the provisioning software but can provide meaningful information to the user.

File/Directory Information

This section only appears if the component type is a file and displays general information about the file. The directory section is identical to this one except that it is labeled directory.

File Name

This is a the text string that names the component type. This field is called Directory Name for a directory.

Time Stamp

The date and time the file or directory was created.

Total Size

The total amount of disk storage space required to store the file or directory.

User

This is the owner of the file or directory.

Group

This is the group relationship for this file or directory.

Permissions

This shows the Read, Write, and Execute permissions for the User, Group, and everyone else not in the first two categories. The first three characters represent the R (read), W (write), and X (execute) permissions for the user (owner). The second three characters represent the R (read), W (write), and X (execute) permissions for the group. The third set of three characters represent the permissions for everyone else who is not either the owner or part of the group.

Options

Displays the options that were checked when the component was created.

Referenced Components

This section of the Components Details Page displays components that are referenced by the parent component.

Resource [tree]

A user definable text string that names the component type that is a child of the parent component (resource object).

Type

This identifies the component type for the child component.

Version

Displays the revision number of the resource. Each time a resource definition is modified, its version number is incremented.

Source

Identifies the source path for the child component (resource).

Action

Allows you to either check in (define) a new resource for the component or select resources from a list of resources that already exist.

Component Variables

This section of the Components Details Page displays information about the component variables.

Variable

A user definable variable that can be used to customize deployments.

Value

A user specified value for the component variables.

Component Procedures

This section of the Components Details Page displays information about the component procedures.

Checkbox

Marks a procedure for inclusion in a plan.

Procedure

Lists the procedures defined in this component.

Actions

Generates a plan that incudes the checked

Buttons

This section of the Components Details Page displays information about the component procedures.

Edit

Takes you to the component edit page allowing you to change component information.

Advanced Edit

Takes you to the XML edit page allowing you to change component information and function at the code level.

Delete

Allows you to delete this component. If some other object references this component, the HTML user interface displays a message and will not allow you to delete the component.

Done

Takes you back to the components page.

Download

Allows you to export the component XML code to a text file.

Variable Settings

Allows you to override the default value of any variable.

Where Installed

Displays where the component has been installed.

The Components Edit Page

The Component Edit page allows you to change Component information and attributes. However, not all fields can be changed.

As with the details page, the edit page displays different fields depending on which component type is displayed. For example, the fields for a file are different from that of an IIS application. The following only discuss the fields that yo can change.

Also, as with the details page, the edit page is organized into the same several general informational and functional sections as the component details page. Each section will be discussed individually.

General Information

This is the first section of the Components Edit Page and displays general information about the component.

Component

Displays the name for the component object. This field was set when the component was created and cannot be changed.

Type

Displays the name for the component type. This field was set when the component was created and cannot be changed

Version

Displays the revision number of the component. Each time a component is modified, its version number is incremented. The version number cannot be changed by the user.

Platform

Allows you to change the operating system(s) that are valid targets for component deployment. This is done by selecting an item from the pull down menu.

Checked In

Displays the date and time when the component was checked in. This field is set by the provisioning software and cannot be change by the user.

Checked In By

Displays the user ID of the one who checked in the component. This field is controlled by the provisioning software and cannot be change by the user.

Label

A text field that allows you to enter or change the label.

Category

Displays the component category. This field was set when the component was created and cannot be changed.

Description

A text field that allows you to enter or change the component description.

File/Directory Information

This section only appears if the component type is a file and displays general information about the file. The directory section is identical to this one except that it is labeled directory. None of these fields are changeable.

Resources Included

This section of the Components Edit Page displays information about the component's resources. Some fields can be changed and some cannot.

Resource [tree]

Displays the path to the resource component.

Type

Allows you to change the resource component type by selecting a new type form the pull down menu.

Version

Displays the revision number of the resource. This field is controlled by the provisioning software and cannot be changed by the user.

Source

Identifies the source for the resource.

Action

Allows you to either check in (define) a new resource for the component or select resources from a list of resources that already exist.

(Check Box)

Marks a resource for inclusion when one of the actions are clicked in the Actions for Checked Resources area. When clicked, Actions for Checked Resources will either check in, delete, move up or down and resource, or set the resource version to the most recent one.

Component Variables

This section of the Components Edit Page displays information about the component's variables.

Variable

This field allows the user to create new variables. This column also lists existing variables.

Value

This field allows the user to set the value for new variables. This column also lists the value for all existing variables.

(Check Box)

Marks a component variable for inclusion when one of the actions are clicked in the Actions for Checked Variables area. When clicked, Actions for Checked Variables will either move up, move down, or delete variable.

Buttons

This section of the Components Details Page displays information about the component procedures.

Check in

Checks in the changed version of the component and increments the revision number.

Check in as

Checks in the changed version of the component using a different name and sets the appropriate revision number.

Cancel

Takes you to the components details page without saving any changes.

How To View Components List

Step

1. In the left-hand navigation menu, click components.

   The HTML user interface displays the components page, which lists the components already checked in to the database.

How To View Components Details

Steps

1. In the left-hand navigation menu, click components.

   The HTML user interface displays the components page, which lists the components already checked in to the database.

2. Find the row listing the component you're interested in, and click details.

   The HTML user interface displays a Components Details page for the component.

How To View A Component's Installations

Steps

1. In the left-hand navigation menu, click components.

   The HTML user interface displays the components page, which lists the components already checked in to the database.

2. Find the row listing the component you're interested in, and click where installed.

   The HTML user interface displays a Components Where Installed page for the component.

How To Create Components

Steps

1. In the left-hand navigation menu, click components.

   The HTML user interface displays the components page, which lists the components already checked in to the database.

2. In the top row of the table listing components, enter a name in the component field for the new component, and click create.

   The HTML user interface displays the Components Details Edit page for the new component. This page is slightly different from the component edit page discussed earlier in that the name and type can be changed here.

3. Use the controls on this page to specify the necessary information that will make up the component.

   • Change the name in the component field, if desired. Once the component is checked in you will not be able to change the name.

   • Select the type from the pull down menu. The component edit page fields will change to match those relevant to the component type selected.

   • Select the platform from the pull down menu.

   • Enter a label in the Label field.

   • Enter a description in the Description field.

   • Continue entering the required information. The information required from here will depend on the component type selected.

   • When finished click check in.

   The HTML user interface displays a window reporting that it is checking in the component as version 1.0.

4. Click continue to check in to finish checking in the component.

How To Edit Components

Steps

1. In the left-hand navigation menu, click components.

   The HTML user interface displays the components page, which lists the components already checked in to the database.

2. Find the row listing the component you're interested in, and click details.

   The HTML user interface displays a Components Details page for the component.

3. Click the edit button.

   The HTML user interface displays a Components Details Edit page for the component.

4. Use the controls on the Components Edit page to modify the component's configuration.

5. When you have finished your modifications, click check in.

6. When you have finished listing all the resources for the component, click check in.

   The HTML user interface displays a window reporting that it is checking in the component as version nth which will be the next incremental number.

7. Click continue to check in to finish checking in the component.

Where to Find Information Reported by the N1 Service Provisioning System Software

The following table tells you how to find some of the information reported by provisioning software.

Topic	To Find . . .	Do This . . .
Components	All the places where a specific component has been installed.	Navigate to the Components page. Find the row listing the component you want. Click where installed.
	A list of the resources included in a specific component.	Navigate to the Components page. Find the row listing the component you want. Click details.
	A list of all the versions of a specific component (the component's version history).	Navigate to the Components page. Find the row listing the component you want. Click details. On the Components Details page, click version history.

Summary of Component CLI Commands

The cdb.c commands provide general-purpose controls for managing components.

Table 5–3 CLI Commands for Managing Components

Command	Description
cdb.c.ci	Checks in non-browsable components and component models.
cdb.c.co	Checks out a component.
cdb.c.la	Lists all versions of all components.
cdb.c.lo	Lists detailed information about a component.
cdb.c.lv	Lists all versions of a component.
cdb.c.mod	Modifies a component.
cdb.c.sc	Applies one or more categories to a component.
cdb.c.sh	Shows or hides a component.
cdb.c.del	Deletes a component

The cdb.ic commands retrieve information about components that are already installed on hosts.

Table 5–4 CLI Commands for Managing Installed Components

Command	Description
cdb.ic.lbc	Lists all the hosts on which a component is installed.
cdb.ic.lbh	Lists all the components installed on a specific host.
cdb.ic.vs.lo	Lists details of the specified generated variable settings object.

The cdb.vs commands manage variable settings for components.

Table 5–5 CLI Commands for Managing Variable Settings

Command	Description
cdb.vs.add	Adds a new variable settings object.
cdb.vs.del	Deletes a variable settings object.
cdb.vs.imp	Imports a variable settings object from one component into another.
cdb.vs.la	Lists all the variable settings objects associated with a specific component.
cdb.vs.lo	Lists the details of a specific variable settings object.
cdb.vs.mod	Modifies a variable settings object.