AJAKS - Software Engineering at RIT · Project Overview This project is being completed for PAETEC, a local telecommunications company. PAETEC provides products such as local and

Product Catalog Editor II AJAKS

Alek Demko Justin Rennell Alaina Somers

Ken Krug Sam Arent

Sponsor: Paetec

Sponsor’s Representatives: Brion Swanson, Jason Gowan

Faculty Mentor

Professor Lutz

Project Overview

This project is being completed for PAETEC, a local telecommunications company.

PAETEC provides products such as local and long distance voice services, Internet

services, and software applications to customers that include businesses, universities,

hospitals, and governmental organizations.

Our project fits in by helping the marketing and sales team manage the PAETEC product

catalog. The tool needs to replicate the existing functionality provided by a set of Excel

spreadsheets and macros. The tool will be designed specifically for the products sold

through the PAETEC PAO system. The tool will be used by both product managers and

developers, and replace two existing systems. It will allow for product managers to

download the existing catalog, edit it, and merge their changes into a working database.

Developers will be able to review changes that are made and generate code to be entered

into the production database.

Basic Requirements

The system must be able to create, edit, review, and delete product catalog elements, and

import from and export to various sources. Specifically, the system must:

Install application. The system must be simple to install and use on any

PAETEC managed computer. The project should be installable by product

managers with little to no help from outside sources. The project should be quick

and simple to start, close, and use.

Manage a product catalog's elements and their details. The system must be

able to manage a product catalog, its elements, and their details. The PAO

database is structured in a hierarchy of elements that represent products sold to

customers:

Figure 1: Breakdown Of Product Catalog Components

The product catalog itself represents the top node in a tree. Products have

features; features have parameters. Each of the three components has its own

unique set of details used by PAETEC to define a product.

The system manages a usable way to create, edit, delete, and review all

components. Components must also require no information other than the default

to be created – this means that components can be added in bulk and edited later

for convenience to product managers.

Manage a local version of a product catalog. Product Catalog Editor must be

able to load from and save to a local version. The local file should be

transferrable between computers and open with Product Catalog Editor. There

must be an option to compare two local files so that if changes are made, a user

can accept, reject, or modify the two to make them identical while editing.

Manage a 'work in progress' database for collaborative editing. Product

Catalog Editor must be able to upload to and download from a central database

specific to the product, and separate from the PAO production database for

collaborative refining of products and creation of new products. The 'work in

progress' database will contain a new version of the product catalog that is being

collaboratively edited and improved. Users should be able to get a copy of the

current 'work in progress' view of the catalog and use an interface to compare this

with their current local file. Users should also be able to upload changes to the

database, comparing the changes with the current database in order to upload the

correct changes.

Export to and import from an SQL file compatible with the PAO database. The project must be able to export to and import from an SQL file as generated by

the current Excel spreadsheet version of Product Catalog Editor. Product Catalog

Editor must be able to import from an SQL file generated either by the current

spreadsheet system or any version of Product Catalog Editor. This will enable an

initial import into the project, as well as allow compatible updates with any

existing SQL files. Product Catalog Editor must also be able to create SQL files

that can be used flawlessly with the PAO Production Database to update changes

and new components.

Usable to product managers and developers. The project must be usable in

order to be adopted. A previous attempt at upgrading Product Catalog Editor to a

web-based program failed due to poor usability; it was simply not preferable to

product managers over the existing spreadsheets. The new version of Product

Catalog Editor must be usable in terms of being easier to use and adopt than the

existing spreadsheets.

The system must be usable two two major groups: product managers and PAO

developers.

Product managers are PAETEC employees who oversee the creation and strategy of

PAETEC's products. They are the primary editors of components and primarily

responsible for the review, creation, changing, and deletion of components. Product

managers also:

Range from technically-minded to not very technical.

Have a familiarity with Windows XP

Have a strong familiarity with the current spreadsheet system

Use a variety of screen resolutions, the smallest of which should be 600px by 800

px

PAO developers will maintain the system once it is completed. Their primary role with

the software is to review the current edited versions and export an SQL file to push to the

PAO Production Database for use by other employees. PAO developers were the

primary contact and sponsor for the creation of this product and thus have the most input

on its evolution. Also, PAO developers will maintain the code of the system once it is

released; the code and build must be well-document to facilitate new features and project

maintenance by PAO developers.

Constraints

The system had many constraints that deal with the computers it will be operating on and

Paetec’s existing systems. Specifically, the technical constraints to the program dealing

with Paetec’s systems were:

Windows XP

Screen resolutions larger than 800x600

Oracle database

The system also does not directly connect to the production database for security reasons.

