Overview

This is the working area for the definition of the COSMOS Use Cases for SDD.

When complete, the use case will be moved to the COSMOS Use Cases page and incorporated into a milestone.

All use case definitions should follow the guidelines described on the COSMOS Use Cases.

Work Draft of SDD Use Cases

Tooling Use Cases

In the 1/22/2008 weekly SDD call, it was decided that the SDD tooling will run inside the eclipse IDE. Hence, references to "the tool" within the use cases can be roughly interpreted as "the SDD eclipse plugin". The plugin will likely be composed of an editor/status tabs, a set of preferences, a set of context menu items, a project type definition, and one or more additional toolbar menus. The first three use cases are all related to mapping, introspection, etc. of existing things in order to create an SDD. The programming model is:

read the data in
map it to SDD
output SDD

Normal development creates artifacts which reside somewhere. Need to create SDDs for these artifacts based on the build information from existing commercial build environments such as ant, maven, etc. Build information can be metadata somewhere or introspected from the artifact itself.
- Identify if there is build information
- Identify where the information is
- Process build information
- Create SDD
Just introspect the artifact (for example, a .jar file, a .dll, or an .rpm) and create as much of the SDD as possible. This is useful especially in the case of a 3rd party component, where the build information is not available.
- Identify the artifact
- Identify where the information is
- Process build information
- Create SDD
Support for build systems beyond the popular rpn, msi, etc. so that metadata from those systems could be brought in.
- Identify the build system used
- Identify the location of the metadata
- Inspect the metadata
Need a set of rules for assembling the metadata and resolving conflicts (when the same set of data occurs with different values) from two or more SDDs. ~~This is applicable to CL-2 only.~~ No, this is applicable to CL1 as well. This explains how to combine two or more descriptors which describe the same product.
- ~~Two or more SDD elements have the same values~~
- ~~Two or more of the same SDD elements have different values~~
- ~~Two or more lists of the same SDD elements have items that match and items that are unique~~
- The user has two or more SDDs that describe one product deployment. The BTG will combine the information of all the SDDs into one resulting SDD.
- The user wants to change the behavior of the combination logic. He/She will write rules to change the default behavior to provide a more customized version of the BTG.
- The user is given a set of existing rules. The user modifies the BTG configuration file to include these new rules.
As the SDD is being created, validate that what has been created is syntactically correct. Validation may be turned on or off. A plug-in rules engine could also be useful to validate user extensions that are allowed by the validation process. This should work in the same capacity as hotswap compiling within eclipse, except instead of compiling source code the tool will be validating SDD documents.
- ~~Run validation on the fly during GUI editing of the SDD~~
- ~~Run validation on the fly during programmatic editing of the SDD~~
- ~~Manually run validation on an already existing SDD (see use case 8.4).~~
- ~~Turn validation off during a particular operation~~
- The user has additional constraints that need to be validated. He/she will add the rules to the validator before running the validation. The validator will process these new rules and throw the proper error messages when they are encountered.
- The GUI editor will make periodic calls to the validator to determine validity during editing of the SDD. The response returned is able to be programmatically parsed to provide the user with the proper feedback in the GUI tool. (see use case 8.4)
- Programs can call a method in the validator to validate their SDDs. The response returned is able to be programmatically parsed so an application can take the appropriate action.
- The user can run validation on an existing SDD from the command line.
- The validation can be switched off during any operation.
In addition to SDD creation, there is a use case for creating the actual package(Package Generation): SDD and artifact onto "media" that would make it consumable. May need to include SDD runtime and repository code in the packaging. Note: SML-IF might be the appropriate packaging format here
- ~~Create a package that includes the SDD and artifacts listed in the SDD~~
- ~~Create a package that includes the SDD and artifacts that aren't listed in the SDD~~
  - ~~Define the files that aren't listed in the SDD~~
- The user wants to create a package that includes all the files referenced in the SDD. He/She will specify a reference location to find the files listed in the package descriptor. The packaging program will bundle the referenced files and the SDD into one package.
- The user wants to create a package that includes files that are not listed in the SDD. He/She will create a list of the needed files and pass that information to the packaging tool. The tool will bundle the referenced files in the SDD, the additional files in the user created list, and the SDD into one package.
Tool must be able to be configured (where is data source, what rules are created, etc): basic administration of the tool parameters. For example, when moving the tool for use in another department or product. These things will be configurable: artifact inputs, location of SDD outputs, custom rules for creation and validation, SDD content constraints (per IU, CU, LU). The functionality of expandable artifact input sets and validation rules is analogous to the Plugin Development Environment within the eclipse IDE. The process of adding a new artifact type definition can be thought of in the same way as adding an editor in Eclipse.
1. Remove artifact input type
  - The end user clicks the Configure menu and selects "Remove Artifact Type"
  - The runtime configuration tool examines an XML file used to track metadata about artifact types that are known and presents the name and description of each to the user
  - The user chooses the artifacts they no longer are concerned with inspecting for input
  - The entries are removed from the metadata file, and the corresponding inspection components are removed from the tool's resources.
