Requirements, Configuration and Deployment

Requirements, Configuration and Deployment Management Software Selection Considerations

Draft – August 16, 2004

Jane Curry Ben Van De Walle Table of Contents: Table of Contents:...... 2 Background...... 3 Required...... 3 Intended audience...... 5 High-level perspective...... 5 Assumptions/Goals...... 8 Out-of-scope...... 9 Constraints...... 9 Desired general characteristics of an integrated software solution...... 9 Desired Requirements Management software characteristics...... 10 Desired Configuration Management software characteristics...... 11 Desired Deployment Management software characteristics...... 11 Related References and Documents...... 12 To do...... 12 Appendix A - Glossary...... 13 Appendix B - Work product examples...... 15 Appendix C – Software Example...... 21 Appendix D – Example User Screen Data...... 23 Appendix E - A control, management and administration perspective...... 24 Appendix F - Top ten reasons why projects fail...... 25 Appendix G – Extracts from HL7 Tooling Architecture Management and Policy Framework...... 26 Appendix H - Requirements / Questions...... 28 Background

The evolution and continuous morphing of HL7 tools to satisfy an increasing number of tooling requirements has resulted in a more systemic, global and virtual approach towards HL7 tools development. A growing user community, maturing methodologies, new standards, new technologies, the need to exchange information between tools and the availability of additional development resources are driving these requirements.

Beginning with one HL7 tool to a collection of tools, a shift is occurring towards the development of an HL7 Tooling Architecture with supporting principles, design guidelines, and requirements, configuration and deployment management software. This shift has created a need to fill the gaps and to meet rapidly changing needs for (a) management software, (b) the use (evaluation and selection) of available commercial off- the-shelf software (COTS) and (c) the ongoing custom development of tools.

Some of the latest and new standards from Standard Development Organizations (SDO) such as W3C, OASIS, ISO, OMG, IEEE, ANSI and others are being leveraged and/or incorporated in the development of HL7’s standards and specifications. The vendor development tools supporting these new standards take some time to be made commercially available for HL7 and others, creating a situation where some of HL7’s tooling needs are currently being met by customized solutions.

From moving data, to messages, to semantic information over the wire, the standards, technologies and vendor tools to support these maturing methodologies, such as HL7’s, are still undergoing significant and rapid transitions to include web services, Service- Oriented Architecture (SOA), Model-Driven Architecture, UML 2.0 and others.

HL7 tools today cover a spectrum, to include: HL7 Version 2, HL7 Version 3, the HL7 Development Framework (HDF) for specification development, the visual design of models and specifications, the Model Interchange Format (MIF) for enabling the exchange of information between models and tools, the publishing of the ballot specifications for feedback and approval, the storage of HL7 artifacts in a registry, electronic services and others. These assist the HL7 Inc. organization with its 30+ Technical Committees and Special Interest Groups and the HL7 International Affiliates in supporting the rapid collaborative development of health-related global standards.

This document was commissioned by the U.S. Department of Veteran’s Affairs to assist HL7 in developing some guidelines to procuring (product evaluation and selection) and/or developing the tools to support a dynamic, productive and an increasing inter- dependent standards and specifications environment within the HL7 Development Framework and HL7 Tooling Architecture Management and Policy Framework (see References below).

Required “The HL7 Tooling Committee is responsible to the HL7 Board for the openness and effectiveness of the processes used to identify, select, develop and support tools and for the resources implications of selecting and using those tools.” 1

HL7 wants to ensure the continued alignment of and to maximize the opportunity of leveraging (a) interim work products and (b) HL7 managed/sponsored/developed tools. To that end, the following are considerations:

 Development and maintenance of internal tooling to support the standards development process.  Activities to support continued maintenance and support of the HL7 tooling.  Tooling requirements from multiple perspectives.  Challenge to understand the current set of requirements.  Difficulty to contribute to or comment on the importance of identified requirements.  Enhance the process of collecting requirements.  Continue to evolve the process to prioritize requirements.  Mechanism to manage and maintain the tooling requirements.  Enable the contribution from HL7 members toward the development of tools to support those requirements.  Ensure the changes to tooling best address the needs of the general standards- development membership in whole and in part.

Software must support the timely and autonomous decision-making of HL7 Technical Committees and Special Interest Groups in their collaborative and cooperative approach in finding solutions to managing complexity and providing interoperability across multiple health-related organizations.

This document highlights some of the guidelines and/or considerations to assist in the re- use, buy or build decision-making processes for the evaluation and selection of software to support the management of HL7 tooling requirements, configuration, and deployment.

1HL7 Tooling Architecture Management and Policy Framework Intended audience

The intended audience for this document is primarily those involved in tools development. This document can also be beneficial for the end-user of tools and other stakeholders in assisting to understand the management, control and administration of requirements identification for new or additional HL7 tooling features and functions to be developed and deployed.

High-level perspective

Terms are in italics are defined in the Glossary section in Appendix A

A high-level perspective of Requirements, Configuration and Deployment includes: Requirements (primary role/responsibility – Project Manager) Documented customer requirement with example and perceived solution Categorization, triage and prioritization of requirements Identify category: V2, V3, publishing, MIF, visual designing, etc. High-level feasibility analysis to better understand a requirement Project charter (with work product deliverables or change request(s)) Configuration (primary role/responsibility – Prime Committer/Developer) Configuration item or work product requirements Detailed analysis and design Re-use, buy or build decision Configuration item or work product testing – test cases, scripts and data Configuration item documentation – internal and maintenance Deployment (primary role/responsibility – Release Manager) Scheduling Quality assurance (validation and requirements traceability) Integration testing of package Integration documentation (includes FAQ – frequently asked questions) Training (material preparation in scope, delivery out of scope) Installation (selection of most appropriate approach for each tool) Support (contact list in scope, help line out of scope) Education (out of scope)