The sponsors requested that the system generate a SQL file to run in the production

database after review.

Development Process

For this system, we used a modified waterfall model. Our model was originally inspired

by the process used by PAETEC, and turned out to be successful for our implementation.

We reviewed our schedule and process with our sponsors, who were pleased with our

choice and our allowance of time to complete the project.

Our waterfall model process had five stages: requirements collection, design,

development, acceptance testing, and delivery. Our sponsor’s representatives will handle

maintenance after delivery of the project.

Requirements Collection. During the requirements collection phase, the

sponsor's requirements were translated by the team into formal requirements and

verified by the sponsors. Requirements for the system were gathered during

weekly sponsor meetings at RIT or at PAETEC. Initially, the sponsor's

requirements were used to create use cases in Blueprint Requirements Center,

software recommended and provided by the sponsor. Once the initial use cases

were entered, the sponsors were able to access the requirements file as it was

updated to suggest changes via e-mail and plan verbal feedback for meetings.

Requirements were also organized into a prioritized list using a three-tiered

system: items the system must have, items the sponsors would like to have, and

items that should be included only if there is remaining time. The team gathered

sponsor verification on all use cases before proceeding from the requirements

collection phase.

Design. The design phase translated the requirements into a programmable

system. An overall design was created and sections were split up for the creation

of detailed designs.

Development. For development, we followed an iterative evolutionary prototype

cycle. We originally planned for three two-week prototype releases to gather

feedback from the sponsors. However, this was not feasible in production. The

schedule was modified to include testing in iterative cycles with two prototype

releases, three beta releases, and a final release candidate.

Acceptance Testing. Acceptance testing was scheduled for several weeks during

the end of the process to validate the project and make sure it fit with the

sponsor's needs. Since a problem with the previous project was that it didn't fit

the sponsor's needs and was not usable with the product managers at PAETEC,

we needed to make sure that our project was deliverable. We planned to do

usability testing with actual users, other students, and our sponsors, as well as

meeting with our sponsors to discuss use of the project and its future.

Delivery and Release Candidate. The sponsor will be given the final release to

use. Since the sponsors intend to improve and maintain the project after

completion, documentation on how to build and maintain the project will be

included with the delivery.

Project Schedule: Planned and Actual

Our original project schedule read as follows:

Winter Quarter Schedule:

Weeks 1-3: Orientation with Sponsor(s)

Weeks 3-8: Requirements elicitation

Weeks 8-11: Detailed design

Week 10: Interim presentation

Orientation with Sponsors: Meet with sponsors. Get a feeling for company, project, and

goals. Set up methodology to follow, project website, and plan for requirements

gathering.

Requirements Elicitation: Meet with sponsors at regular meetings. Discuss project

goals, business needs, and features for product.

Provide updates on requirements definitions and get feedback. Hone requirements to

meet sponsor approval.

Detailed Design: Work on design diagrams that satisfy requirements and provide a

strong basis for moving ahead into development.

Design must take into consideration possible requirements volatility, though the

likelihood of significant volatility is expected to be low.

Interim Presentation: Create, refine, rehearse, and carry out mid-project presentation

for Faculty, Students, and Sponsors.

Spring Quarter Schedule:

Weeks 1-3: First Prototype development

Weeks 3-5: Second Prototype development

Weeks 4-6: Project poster creation

Weeks 5-7: Final Prototype development

Weeks 6-8: Usability testing

Weeks 6-8: Testing

Weeks 8-10: Cleanup and Delivery

First Prototype development: Create the first "Thin, vertical slice" of the application

and deliver to sponsors. This should include basic functionality with creating and

hopefully saving Product Catalog on a local machine. Begin getting informal feedback on

usability.

Second Prototype development: Expand functionality of first prototype. This should

introduce the complete catalog editing functionality, strong integration with the work-in-

progress database, and the main compare and merge functionality.

Project poster creation: Design project poster for the SE Senior Project deliverable.

Final prototype development: This should fill in any functionality gaps missing from

the second prototype. If possible, usability issues identified in usability testing should be

addressed here. This should include at minimum beta-quality functionality of ALL

features.

Usability testing: More formal usability testing should be conducted starting with the

second prototype for usability metrics such as keystrokes per use case and specific

questions for sponsors based on usability/satisfaction. This must be coordinated with

sponsors and team for availability and scheduling.

Testing: Conduct updated usability testing based on updated prototype(s). Create

prototypes as requested with updates. Document and correct any functionality issues not

resolved in prototype development. Create release candidate(s) for sponsors to

acceptance test starting week 7 and as requested after that.

Cleanup and Delivery: Package documentation and project artifacts for delivery. Create

