EPLC_Version_Desc_Doc_v1.0.doc

Food and Drug Administration

<PROJECT NAME & RELEASE #>

Enterprise Performance LifeCycle

VERSION DESCRIPTION DOCUMENT

Document Version Number: 1.0 Document Version Date: 9/14/10 Notes to the Author

This document is a template of a Version Description Document for a project. The template includes instructions to the author, boilerplate text, and fields that should be replaced with the values specific to the project.

· Blue italicized text enclosed in square brackets ([text]) provides instructions to the document author, or describes the intent, assumptions and context for content included in this document.

· Blue italicized text enclosed in angle brackets (<text>) indicates a field that should be replaced with information specific to a particular project.

· Text and tables in black are provided as boilerplate examples of wording and formats that may be used or modified as appropriate to a specific project. These are offered only as suggestions to assist in developing project documents; they are not mandatory formats.

When using this template, the following steps are recommended:

1. Replace all text enclosed in angle brackets (e.g., <Project Name>) with the correct field document values. These angle brackets appear in both the body of the document and in headers and footers. To customize fields in Microsoft Word (which display a gray background when selected) select File->Properties->Summary and fill in the appropriate fields within the Summary and Custom tabs.

After clicking OK to close the dialog box, update all fields throughout the document selecting Edit>Select All (or Ctrl-A) and pressing F9. Or you can update each field individually by clicking on it and pressing F9.

These actions must be done separately for any fields contained with the document’s Header and Footer.

2. Modify boilerplate text as appropriate for the specific project.

3. To add any new sections to the document, ensure that the appropriate header and body text styles are maintained. Styles used for the Section Headings are Heading 1, Heading 2 and Heading 3. Style used for boilerplate text is Body Text.

4. To update the Table of Contents, right-click on it and select “Update field” and choose the option - “Update entire table”.

5. Before submission of the first draft of this document, delete this instruction section “Notes to the Author” and all instructions to the author throughout the entire document.

A Version Description Document (VDD) contains the critical contacts (FDA, contractor, or both) that may be called upon during the deployment lifecycle. It identifies the risks, customer impacts, assumptions, and dependencies of the application release (Section 1).

The VDD consists of one or more Application Installation Guides, which provide the detailed instructions to prepare for (Section 2) and implement (Section 3) all aspects of an application release (not limited to executable deployments as configuration changes may be included) including verification of the proper implementation (Section 4), and, if necessary the backout of the release if verification is not successful (Section 5).

The Design Proposal Summary (DPS) document is a key component of pre-implementation of a release. The DPS referenced in Section 2 will provide key physical aspects of the target environment, including:

· Hostnames

· Storage allocations

· CPU/memory allocations This DPS information will be referenced (in many instances) in the installation instructions created in this document.

Detailed installation instructions documented in Section 3 are required for each unique server build, so the contents of this document needs to provide all relevant instructions to complete installation for all target servers for the release (Section 1.6). Database server installation instructions are included in Appendix B.

NOTE: In the event that several servers of identical build are required for a deployment, then only one instance of this installation documentation needs to be provided. The table provided in Section 1.6 should identify the target servers for this guide.

The author(s) of the Version Description Document should ensure that all relevant information is provided to setup, install, and verify each application server. The exact format of the installation instructions are not mandated, to provide the flexibility of including or attaching pre-existing instructions. So a completed installation guide may contain vendor documentation, as well as specific instructions and references to provided configuration files or installation scripts. Providing sufficient detail will be critical to a successful installation. Configuration details need to be explicit, in the following two examples.

The DPS may specify that the application server will have a 100GB SAN LUN attached. The installation instructions need to identify drive letter, file system to be applied, RAID levels, etc. Within this file system, the folder structure may need to be specified for the placement of application modules, data, logs, etc.

For database applications utilizing Oracle, each application connection to the Oracle DB instance needs to be specified. This should include the Oracle service name and the service type (active/spare, active/symmetric, active/asymmetric). An example would be:

Application "x" will connect to Oracle service name "abc3" with a service name type of active/spare”. Application "x" will also use a secondary application server cluster servers "y" and "z" and will connect to Oracle service name "abc1" and "abc2". Oracle service name "abc1" and "abc2" all connect to the same database "abc".

The VDD documents known issues and behaviors associated with the application release (Section 6).

VERSION HISTORY

[Provide information on how the development and distribution of the Version Description Document will be controlled and tracked. Use the table below to provide the version number (FORMAT: Major.Minor.Build Number), the author implementing the version, the date of the version, the name of the person approving the version, the date that particular version was approved, and a brief description of the reason for creating the revised version.]

Table of Contents

4VERSION HISTORY

61.0

INTRODUCTION

61.1 Points of Contact

61.2 Application Servers in Scope

71.3 Software Media Required

91.4 Configuration Changes Included

102.0 Pre-implementation

102.1 Technical Assumptions

102.2 Technical Dependencies

102.3 Technical Risks

112.4 Terminology and Acronyms

112.5 DPS Review

112.6 Pre-work

122.6.1 Preparing for Backout

133.0 Installation Instructions