Project planning and integrated project management applies to all of the above. Examples of artifacts that could be managed by software are included in Appendix B. The following represents a high level diagram of key functions and roles:

Requirements – from user | Assessment – by a Prime Committer/Developer--->-Urgent, high impact bug fix |

| | Change request – prepared by Release Manager-->------>--- | | | | Project plan – prepared by Project Manager | |

| | | Development – assigned to Prime Committer/Developer--<------<------| Deployment – implemented by Release Manager

The following Figure provides additional context: 12 1 2

Developer Tooling Requestor submits requests CVS Committee solicits change request repository access requirements HL7 Requirements, No– suggest Committer notified of request HL7member? Ongoing support membership Configuration and

Triage Release Process Yes 14 request 3 21

Membership CVS Access Developer request advises on granted new CVS node 13 priorities 5

Urgent action Yes No Project No – have required? definition Developer complete approved? project definition 6 Tooling Committer Committee Yes prioritizes request prioritizes request Tooling committee CVS node publishes project 4 Prioritized created definitions requirements published 7 The decision of what will be included in a particular release is made by the 16 15 committer, though it will be Investigate Internal Internal or solution influenced by (Influence) External? recommendations from the alternatives 8 tooling committee.

External

17 Tooling Developer submits Committer Acquire external Committee content to be solution determines advises on release Distribute release committed release targets targets Release targets influence decision to commit No– return to 10 certain content (and where to commit it) developer 9 11 Legend 20 Commit changes Patch release User Community Code ok? Yes to code base Requestor

Committer 18

Developer No– rework Release Beta release Yes required complete? Tooling Committee

HL7Headquarters CVS Manager Integration testing 19 Release Manager

Distributor

Custom&off the shelf Release Final release No– rework required criteria met? Yes Custom tools only

Requirements Management 1. A – TC solicits requirements (1) (2) (3) (4) (5) 2. A – Requestor submits change  Form to be filled out online request  “Date required by” field  “showstopper” field 3. A – Triage change request (by Filter bug “show stoppers” committer) (6) (7) D – Urgent action required? (8) 4. A – Committer prioritizes change (9) request 5. A – Membership advises on priorities (10) 6. A – TC prioritizes change requests (11a) (11b) 7. A – TC publishes requirements (12) 8. A – TC investigates solution (13) alternatives D – Internal or external solution (14) (COTS)? 9. A – TC acquires external solution (15) 10. A – Tooling Committee advises on (16) (17a) (17b) release targets 11. A – Committer determines release (18a) (18b) targets Configuration Management 12. A – Developer requests CVS access (19a) (19b) D – HL7 member? (20) 13. A – CVS access granted (21) 14. A – Developer request new CVS node (22a) (22b) D – Project definition approved by (23) TC? 15. A – TC publishes project definitions (24) 16. A – CVS node created (25) 17. A – Developer submits code to be (26) committed D – Code OK? (27a) (27b) 18. A – Commit changes to code base (28) D – Release complete? (29) Deployment/Release Management 19. A – Integration testing (30) D – Release criteria met? (31a) (31b) 20. A – Distribute release (32) 21. A – Ongoing support (33a) (33b) Note: (numbers) are referenced in Appendix H

Assumptions/Goals

There exist a number of global HL7 user audiences and communities, each with their ongoing needs, challenges and deliverables. These include specification content creators, model and vocabulary facilitators, specification designers, publishers, balloters, early adopters, tools developers and specification implementers. International Affiliates have all the same kinds of audiences but may have additional requirements to localize specifications for their own environments. One complicating factor is that the same people may participate as more than one of the above type of audience or in more than one community.

A few assumptions/goals are included below:

 The process of developing, acquiring and enhancing tools needs to be open, transparent, effective, efficient, relevant, and useful to multiple audiences  Existence of a source control mechanism to manage multiple specificity levels  Evolving HL7 methodology and design considerations reflected/enforced by tools  Tool features/functions to be made available in a timely manner  Increase self-discoverable understanding and submission of tooling requirements  Assist in involving more developers in the tooling effort  If a feature/function does not exist, first research open-source and current COTs markets before committing to HL7 development  Environments are controlled locally and managed across locations  The existence of an updated Intellectual Property policy and registry for artifacts  Platform independence wherever possible for deployed solutions  No specified IDE (integrated development environment)  Needs-based configurable tooling and “packages” created from multiple sources  Tooling enables vendor software interfacing and registration of profiles  Tooling leverages global standards from Standards Development Organizations  Web-based for global usability and non-proprietary tool set  UML 1.4 or higher compliant with ability to extend (current profile – UML 1.4) Challenge of different implementations of a specification concept  Minimize overlap of functionality across configuration items and branches  Transparency of requirements gathering, prioritizing, development and delivery Available multiple views from start to finish  Requirements related information - MUST Captured online, easily collectible (templates), readily exchangeable Incrementally added to, changes identifiable, highlight dependencies  Beta tester test prototypes and software prior to final release of package  Early adopters are individuals/organizations providing/validating requirements.  Implementers refer to (a) developers/specification, (b) user/released “packages”  Consistency and congruency with other HL7 documentation and practices  Use of a common set of terms defined a glossary

Out-of-scope

Tooling covers a broad range of areas and the following exclusions have been identified as out-of-scope relative to the stated “Required” above:  Research and subsequent recommendations on specific software to use  Governance-related considerations  A tool interchange format or the actual development methodology (or processes)  Training delivery, education and help line

Constraints