final presentation and preparations for "poster presentations". Hand off deliverables to SE

department and sponsors. Conduct additional cleanup steps as necessary (to be

determined at end of quarter). This also includes providing "release notes" and

documentation for our sponsors on setup and maintenance of the product.

Our final schedule varied some, but we were still able to deliver with the same intended

feature set. Winter quarter design took longer than expected; the schedule was adjusted

to allow the design to simply be completed before spring quarter. At this time, we were

still within our schedule constraints and we worked on the interim presentation and the

design at the same time.

During development, the schedule was adjusted further. As development began, it was

realized that the system would take more than three iterations; instead, we created two

prototype releases with partial functionality before releasing three beta releases. Testing

was combined into iterations of the prototypes and beta releases instead of being a

separate cycle at the end of the development period.

Prototype releases included increasing amounts of functionality with non-unified drivers.

The second prototype introduced the graphical user interface. Each beta release was in a

single package and was released to the sponsors for acceptance testing and validation,

and were expected to be defect-free. In practice, each beta release had a number of

defects and usability improvements, which were closed before the next beta release. The

schedule was often delayed a few days. Overall, however, the final release candidate was

released to the sponsors on time.

System Design

The architectural pattern we chose is the MVC pattern. We will split out the UI from the

business logic of the system using this pattern to maximize cohesion and minimize

coupling between components. We are also borrowing some concepts from J2EE

architecture with entities and view-action objects to simplify access points for the UI.

Component Partitioning

Our use cases were broken up into 4 sections based on the actors we defines: System

Administration, Product Manager, PAO Developer, and General (Product Manager and

PAO Developer) use cases.

For the design, there are 5 major sections, or components, we define:

1. Core Model - The Core Model is the foundation for the system. It provides the

low level implementation of the Product Catalog and the Components along with

the supporting logic for manipulating the Catalog. Much of the information for

the user session of the application is handled directly in the Session object. Below

are the different major sections that make up the entirety of the Core Model:

Session

The Session is a singleton object that gets created when the application is launched. The

Session stores the information related to the state of the system as the user works with the

Product Catalog. The actual loaded Product Catalog and Components are stored within

the Session. The Session also handles the behind-the-curtain operations for the GUI-

centric activities such as cut/copy/pasting components, creating new Catalogs and/or

components, and the undo/redo system.

Product Catalog

A Product Catalog is a collection of Products and their Features and Parameters. The

Session contains a single "loaded" Product Catalog for the application, but any number of

Product Catalogs may exist at any time, and this is used for doing comparisons.

Component

Components are the Products, Features, and Parameters in the Catalog, as mentioned in

the requirements section.

Properties

There are numerous fields that have specific ranges of values, but those ranges may

change. These values include:

1. Product Categories

2. Recurring Rate Types

3. Nonrecurring Rate Types

4. Parameter Types

5. Parameter Groups

CRUDComponents

The CRUDComponents abstract the complexity of creating, reading, editing, and deleting

Components.

Undoable Actions

UndoableActions are actions that can be executed, undone, and redone. Not all actions

are undoable, and only undoable actions follow this process.

The Session keeps an undo stack and a redo stack, both comprised on undoable actions.

The following figures demonstrate the actions of the undo stack's execution:

Figure 2.1: Execute the first undoable action

Figure 2.2: Execute a second undoable action

Figure 2.3: Undo second undoable action

Figure 2.4: Undo first undoable action

Figure 2.5: State of stacks after undoing actions

Figure 2.6: Redo first action from redo stack

Figure 2.7: Perform new undoable action (actions are cleared from redo stack)

Component Nodes

Component nodes are very simple representations of a Component.

These are used to display the basic Catalog Tree where all that's known is a

Component type, a name, and the ID of the Component.

Figure 3.1: Example Catalog Tree

Figure 3.2: Example Component Node Tree (corresponds with Figure 3.1)

Cut Copy and Paste

Features and Parameters may be copy and pasted to other Products or

Features, respectively.

Database Locations

A DatabaseLocation is analogous to a Repository Location in Eclipse. A

location represents the address (url and port) and credentials (username and

password) of a database that can be connected to. Each location can be given

a name that describes it.

2. Import + Export Design

Loading and publishing to local copy or work-in-progress

Importing from and exporting to SQL file(s)

3. Compare + Merge Design

The core logic for versioning and comparisons

Diff

Contains information about the differences between two Components. This

information is stored via arrays of Components that are similar, added, or

changed.

DiffUtil

Builds a DiffReport of a catalog by building a Diff for each type of

Component.

DiffReport

Contains a Diff for each type of Component.

MergeUtil

This class allows for obtaining a new ProductCatalog from the selected