144.0 Verification Plan

155.0 Backout Plan

155.1 Backout Plan

155.2 Backout Verification Plan

166.0 Known Problems

17Appendix A – Database Instructions

17Oracle Database Specifications

18MS SQL Server Database Specifications

1.0 INTRODUCTION

This section provides a brief overview of the system.

[This subsection of the Version Release Package summarizes the purpose of the document and describes any security or privacy considerations associated with its use.]

1.1 Points of Contact

[This subsection of the Version Release Package presents the names, roles, and contact information for all key personnel involved in the management, design, implementation, and testing of the current software release. The table below should contain at a minimum:

· Project Managers

· IT Tech Leads

· Any SMEs or other resources that will be supporting the development or deployment of this installation guide

· CM contact for distributing the application media to the WODC/CHDC for installation]

1.2 Application Servers in Scope

The following table contains the list of server instances that are the target for this Release Package Installation Guide. This document may be applied to one specific server, or many, if each server receives an identical application build.

Include the Application number and name, which are provided in section 2.1.1 of the DPS, or from the target state diagrams. Provide the hostname from section 3.2.1 of the DPS.

1.3 Software Media Required

This section is primarily for use by CM.

Notes on how to use this section follow:

· The software will be transferred by CM from the Developer CM environment (Location) to the CM Staging Area (\\fdswf012\post-migration_release). Only the CM Team has RW access to the CM Staging Area. The Data Centers have RO access to the CM Staging Area.

· The following guidance on how to properly designate files for release in the Developer CM environment is also available in the CM TSOP. All the TSOPs are stored in this eRoom: http://eroom.fda.gov/eRoom/OC7/FDASystems/0_f7c.

· The success of this process is dependent upon CM having access to the Developer CM Environment. This access must be provided by the application team.

“Location” Defined

<Fully-Qualified path>\<Center>\<Application Acronym>\<Release Number>\<Environment>\”Docs” or “EXEs” or “Scripts” or “DB Objects”]

<Center>\<Application Acronym>\<Release Number>\<Environment>\”Docs” or “EXEs” or “Scripts” or “DB Objects”]

<Center>\<Application Acronym>\<Release Number>\<Environment>\”Docs” or “EXEs” or “Scripts” or “DB Objects”

Furthermore, the designated files must be assigned a PVCS Version Label that follows the naming convention detailed above.]

<Center>\<Application Acronym>\<Release Number>\<Environment>\”Docs” or “EXEs” or “Scripts” or “DB Objects”]

· Environment: TEST, PRE-PROD, PROD, or ANY

· The WODC/CHDC personnel will access the files from the CM Staging Area and deploy them into the target environment.

Table 1.3.1: Application Identification Information

Center

Application Name

Application Acronym

Release Number

Location

(SVN Tag, PVCS Version Label, or Share Drive)

Approved RFC Number

The following tables are intended to provide a categorized, comprehensive list of all the software files necessary to install this application on the Data Center server. They should contain all required application files: executables, any hot fixes, patches, scripts, config files, or documentation.

Table 1.3.2: Inventory of Software Released

Table 1.3.3: Inventory of Database Objects

Table 1.3.4: Scripts Affecting the Current Release Only

Table 1.3.5: Documentation Updated for the Current Release Only

Table 1.3.6: Required Software Licenses A confirmation needs to be provided that each SW module included in the tables above has a valid license. Provide license keys as required for installation.

1.4 Configuration Changes Included

[This subsection of the Version Description Document lists all the configuration changes incorporated into the software release since the previous version. This section does not apply to the initial software version.] The table below outlines the Problem/Change Requests (PCRs) that have been addressed by the current <application name> software release.

Table 1.4.1: Problem/Change (PCR) Requests

PCR Tool Used

(JIRA, Tracker, Other)

(Change Request, Defect, etc.)

[PCR Types may include: defects, enhancements, etc. and are typically documented in JIRA or PVCS Tracker.]

2.0 Pre-implementation

2.1 Technical Assumptions

[This section contains all relevant assumptions regarding the installation of this application, such as availability of support personnel or skill set required. Include any security support requirements, or support from any other organization or vendor.]

2.2 Technical Dependencies

[This section lists all key dependencies that are required for a successful installation. Examples are infrastructure services, such as DNS, WINS, etc, or other applications that must be available prior to beginning this application installation.

This section also contains any required sequencing of applications installations, identifying predecessors and successors, if a particular sequence of installations is required for bringing a complete system online (i.e. App A needs to be operational before App B can begin installation).

Identify any upstream or downstream applications that are directly affected by this application.

Determine whether any of the previous versions of the software will need to be uninstalled before installing the new items.

Ensure that installation scripts generate meaningful status information as they run or that an installation log is created.

The release files staged to the CM Staging Area must be accessible to the Data Center personnel.]

2.3 Technical Risks

[This section identifies any significant technical risks (associated with this particular release only) to the successful completion of this installation. Ensure that any support or application knowledge shortcomings (i.e. the original developer is no longer available) are identified.]

2.4 Terminology and Acronyms

This table defines the client-specific terminology and acronyms used in this document.