Constraints include:

 Limited financial funds available for acquiring and maintaining software  Limited developer resources available  Limited volunteers available  Limited time to satisfy an increasing number of requirements  Communication and semantic complexities  Absence of selectable glossary by audience or transitional glossary  Overloaded HL7 terms – e.g. implementation  Unavailable definitions for some HL7 terms – e.g. project

Desired general characteristics of an integrated software solution

To assist in the evaluation of software for the management of requirements, configuration and deployment software, the starting point is the ideal scenario where one piece of software could satisfy all of HL7’s needs. The reality is that more than one software tool may be necessary to achieve the multiple goals.

The following highlight some of the characteristics and/or features of an integrated software solution:

 Can be installed in a source-controlled and reliable environment  Secured and managed access – authentication and authorization  IDE independent  Ability to identifying interdependencies  Ability to exchange relevant information  Flexibility, adaptability and ability to customize including filters  MIF (integration of)  Selectable features and functions  Ability to add incremental features and functions  Ability to use naming conventions  Ease of use by audience – e.g. GUI and a command line  Ability to select contents of a package to be released for consumption  Ability to select deployment based on target environment  Ability to create and customize documentation, help files and training materials  Ability to filter (resources/skill sets and capacity/capability)  Ability to track changes  Ability to provide/restrict access based on roles and/or declared area of interest  Ability to capture requirements and their associated project plans and deliverables  Ability to create “packages” across multiple locations  Ability to capture roles, responsibilities and accountabilities  Ability to create workflows

Desired Requirements Management software characteristics

For Requirements Management the following specific software characteristics have been identified as some of the considerations when evaluating software:

 Receive request via the Internet  Receive with the request any or all of: An example of current situation and desired end state A statement/criteria for describing “measurement of success” A test case and test data Rationale for making a change  Receive request from multiple audiences/users/declared area of interest Addition – new feature, function or code base Correction – bug or patch Modification Enhancement Re-write/re-factor/re-engineer Recommendation to use an off-the-shelf component/software  Confirm receipt of change request  Provide additional information to initial change request or resulting project  Identify the urgent – e.g. show-stopping bug fix  Capture the Risk assessment Impact assessment – positive (e.g. productivity) and undesirable Availability assessment (re-usable component(s), open source, buy, build) Feasibility analysis (time, skills, availability, etc.) Total effort by change request to include anticipated future maintenance  Provide flexible “rack and stack”  Trace to HL7 overall priorities  Triage  Provide choices for: Categorization Priorities Target dates  Provide various views/reports of selectable global need-specific information  Identify the acceptance criteria – by change request, by project, etc. Standards and Technologies Principles Backward and forward compatibility Documentation Training Dates Costs - total effort, both direct and indirect  Assign the change request or project

Desired Configuration Management software characteristics

For Configuration Management the following specific software characteristics have been identified as some of the considerations when evaluating software:

 Provide read and/or write on a branch/node basis  Align a configuration item with the Tooling Architecture  Enforce coding standards  Identify code base and the prime and other committers  Identify developers – by artifact, by projects, by change request, etc.  Identify artifacts – by id, by test cases, by test data, by configuration item  Identify package – by id, by documentation, by training material  Identify performance testing – by artifact, by package, etc.  Identify configuration item by code base/branch  Track – configuration item, artifact, package, project, documentation, etc.  Identify configuration item/code/artifact dependencies and interdependencies  Track verification of base criteria for development Coding standards Documentation standards (internal and external) Unit test standards Architectural alignment Alignment with prioritized requirements  Track verification of package with end-user acceptance criteria  Track patches, bug fix, minor and major releases, packages, etc.

Desired Deployment Management software characteristics

For Deployment Management the following specific software characteristics have been identified as some of the considerations when evaluating software:

 Provide for the tracking of adequate Quality Assurance  Delivery a package to distributed end-user location(s)  Create a readily installable package  Notify user when package is ready  Indicate the availability of a created package  Access created package(s)

Related References and Documents

Project Management Institute Guide to the Project Management Body of Knowledge (PMBOK Guide)

Software Engineering Institute Capability Maturity Model Integration Requirements Management Model Requirements Development Model Configuration Management Model Integrated Project Management Model Product Integration Model

HL7 Development Framework HL7 Tooling Architecture Management and Policy Framework

HL7 Requirements, Configuration and Deployment Management

Architectural Decisions

Clarify the roles, responsibilities and accountabilities Update this document afterwards for increased clarity and consistency

Package – need definition

Appendix A - Glossary

A number of terms are used in this document for which a definition/criteria has been included to assist the reader with the semantics and a context for key concepts and overloaded words. The source of the definitions identified by CMMI is the Software Engineering Institute’s (SEI’s) Capability Maturity Model Integration glossary.

