REQUIREMENTS SPECIFICATION

An Engineering Data Management System for the Global Design Effort
of the International Linear Collider

John Ferguson[1], Lars Hagge[2], Richard Stanek[3], Thomas Walter Markiewicz[4],
Harry Weerts[5], Nobu Toge[6]

Document History

Document Title / An Engineering Data Management System for the global Design Effortof the International Linear Collider
Last Modification Date / Oct. 24, 2005 LH
Revision History / Oct. 24, 2005: Initial version
Layout of document structure, keywords for each section, initial versions of section 4 (use cases) and section 5 (functional req’s)

Table of Content

1.Introduction

1.1.Preamble

1.2.Purpose of the Document

1.3.Overview of the Document

2.Overview

2.1.Objective and Perspective

2.2.General Capabilities

2.3.General Constraints

2.4.User Characteristics

2.5.Environment

2.6.Assumptions and Dependencies

3.Basic Concepts and Terms

3.1.Quality of Information

3.2.Document Management

3.3.Part Management

3.4.Product Structure Management

3.5.Configuration Management

3.6.Workflow Management

3.7.3D CAD Data Management

3.8.Visualization and Digital Mock-Up

3.9.Glossary

4.Examples for Usage Scenarios

4.1.Organize and Archive Meeting Documentation

4.2.Write Report with Authoring Team

4.3.Distribute and Maintain Technical Documentation

4.4.Maintain the ILC Reference Design

4.5.Compare Design Alternatives

4.6.Collaborative Design of Accelerator Components

4.7.Conducting Industrial Studies

4.8.Review and Approve Notes and Reports

4.9.Calculating Cost Roll-Ups

5.Functional Requirements

5.1.Database Requirements

5.2.User Interface Requirements

5.3.Core Functionality and Workflow Requirements

5.4.System Interface Requirements

6.Non-Functional Requirements

6.1.Scalability

6.2.Usability

6.3.Security

7.Open Issues

8.References

9.Appendix: Requirements Format

1.Introduction

1.1.Preamble

One of the first deliverables of the group should be a written set of requirements for the software tools. The recommended solution must reflect the international, multi-institution nature of the ILC and should try to unify the work occurring in the different regions on the many disparate aspects of the ILC. A progress report to the GDE should be made at the December 2005 meeting. It is hoped that a decision can be made early enough in 2006 that implementation, testing and backfilling of the archive can occur before the fourth meeting of the GDE in March 2006, with release to the general ILC community targeted to April 1, 2006.

1.2.Purpose of the Document

The …

1.3.Overview of the Document

The next chapter gives an introductory overview of the envisioned EDMS for ILC. Chapter 3 introduces some of the most important EDMS concepts, including document and 3D CAD data management, part and structure management, configuration management and workflow. Chapter 4 provides example usage scenarios of an EDMS for the GDE activities. Derived functional requirements on an EDMS are contained in chapter 5, while the non-functional requirements and constraints are collected in chapter 6. The document concludes with references and an appendix on the requirements format.

2.Overview

2.1.Objective and Perspective

The committee should recommend a specific web based software solution, which may mean an integrated collection of distinct software packages that will allow ILC collaborators worldwide to store, search for and retrieve various kinds of documents. Throughout this document, this solution will be referred to as an Engineering Data Management System, EDMS.

The EDMS should handle at least three basic kinds of documents:

  1. Meeting, conference and seminar related files,
  2. Publications, white papers and notes, and
  3. Engineering documents, e.g. CAD drawings, cost estimates, vendor quotes, and QC documents.

The recommendation of other related virtual communication tools may be made if they enhance the functioning of the basic document management system. Such tools may include calendars, agendas, emailing lists, email notification, discussion forums, user-modifiable ("wiki") web pages for interactive working group documentation, etc. The recommendation or incorporation of these tools should be considered secondary to the selection of system that supports the core functions of storage, search and retrieval.

