The purpose of this document is to define what the system is to do from the user’s point of view. User requirements define system functions that the users can see and system properties that customers are ready to pay for. Although it may sound harsh, requirements are defined mainly to determine what the user needs, rather than what the user wants.
Table 1. Possible readers of this document
Group of the readers
Reasons for reading
Users and customers
To give feedback about the user requirements
System developers
To understand what functions and properties the system must contain
Testers
To test the system against the requirements
Writers of user manuals
To get material for user manuals
Project team
To follow-up the status of the project against the requirements
1.2. References
These documents have been used as an information source and are necessary for understanding this document.
Table 2. A list of all other relevant documents
Name of the document
Short description of the document contents
Engineering Document Management Research
An overview of the document management system used in this project. ICBN must be integrated into this system. http://projects.icbroker.com/edmr/docs/
BizTalk
BizTalk is an EAI messaging server which can handle document exchange between two parties using RosettaNet PIP standards. It offers standard transparent services such as compression, encryption, authentication etc. http://www.microsoft.com/biztalk/
ICBN research project
The customer’s project at IC Broker IT. ICBN tries to improve the predictability of lead-time or resources in networked product development projects by better engineering change management and integration of product data management systems. http://projects.icbroker.com/icbn/docs/
PINJA API
Code and description of the Java API used to interact with the EDMS http://edmspc.soberit.hut.fi/pinja/
PIP
RosettaNet Partner Interface Process. A description of a process which is related to document exchange between two parties. PIP envelopes are described using XML. http://www.rosettanet.org
RosettaNet
A self-funded, non-profit organization, RosettaNet is a consortium of major Information Technology, Electronic Components and Semiconductor Manufacturing companies working to create and implement industry-wide, open e-business process standards. These standards form a common e-business language, aligning processes between supply chain partners on a global basis. http://www.rosettanet.org/
SOAP
Code Library: SOAP Librarysimplifies processing and creation of SOAP messages. http://xml.apache.org/soap/
Velocity
Code Library: Velocity – Template Engine, Velocity can be used to build a web-application based on MVC-model http://jakarta.apache.org/velocity
XML
Code Library: XML & XSL(T) Engine,Apache Xalan (XSL(T)) and Xerces (XML) http://xml.apache.org
ICReq Research Project
Qure project lists good requirements engineering methods and possible problems related to gathering and management process regarding user requirements.
Drools
Drools is a Java-based Rule Engine implementation which uses Rete-OO-algorithm for resolving rule matches. Drools is the most important module in ICBN. http://drools.org/
Functional Specification
Functional Specification includes use case descriptions.
1.3. Requirements sources
A list of people who have defined requirements.
ID
Person name
Email
Phone
Organization
Title
DT
Dante Dionne
Project Lead
JK
Jason
System Architect
AA
Alexander
Sponsor
1.4. Definitions
1.4.1. Degree of necessity
ESSENTIAL
Implies that the software will not be acceptable unless these requirements are provided in an agreed manner.
CONDITIONAL
Implies that these are requirements that would enhance the software product, but would not make it unacceptable if they are absent.
OPTIONAL
Implies a class of functions that may or may not be worthwhile. This gives the supplier the opportunity to propose something that exceeds the scope of requirements specification.
1.4.2. Implementation schedule codes
I1
Requirement implemented at the 1st implementation phase
I2
Requirement implemented at the 2nd implementation phase
I3
Requirement implemented at the 3rd implementation phase
1.5. Glossary
The special terms, acronyms and abbreviations used in this document.
Acronym/ abbreviation/ special term
Description
API
Application Interface – A language and message format used by an application program to communicate with the operating system or some other control program.
ICBN
Document Distribution Process – Actions that happen when a document is distributed.
EDMS
Engineering Data Management System – System for managing engineering documents.
GUI
Graphical User Interface – A graphics-based user interface that incorporates icons, pull-down menus and a mouse.
HTML
Hypertext Markup Language – The document format used on the World Wide Web. Web pages are built with HTML tags (codes) embedded in the text.
HTTP
Hypertext Transport Protocol – The communications protocol used to connect to servers on the World Wide Web. Its primary function is to establish a connection with a Web server and transmit HTML pages to the client browser.
IC Broker
Name of the project team
UML
Unified Modeling Language – An object-oriented analysis and design language from the Object Management Group (OMG).
PIP
(RosettaNet) Partner Interface Processes – System-to-system XML-based dialogs which define business processes between trading partners.
SOAP
Simple Object Access Protocol – A message-based protocol based on XML for accessing services on the Web.
1.6. Guideline for defining good requirements
Features of a good requirements specification document:
one requirement per sentence
clear structure
correctness (contributes to real user need)
understandability (use user’s language and terminology)
unambiguity (clarity, only one possible interpretation)
verifiable (requirement can be tested)
consistency (no subset of individual requirement conflict)
completeness (everything the system is supposed to do is included in the document)
traceability (every requirement has a unique identifier)
ICBN is a software component which is able to store and manage object-related business rules. Objects can describe some real world elements such as documents, projects, users or some more abstract values or system services. The primary purpose of ICBN is to offer an easy way to define rules for document distribution processes between different companies. ICBN interacts with existing legacy system called Engineering Data Management System (EDMS) and Enterprise Application Integration (EAI) System called Biztalk. ICBN listens to events coming from the EDMS and initiates different document distribution processes if the corresponding business rules are matched. ICBN then calls BizTalk and instructs it to transfer the matching documents.The architecture of ICBN will be designed to be modular and independent of surrounding project related systems. Therefore it can be plugged into any document management system – not just EDMS. ICBN offers a simple HTML-based user interface for managing and visualizing rulesets for different projects.
2.1. System description
The purpose of the project is to develop a system that enables legacy document management systems to exchange documents according to definable rules. The core component that will enable this functionality will be called ICBN. ICBN system will provide a rule engine and a user interface through which user can define these rules The rule engine checks the rules to see which documents have to be sent and to which recipients. ICBN system is located between the document management system and the transport system with which it interacts.
2.2 System users and main functions
Figure 1. System users and main functions.
3. Business goals
3.1 Background
At the moment numerous product changes during product development cause extra delays or a need to use extra resources in product development projects. This is due to a lack of common iteration procedures between companies. Integration of document management systems is not possible because of a lack of common syntax and semantics. This kind of integration has been done earlier in order-to-delivery process, though, e.g. EDI (Electronic Data Interchange). In order to achieve the same kind of integration in product development messages (contents, syntax) must be formally described so that computers can process them.
3.3 Business Opportunities
The ICBN research project will analyse processes between partner companies. Based on this analysis a new framework for iteration is defined to enable better predictability of product development project schedule and resource usage. Inter-company messages are analyzed and common semantics is defined using appropriate schemas. Based on these the ICBN project will implement a software prototype where communication happens according to RosettaNet standards. ICBN will be a part of this prototype.
3.2 Business Objectives
The ICBN software will be part of a larger system. The main driver is to get some research data from using the system and to see if this kind of a system is feasible to implement. Customer will publish articles based on the research data obtained from the project. There are no economical interests and the system is to be used in business intelligence research. Result of this research can be used later in developing a better solution for the problem or as a model for a commercial system.
4. User groups
This section describes intended users of the system.
Table 3. Users of the system
ID
User group
Description
Number of users
PM
Project Managers
Project Managers define and manage controls for their projects.
1-20
Admin
Administrators
Administrators are able to create the most complex business rules and administer rule-sets for different projects. They can create new rule-templates, repositories and manage existing settings. Admins define what PIPs are used between different companies.
1-5
Partner
Partner Companies
Partners are other companies which do not directly interact with ICBN but their activity causes changes in the EDMS which indirectly instantiate events in ICBN. Basically partner is an instance which has right to receive certain documents or document types.
1-2000
BizTalk
EAI BizTalk
Enterprise Application Integration messaging server can be seen as a user from ICBN point of view. BizTalk is responsible for sending the documents ICBN instructs it to send via SOAP calls.
1
EDMS
EDMS
EDMS is the document management system which can also be regarded as a user. EDMS sends events to ICBN when documents change. ICBN should then evaluate the defined rules and in case of a match, initiate certain ICBNs.
1
5. Functional requirements
This section defines all functions and services that the system will provide. See Functional Specification document for accurate descriptions.
ID: RQ-001
Source: AA
Date and phase: 22.10.2002, PP
Priority: High
Class: ESSENTIAL
Release: I1
Requirement: user must be able to login into the system with a username and password
ID: RQ-002
Source: AA
Date and phase: 22.10.2002, PP
Priority: High
Class: ESSENTIAL
Release: I1
Requirement: user must be able to define new ICBN rules
ID: RQ-003
Source: AA
Date and phase: 22.10.2002, PP
Priority: High
Class: ESSENTIAL
Release: I1
Requirement: user must be able to create new rules using existing rules as templates
ID: RQ-004
Source: AA
Date and phase: 22.10.2002, PP
Priority: High
Class: ESSENTIAL
Release: I1
Requirement: user must be able to modify existing rules
ID: RQ-005
Source: AA
Date and phase: 22.10.2002, PP
Priority: Low
Class: ESSENTIAL
Release: I2
Requirement: user must be able to delete existing rules
ID: RQ-006
Source: AA
Date and phase: 22.10.2002, PP
Priority: High
Class: ESSENTIAL
Release: I1
Requirement: user must be able to view all rules related to given project
ID: RQ-007
Source: AA
Date and phase: 22.10.2002, PP
Priority: High
Class: ESSENTIAL
Release: I1
Requirement: user must be able to define a rule as a rule template
ID: RQ-008
Source: AA
Date and phase: 22.10.2002, PP
Priority: Medium
Class: ESSENTIAL
Release: I1
Requirement: user must be able to view all rule templates
ID: RQ-009
Source: AA
Date and phase: 22.10.2002, PP
Priority: High
Class: ESSENTIAL
Release: I1
Requirement: user must be able to list all documents belonging to a certain project
ID: RQ-010
Source: AA
Date and phase: 22.10.2002, PP
Priority: High
Class: ESSENTIAL
Release: I1
Requirement: user must be able to list all projects
ID: RQ-011
Source: AA
Date and phase: 22.10.2002, PP
Priority: Low
Class: OPTIONAL
Release: I3
Requirement: user must be able to list all users (other companies)
ID: RQ-012
Source: AA
Date and phase: 22.10.2002, PP
Priority: High
Class: ESSENTIAL
Release: I1
Requirement: user must be able to list all companies belonging to a certain project
ID: RQ-013
Source: AA
Date and phase: 22.10.2002, PP
Priority: High
Class: ESSENTIAL
Release: I1
Requirement: user must be able to view properties and values of given business object (document, project, user)
ID: RQ-014
Source: AA
Date and phase: 22.10.2002, PP
Priority: Medium
Class: ESSENTIAL
Release: I1
Requirement: user must be able to send documents regardless of defined rulesets
ID: RQ-015
Source: AA
Date and phase: 22.10.2002, PP
Priority: High
Class: ESSENTIAL
Release: I1
Requirement: user must be able to define what companies are allowed to receive a certain document
ID: RQ-016
Source: AA
Date and phase: 22.10.2002, PP
Priority: High
Class: ESSENTIAL
Release: I1
Requirement: user must be able to define what companies are allowed to receive a certain document type
ID: RQ-017
Source: AA
Date and phase: 22.10.2002, PP
Priority: Medium
Class: ESSENTIAL
Release: I1
Requirement: user must be able to list what documents a certain company can receive
ID: RQ-018
Source: AA
Date and phase: 22.10.2002, PP
Priority: Medium
Class: ESSENTIAL
Release: I1
Requirement: user must be able to list what document types a certain company can receive
ID: RQ-019
Source: AA
Date and phase: 22.10.2002, PP
Priority: Medium
Class: CONDITIONAL
Release: I2
Requirement: user should be able to visualize which rules are bound to a specific document
ID: RQ-020
Source: AA
Date and phase: 22.10.2002, PP
Priority: Medium
Class: CONDITIONAL
Release: I3
Requirement: user should be able to simulate what eventss take place when a certain EDMS event is fired
ID: RQ-021
Source: AA
Date and phase: 22.10.2002, PP
Priority: Medium
Class: CONDITIONAL
Release: I2
Requirement: user should be able to view activity log for a certain project
ID: RQ-022
Source: AA
Date and phase: 22.10.2002, PP
Priority: Low
Class: CONDITIONAL
Release: I3
Requirement: user should be able to view error log of the entire application
ID: RQ-023
Source: JV
Date and phase: 22.10.2002, PP
Priority: Low
Class: OPTIONAL
Release: I3
Requirement: user can retrieve a certain rule as XML via HTTP
ID: RQ-024
Source: JV
Date and phase: 22.10.2002, PP
Priority: Low
Class: OPTIONAL
Release: I3
Requirement: user can insert a new rule into the system as XML using the GUI
ID: RQ-025
Source: AA
Date and phase: 22.10.2002, PP
Priority: Low
Class: OPTIONAL
Release: I3
Requirement: user can get email notification of a successful ICBN execution and a list of companies and documents which were sent to each company
ID: RQ-026
Source: AA
Date and phase: 22.10.2002, PP
Priority: High
Class: ESSENTIAL
Release: I1
Requirement: ICBN must be able to retrieve documents, projects and users from EDMS
ID: RQ-027
Source: AA
Date and phase: 22.10.2002, PP
Priority: High
Class: ESSENTIAL
Release: I1
Requirement: ICBN must be able to receive events regarding changes in documents, projects and users from the EDMS via HTTP
ID: RQ-028
Source: AA
Date and phase: 22.10.2002, PP
Priority: High
Class: ESSENTIAL
Release: I1
Requirement: ICBN must be able to send XML messages to BizTalk to define which document should be sent and which PIP should be used
ID: RQ-029
Source: AA
Date and phase: 22.10.2002, PP
Priority: High
Class: ESSENTIAL
Release: I1
Requirement: ICBN must be able to receive positive acknowledgement event from BizTalk of successful sending process
ID: RQ-030
Source: AA
Date and phase: 22.10.2002, PP
Priority: High
Class: ESSENTIAL
Release: I1
Requirement: ICBN must be able to receive negative acknowledgement event from BizTalk of failed sending process
6. Non-functional Requirements
6.1 Quality Requirements
6.1.1. Usability Requirements
This category identifies the requirements for usage related areas such as look and feel of the product.
ID: USE-001
Source: AA
Date and phase: 22.10.2002, PP
Class: ESSENTIAL
Priority: Medium
Release: I2
Requirement: the GUI should be understandable also to non-technical users
ID: USE-002
Source: AA
Date and phase: 22.10.2002, PP
Class: ESSENTIAL
Priority: Medium
Release: I3
Requirement: the GUI should be able to visualize rules related to certain project and document
ID: USE-003
Source: AA
Date and phase: 22.10.2002, PP
Class: ESSENTIAL
Priority: Medium
Release: I3
Requirement: the GUI should be able to visualize what rules are executed when a certain business object changes state, e.g. status of a document changes
ID: USE-004
Source: HP
Date and phase: 27.10.2002, PP
Class: ESSENTIAL
Priority: Medium
Release: I2
Requirement: the GUI should present the rules in a hierarchical way so the user can more easily understand the relationships between different parties.
6.1.2 Performance Requirements
ID: PERF-001
Source: AA
Date and phase: 22.10.2002, PP
Class: ESSENTIAL
Priority: Medium
Release: I3
Requirement: Evaluation of rules should be done in less than a minute.
6.1.3 Reliability Requirements
ID: REL-001
Source: AA
Date and phase: 22.10.2002, PP
Class: ESSENTIAL
Priority: Medium
Release: I3
Requirement: ICBN should be as stable as EDMS.
6.2 System Requirements
6.2.1 Interface Requirements
This category identifies the interface requirements for the product and includes external interfaces as they relate to hardware, protocols, external software packages, databases and any other external communication requirements. Third party software products which have interfaces internal to the product are also be specified here.
ID: IF-001
Source: AA
Date and phase: 22.10.2002, PP
Class: ESSENTIAL
Priority: High
Release: I1
Requirement: ICBN must be able to access EDMS using the PINJA Java API.
ID: IF-002
Source: AA
Date and phase: 22.10.2002, PP
Class: ESSENTIAL
Priority: High
Release: I1
Requirement: The product must be able to send document transfer commands to BizTalk using HTTP Protocol (SOAP is an option).
ID: IF-003
Source: AA
Date and phase: 22.10.2002, PP
Class: ESSENTIAL
Priority: High
Release: I1
Requirement: ICBN must be able to receive acknowledgement/negative acknowledgement messages from BizTalk related to certain ICBN.
ID: IF-004
Source: AA
Date and phase: 22.10.2002, PP
Class: ESSENTIAL
Priority: High
Release: I1
Requirement: ICBN must be able access rule repository via a generic interface which isn’t bound to any specific RDMBS or file system.
6.2.2 Compatibility Requirements
This category identifies the requirements for interoperability with existing products and third-party products, in addition to components of this product such as existing databases from prior releases.
ID: COMP-001
Source: AA
Date and phase: 22.10.2002, PP
Class: ESSENTIAL
Priority: High
Release: I3
Requirement: The graphical user interface must be usable with Internet Explorer 4.0 or later
6.3 Other Requirements
6.3.1 Documentation Requirements
ID: DOC-001
Source: AA
Date and phase: 22.10.2002, PP
Requirement: JavaDoc
Priority: High
Release: I1
Requirement: All source code must be commented using JavaDoc. JavaDocs must be generated to HTML files.
ID: DOC-002
Source: AA
Date and phase: 22.10.2002, PP
Requirement: User Manual
Priority: Medium
Release: I3
Requirement: Product should have simple user’s manual which explains all important operations and how to execute them. Either in HTML or PDF format.
ID: DOC-003
Source: AA
Date and phase: 22.10.2002, PP
Requirement: UML Models
Priority: Medium
Release: I3
Requirement: Product documentation should include UML class diagrams, UML Use case diagrams and Component architecture description.
7. Main domain concepts
This section contains
Textual definitions of the most important terms
A graph defining the relationship of the main concepts
Table 4. Main concepts of the users
Concept
Description
Rule Engine
Software Module which is able to efficiently evaluate a large set of business rules and a pool of business objects. Business objects are given as arguments to different rules to find rules that have matching conditions. When such a rule is found, action(s) of that rule are executed. Rule Engine used in this project is Drools which uses a well-known algorithm called Rete (Object Oriented version).
Rule
a business rule consists of condition(s) and action(s). Conditions are defined by combining business object attribute comparisions (e.g. project.status == “finished” and document.type = “specification”). Action is usually a command to send the document to its recipient. Rules can have arbitrary level of complexity and they can address any attributes of any available business object.