Beta – see prototype Branch – main line of code; environment dependent Bug fixes – applies to code; can include various documentation Change request – MUST be completed prior to ALL changes to code; is a subset of a project charter; can include bug fixes and patches Configuration item – an aggregation of work products that is designated for configuration management and treated as a single entity in the configuration management process (CMMI). Configuration control – an element of configuration management consisting of evaluation, coordination, approval or disapproval, and implementation of changes to configuration items after formal establishment of their configuration identification (CMMI). Configuration management – a discipline applying technical and administrative direction and surveillance to (1) identify and document the functional and physical characteristics of a configuration item, (2) control changes to those characteristics, (3) record and report change processing and implementation status, and (4) verify compliance with specified requirements [IEEE Std 610, 1990]. (CMMI). Derived requirements – requirements that are not explicitly stated in the customer requirements, but are inferred (1) from contextual requirements (e.g. applicable standards, laws, policies, common practices and management decisions) or (2) from requirements needed to specify a product component. Derived requirements can also arise during analysis and design of components of the product or system (CMMI). Documentation – qualifiers include system, environment, code, end-user, help file, training, education, frequently asked questions (FAQ), best practices, etc. Environment – development, prototyping/staging, implemented Functional architecture – the hierarchical arrangement of functions, their internal and external functional interfaces and external physical interfaces, their respective functional and performance requirements, and their design constraints (CMMI). Patch – applies primarily to documentation; not code Package >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>need definition Product – any tangible output or service that is a result of a process and that is intended for delivery to a customer or end-user (CMMI). Product requirements – a refinement of the customer requirements into the developer’s language, making implicit requirements into explicit derived requirements. The developer uses the product requirements to guide the design and building of the product (CMMI). Project charter – applies to a significant (to be defined) amount of a work; MUST have a project plan; required for the creation of a main code branch or major branch rewrite Project manager – the person responsible for planning, directing, controlling, structuring and motivating the project. The project manager is responsible for satisfying the customer (CMMI). Project plan – a plan that provides the basis for performing and controlling the project’s activities, which addresses the commitments to the project’s customer. Project planning includes estimating the attributes of the work products and tasks, determining the resources needed, negotiating commitments, producing a schedule, and identifying and analyzing project risks. Iterating through these activities may be necessary to establish the project plan (CMMI). Prototype – a preliminary type, form or instance of a product or product component that serves as a model for later stages of for the final, complete version of the product. This model (e.g., physical, electronic, digital, analytical) can be used for the following (and other ) purposes: assessing the feasibility of a new or unfamiliar technology assessing or mitigating technical risk validating requirements demonstrating critical features qualifying a product qualifying a process characterizing performance or product features elucidating physical principles (CCMI). Requirement – (1) A condition or capability needed by a user to solve a problem or achieve an objective. (2) A condition or capability that must be met or possessed by a product or product component to satisfy a contract, standard, specification, or other formally imposed documents. (3) A documented representation of a condition or capability as in (1) or (2) [IEEE Std 610.12, 1990]. (CMMI). Requirement analysis – the determination of product-specific performance and functional characteristics based on analyses of customer needs, expectations and constraints; operational concept; projected utilization environments for people, products and processes; measures of effectiveness (CCMI). Requirements elicitation – using systematic techniques, such as prototypes and structured surveys, to proactively identify and document customer needs and end-user needs (CMMI). Requirements management – the management of all requirements received by or generated by the project, including both technical and non-technical requirements as well as those requirements levied on the project by the organization (CMMI). Requirements traceability – the evidence of an association between a requirement and its source requirement, its implementation and its verification (CMMI). Stakeholders – customers, end-users, suppliers, builders, testers and sponsors Work product – any artifact produced by a process. These artifacts can include files, documents, parts of the product, services, processes, specifications and invoices. A key distinction between a work product and a product component is that a work product need not be engineered or be part of the end product (CMMI). Appendix B - Work product examples

The following are examples of the work products that an open-source, COTS or customized solution could manage either in whole or in part. The examples have been classified under the following categories (adapted from the Software Engineering Institute’s Capacity Maturity Model Integration based on CMMI v1.1 models): Stakeholder/Customer/End-user Requirements Management Configuration Management Configuration Requirements Development Integrated Project Management (spanning Requirements, Configuration and Deployment) Project Plan Development

Work product examples that may be placed under Stakeholder/Customer/End-user Requirements Management include: Lists of criteria for distinguishing appropriate requirements providers Criteria for evaluation and acceptance of requirements Lack of criteria results in inadequate verification and/or costly rework Examples Clearly and properly stated (various templates) Complete (criteria identified) Consistent with each other (across various user) Uniquely identified Appropriate to implement Verifiable (testable) Traceable Results of analyses against criteria An agreed-to set of requirements Requirements impact assessments Documented commitments to requirements and requirement changes Requirements status Requirements/change request database Requirements decision database (change history with rationale) Requirements traceability matrix (may be a tool by itself) Bidirectional between requirements and project plans Functions, objects, people, processes, work products, tests and issues Function to function, service and other across interfaces Requirements tracking system (may be a tool by itself) Documentation of inconsistencies including sources, conditions and rationale Corrective actions Training materials for people performing or supporting requirements processes Application domain Requirements definition, analysis, review and management Requirements management tool(s) Negotiation and conflict resolution (issues – requirement definition) Work product examples that may be placed under Configuration Management include:

Plans Process descriptions Design/test data and/or product data files Drawings Customer Requirements Product requirements (see Configuration Requirements Development below) Product-component requirements Product specifications Code and Compilers Product technical publications Product-component specifications

Work product examples that may be placed under Configuration Requirements Development include: Basis for design, i.e. the requirements developed from the following activities: Elicitation, analysis, validation and communication of customer’s needs, expectations and constraints to obtain customer requirements that constitute and understanding of what will satisfy stakeholders Collection and coordination of stakeholder needs Development of the life-cycle requirements of the product Establishment of the customer requirements Establishment of initial product and product-component requirements consistent with customer requirements Results from analyses occurring recursively (product/component requirements) More detailed layers until sufficient information for detailed design Technology demonstrations Working groups Interim project reviews Questionnaires, interviews and operational scenarios obtained from users Walkthroughs and end-user task analysis Prototypes and models Brainstorming Quality Assurance deployment Market surveys Beta testing Extraction/harvesting from documents, standards and/or specifications Use cases and/or business case analysis Details of operational concept Functionality, support, maintenance and disposal