Project management tools (WBS, scheduling, resource planning) are outside the scope of current charge. Figure 1summarizes the role of the envisioned EDMS.

Figure 1:Scope of an EDMS for the ILC GDE

The EDMS is intended to be introduced as the GDE is launched and to satisfy the requirements throughout the lifespan of the GDE. The most urgent requirements address document management issues for the community, including the management of meeting materials and the authoring of reports. As the GDE progresses, engineering data is expected to become of increasing importance as laboratories start exchanging parts and industrial companies prepare for manufacturing large series of components.

Figure 2 shows a context diagram of an EDMS in the ILC community which highlights some of the EDMS user groups.

Figure 2: Context Diagram of an EDMS for the ILC GDE

2.2.General Capabilities

Document management for notes, papers meeting minutes

3D CAD Data Management and Visualization for common component designs

Product Structure and Configuration Management for BCD and ACD

Workflow Management for Change Control

Workflow and Document Management for supporting industrialization

2.3.General Constraints

The EDMS has to be fully Web based.

Support teams for interactive hotline support have to be created in the three regions

Document management capabilities (access, visualize, upload etc) have to be provided free of charge. Systems for creating documents (Office, graphics, CAD, simulation packages) are in the responsibility of the contributing institute.

System has to support requirements at least up to beginning of ILC project in 2009 or 2010.

2.4.User Characteristics

Casual users / information users searching for and navigating to information

review boards,change control board, decision makers

Speakers and convenors of meetings, authors of ILC notes

Members of working groups, QA engineers

Design and manufacturing engineers

Administrators

All of the EDMS user groups are familiar with the internet and web technologies. They are using web applications routinely as part of their everyday work. Design and manufacturing engineers are using one or more CAD systems

2.5.Environment

The …

EDMS to be fully web based, English as working language

integrate into available lab infrastructure

integrate with available CAx systems

EDMS-Clients to run at least on Windows, Linux and Macintosh clients

Multi-site capabilities

2.6.Assumptions and Dependencies

Given the time constraints, only systems which are in use at an HEP laboratory and which are provided by teams with experience in implementing, running and supporting an EDMS will be considered.

3.Basic Concepts and Terms

This section briefly introduces and defines some of the key concepts of Engineering Data Management for the ILC and provides a short glossary of terms.

THIS SECTION IS IN A VERY PRELIMINARY SHAPE AND TO BE IGNORED AT THE MOMENT.

3.1.Quality of Information

A project is exchanging information at different levels of quality, ranging from ad-hoccommunication for discussion and coordination over minutes, notes andpresentations to structured information and official documents like specifications, contracts, or design models.

Ad-hoc information is passed without further explanation along intuitive and easy-to-use communicationchannels, while official documents need to be reviewed, released and stored in a way which guarantees their availability and accessibility throughout the project lifecycle. A rule ofthumb for deciding whether information is ad-hoc or of lasting relevance refers to“the magical fifteen minutes”: any information which takes less than fifteenminutes for authoring or for reading and understanding can be considered ad-hoc, whileany other information should be considered structured or “official”.

Official documents shall be passed with metadata, e.g. instructions on howto use the information, keywords for information retrieval, or status information. An Engineering Data Management System targets structured and official documents.

3.2.Document Management

The …

Documents hold the intellectual assets of organizations, the knowledge and expertise of its people, and the information and data they have compiled [AIIM]. Document management encompasses the storing, categorizing, exchange and retrieval of documents.

Document management is the key capability for managing meeting material, notes, papers, reports etc.

3.3.Product Structure Management

The …

A part is any component or assembly that is included in the overall product. Parts can be classified (component, assembly, manufacturing part …) and catalogued (part family mgmt)

Multiple parts can be assembled into a product structure. Product structures are divisions of a single product into a hierarchy of assemblies and components. In project management, a product breakdown structure (PBS) is an exhaustive, hierarchical tree structure of components that make up a projectdeliverable, arranged in whole-part relationship.