2. Add artifact input type
  - The end user clicks the Configure menu and selects "Add Artifact Type"
  - The runtime configuration tool prompts the user for the location of the inspection component (which has a well-defined structure much like an eclipse plugin). The inspection component may be located from the filesystem, a CVS repository, etc. The workflow should mirror the behviour of the Eclipse IDE when you click on "Import" from the file menu or a context menu.
  - The entries are added to an XML file used to track metadata about artifact types that are known.
3. Change default directory for SDD outputs
  - User clicks the Edit menu and chooses "Preferences".
  - Within the preferences window that is created, a browser is displayed for selecting the default output location. This might be the local filesystem, a CVS repository, etc.
4. Edit creation defaults
  - User clicks the Edit menu and chooses "Preferences".
  - A "Creation Defaults" link creates a window that allows user to see a searchable list of all the predefined properties that go into an SDD (Manufacturer names, contact addresses, etc).
  - User fills in default values for any property they are interested in.
5. Edit validation defaults
  - User clicks the Edit menu and chooses "Preferences".
  - A "Validation Defaults" link creates a window that allows user to see a searchable list of all the predefined acceptable value ranges, etc. than can be used as values within an SDD (for example, the amount of free space required for the installation on the target filesystem).
  - User fills in default values for any property they are interested in.
6. Edit Content Constraints
  - User clicks the Edit menu and chooses "Preferences".
  - A "Content Constraints" link creates a window that allows user to see a searchable list of all the predefined acceptable value ranges, etc. than can be used as values within the unit type (which is specified with a drop down menu whose values are "Installable Unit", "Configuration Unit", and "Localization Unit").
  - User selects or deselects values which should be hidden or disabled when editing SDDs.
Need a GUI front end to create and edit the SDD that has been initially created, or create one from scratch. GUI tool could also need the options to validate, package and deploy. Such a front end would need the same kind of location definitions and constraint administration to allow or disallow parts of the SDD that are "editable".
1. Create a new SDD from scratch
  - From the file menu (or context menu), the end user chooses "New Project->SDD Project:No Existing Package"
  - The end user is prompted to pick a location where the configuration data (e.g. the SDD) will be stored.
  - The tool creates an empty SDD
  - The user provides input values for the SDD. Parts that are marked as uneditable in use case 7.6 are either hidden or disabled.
  - The tool writes out editable parts of the SDD as instructed by the user.
  - When user has completed input of raw data, they choose either "Validate", "Package", or "Deploy" from the Tools menu.
2. Create a new SDD from some other build system (rpm, msi, etc)
  - From the file menu (or context menu), the end user chooses "New Project->SDD Project From Existing Package"
  - The end user is prompted to pick a location where the configuration data (e.g. the SDD) will be stored.
  - The end user is prompted to pick the location of the existing package.
  - If the format of the selected package is one that the SDD cannot process, notify the user and ask if they want to cancel or choose another package.
  - The tool creates an SDD using as much of the information as it can glean from the chosen package.
  - The user provides input values for the SDD. Parts that are marked as uneditable in use case 7.6 are either hidden or disabled.
  - The tool writes out editable parts of the SDD as instructed by the user.
  - When user has completed input of raw data, they choose either "Validate", "Package", or "Deploy" from the Tools menu.
3. Edit an existing SDD
  - End-user launches SDD runtime configuration tool by double clicking the application icon.
  - From the file menu, they choose "Open" to edit an existing SDD.
  - The end user is presented with a file browser and prompted to pick the location of the configuration they want to edit.
  - The user provides input values for the SDD. Parts that are marked as uneditable in use case 7.6 are either hidden or disabled.
  - The tool modifies editable parts of the SDD as instructed by the user.
  - When user has completed input of raw data, they choose either "Validate", "Package", or "Deploy" from the Tools menu.
4. User chooses "Validate" from the tools menu within the context of editing an SDD.
  - The configuration tool performs XML validation against the SDD schema and checks that the parameters entered by the user make sense. The document validates, and the user is notified with a brief notification dialog.
  - The configuration tool performs XML validation against the SDD schema and checks that the parameters entered by the user make sense. The document does not validate, and the user is notified with a brief notification dialog.