Derived requirements Constraints of various types Technological limitations Cost and cost drivers Time constraints and schedule drivers Risks Consideration of issues implied but not explicitly stated by the customer or end-user Factors introduced by the developer’s unique business considerations, regulations and laws Relationships among requirements Hierarchy of logical entities (functions and object classes) Rationale for decision points Interface requirements Origination and destination Stimulus Data characteristics Functional architecture Results from functional analysis Actions Sequences Input and outputs Activity diagrams and use cases Measures used for monitoring and controlling - reporting Cost, schedule, work, re-work Integration of product components criteria to include: Level of testing for build components Verification of interfaces Derived requirements for the assembly and its external interfaces Allowable substitutions of components Testing environment parameters Limits on cost of testing Quality/cost tradeoffs for integration operations Delivery rate and its variations Lead time from order to delivery Personnel availability Availability of the integration facility/line/environment Table of relationships among the different components Sequencing of any kind Results from meetings to include: Issues and conflicts Non-compliance Resolutions Rationale Packaging standards Naming conventions

Work product examples that may be placed under Integrated Project Management, spanning Requirements, Configuration and Deployment include:

Plan components Plans that affect the Project Plan Quality assurance Risk management strategy Configuration management Documentation Definition of measures and measurement activities Parameters to monitor progress Identified and analysis of product and project risks Incomplete information Availability of COTS components/tools Inadequate resources Scheduling of tasks on the critical path to include: Size and complexity of tasks Integration and test issues Needs of the customer and end users Availability of critical resources Availability of key personnel Performing peer review Required training Objective entry and exit criteria to authorize work Documented revisions to requirements, plan and commitments Data recorded as part of the project Task descriptions Assumptions Estimates Revised estimates Actual Context information Associated information needed to reconstruct derived data Dependencies Commitments Meeting Agendas Schedules Minutes Team member Roles Responsibilities Accountabilities

Work product examples that may be placed under Project Plan Development include:

Project parameters Organizing, staffing, directing, coordinating, reporting, budgeting Project requirements Customer Product Organization Security Others that impact the project Scope with work breakdown structure Identify work products Identify risks and their mitigation tasks Tasks for deliverables and supporting activities Tasks for skill and knowledge acquisition Task for development, quality assurance and deployment Tasks for integration and management of non-developmental items Task dependencies Method of retrieval, reproduction and distribution Identified tasks and work products Technical approach Attributes of the work products to measure (e.g., size, complexity, etc.) Number of functions Function points Source lines of code Number of classes and objects Number of requirements Number of interfaces Number of pages Number of inputs and outputs Number of technical risk items Volume of data Budget and Schedule Committed and expected available resources Time phasing of activities Breakdown of subordinate schedules Dependencies between activities Schedule of activities and milestones for progress measurement Delivery milestones Determining reserve/buffer Documented project assumptions and rationale Models and/or historic data

Methodology used to determine needed skills, labor hours, costs, etc. Judgmental estimates provided by an expert Risks, including the extent to which the effort is unprecedented Constraints Critical competencies and roles needed to perform the work Product and product-component requirements Technical approach Size estimates of work products and anticipated changes Cost of externally acquired work products (open source, COTS and other) Capability of current tools to create tools and/or components Skill level of managers and staff needed to perform the work Knowledge, skill and training needs Facilities needed Travel Level of security for tasks, work products, environment(s), personnel, etc. Service level agreements/commitments Stakeholders List of relevant ones Rationale for stakeholder involvement Roles and responsibilities of relevant stakeholders Relationships between stakeholders Resources needed to ensure stakeholder interaction Schedule for stakeholder interaction

Appendix C – Software Example

The following provides as an example, NOT a recommendation, of the features of a Requirements Software tool named Active! Focus from Xapware taken from their website at www.xapware.com (see Appendix D).

Requirements Management

Full requirements breakdown for the project Individual team member tasks breakdowns of specific requirements Complete traceability of the requirement’s history Hierarchically displayed requirements and, requirements tasks, enable YOU to determine the granularity of requirement definition Requirement linking Support for file attachments Full featured requirements editor Collaborate using threaded discussions (clarify requirements, explore alternatives, etc)

Change Management

Control Change Management from inception through implementation Link Change Requests directly to Requirements, or to other entities Specify change type, priority, and other key factors Assess Change Impact through Change Impact Reports Assign team members the task of submitting an Impact Report to you Change Request Entire team contributions to Change Impact, enabling smarter, less costly changes to ongoing development Collaborate using threaded discussions (discuss priority, feasibility, cascading, impacts, etc)

Defect Management

Track and resolve defects for the project Capture defect information by release and area Identify defect severity for prioritizing work Assign resolution to team members Capture requirement quality information by linking to requirements Support for file attachments Monitor progress through tracking of assignment and status changes Print defect log for review meetings Collaborate using threaded discussions (review severity, discuss resolution options, etc)

Risk Management

Quick assessment of project Risks Identify probability and impact of Risks Link Risks to other entities (Requirements, Change Requests) Fully report risk condition and consequence to managers and decision-makers Entire team contributes to Risk identification Mitigate Risks through Action Plans Assign Action Plans responsibilities Collaborate using threaded discussions (discuss impact, probability, exposure, review alternative mitigation strategies, etc)

Issues Management

Actively manage and resolve key project issues Identify situation and impact Organize issues by type and area Manage issue resolution through detailed response plans Assign overall issue responsibility as well as individual response actions Manage progress through issue logs Support for file attachments Collaborate using threaded discussions (discuss impact, resolution strategies, etc)

Team discussions

Increase team collaboration and communication through project level discussions Identify, communicate, and record the topics important to your success Discussion of important matters with the entire team without meetings Quickly get feedback from across the team Discuss topics at the project level or entity (Requirement, Risk, etc) level

Appendix D – Example User Screen Data

The following provides as an example, NOT a recommendation, of the user screens of a Requirements Software tool named Active! Focus from Xapware taken from their website at www.xapware.com (see Appendix C).

User screens (sheets and fields) include:

Summary Requirements Tasks Change Requests Sheets: Detail; Description; Response Fields for Detail Sheet: Title; Originated By; Change Type; Status; Requirement Number; Assigned To; Originator Priority; Change Response Team Priority; Planned Release; Entered by; Date/Time Entered Risk Impact Fields: Assigned To; Due Date; Status; Effort; Submitted By; Description; Changed By Defects Sheets: Detail; User Description; Technical Fields for Detail Sheet: Title; Submitted By; Severity; Status; Reported in Release; Defect Type; Assigned To; Date Resolved; Resolved in Release; Area; Requirement Number; Effort; Entered by; Date/Time Entered Issues Sheets: Detail, Situation, Resolution Fields for Detail sheet: Date identified; Target Date Resolution; Status; Date Resolved; Assigned To; Impact; Issue Type; Release; Area; Raised By; Entered By; Date/Time Entered Versions Tracking Link

Appendix E - A control, management and administration perspective

Control Access – environment, RCD, branch, node, configuration item Security driven policies – validation/authentication, authorization, termination, etc Modifications (read and commit) and tracking Processes - proposal, justification, evaluation, coordination, approval (or not) Ownership, roles, responsibilities, accountabilities Reporting and management by objective/exception Status Index of work units, approved (or not), progress, target completion, owner History, current and planned Other queries/views – roles, nodes, milestones, dependencies, deliverable Audit Verify functional and physical conformance to specifications or standards and/or other contractual requirements Traceability Highlight and/or fix impacted files, objects, entities, relationships, etc. Version control and management Development, prototype and released Release build generation Requirements Implemented Archived Documentation – semantics Governance, decision-making practices and feedback Best practices Glossary of terms, selectable by audience Feature/function, phase, requirement, template, profile, release, package, etc. Training

Appendix F - Top ten reasons why projects fail

(from Software Engineering Institute’s Capability Maturity Model Integration)

Requirements are unclear, and the goals and objectives are not clearly understood.

Plans are either poorly developed or overly optimistic E.g. plans encompass too much work in too little time

Financial estimates are unrealistic Plans are based on insufficient data

Planning is performed by a separate proposal team

No one knows the major milestone dates

Project estimates are best guesses and are not based on any history or standards

Not enough time is given for proper estimating

No one confirms that there will be personnel available with the required skill sets

People are working on different versions of requirements or configurations

People are constantly shuffled in and out of the project with little regard for schedule

Appendix G – Extracts from HL7 Tooling Architecture Management and Policy Framework

Scope of the Framework is to identify tooling architecture management considerations, such as: the roles that need to be commonly understood, the processes that need to be articulated the policies that need to be agreed, and the indicators that need to be monitored

Components can be understood in terms of their: Business – includes functions performed, sequenced processes, roles and policies Information – including both structured meta-data, and unstructured information such as user and support documentation, training materials, project charters and recorded decisions. Software – including integrated development environments, HL7 customized, commercial or open source applications; either as a whole or as reusable parts. Technology – including hardware, operating systems and networks.

Constraints may include: Limits on the terms of technical platform choices including operating systems, network protocols or end user client environments. Access and Security acceptance of risk Resources available for development, support and maintenance

Expectations may include Accessibility to find and use components when and where needed Protection of HL7 Intellectual Property Reliability of components to perform as expected Response time expectations from an end user perspective Ease of use for user with different levels of experience, including the “seamlessness: of the experience when using multiple components, and Ease of support and evolution

Tools used to automate the process of designing, publishing, approving, disseminating and supporting HL7 specifications are in scope. Collaboration and content management tools used to enable active participation and understanding of HL7’s organization, events, activities and products may also be in scope.

Policy (from principles to rules) enforcement To be determined

The Tolling committee will need transparent processes to identify: The target architecture for tooling environments The components that make up the Tooling Environment The tooling features of components Whether to sponsor the development or buy components How to release useful packages to users Migration strategies to move from the current environment to the target environment.

Expected Roles the Tooling Committee will need to recognize include: Architects who decide what the target environment is and how to get there Committers who take responsibility for specific components Developers who help build components Release Manager who ensure a suite of tools is ready for use Supporters who help users make effective use of tools Requesters who identify new features or improvements to existing features Approvers who agree to changes in priorities, policies, and changes Tool Users who actually use tools and expect to be able to participate in priority decision of what tools to acquire and what features the tools should have.

Stakeholders HL7 Board - Open process that achieves a balance of increasing usefulness within available resources. HL7 Specification -Tools that are easy to use by authors, reliable, well supported and increase their productivity HL7 Balloters - Tools that help balloters understand what specifications they are being asked to approve, what has changed since the last approval process, the impact of those changes and makes it easy to cast their votes to identify suggested improvements and know how their votes were resolved

HL7 Users - Tools that help users find and understand specifications and to produce conformance profiles and realm localizations to support their business needs HL7 Developers - an environment that makes it easy fro them to contribute their time and skills to help HL7 increase the productivity and effectiveness of specification development and deployment. HL7 Educators - tools that are easy to teach and have appropriate support documentation or other educational material available

Indicators of success Productivity measures Number of tools features added, number of defects detected after release to end- users Number of calls to a help line Etc. Appendix H - Requirements / Questions