A PBS can help clarify what is to be delivered by the project and can help build a work breakdown structure.

Product structure management is the core functionality for maintaining the ILC reference structure and its variants.

3.4.Configuration Management

The …

… required for keeping track of developments and managing variants …

3.5.Workflow Management

The WfMC states that "workflow is concerned with the automation of procedures where documents, information or tasks are passed between participants according to a defined set of rules to achieve, or contribute to, an overall business goal." The WfMC notes that workflow is often associated with the core business processes of an organization.

… required for establishing change control board …

3.6.3D CAD Data Management

The …

… required for collaborative designs, exchanging parts and module, industrial studies …

3.7.Visualization and Digital Mock-Up

The …

… required for analyzing designs from other laboratories …

3.8.Glossary

Document
Information
Part
Serialized Part
Workflow
Lifecycle
Relation

4.Examples for Usage Scenarios

This section presents the major use cases of an EDMS for the ILC. It names the tasks which should be supported by the EDMS andsketches their relevance to the GDE activities.Short scenarios describe how each task could be performed with an EDMS and illustrate how the activities would benefit from an EDMS (these scenarios are only examples for discussion; many other alternative scenarios can be imagined).

The use cases are the basis for deriving the essential functional EDMS requirements (see following chapters).

4.1.Read ILC-Related Documents

Relevance: Anybody joining or participating in ILC-related R&D activities needs to get an overview and continuous updates of ongoing developments. The entire material has to be accessible from a single point of access to ensure for example the completeness of search results.

Objective: The EDMS should be the central point of access for ILC-related documents.

Usage scenario: Document retrieval

  1. Users enter a search term into the EDMS (alternatively: use a pre-defined entry point such as a root folder, a topical web page …)
  2. The EDMS presents a list of documents matching the search term.
  3. Users select a document from the result list
  4. Optional: If the user does not have an adequate viewer for looking at the document, the EDMS offers to download an adequate application to the user’s PC.
  5. The EDMS displays the document, lists the document metadata and offers navigation to related documents.

4.2.Organize and Archive Meeting Documentation

Relevance: Related to the GDE efforts, numerous workshops are being held in places all over the world. The resulting material needs to be accessible to the community to achieve good distribution of information as a basis for establishing consensus on results.

Objective: The EDMS should be the central point of access for retrieving presentations and other material from all the ILC workshops.

Usage scenario I: Document management

  1. Authors uploadtheir meeting presentations to the EDMS.
  1. Meeting organizers create web pages for their sessions which include links to the presentations in the EDMS
  2. Users access the presentations either through the meeting web pages or through the EDMS search engine.

Usage scenario II: Agenda management

  1. Meeting organizers create an entry for the meeting in an agenda system like e.g. CDS agendas (which can be locally run be the meeting organizers).
  2. Authors upload presentations to the agenda system.
  3. At the end of the workshop, meeting organizers export the contributions and their metadata from the agenda system, and the ILC documentation team bulk loads the presentations into the EDMSproviding adequate (automatic) classification.
  4. Optional: The meeting organizers replace the presentations in the agenda system with links to the EDMS.

4.3.Write Reports with Authoring Teams

Relevance: Summary reports, design reports, the BCD or other documents (including this specification) are usually written by teams of authors. Authors contribute parts of the document, review and comment on the document as it grows and release and publish a final version. The GDE requires efficient support for globally distributed authoring teams.

Objective: The EDMS should coordinate the authoring, reviewing and publication activities of collaboration documents and keep track of their development history.

Usage scenario: Authoring teams

  1. Authors upload contributions to a protected team area in the EDMS.
  2. The EDMS informs team members about new or modified contributions.
  3. Team members annotate, modify or approve the contributions until consensus has been reached (e.g. all the team members approve a document)
  4. The leading author releases the final document(s) to the public EDMS areas.