5. User chooses "Package" from the tools menu within the context of editing an SDD. Note: We are not creating a package in the sense of an MSI or RPM... We are simply bundling the SDD (which describes those artifacts) with the associated artifacts (which themselves might be MSIs or RPMs).
  - The configuration tool validates the SDD (see use case 8.4)
  - The configuration tool creates a deployable entity by bundling together into a package structure (like a self-extracting zip file) one or more Package Descriptors, the Deployment Descriptor, and the associated artifacts specified by the user.
6. User chooses "Deploy" from the tools menu within the context of editing an SDD.
  - If no package has been created from the SDD, the configuration tool creates one (see use case 8.5).
  - The configuration tool invokes the SDD runtime system with the package created from the SDD.

Tooling Use Cases 'To Do' list

As soon as the lines between CL-1 and CL-2 become more clear, each use case needs to be labeled regarding which conformance level it needs to be in place for. The differences between CL-1 and CL-2 are being delineated in a document by Merri Jensen and should be available soon.
Need more information regarding legal agreements for sharing code between oasis and eclipse -- do we need to get grant clauses in the xml?
Expand use cases which are specific to tool workflows to reflect end user workflows as well.
Look into integrating SDD creation as part of the workflow of other existing eclipse-based concepts (e.g. WAR/EAR creation). This presumably will constitute one or more additional use cases.

Deployment Use Cases

Use Case 1: Install new software
Description: A system administrator/end user installs an application into a development/testing/production environment
Actor(s): System administrator/end user
1. The administrator/end user invokes the install process

- ensure proper credentials**

2. The install process initializes a runtime/management data repository service or API
3. The install process interrogates the environment for system requirements
4. Th administrator/end user completes install interview questions -- this may be wizard based in a windowing environment, a text interface in a non-windowing environment or by response file in a batch/provisioned environment
5. The install process determines artifacts to be installed based on requirement checks and interview questions
6. The install process copies selected artifacts to the system

- communicate status/progress during the install

7. The install process runs post-copy steps/configuration
8. The install process registers the change with the MDR service/API
9. The install process performs any completion actions (reboot, restart, **validation. etc.)
10. The administrator/end user exits the install process
11. The install process performs appropriate system cleanup -- removal of temporary files, etc.

- what about error conditions: e.g., what if an earlier version is on the system? Or some operation fails?

Use Case 2: Uninstall software
Description: A system administrator/end user uninstalls an application from a development/testing/production environment
Actor(s): System administrator/end user
1. The administrator/end user invokes the uninstall process

- ensure proper credentials**

2. The uninstall process initializes a runtime/management data repository service or API
3. The uninstall process interrogates the environment for system requirements
4. Th administrator/end user completes uninstall interview questions -- this may be wizard based in a windowing environment, a text interface in a non-windowing environment or by response file in a batch/provisioned environment
5. The uninstall process determines artifacts to be uninstalled based on requirement checks and interview questions

- for common components, only remove if use count = 0?

6. The uninstall process removes selected artifacts from the system

- communicate status/progress during the uninstall

7. The uninstall process runs post-removal steps/configuration
8. The uninstall process registers the change with the MDR service/API
9. The uninstall process performs any completion actions (reboot, restart, etc.)
10. The administrator/end user exits the uninstall process
11. The uninstall process performs appropriate system cleanup -- removal of temporary files, etc.

- what about error conditions: If some operation fails?

Use Case 3: Configure software
Description: A system administrator/end user configures an application in a development/testing/production environment
Actor(s): System administrator/end user
1. The administrator/end user invokes the configuration process
2. The configuration process initializes a runtime/management data repository service or API
3. The configuration process interrogates the environment for system requirements
4. Th administrator/end user completes configuration interview questions -- this may be wizard based in a windowing environment, a text interface in a non-windowing environment or by response file in a batch/provisioned environment
5. The configuration process determines artifacts to be installed and configured based on requirement checks and interview questions
6. The configuration process configures the selected artifacts
7. The configuration process runs post-configuration steps
8. The configuration process registers the change with the MDR service/API
9. The configuration process performs any completion actions (reboot, restart, etc.)
10. The administrator/end user exits the configuration process
11. The configuration process performs appropriate system cleanup -- removal of temporary files, etc.

Use Case 4: Undo an application update
Description: A system administrator/end user undoes an application update in a development/testing/production environment
Actor(s): System administrator/end user
1. The administrator/end user invokes the undo process

- ensure proper credentials**

