Component Guidelines.doc
Upcoming SlideShare
Loading in...5
×
 

Component Guidelines.doc

on

  • 523 views

 

Statistics

Views

Total Views
523
Views on SlideShare
523
Embed Views
0

Actions

Likes
0
Downloads
14
Comments
0

0 Embeds 0

No embeds

Accessibility

Categories

Upload Details

Uploaded via as Microsoft Word

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

Component Guidelines.doc Component Guidelines.doc Document Transcript

  • Washington State Enterprise Architecture Program Component Guidelines Version 1.0 October 19, 2005 1
  • Table of Contents Introduction/Purpose.......................................................................................................................3 Components and Artifacts...............................................................................................................3 Levels of Component Detail............................................................................................................5 Templates.......................................................................................................................................5 General Guidelines.........................................................................................................................5 Business Architecture Component Guidelines................................................................................6 Guidelines for Grouping Mechanism(s)......................................................................................6 Guidelines for Components........................................................................................................7 Information Architecture Component Guidelines.............................................................................8 Guidelines for Grouping Mechanism(s)......................................................................................8 Guidelines for Components........................................................................................................8 Technology Architecture Component Guidelines..........................................................................10 Guidelines for Grouping Mechanism(s)....................................................................................11 Guidelines for Components......................................................................................................12 Guidelines for Levels of Detail..................................................................................................12 Solution Architecture Component Guidelines................................................................................13 Guidelines for Components......................................................................................................13 Document History: Date Editor Change Synopsis September 21, 2005 Scott Came Initial draft October 19, 2005 Scott Came Added technology architecture guidelines regarding levels of detail (TA-13) 2
  • Introduction/Purpose The purpose of this document is to establish guidelines for the structure and style of Tier One components in the Washington State Enterprise Architecture. It supplements the core advice in the NASCIO Enterprise Architecture Framework regarding the types of components and their purpose in the architecture. It also provides templates for component metadata, also drawn from the NASCIO framework. These guidelines are an important mechanism in achieving the Enterprise Architecture Committee’s goal of evolving a single, cohesive Tier One enterprise architecture. This goal was affirmed by a Committee motion passed on September 7, 2005. Without guidelines regarding the types of components supported by the architecture and the supported style and structure of those components, the goal of a single cohesive architecture would be very difficult to achieve. These guidelines are intended to be read in concert with the Enterprise Architecture Program’s Program Management Plan. In particular, the links with this plan are: • The guidelines in this document are intended to support and govern the contributions of documenter teams to the architecture • The guidelines in this document are intended to guide the staff of the Program in leading and coordinating the work of documenter teams • The purpose of these guidelines is to improve opportunities for reuse and sharing of components across enterprise initiatives and across the work of initiative-oriented documenter teams; the guidelines are intended to reduce the costs of creating a unified cohesive architecture • The guidelines, along with the NASCIO framework, set clear expectations as to what kinds of information are in the architecture, and how the information is organized; consequently, the guidelines are intended to guide the evolution of an architecture that is more accessible to a wider range of stakeholders • The guidelines are intended to smooth the process of reviewing and approving components, by ensuring consistency in the structure, format, and style of components presented to the Enterprise Architecture Committee, the Information Services Board, and other stakeholder groups for review (Note that the role of Documenter Teams, referenced in the bullets above, is defined in the NASCIO framework. The relationship of Documenter Teams to the Enterprise Architecture Program is detailed in the Program Management Plan.) Since the Enterprise Architecture Program’s Communications Plan defines how the Program will communicate the architecture to identified stakeholder groups, the guidelines in this document further specify the requirements identified in the Communications Plan. In particular, the tools identified in the Communications Plan will need to support the presentation of the component information defined here. Components and Artifacts The Enterprise Architecture consists of components, which are organized by grouping them into the four architectures identified by the NASCIO framework. The framework identifies the following components within the four architectures: 3
  • Architecture Grouping Component Description Mechanism Business • Domains (major Various (see functional or guidelines below) topical subset) • Perspectives (segmenting based on views) Information • Subject areas Process Components Definitions of shared information processes Information Meta- Definitions of shared Components information structures Technology • Domains (major Product Components Specific products, functional or product families, or topical subset) protocols on which the • Technology areas enterprise (implementation- standardizes oriented subsets of domains) Compliance Policies, standards, or Components guidelines that guide/ govern decision making about approach or technique Solution None Application Solution Description of an Sets implementation of an enterprise system or application (organized into views) Infrastructure Solution Description of an Sets information technology infrastructure asset or family of assets (organized into views) In addition to these seven component types, each architecture can have its own set of principles, which are textual in nature and are intended to guide decision-making about components in each architecture. A component is by nature an abstract concept. One of the goals of enterprise architecture is to render abstract components concrete by describing them from different vantage points. This is accomplished through the development of artifacts. An artifact is a physical document or model of some kind that describes important features of a component from a particular perspective. Each component will have an artifact that contains metadata about the component, which supports management of the component. Component metadata includes attributes such as: name, current level of detail (see the next section), ownership/contact information, brief description, edit history, artifacts that describe the component, keywords (to support searching for 4
  • the component), and so on. The other artifacts associated with each component appear in the guidelines sections for each architecture below. Levels of Component Detail This plan recognizes the operational strategy of the Enterprise Architecture Program to evolve the enterprise architecture by iteration through increasing levels of detail. This strategy and the detail levels are described in the Program Management Plan. In presenting component guidelines below, this plan will be clear about the precision of documentation and kinds of artifacts expected at each level of detail. Templates The guidelines presented in this document include templates for artifacts delivered as textual documents. The initial artifact templates consist of Microsoft Word documents and are modified versions of the templates in the NASCIO framework. Because the NASCIO templates contain mostly component metadata, it is likely that the information contained in the Word templates will eventually be migrated into the Enterprise Architecture Program’s artifact repository tool/solution. General Guidelines Textual artifacts must be readable and easy to understand by their intended audience. They also must be accessible to authors and readers using commonly-available software; accessibility in this sense includes being able to read and print the artifacts. Guideline G-1: In the Washington State Enterprise Architecture, all textual artifacts should comply with the terms of Executive Order 05-03 (“Plain Talk”) and other practices to maximize the ability of stakeholders to read and understand them easily. Guideline G-2: In the Washington State Enterprise Architecture, all textual artifacts should be authored in Microsoft Word. If a template exists for a textual artifact, the artifact should adhere to the template. Graphical artifacts such as visual models must also be readable and easy to understand by their intended audience. They must also be accessible to authors and readers using a limited range of commonly-available modeling tools; accessibility in this sense includes being able to read and print the artifacts. To the extent industry or open standard modeling notations or conventions exist for an artifact, the artifact must employ such notations or conventions. If the intent of a visual model fits the purpose of a standard diagram type in the Uniform Modeling Language (UML) 2.0 specification, then absent a justification to the contrary, the model should utilize the UML diagram type. It is expected that non-UML or non-standard modeling notations will be required in many cases. For example, network modeling utilizes notations and conventions developed in that domain. It is the responsibility of each Documenter Team to establish the modeling notations it will use in visual artifacts. The Enterprise Architecture Program will select a standard modeling tool to be used in creating graphical models. At the time of the tool selection, the Program will add a corresponding guideline to this document. Guideline G-3: Graphical model artifacts should use the Uniform Modeling Language (UML) 2.0 specification notation to the extent that a model’s intent fits one of the UML diagram types. 5
  • Guideline G-4: Documenter Teams should establish graphical modeling notations to be used in their artifacts, and should consult with the Enterprise Architecture Program in making notation choices. Guideline G-5: All graphical model artifacts in the enterprise architecture should be created with the same graphical modeling tool. The Enterprise Architecture Program will select this tool in consultation with stakeholders and existing Documenter Teams. After the tool selection, this guideline will be updated appropriately. Note that this document does not specify precise guidelines regarding the required number of components for an enterprise initiative, nor does it specify the required distribution of those components across the available types. It is up to the discretion of each Documenter Team, in consultation with the Enterprise Architecture Program, to determine the appropriate number and types of components. Guideline G-6: Each Documenter Team is responsible for maintaining a clear vision as to the number and types of components that it will add to the enterprise architecture through pursuit of its initiative. The initial statement as to this vision should be documented in the team’s charter. In order to achieve the Enterprise Architecture Committee’s vision of a single, cohesive architecture for the enterprise, it is important that all Documenter Teams evolve the same types of components and utilize the same terminology in documenting them. The Enterprise Architecture Program and Committee have standardized on the NASCIO framework component types and terminology; the expectation is that the framework will prove adequate in identifying and documenting all of the components in the enterprise architecture. Deviations from the framework component types and terminology should be conscious and deliberate. Guideline G-7: The Washington State Enterprise Architecture will contain only the component types supported by the NASCIO Enterprise Architecture Framework. If a Documenter Team wishes to evolve a component of some other type, the team should consult with and obtain the approval of the Enterprise Architecture Program Director and Enterprise Architecture Committee. In order to achieve the Enterprise Architecture Committee’s vision of a single, cohesive architecture for the enterprise, it is important that all Documenter Teams store component artifacts in a single, central architecture repository. Guideline G-8: All component artifacts in the Washington State Enterprise Architecture will be stored in a central architecture repository that is maintained by the Enterprise Architecture Program. Business Architecture Component Guidelines This section contains guidelines for components in the business architecture. Guidelines for Grouping Mechanism(s) The NASCIO framework organizes Business Architecture components into domains, and into perspectives within domains. Each component must be associated with at least one domain. The documentation for a domain must capture key domain metadata, as required in the Business Domain template. 6
  • Guideline BA-1: In the Washington State Enterprise Architecture, each component in the Business Architecture should be associated with at least one domain. This domain should be indicated in the component’s metadata, in the manner prescribed in Guideline BA-5 below. Guideline BA-2: In the Washington State Enterprise Architecture, each Business Architecture domain must be documented in an instance of the Business Domain template, included in the appendix to this document. As the enterprise architecture incorporates new business components into the Business Architecture, it will be important to ensure that the documentation for each domain remains consistent with the nature of the business components included within that domain. Guideline BA-3: As new business components are added to the Business Architecture, the Enterprise Architecture Program and appropriate Documenter Teams should review the documentation for associated business domains to ensure that the documentation remains consistent with the included components. The NASCIO framework allows Business Architecture components to be associated with a perspective. The purpose of a perspective is to provide information from a certain point of view or vantage point. Generally, perspectives address the six basic interrogatives: Who, What, When, Where, How, and Why. In this way, a perspective is a view of the business from the point of view of one of these interrogatives. Each Business Architecture component should address one of the six basic perspectives. A Business Architecture domain should contain components that address all six perspectives; if a domain should properly exclude a perspective, the Documenter Team must provide justification for that exclusion. Note that the NASCIO EA Toolkit, version 3.0, Business Architecture, pp. 37-38 contains useful guidance on how to address the six basic interrogatives. Guideline BA-4: Each Business Architecture domain should address the six basic perspectives, in terms of the following interrogatives: Who, What, When, Where, How, and Why. The domain should address these either by including a component, or by providing justification for why the perspective is not addressed. See also Guideline BA-6 below. Guidelines for Components The documentation for each Business Architecture component must capture key metadata, as required in the Business Architecture component template. Guideline BA-5: In the Washington State Enterprise Architecture, each Business Architecture component must be documented in an instance of the Business Architecture Component template, included in the appendix to this document. Guideline BA-6: Each Business Architecture component should address one of the six basic perspectives, and should document in the component’s metadata which perspective is addressed. The specific artifacts used to document each Business Architecture component are left to the discretion of each Documenter Team. As the Enterprise Architecture Program gains more experience with Business Architecture components, it may in the future modify these guidelines to contain more specific guidance. 7
  • Guideline BA-7: Documenter Teams are free to choose artifact types and formats that best describe each Business Architecture component. Information Architecture Component Guidelines This section contains guidelines for components in the information architecture. Guidelines for Grouping Mechanism(s) The NASCIO framework organizes Information Architecture components into subject areas. Each component in the Information Architecture must be associated with at least one subject area. The documentation for a subject area must capture key metadata about that subject area, as required in the Information Subject Area template. Guideline IA-1: In the Washington State Enterprise Architecture, each component in the Information Architecture should be associated with at least one subject area. This subject area should be indicated in the component’s metadata, in the manner prescribed in Guideline IA-4 below. Guideline IA-2: In the Washington State Enterprise Architecture, each Information Architecture subject area must be documented in an instance of the Information Subject Area template, included in the appendix to this document. As the enterprise architecture incorporates new components into the Information Architecture, it will be important to ensure that the documentation for each subject area remains consistent with the nature of the components included within that subject area. Guideline IA-3: As new components are added to the Information Architecture, the Enterprise Architecture Program and appropriate Documenter Teams should review the documentation for associated subject areas to ensure that the documentation remains consistent with the included components. Guidelines for Components The documentation for each Information Architecture component must capture key metadata, as required in the templates for Information Architecture components (Process Components and Information Meta-Components). Guideline IA-4: In the Washington State Enterprise Architecture, each Process and Information Meta-Component in the Information Architecture must be documented in an instance of the appropriate component template. Templates for Process and Information Meta-Components are included in the appendix to this document. Documenting Process Components and Information Meta-Components beyond the contextual level of detail is well-suited to Uniform Modeling Language (UML) notation. Guideline IA-5: In accordance with Guideline G-3, documentation of Process Components and Information Meta-Components beyond the contextual level of detail should utilize Uniform Modeling Language (UML) 2.0 notation, absent a valid justification for doing otherwise. The guidelines for Process Components and Information Meta-Components depend upon the level of detail of the components. 8
  • Guideline IA-6: In the Washington State Enterprise Architecture, Process Components within the Information Architecture should be documented in specific artifacts, as outlined in the following table. Level of Detail Artifact Guidelines Contextual Microsoft Word Document • Include all component instance of Process metadata in template Component template • Name the component • Provide short description of component • Note potential links with other components Conceptual UML Static Structure Diagram • Depict component on diagram • Identify (name and brief description only) key component operations (behavior) • Depict dependant components on diagram; indicate relationship with dependency notation UML Sequence Diagrams • Depict sequence of (one per process flow) interactions/collaborations between components • Principal process flows only UML State Diagrams • Use only as needed • Use to depict cross-flow state changes in the overall workflow Logical UML Static Structure Diagram • Add full signatures to operations (signatures will refer to Information Meta- Components) • Include exceptional/abnormal operation exits UML Sequence Diagrams • All Tier One process flows (one per process flow) UML State Diagrams • Use only as needed • Use to depict cross-flow state changes in the overall workflow 9
  • Guideline IA-7: In the Washington State Enterprise Architecture, Information Meta- Components within the Information Architecture should be documented in specific artifacts, as outlined in the following table. Level of Detail Artifact Guidelines Contextual Microsoft Word Document • Include all component instance of Information Meta- metadata in template Component template • Name the component • Provide short description of component • Note potential links with other components Conceptual UML Static Structure Diagram • Depict component on diagram • Identify key component attributes • Identify key relationships with other components • Provide basic definitions for component, attributes, and relationships Logical UML Static Structure Diagram • Identify and provide complete definition for all attributes • Identify and provide complete definition for all relationships with other components • Identify cardinality of attributes and relationships • Identify data types of attributes Microsoft Word Document: • Identify any business rules Business Rules Document associated with the component • Business rules can include: data formatting rules, data integrity/consistency rules Note that this document is deferring the definition of guidelines for the Physical and Out-of- Context levels of detail until the Program gains more experience with documenting components. Technology Architecture Component Guidelines This section contains guidelines for components in the technology architecture. 10
  • Guidelines for Grouping Mechanism(s) The NASCIO framework organizes Technology Architecture components into domains, disciplines, and technology areas. Each component in the Technology Architecture must be associated with one domain. The documentation for a domain must capture key metadata about that domain, as required in the Technology Domain template. Guideline TA-1: In the Washington State Enterprise Architecture, each component in the Technology Architecture should be associated with one and only one domain. This domain should be indicated in the component’s metadata, in the manner prescribed in Guideline TA-10 below. Guideline TA-2: In the Washington State Enterprise Architecture, each Technology Architecture domain must be documented in an instance of the Technology Domain template, included in the appendix to this document. As the enterprise architecture incorporates new components into the Technology Architecture, it will be important to ensure that the documentation for each domain remains consistent with the nature of the components included within that domain. Guideline TA-3: As new components are added to the Technology Architecture, the Enterprise Architecture Program and appropriate Documenter Teams should review the documentation for associated subject areas to ensure that the documentation remains consistent with the included components. Technology architecture disciplines and technology areas will be created as needed to organize components. Each discipline and technology area must capture key metadata, as required in the respective templates. Guideline TA-4: In the Washington State Enterprise Architecture, each component in the Technology Architecture may be associated with a discipline and a technology area. If so associated, the discipline and technology area should be indicated in the component’s metadata, in the manner prescribed in Guideline TA-11 below. Guideline TA-5: In the Washington State Enterprise Architecture, each Technology Architecture discipline should be associated with one and only one domain. This domain should be indicated in the discipline’s metadata, in the manner prescribed in Guideline TA-7 below. Guideline TA-6: In the Washington State Enterprise Architecture, each Technology Architecture technology area should be associated with one and only one discipline. This discipline should be indicated in the technology area’s metadata, in the manner prescribed in Guideline TA-8 below. Guideline TA-7: In the Washington State Enterprise Architecture, each Technology Architecture discipline must be documented in an instance of the Technology Discipline template, included in the appendix to this document. Guideline TA-8: In the Washington State Enterprise Architecture, each Technology Architecture technology area must be documented in an instance of the Technology Area template, included in the appendix to this document. Technology architecture domains will be organized into single Microsoft Word documents. If this strategy proves difficult to implement as the architecture grows, these guidelines will be updated. 11
  • Guideline TA-9: In the Washington State Enterprise Architecture, each Technology Architecture domain will be documented in a single Microsoft Word document. Disciplines and Technology Areas will be represented by sections within the single domain document. Compliance Components and Product Components likewise will be documented in sections within the document, organized as sub-sections of the appropriate Disciplines and/or Technology Areas. Each section (for a Discipline, Technology Area, or component) will begin with the metadata section defined by the appropriate artifact template. The Washington State Enterprise Architecture will continue to evolve as new components are added. The addition of new components to the Technology Architecture may require adjusting the definition of domains, disciplines, and technology areas to accommodate them. The Enterprise Architecture Program will coordinate these adjustments across the architecture. Guideline TA-10: As new components are added to the Technology Architecture, the Enterprise Architecture Program and appropriate Documenter Teams should review the documentation for associated subject areas to ensure that the documentation remains consistent with the included components. Guidelines for Components The documentation for each Technology Architecture component must capture key metadata, as required in the templates for Technology Architecture components (Product Components and Compliance Components). Guideline TA-11: In the Washington State Enterprise Architecture, each Product and Compliance Component in the Technology Architecture must be documented in an instance of the appropriate component template. Templates for Product and Compliance Components are included in the appendix to this document. The purpose of Compliance Components in the NASCIO framework is to represent policies, standards, and guidelines for information technology. All policies, standards, and guidelines relating to Tier One components in the Enterprise Architecture should therefore be represented as Compliance Components. Guideline TA-12: Policies, standards, and guidelines relating to Tier One components in the Washington State Enterprise Architecture should be represented as Compliance Components. Guidelines for Levels of Detail Technology Architecture components will take on particular forms at each level of detail. Guideline TA-13: In the Washington State Enterprise Architecture, each Domain, Discipline, Technology Area, Compliance Component, and Product Component will follow the level-of-detail guidelines in the following table. Level of Detail Guidelines Contextual • Domain, Disciplines, Technology Areas defined and briefly described • 80% of Compliance Components identified and briefly described • Linkages to other architectures sketched 12
  • Conceptual • Domain, Disciplines, Technology Areas defined in detail • 90% of Compliance Components identified and fully described • Linkages to other architectures briefly described Logical • Compliance Components drafted as policies, standards, guidelines • Product Components identified and briefly described • Compliance Component linkages to other architectures formalized (e.g., parameterization of Compliance Components) Physical • Product Components drafted as policies, standards, guidelines • Product Component linkages to other architectures formalized Solution Architecture Component Guidelines This section contains guidelines for components in the solution architecture. Guidelines for Components The solution architecture in the NASCIO framework consists of Solution Set components, each of which consists of a set of component metadata accompanied by one or more views that describe the solution. The set of appropriate views will depend on the nature of the solution. The Documenter Team for an initiative, in consultation with the Enterprise Architecture Program, is responsible for selecting the set of views that is appropriate for the solution. The documentation for each Solution Set must capture key metadata, as required in the Solution Set template. Guideline SA-1: In the Washington State Enterprise Architecture, each Solution Set component in the Solution Architecture must be documented in an instance of the appropriate component template. Templates for Solution Set components are included in the appendix to this document. Guideline SA-2: The Documenter Team for each initiative, in consultation with the Enterprise Architecture Program, should determine which views are appropriate for each Solution Set component. The expected views should be enumerated in the initiative charter document, but the Documenter Team should add additional views to its scope as required. 13