2.5 DPS Review

[The Design Proposal Summary (DPS) is provided to the Data Center to communicate the physical design of the target servers for the application migration. This document will include:

· Hostnames

· Storage allocations

· Virtual CPU & Memory allocations

· DNS requirements

· Load balancer configuration

The DPS must be reviewed for completeness, to ensure that the physical infrastructure is at a ready state for the application install to begin.

Very Important – The DPS reflects the infrastructure configuration that will be put in place to enable the execution of this installation guide. Any missing information needs to be communicated back to the WODC/CHDC, otherwise this installation will fail. An example would be storage allocations, specified in Section 4.3 of the DPS. If a required drive is not identified in the DPS, it will not be available on the server at installation time.]

2.6 Pre-work

[This section contains all pre-work items that must be completed before following the installation instructions, such as creating backup copies of critical files, locating IDs/passwords, converting data, or verifying any server settings.]

2.6.1 Preparing for Backout

[This section provides details on what will need to be done should a backout be necessary.]

3.0 Installation Instructions

[This section is primarily for Data Center use.

This section provides the detailed instructions which would allow a systems administrator to use the media identified in Section 1.2 - Software Media Required and successfully install the application on the target server.

Note: The installation instructions should not include the following:

· Windows operating system

· Unix operating system

· Middleware products: IIS, Oracle AS, Apache Tomcat, Oracle DB, SQL Server, Coldfusion, Business Objects, Documentum

A standard WODC/CHDC installation procedure will be followed for these products.

Note: Additional tables may be added below, as needed, to address multiple target environments.] Stage/Phase (Target Environment):

Duration:

4.0 Verification Plan

[This section describes the criteria and verification tests that the WODC/CHDC Systems Administrator should perform after completing the installation, to confirm successful completion. This is usually a short list of simple checks, such as communication to target devices, status on consoles, interface of the application through a web browser, etc. These checks will be conducted prior to turning the application over for full system testing.

Note: This section should include basic system verification steps, not a full blown system test plan. The system test plan is maintained independently from this document. Upon successful completion of the Verification Plan, the system will be turned over for formal and complete system testing.] Target Environment:

5.0 Backout Plan

5.1 Backout Plan

[This section describes any steps necessary to backout an unsuccessful installation. This does not need to include steps to uninstall the software on the target server, but rather to reset any links, DNS entries, or other external dependencies that may have been established assuming the new server coming online. This section should also include any dependant applications and/or components that may need to be reset if this installation fails.]

5.2 Backout Verification Plan

[This section describes any checks necessary to confirm successful execution of the backout plan.] Environment:

Note: If the system fails in PROD, then any special steps to be taken should be detailed in a “Backout From PROD SOP” to be added as an Appendix to this document.

6.0 Known Problems

[This section contains all known problems with the application installation or ongoing operational issues, such as known bugs or unusual behavior.] Appendix A – Database Instructions Database Application Release Instructions

Oracle Database Specifications

[This section contains information about how the release will affect Oracle database instances in the CHDC. This section only needs to be updated if there are applicable database changes in this release.] Oracle Information

What are the names of the Oracle databases being affected by this release?

Are any new tablespaces to be created? If so, what is the total size of the tablespaces to be added?

Are any tablespaces to be dropped?

What is the revised projected growth per year of the database in GB?

List any new Oracle database components to be installed.

Type of database: Hybrid, Transactional, or Warehouse

List any new, dropped, or modified database userids in this release.

Does the release introduce any database replication scheme? If yes, what kind?

Are there any changes in the way security is enforced in the databases, i.e. just roles, or roles, label security, Virtual Private Dates (VPD), etc.?

Are there any changes to the job schedules as a part of this release?

Will there be a change to the peak times? If so, how?

List any new applications that connect to the databases in the Application Connection Table below

If there are new applications connecting:

1) Are these applications certified for 10g RAC?

2) Do these applications use bind variables?

3) Do these applications use literal values?

Backup Strategy

List any required changes to the backup strategy and backup retention for the databases?

Oracle Database Information – Application Connections

[For database applications utilizing Oracle, each application connection to the Oracle DB instance needs to be specified. This should include the Oracle service name and the service type (active/spare, active/symmetric, active/asymmetric). An example would be:

Application "x" will connect to Oracle service name "abc3" with a service name type of active/spare”. Application "x" will also use a secondary application server cluster servers "y" and "z" and will connect to Oracle service name "abc1" and "abc2". Oracle service name "abc1" and "abc2" all connect to the same database "abc".

Identify the applications that will utilize this database instance.] Application Connection Table

MS SQL Server Database Specifications

[This section contains information about how the release will affect SQL Server database instances in the CHDC. This section only needs to be updated if there are applicable database changes in this release.] SQL Server Configuration

Provide the database names and estimated space required in GB for this release

Specify SQL Components to install as part of this release:

Example: Analysis Services, Notification servers

Note: SQL Engine, SQL Agent, & Integration Services will be installed by default, while Reporting Services will NOT be installed on the same SQL server.

Backup Strategy

List any required changes to the backup strategy and backup retention for the databases?

PAGE