2. The undo process initializes a runtime/management data repository service or API
3. The undo process interrogates the environment for system requirements
4. Th administrator/end user completes undo interview questions -- this may be wizard based in a windowing environment, a text interface in a non-windowing environment or by response file in a batch/provisioned environment
5. The undo process determines updates to be undone based on requirement checks and interview questions
6. The undo process undoes the selected update(s)

- communicate status/progress during the undo

7. The undo process runs post-undo steps
8. The undo process registers the change with the MDR service/API
9. The undo process performs any completion actions (reboot, restart, etc.)
10. The administrator/end user exits the undo process
11. The undo process performs appropriate system cleanup -- removal of temporary files, etc.

Use Case 5: Update an application
Description: A system administrator/end user updates an application in a development/testing/production environment
Actor(s): System administrator/end user
1. The administrator/end user invokes the update process

- ensure proper credentials**

2. The update process initializes a runtime/management data repository service or API
3. The update process interrogates the environment for system requirements
4. Th administrator/end user completes update interview questions -- this may be wizard based in a windowing environment, a text interface in a non-windowing environment or by response file in a batch/provisioned environment
5. The update process determines updates to be done based on requirement checks and interview questions
6. The update process deployes the selected update(s)

- communicate status/progress during the update

7. The update process runs post-update steps
8. The update process registers the change with the MDR service/API
9. The update process performs any completion actions (reboot, restart, ** validation, etc.)
10. The administrator/end user exits the update process
11. The update process performs appropriate system cleanup -- removal of temporary files, etc.

- what about error conditions: If some operation fails?

Use Case 6: Register/re-register a previously created MDR
Description: A system administrator implementing a CMDB after intial change was performed wishes to now register and manage that change in the CMDB
Actor(s): System administrator
1. The administrator/end user invokes the registration process
2. The registration process initializes at management data repository service or API
3. The administrator is presented via a wizard MDR(s) or subsets of MDR(s) to be registered
4. The administrator chooses which MDR(s)/subsetted MDR(s) to register
5. The registration process gathers CMDB information from the administrator via a wizard
6. The registration process registers the selected MDR(s)/subsetted MDR(s) with the CMDB
7. The registration process performs any completion actions
8. The administrator exits the registration process
9. The registration process performs appropriate system cleanup -- removal of temporary files, etc.

- What about installing maintenance?

BACKUP Use Case Definitions -- notes from 1/14 discussion

Deployment

Background: There are two categories of applications: Non-Federated and Federated (whether it is exposed to a federated inventory kind of database or not). For Federated Applications: need Web Services port open, take CMDBf graph queries and give replies about the MDR.
Assumptions: No way to know if a federated CMDB is accessible or not. But if it is, need to query it and write to it. Using the federated CMDB is the extra step in the below use cases for the federated case. Which repository to use should be transparent to the install program as much as possible, it should be handled by the runtime based on a configuration setting or documented install parm (e.g., CMDBf = True, CMDBServer=ipaddr).
The install target can be one of: Test/Development, Production, Hardened.
Requirement to run from media is supported by OASIS use cases 14, 15, 192.
What format is required for the repository? SML? Single MDR for the non-federated case that represents all software on the system? Store is not as important as being able to get the right info in and out of it.

Deployment Use cases

Installing a Non-Federated application: include a runtime to interpret the package and perfrom these tasks:
- bootstrap the runtime if not already there
- install the artifacts
- register the existence of the resource in a repository (create/initialize if not already there)
- completion actions (reboot, start/stop service, cleanup, etc.).
Uninstalling a Non-Federated application: perform these tasks
- bootstrap the runtime if not already there
- de-register the resource from the repository
- remove the application
- completion actions (reboot, start/stop service, cleanup, etc.)
Configuring a Non-Federated application: perform these tasks
- bootstrap the runtime if not already there
- configure the artifacts
- register the configuration change in a repository (create/initialize if not already there)
- completion actions (reboot, start/stop service, cleanup, etc.).
Undo a Non-Federated application: perform these tasks
- bootstrap the runtime if not already there
- remove the last level of update to the application
- change the registration as needed. Undo only applies to an update to a resource, not a configuration.
- completion actions (reboot, start/stop service, cleanup, etc.)
Updating a Non-Federated application: perform these tasks
- bootstrap the runtime if not already there
- update the application
- change the registration as needed.
- completion actions (reboot, start/stop service, cleanup, etc.)
Be able to register in federated CMDB without requiring a re-install (for updating an already-installed application into the CMDB).

Deployment use cases discussion from 3/17/08

Use Case 1: Install new software

Description: A system administrator/end user installs an application into a development/testing/production environment