4.4.Review and Approve Notes and Reports

Relevance: The various notes, reports and other publications originating from the ILC R&D activities have to be accessible to the community for discussion and for reference. The reliability, relevance and official use of documents has to be qualified e.g. in a review-and-release status of each document.

Objective: The EDMS should coordinate document reviews and approvals.

Usage scenario: Document Approval

  1. Authors submit notes to the EDMS and request a formal review by an officially appointed review board (it is assumed that the GDE will appoint review boards for specific types of documents).
  2. The EDMS distributes the documents to the members of the review boards, who read and comment the document. The reviewers can watch each others activities in the EDMS.
  3. Optional: At least one member of the review board rejects the document. The according comments are provided to the author by the EDMS (who might either update the document and restart the scenario or leave the document as a “working” contribution).
  4. The reviewers have approved the document, which receives the according status tag.
  5. Depending on the status, the EDMS automatically conducts follow-up activities like e.g. distributing the document to mailing lists or posting it to web sites.

4.5.Distribute and Maintain Technical Documentation

To be defined.

(Build product breakdown structure (PBS) and associate documents, drawings and CAD models with the PBS items; use for maintaining the ILC reference design, but also for joint development of components)

4.6.Conduct Industrial Studies

Relevance: Industrial studies are carried out by potential manufacturers of components for the ILC. They are investigating component designs and production processes to optimize them for fabrication. For example, the studies could re-engineer mechanical designs with the objective of reducing the number of parts which are required for fabricating components. They are based on analyzing the component’s specifications and on experience from constructing prototype series.

Industrial studies are essential for estimating costs and efforts and proving the feasibility of building the ILC.

Objective: The EDMS should make the results of industrial studies available to the ILC laboratories. Ideally, the EDMS should be the collaboration platform for the industrial companies and the contracting laboratory during the studies.

The usage scenarios refer to the two objectives: the first scenario reflects the publication of “paper-based” documentation, while the second scenario addresses joint optimization and verification of the mechanical 3D design.

Usage scenario I: Exchange and publication of “paper-based” documentation

  1. The contracting laboratory uploads specifications and technical drawings into the EDMS for distribution to industry.
  2. The supplying industrial companies receive EDMS access to controlled areas and download the material from the EDMS.
  3. The companies conduct the study and create a final report including revised technical drawings.
  4. The companies upload their final material into the EDMS.
  5. ILC labs can download the material through the EDMS(which ensures that the results remain inaccessible to competing industrial companies).

Usage scenario II: Collaborative optimization of mechanical 3D designs

  1. The contracting laboratory uploads specifications and its 3D mechanical design models into the EDMS for distribution to industry, ideally using CAD connectors to directly store the CAD models and associated drawings in the EDMS.
  2. The supplying industrial companies receive EDMS access to controlled areas and download the material from the EDMS. The companies ideally use 3D CAD connectors to obtain direct access to the mechanical design data.
  3. The companies review and change the mechanical design models according to their expertise, and the models are stored directly in the EDMS.
  4. The contracting laboratory downloads and checks intermediate versions of the modified designs for compatibility with their requirements (e.g. whether re-designed couplers still fit the modules).
  5. The laboratory approves or rejects the modified designs.
  6. The companies create a final report which is uploaded to the EDMS and made accessible to the ILC community.

4.7.Collaboratively Design Accelerator Components

Relevance: Essential accelerator components like e.g. the cryomodules for the ILC will be designed by collaborations of several laboratories. The labs need to access each other’s design data to verify that the various parts are fitting and to design the interfaces of the parts.

For example, laboratories might need to verify whether couplers designed in another lab are fitting a cryomodule (e.g. stay within agreed space, use compatible flanges and support structures), or they need to check if modules from another lab can be integrated into their facilities (e.g. use compatible types and sizes of connectors and supply lines). The available engineering models need to provide enough level of detail for these investigations.