(1) How? How often? (2) Requestor of correction, modification or enhancement/addition [RCD] Change requests can include bug reports, requests for functional or usability enhancements to existing products, recommendations to consider endorsement of an existing off-the-shelf product as well as requests for completely new tools. [RCD] Includes changes requested by a developer working on the code [RCD] What gets recorded, i.e. what are the fields on the form? What gets tracked and by whom? (3) This triage assumes it is done by someone who “knows” the code in order to be able to make an assessment and the triage. With multiple code bases of different complexities who will do this on a volunteer basis and have the knowledge of all the code required? If a “triage” committer starts coordinating assessments with “code base” committers in order to do triage, will this suffice? What are the expectations and corresponding service levels? What about a request for a feature/functionality/component that does not exist? Why does this go to a “triage” committer before the Tooling Committee? Can the process be driven by the requestor assessing if their need requires a “showstopper” approach to have an assessment done by a “triage” committer? Which committer does this go to and what is the criteria? Excludes where the requestor knows the feature belongs to an existing tool Does the submitter chose an option from a drop down list box where the choices are only projects with committers and the request is automatically routed by the software to the committer once the requestor has submitted a change request online, or something else? If project is not known then routed is it routed to the Tooling Committee? If routed incorrectly to a committer, then re-routed to Tooling Committee? Is there an “overseer or triage” committer who monitors the requests received? Is there a backup? How do we know these to contact them and under what circumstances? Is all user contact through the TC? What happens if a project is approved? Are there multiple communication contact points or is this information available online? Does an enhancement need to go through this first triage? Is this the stage where user availability and their time requirements for new and enhancements is determined? (4) Can the requestor view prior to submission of a change request a list of existing projects with a brief description of each? (5) What are the criteria for submitting a change request? Mandatory fields? (6a) Are the following questions from [RCD] asked and answered here? Before a decision can be made about when (and whether) to action a particular change request, several pieces of information must be known. 1. What sort of change is it? Possibilities include:  Bug fix  New features/functionality for existing code base  Re-engineer existing code base  New code base (i.e. brand new application) 2. How much effort will be required to make the requested change? (6b) Review section 6.2 [RCD] for clarity, consistency and practicality vs. (3) above (7) What impact will the change have on the broad user community? What is the criteria for triage? Who decides? How are these communicated? What are the documented service levels? Where are these located? Who has access to these? What are the criteria where development, documentation and testing be done prior To Tooling Committee endorsement? (8) What is the criteria for urgent? Who decides? How are deltas communicated? (9) What is the criteria for priorities? Who decides? How are deltas communicated? (10) Who and how? By TC? By SIG? By individual? By Affiliate (consolidated)? (11a) The prioritization will be done using criteria developed by the committee, and likely including such considerations as:  Architectural alignment  Productivity impact on HL7 members  Effort [RCD] The example criteria provided here are not intended to be definitive, but rather to give an idea of what sort of considerations are involved and to get the conversation started. In selecting or endorsing criteria, the Tooling Committee will leverage industry best practices. [RCD] This is the key decision area for configuration management. It is where the Tooling Committee can guide architectural alignment and the strategic direction of HL7 tools. Considerations here include:  Does the request align with HL7’s organizational priorities?  Does the request align with HL7's architectural direction? (Pre-requisite is to decide what that direction is . . . )  Does the benefit of the change to users outweigh the costs of complexity, training, etc.?  Do we have the resources to develop and maintain the feature? [RCD] (11b) Other criteria? How are criteria communicated? How are deltas communicated? What assumptions are being made here of the information that will be gathered and provided for by the “triage” committer in writing to the Tooling Committee and what label will be given for this – “assessment information”? Is this an attachment to the change request as an appendix or a different document? (12) TC defines acceptance criteria for new tooling artifacts [RCD] Is a requirement a tooling objective? [RCD] How? Where? Format? Who monitors requirements satisfied? When? (13) HL7 has five potential sources for tooling to meet HL7 requirements:  Off-the-shelf commercial tools  Off-the-shelf open source tools  Off-the-shelf commercial tools with HL7-customization via scripts or plug-ins  Off-the-shelf open source tools with HL7-customization via scripts or plug-ins  Custom build HL7 solutions [RCD] Trade-offs in terms of level of solution fit, customizability, acquisition time, acquisition cost and maintenance cost. [RCD] Criteria for solution? Time and effort limits? (14) Is this where a project manager gets assigned? [RCD] Can a project manager be assigned to an “external” project? [RCD] Does a “sponsored” effort need a project manager? [RCD] Criteria for solution? Time and effort limits? (15) What happens if customization of an external solution is required from a process point of view, given that there may be additional features over and above the requirements or some incrementally cost efficient features which a requestor might identify given an awareness of additional capabilities with a COTS? (16) If a particular development project is being funded, this step will be the part where a Project Manager would begin to get involved, both in helping to define the scope, as well as planning timelines and setting estimates. [RCD] (17a) What information and management/software reports will the Tooling Committee be expected to have to assist them in “advising”? How current does the information and reports need to be? How often will the “advising” take place? (17b) For membership advice on priorities -who and how? By TC? By SIG? By individual? By Affiliate (consolidated)? If “Date required by” field of change requestor different than Membership and Tooling Committee, who reconciles this – TSC, Board or other? (18a) Committer who will be responsible for the use of the product within the HL7 environment, including tracking product version changes and enhancement requests. [RCD] While no code will be committed, the product will still need to be guided through the release process, including beta releases and integration testing leading to a full package release. [RCD] The criteria here are basically a balancing of time, resources and functionality. If two of the three are constrained, the third can be determined. For example, if the functionality to be built and the time of delivery are fixed the necessary number of resources can be determined. If the allowed time is increased or the functionality decreased, the number of resources can be reduced. [RCD] This decision also includes determining what branch a particular change request should be included in. For example, should the change be treated as a bug patch to the current production release, be included in the next short-term release or be incorporated in a long-term major rewrite. The criteria here are:  If the change is a bug fix for which no reasonable workaround exists or for which a workaround exists, but the effort is minor, the change should be made as a bug patch to the current production release  If the change is for a bug fix with a workaround and whose repair will have a significant user impact or if the change is not a bug fix, but can be made using the current application architecture in time for the next short-term release, the change should be included in one of the short-term release branches If the change is not a bug fix and depends on significant architectural design, it should be incorporated in the long-term rewrite branch. [RCD] (18b) User documentation and training a responsibility of the committer here rather than the developer as documented in the roles? For an external solution, are there any circumstances where a “patch” or “beta” release apply? (19a) To help support its release strategy, HL7 will likely move to the use of a source control mechanism, such as CVS. To support the development community in the use of this resource, HL7 must provide for three functions: 1. HL7 must provide a mechanism for developers to request ‘read’ access to the repository so they can work on modifications to existing code. 2. HL7 must provide a mechanism for developers to start a new ‘Node’ within the source-control application when they want to begin a new development effort HL7 must provide a mechanism for developers who have been approved by the existing committers for a node to be added to the list of those who can commit changes for that application. [RCD] Read access – Available to members who sign of a “conditions of use” policy. The conditions of use should address the issue of intellectual property (both use of the artifacts, and incorporation of code). [RCD] In addition to read-access criteria, commit access should be granted to proposers of a new nodes upon acceptance by the tooling committee of a project proposal. It should also be granted to individuals nominated by the current set of committers for a project. [RCD] (19b) Criteria for access determined and documented? (20) Documented benefits of being a member from a tooling perspective (21) What about read only access? (22a) From time to time, a developer will propose a new application be constructed, and there for a new CVS node be created. The criteria for creating a branch are:  A project proposal is provided, including identification of the purpose of the application, the expected benefits of the application, architectural details of the application and any relationships to other applications. The project proposal does not need to be endorsed by the Tooling Committee, but must be complete.  The project proposal is accepted by the Tooling Committee.  The initial set of committers for the project meet the criteria for access as committers. [RCD] (22b) Developer accountable to a committer? What are the developer guidelines and/or criteria for development? (23) Is a project definition a project charter? What is the template? How can Tooling Committee make a decision on internal or external without the information collected for the project definition to be able to estimate the resources required to be able to make a decision? Is acceptance criteria defined in the project definition? If not here, then where? What is the criteria for approval of a project definition? Where is the project manager? Is the project manager responsible for the project definition and reviewing acceptance criteria with the Release Manager? Are test cases and/or data required as a part of completing a project definition? Does the requestor need to provide the test cases and/or test data? If not, who? (24) Where published? Who has access? (25) Who needs to know about this? How are they notified? (26) Content includes the development of documentation, training, test cases and test data [RCD] What is the criteria for submission given that there will be many developers and some level of consistency would be desirable? (27a) At some point, code must be modified. In this document, the concept of ‘code’ is quite broad, and encompasses more than just the programming language component. Specifically, it also includes internal documentation, maintenance documentation, user guides, training presentations, test cases, test scripts and test data. [RCD] (27b) What is the acceptance criteria given that there will be many committers and some level of consistency would be desirable? Is there a backup committer for each project from a continuity of planning perspective? Is this where sponsors are given an update on the progress? If so, by who? If not, then when and by who? Who coordinates activities between the committers responsible for a code base and who determines these activities? (28a) When a developer proposes changes for inclusion in the code base (including code developed by a committer), the committer must make an evaluation about whether the change is appropriate. Each code base may have different criteria, depending on the needs of the project and the desires of the committers for that application. However, the Tooling Committee will likely provide a suggested set of base criteria. Examples of criteria include:  Coding standards  Documentation standards  Unit test standards  Architectural alignment  Alignment with prioritized requirements [RCD] (28b) What is the criteria to be able to commit changes to a code base? What is the definition of a patch and given that there is no Quality assurance by the Release Manager, what is the acceptance criteria for a patch release? What is the process to go from a distributed patch release to a final release or assumed part of a final release? (29) What is the definition of a beta and given that there is no Quality assurance by the Release Manager, what is the acceptance criteria for a beta release? What is the process to go from a distributed beta release to a final release? What is the criteria of a beta and the permitted beta period? (30) Is there only one Release Manager? Is there a backup? If there is more than one, what is the integration testing acceptance criteria given that there will be many to assure a level of consistency? (31a) Note that the creation or modification of code will not always be driven by requests provided through HL7 requirements submission process. Individual developers, vendors and open-source initiatives can and will make changes on their own. HL7 cannot manage the development process, but can manage the decision process by which developed code is released and endorsed within the HL7 community. [RCD] This is the point that HL7 asserts control over what applications and features will be rolled out to their users. Systems which fail to pass tests, integrate poorly with other applications, have insufficient documentation or which do not align with HL7 architectural strategy may be rejected or asked to undergo modification. [RCD] Once code has been committed, there comes a time when it is ready to be released to the user community. This is the point where HL7 (and the Tooling Committee) have full control. While HL7 cannot control what tools are developed, they can control what tools are endorsed and posted through their website. [RCD] (31b) Is this the project definition acceptance criteria? TC criteria? Developer test cases and test data? Release Manager integration and inter-version testing? Alignment with architectural direction? Alignment part of project definition? (32) Who gets notified of the release and how? Central location for all tools or multiple locations? (33a) Despite the statement in the previous section, the reality is that there is no such thing as an end point in tooling development. All released software will require ongoing support. The support may include:  Training and education  Answering users questions on the list server or by other means  Responding to bug reports and enhancement requests (starting the cycle all over again ) [RCD] (33b) What is the scope of support? Who determines the scope? Who provides the support? What is the process for request support? How is this managed? What are the service levels? Are these all volunteers? Possible Organization chart for Roles for Requirements/Configuration/Deployment

Tooling Committee | ------| | | | | | | CVS Code base Triage Project Release Distributor Support Manager committer Manager Manager | ------| | Developer | | Branch committer | Developer