Components in a DiffReport. This relies on a user interface that allows the

user to select which Components to keep from each ProductCatalog.

4. User Actions Design (GUI->Model design)

Control mechanisms

Starting/stopping application

Shortcuts and optimization hooks

5. GUI Design

SWT Portion for displaying info

Must allow all actions to be performed

Controlling actions available in current state

Process and Product Metrics

Our metrics tracked our effort on the project as well as its usability. We tracked our

effort spent on the project using our tracking tool, Redmine. We also tested clicks per

use case on a variety of external users.

We tracked over 720 hours for the final project.

Figure 4: Breakdown of Hours Spent By Month and Category

Figure 5: Breakdown of Time Spent By Task by Development Cycle Order

Figure 6: Breakdown of Time Spent By Task by Most Time Spent

Figure 7: Breakdown of Percentage of Time Spent on Tasks

Figure 4 shows the hours spent by both month and category, showing how we progressed

through our waterfall cycle, and spent the majority of our time on requirements, time, and

development. At the beginning of the project, our original sponsor dropped out. We lost

most work time in December and spent time learning about our new project and meeting

with our sponsors initially before starting to work on requirements for the project.

In January and February we began to clarify requirements and create use cases to review

with sponsors. A significant portion of time was still spent completing overhead work of

ensuring a rapport with the sponsors and setting up work environments, as well as

working on documentation to complete the initial required work for the project. February

constituted similar goals with more of a focus on requirements collection.

Development took up the bulk of the effort in March and April. In March, design and

development began with the end of winter quarter and the start of spring quarter.

Therefore, as predicted, our hours spent on the project started to increase dramatically.

The design was completed; development began. Development unfortunately took more

time than expected due to unexpected errors and incorrect estimation; in many cases

estimated time spent was correct, however when it was incorrect, an item took more time

than expected rather than less.

In May, the majority of the project was completed and most development focused on

fixing errors. Testing was done by the team for most functionality, however many errors

were found during development or by the sponsors following a release. Since the

sponsors’ efforts are not tracked, testing time is somewhat skewed.

Figure 5 and Figure 6 show the amount of time spent by task. Development took up the

bulk of our time, followed by overhead and requirements. Development of the project

itself logically takes up the most time, to create and debug the project properly for

delivery. We also spent significant time collecting requirements. This ensured that the

project met the sponsor's expectations completely. This worked out well for us – little to

none of our time was spent refactoring or redefining requirements later on, and the

sponsors were very upfront that they would likely not change requirements on the project.

Figure 7 shows a breakdown of time by task. 52% of the total time on the project was

spent working on development, however, the largest specific section was taken up by

“meetings and administration,” meaning meeting time, as well as overhead and

administrative work.

The other collected metric was for usability: clicks per use case. It was measured using

the following examples:

Figure 8: Raw Data for Clicks Per Use Case

The raw data for clicks per use case is shown in Figure 8. Clicks per use case was

calculated by testing the project with students in the RIT College of Business; since

testing with actual users was not feasible in the project, business students were deemed to

be the closest easily accessible substitute. Business students, like product managers,

range in their technical skill and familiarity with technical products. Seven users were

tested.

Clicks per use case was an important metric to calculate due to the importance placed on

usability in the project. In general, most use cases centered around few clicks to

complete; many of them only took a single click or set of clicks, especially to create and

save an item.

Product State at Time of Delivery

The final product at the time it was delivered to the sponsors is our release candidate.

There are no known issues. The release candidate includes all planned features. Many of

the usability requirements of the program were modified during development – sponsors

had different feedback after running and using the program compared to hypothetical

input.

The only major change of requirements, which was not large, involved the bulk add of

parameters and features. This was modified so that default values are set in features and

parameters upon adding them.

Project Reflection

Overall, the project went well – it was completed and it satisfied the sponsor's needs. We

hope to see it implemented at PAETEC.

If this project was re-created, the schedule should have been adjusted to allow for more

development time and creation of iterative cycles earlier in the project.

Glossary

product catalog – the head node in the product tree; a product catalog may have product

children and no parents

components – a product, parameter, or feature

product – a type of component that represents a PAO product; a product's sole parent is

the product catalog node, and it may have parameter children

parameter – a type of component that represents a PAO parameter; a parameter's sole

parent is a product, and it may have feature children

feature – a type of component that represents a PAO feature; a feature's sole parent is a

parameter, and it has no children

Product Catalog Editor – the software project that manages the product catalog; past

versions include a currently used series of Microsoft Excel spreadsheets that generate

SQL files, and a previous web-based software project that was never widely adopted; the

project discussed in this technical report is the new version of the project