maintenance by HC111111032554

VIEWS: 125 PAGES: 25

									1. Introduction and Scope
This document is intended to describe the maintenance procedures for the separate
components that make up MetroViz. It is intended to be a reference document primarily
for the City Information Systems (CIS) department of the city of Pittsburgh, giving
enough detail to understand the internal structure of the system and code and to modify it
as necessary.

The document is divided into five major sections:
    Deployment
    Interfaces
    Code Overview
    Database
    Future Implementation


2. Deployment
This section describes the maintenance procedures that are required to deploy MetroViz
to potential users and their computers.

2.1 Licensing

Let‟s start with the good news: MetroViz is unencumbered by licensing requirements for
new installations. As long as the software continues to include the copyright statements
already found in the About MetroViz window, the third-party licensing requirements will
be satisfied. However, in order for the “Export Excel Report” function to work properly,
a fully licensed installation of Microsoft Office (version 10.0/2000 or above) is needed.
We believe that this is a reasonable requirement and should not be difficult to satisfy,
since most city employees already have an acceptable version of MS Office installed.
Use of the MetroViz application itself is free of cost or obligation of any kind.

2.2 Tools and Techniques

As a background in the development process, this section gives a high level view of the
environment, programs, and libraries were used to create MetroViz.
    Windows XP
    Microsoft Office 2000 and 2003, includes Access, Excel, and Word
    Visual Basic .NET 2002 and 2003
    NHibernate. A .NET library, this will be described in further detail in the code
       overview section.
    NPlot. A .NET library, this will be described in further detail in the code
       overview section.

2.3 Installation Requirements
MetroViz was designed with the city of Pittsburgh‟s computer infrastructure taken into
consideration, and therefore the program can be added to existing systems with minimal
upgrades or installations for most users. Special processing power is not necessary for
MetroViz. It is a relatively small and simple program that should run on any machine that
meets the below requirements and has the available space. MetroViz requires:

2.3.1 Microsoft Windows.
MetroViz is designed to run on Windows XP but will also run on some older versions of
Windows. MetroViz will not work with other operating systems.

2.3.2 Microsoft Access 2000 or 2003.
Access is required for MetroViz to access the data needed to produce the graphs.

2.3.3 Microsoft Excel 2000, XP, or 2003.
In order to take advantage of MetroViz‟s ability to export data directly to Excel, a copy of
that software is required.

2.3.4 Microsoft .NET run time environment.
This is a redistributable, free download package from Microsoft‟s website and includes
everything needed to run .NET applications.

2.3.5 MetroViz installer package (includes NHibernate and NPlot)
Everything needed for installation is included on the distribution CD. Required libraries
will be installed along with the main application.

2.3 User Permissions

Although MetroViz reports and graphs city data, none of the data can be tracked back to a
single person nor includes sensitive personal information. Therefore, a login and
password is not required to use MetroViz from day to day. However, some DPW and
OMB employees will require write access to the Access database in order to use the input
and change interfaces (see section 3). Based on prior discussions with CIS, we
recommend the creation of a small user group with group-level write access privileges for
the database. Support for logging in and out are recommended improvements when
expanding to another department (see section 6.3.1).

2.4 Database Support

MetroViz uses data from a central Access database file in order to generate graphs and
reports. In order for data to be available for visualization on a timely basis as it is input,
we recommend that a single database file be made available to all users of MetroViz.
This will require ordinary file-level read access to the database file for all users, for
example on a shared network drive. This file is expected to grow at a rate of
approximately 1 MB per 6 months of recorded data. Since this is a relatively small
amount of data, we recommend that the entire database be backed up regularly via
ordinary file backup techniques. A daily backup schedule should be sufficient for
acceptable levels of data integrity.


3. Interfaces
3.1 Graphing Interface

3.1.1 Layout and Overview




   1. Menu Bar
   2. Metric selection
          A. Search/filter box
          B. Metric tree
          C. Expand/collapse
   3. Description
   4. Graph area
           A. Title
           B. Graph - axis, legend, visuals
           C. Data table
           D. Show/hide table
   5. Graph Data
   6. Graph Type
   7. Compare by
   8. Time Axis

3.1.2 Menu Bar

The “File” menu includes general functions such as print, export to excel, and exit. The
“Graph” menu contains functionality related to building and editing graphs, such as
choosing graph type and editing graph options. The “Compare” menu offers an additional
way to choose to compare by years, divisions or totals. The “Favorites” menu allows
users to save (add), load and manage graphs. Finally, the “Help” menu includes
information to assist users in using and navigating MetroViz as well as licensing info.

3.1.3 Metric Selection

This section of the interface deals with selecting metrics to graph. There are two options
for selecting a metric: Searching and Browsing.

3.1.3.1 Search/Filter metrics




When trying to find a specific metric, the user can start typing it into the search box and
the metric tree will update to show only the metrics that contain those keywords. This
method will assist users in finding metrics quickly without sifting through hundreds of
metrics in the tree.

3.1.3.2 Metric tree

Another option to select metrics is to browse through the metric tree. Each category has a
[+] icon next to it to indicate that it can be expanded to see all the metrics associated with
it. Clicking on the icon or double-clicking on the metric title itself will expand the
category. A fully expanded category will have a [-] icon next to it. An expanded category
may be collapsed by clicking on the icon or double-clicking the title itself. The user can
select a metric by selecting it with the mouse to highlight, can use the up, down, left, and
right arrows to scroll through the metrics once a selection has been made, or can use a
control+< and a control+> to move to the previous and next metric respectively.

3.1.3.3 Expand all/Collapse all

The metric tree can become quite intimidating with many categories expanded. If it
becomes difficult to navigate the tree, the user may want to collapse the entire tree to tidy
things up and start fresh. Clicking on the “Collapse All” button will allow the user to
view only high level categories. On the other hand, the user may want to see all the
metrics at once, which can be accomplished with the “Expand All” button.

3.1.4 Description

The description box contains a brief explanation of the metric selected. If more than one
metric is selected, it informs the user what metrics are currently selected. This function is
read-only in MetroViz, meaning that it cannot be edited in this interface. However, the
change interface will allow authorized users to edit and add descriptions.

3.1.5 Graphing Area
This area of the interface is where the graphs will appear when metrics are selected. It is
also where error messages will appear if metrics are unable to be graphed or the data does
not exist to create the graph. If a category is selected, the summary table for that section
will appear in place of an individual graph.

3.1.5.1 Title

If one metric is selected, the title of the graph appears above the data. If more than one
metric is graphed, the title is removed to save space and reduce clutter.

3.1.5.2 Graph axis, legend, visuals

Most of the graph area is reserved for the actual line or bar graph, but other elements help
to make up the entire area. The y-axis adjusts automatically to the units of measure for
the graphed metric and the unit name is displayed vertically on that axis. If there are two
different units used, two different y-axes will appear, one on the far-left and one on the
far-right. Both axes will be labeled accordingly. The x-axis always represents time. The
time range can be adjusted by changing the start and end date in the x- axis control below
the graph (see 8 in the screen shot at the beginning of this document). The data selected
will be represented by a colored bar or line depending on which graph type is selected. If
more than one metric or attribute is selected, e.g. comparing more than one division, a
legend will appear below the graph to explain which data point the lines or bars shown
represent.

3.1.5.3 Data Table

In addition to viewing data visually, the user may also view the data table associated with
a particular graph. This area expands and collapses when the “Show/Hide table” button
next to the x-axis is clicked.

3.1.5.4 Show/Hide Table

To view a data table containing all data points associated with the graph, click on the
show table button. The button label will change to “Hide Table.” To hide the table again,
click the button a second time.

3.1.6 Graph Data

“Actual value,” “Planned value,” “Percent Change,” and “Percent of plan” are all ways of
graphing the metric data. This function is defaulted to actual value, but the user can select
multiple values on the same graph, or flip between views by checking or unchecking the
appropriate checkboxes.

3.1.7 Graph Type
MetroViz supports both line and bar graphs and the user can switch between the two
types using the two radio buttons. If more complex graph types are desired, the user may
choose to export the current graph or data to Excel.

3.1.8 Compare By

MetroViz graphs the total value over an indicated time frame by default, but there are
other ways you may want to view data. Under the compare by function, you can select
“years” to compare by years, e.g. if you wanted to see salt used for January to march with
2005 and 2004 as individual lines on the graph. If you‟d prefer to compare performance
by divisions, you may want to select “divisions.” A series of checkboxes would appear
and there you would check off the divisions you‟d like to compare on the graph.

3.1.9 Time Axis

The time axis controls the x-axis of the graph. It changes depending on what is selected
under “Compare by”. To change the time axis, click on the text box labeled “Start:” A
calendar will appear. Clicking on a date will select that date as the start date. Also,
clicking on the title of the month will allow you to scroll through the months quickly.
Clicking on today‟s date at the bottom of the calendar will also select today‟s date as the
start date. Repeat the action with the text box labeled “End” to set the end date.

3.2 Input Interface

3.2.1 Layout and Overview
   1. Metric Selection area
   2. Description
   3. Data Entry
        A.Data Type
        B.Time Period
        C. Data Value
        D. Add to database
   4. Current Entries
       A. Data Table
       B. Delete Row
       C. Apply changes
   5. Metric Navigation

3.2.2 Metric Selection
The metric tree works just like the main visualization interface to select metrics. In this
case, the user is selecting a metric to either edit the existing data or add new values to the
database.

3.2.3 Description
The description gives more information on what the metric means. It is read-only in this
interface. However, change interface allows a user to edit descriptions.

3.2.4 Data Entry
This area of the interface is where the user can enter new values.

3.2.4.1 Data Type
There are two monthly values that are important to note, planned and actual. Planned
values are what the city budgeted to use that year. Actual is the value that was actually
used per month. These values are essential to calculate such things as % of plan.

3.2.4.2 Time Period
Using calendar controls, the user can set the start and end date for which the value refers.
For instance, if the user enters values for the month of May, 2005 the start date would be
05/01/05 and the end date would be 05/31/05. The user cannot enter values with the same
start and end date of an entry that already exists in the database.

3.2.4.3 Data Value
This is where the user enters the numeric value for the specific data. The units of measure
are noted after the text box. The unit used can be edited in the change interface.

3.2.4.4 Add to Database
Clicking on the “Add” button will add the entered values into the database. The new
entry will appear immediately in the database. The user can also use the “Enter” key to
add the value to the database.

3.2.5 Current Entries
This area of the input interface allows users to edit or delete existing entries in the
database.

3.2.5.1 Data Table
The data table shows past entries that exist in the current database. Entries can be edited
by clicking on the appropriate row or column.

“Start” and “End” indicate the start and end dates of the entry. Clicking on a start or end
date value will bring up a calendar where the user can choose a new date.

In the column labeled “Actual,” a checked box indicates that the value shown is an actual
value, while an unchecked value indicates that it is a planned value. The user may change
the status by checking or unchecking that value directly.

The “Value” column can be edited, simply by clicking in the textbox and typing in a new
value.

3.2.5.2 Delete Row
An entire entry in the data table can be deleted from the database simply by clicking on
the row desired (an arrow will appear on the left-hand side indicating that it is selected)
and clicking on the button labeled “Delete”.

3.2.5.3 Apply Changes
To submit changes to the database, click on the “Apply” button at the bottom of the
screen. If the user clicks on a new metric without clicking “Apply”, they will be
prompted to save changes.

3.2.6 Metric Navigation
The “Previous Metric” and “Next Metric” button helps users move quickly through the
tree of metrics. The user may also interact directly with the metric tree to view or add
values.

3.3 Change Interface

3.3.1 Layout and Overview




 1.   Metric Selection area
 2.   Add new
 3.   Delete
 4.   General information
 5.   Labeling (default graph title for selected metric)
 6.   Units of measure
 7.   Automatic Input
 8.   Apply changes


3.3.2 Metric Selection area
The metric tree works just like the main visualization interface to select metrics. In this
case, the user is selecting a metric to either edit its existing data or adding new metrics or
categories to the database.

3.3.3 Add new
Using the “Add metrics” and “Add category” buttons, the user can create a metric or
category that does not already exist in the database. After completing each section of
data, click on “Apply” to save the changes.

3.3.4 Delete
Select a metric from the tree. Click on the “Delete” button to permanently delete the
metric from the database.

3.3.5 General Information
This area of the change interface allows users to edit general information about the
metric. “Name” refers to how the metric will appear in the metric tree. Description
controls what text appears in the description field in the data visualization interface.
“Type” refers to what section of the current CitiStat template the data belongs in. Options
include: input, output, efficiency, quality, outcomes.

3.3.6 Labeling
The settings in this section have to do with the format of graph titles when one metric is
selected. The “Start Style” refers to how the metric and category are arranged, for
instance <category><metric> means the category appears first with the metric following
it, e.g. “Leaf removal labor hours.” “End Style” appends the information to the format
selected in “Start style.”

3.3.7 Units of measure
The units section of the interface controls what unit of measure the selected metric is
recorded in. This unit can be changed easily by using the dropdown menus next to
“Kind.” The drop down menus specify what type of unit to use, such as weight, and the
specific unit of measure such as tons or pounds.

3.3.8 Automatic Input
Certain metrics in the system can be automatically imported straight from the Foreman
System. The automatic input region allows the user to specify whether a particular metric
should be automatically imported. If the metric can be directly imported the user must
specify the Project Code, Task Code, and the database Column Name that correlates to
where the metric comes from in the Foreman system. Checking the box next to
“Enabled” allows the user to enter this data.

3.3.9 Apply changes
Clicking on the “Apply” button will save any changes made in the current session to the
database. If the user tries to select another metric without clicking “Apply” they will be
prompted to save their changes.
4. Code Overview
4.1 General Overview




4.1.1 MetroViz is a complete system including input, change management, and
visualization features. Each of those major clusters of functionality is represented in a
separate graphical user interface, tailored to the task being performed. However, all of
the interfaces share a common, central data store and basic visual layout.

4.1.2 Data Storage

The heart of MetroViz is a single Access database. All information regarding metrics
and their associated data values is stored in a few simple tables. The application itself,
however, is written in Visual Basic.NET. The most intuitive way to manipulate data in
an object-oriented language such as VB.NET is to represent it as discrete data objects,
rather than as SQL commands and tabular result sets.

The NHibernate library is designed to bridge this gap between data objects and relational
databases through an explicit mapping process. (NHibernate is one of a general class of
tools called "Object-Relational Mapping" or ORM toolkits.) Each data object in
MetroViz is associated with a particular table in the Access database. Properties of VB
objects are represented as data columns in the appropriate table. References between
objects are represented as foreign key columns that link to particular rows of other
database tables. These mappings from object to relational representation are described to
NHibernate in the form of a simple XML document. The figure below shows the
architecture of a simple NHibernate application. (The graphic was borrowed from the
original Java-based Hibernate documentation, but is equally applicable to the .NET
NHibernate port.)
For example, the Metric class in VB is defined in the source file "Metric.vb". Instances
of this class are stored as rows in the "Metric" table of the Access database. The mapping
that describes to NHibernate how to transform the data from VB to Access and vice versa
is stored in the mapping file "Metric.hbm.xml".

In addition to the individual mappings for classes/tables, NHibernate requires some
general setup and configuration information. This includes the connection string for
communication with the database, configuration of the type of database in use, and other
parameters. NHibernate gathers this information from the "App.config" file for the
application. The necessary setup can also be performed explicitly in code during
initialization. MetroViz currently uses the former method, but as the tool is rolled out to
additional departments, the latter method may be preferable.

NHibernate provides a number of sophisticated features to make data persistence a
graceful part of an application's codebase. MetroViz takes advantage of these features as
appropriate, especially "transitive persistence". This feature allows a developer to persist
an entire data structure with a single line of code by automatically following links
between objects and detecting changes. We highly recommend that any developer
wishing to extend MetroViz read the rich set of Hibernate and NHibernate documentation
available online.

4.1.3 Metric Tree

                           The metric tree (shown at the left) is a common element in all
                           three of the graphical interfaces included in MetroViz. This
                           panel is maintained as a integrated set of controls that work
                           together to provide a strong user experience for MetroViz
                           users. Some of the controls are maintained with complete
                           consistency between the three interfaces. For example, the
                           behavior of the search box is the same in the main
                           visualization interface, the change metrics interface, and the
                           data input interface. Certain features of the metric tree are
                           tailored to each interface, however, and require special care in
                           ongoing maintenance. The code that manages the individual
                           components of the metric tree can be found near the top of the
                           VB code for each of the interfaces.

                           The tree in the visualization interface has a special set of
                           requirements in order to support the comparison of multiple
                           metrics at the same time. Multiple-selection was
                           implemented as an extension of the standard Microsoft
                           TreeView control. Since this specialized function was
                           developed with the help of sample code available online
                           which was written in C#, it is separated from the rest of the
                           MetroViz codebase. This code can be found in the
                           TreeViewMS project included with the MetroViz source
                           code. Note that since multiple-selection was only required for
                           the visualization interface, the other two interfaces use the
                           standard Microsoft TreeView included with the .NET
                           Framework.

                           The change metrics interface also has a unique property. It is
                           the only interface which does not include a feature to
automatically expand categories that are clicked upon. This difference is necessary to
support the drag and drop behavior used to reorder metrics in the tree.

4.1.4 Visualization

Drawing dynamic graphs is the centerpiece of the MetroViz system. The code which
drives the calculation and display of these images is arranged as a multi-stage pipeline.
Each step of the pipeline adds richness to the final presentation, checking for errors and
compensating for edge cases along the way. At the center of this pipeline is the
RecalcGraph() method, which drives the overall flow of the process. The end goal is to
properly configure the NPlot library, which handles the actual drawing of graphics to the
screen. The best way to understand the details of this process is to step through the code
for RecalcGraph() and read the code comments describing each step.

4.2 Development Tools

In addition to the development in Microsoft .NET, additional libraries were used to
supplement .NET‟s capabilities. They were chosen because of their free, open source
licenses with sufficient online support if problems were ever to arise. The following two
sections describe these libraries.

4.2.1 NHibernate

4.2.1.1 Overview
NHibernate was chosen for its ability to bridge the gap between Microsoft Access and
Visual Basic objects. Although it began in the java world, it was converted over to .NET
and has a good amount of online support. Additionally, it is open source with no bottle
necks or major requirements for further distribution. As long as NHibernate‟s copyright
statement is included in the About window and in the code distribution, the city of
Pittsburgh is free from any legal liability.

4.2.1.2 Updating
Additional updates or bug fixes may become available online for NHibernate. Although
it can be advantageous to monitor and perform these updates there is no requirement to
do so.

4.2.2 NPlot

4.2.2.1 Overview
NPlot was chosen for its ability to create graphs and charts from data. There is a good
amount of documentation online about NPlot‟s functionality if needed in the future. It is
an open source library that is completely free and easily accessible online. As such, the
city of Pittsburgh has no legal liability for use of distribution of the NPlot code.

4.2.2.2 Updating
NPlot‟s development staff is very good at quickly turning around bug fixes that occur and
are submitted. Fixes and updates are available online and it will be beneficial to monitor
these updates and keep the library as up to date as possible.

5. Database

5.1 Overview and Structure
The database is a central and vital part of Metroviz. It is organized into ____ tables that
include all of the metrics and information that DPW report to the CitiStat team to
complete the template file. The database is necessary for creating the graphs, as well as
creating the Excel documents used for reporting.
It is our intent that the majority of metric maintenance can be completed in the change
and input interfaces requiring little to be done by hand in the actual database tables. If
such a need does arise, the following sections will describe each of the columns and the
naming conventions associated with them.

5.2 “Metric” Table

5.2.1 Overview
The “Metric” table contains all of the metrics reported to CitiStat and maintains all
information associated with each of those metrics in terms of the order it should be
displayed in the metric tree, where the metric comes from in the foreman system, the
units that it is reported in, etc. Each of the table‟s columns are explained in detail below.

5.2.2 Column Explanations

5.2.2.1 MetricID
“MetricID” is an automatically generated number in the Access Database created in the
order the metrics and categories were manually entered into the database. With a few
exceptions the numbers are continuous from 1 to the current number of lines in the
database at the time of delivery. With the addition or deletion of metrics from the
database (see input and change interface user documentation) the MetricID numbers will
add or change accordingly.

5.2.2.2 name
The “name” column in the database refers to the name of the metric or category that will
be displayed in the metric tree of each of the three interfaces (graphing, input, and
change). This can also be viewed as the shortest possible description of the metric or
category that is still understandable. It can be maintained using the change interface.

5.2.2.3 description
The “description” field of the table is reserved for other information that may be vital for
a metric. This field is meant to help communication between DPW and CitiStat by
displaying explicitly how the metric is calculated or tracked. It can be maintained using
the change interface.

5.2.2.4 ParentID
The “ParentID” is a number that corresponds to the parent of a particular metric. This
number is used to determine the hierarchy of the metric tree and the children of a
particular category. This column should require minimal maintenance in the database
since it is done automatically by NHibernate when a user updates the hierarchy in the tree
using the change interface.

5.2.2.5 sort_order
The “sort_order” column describes the order in which items are sorted under each
category in the metric tree. The numbers ascend from 0 being the first item displayed to
the highest number being the last item displayed. This is used in sorting the order the
categories are displayed as well as the metrics underneath particular categories.
Changing the sort order of the tree can be accomplished in the change interface and it is
recommended that any updates or changes should be done there.

5.2.2.6 UnitID
The “UnitID” column includes a number that links to the Unit table in the access
database. The number refers to the units of measure that a particular metric is reported
in. See the Unit table description for further information.

5.2.2.7 metric_type
In the CitiStat Template (Excel document) used for reporting and tracking DPW‟s
metrics, each of the metrics was divided into sections of inputs, outputs, efficiency,
quality, and outcomes. Respectively, these are represented by 0, 1, 2, 3, and 4 in the
database. 5 is reserved for other objects in the database that do not belong to those
sections such as category headings in the metric tree. This information is vital when
exporting information to an Excel document because it gives an order for how they are
displayed in Excel.

5.2.2.8 start_name, end_name
The two columns “start_name” and “end_name” together represent how the metric name
and vital information is displayed as a title of the graph. For example, sometimes it is
sufficient to have only the metric name, whereas other times (e.g. labor hours) more
information is required to be sufficient as a graph title.

start_name includes the numbers 0, 1, 2 and represent the following:
        0 – metric name only
        1 – display the parent name of the metric followed by the metric name
        2 – display the grandparent name of the metric followed by the metric name

end_name includes the numbers 0, 1, 2 and represent the following:
      0 – no other information is necessary
      1- append to the start_name the word “for” plus the parent name
      2 – append to the start_name the word “for plus the grandparent name

For two examples of how this works consider the following start_name, end_name
combinations:
       1) 0, 0 could represent only “salting/plowing” as a title – the metric name with no
               other information.
       2) 1, 2 could represent “labor hours salting/plowing for snow and ice removal” as
               a title – the parent name of the metric, followed by the actual metric,
               followed by its grandparent name.

5.2.2.9 accumulate
The “accumulate” column contains only check boxes. If checked (the default) this means
that the percent of plan for a particular metric accumulates over the entire year and not
just on a per month basis as is the case for some metrics.
5.2.2.10 automatic
The “automatic” column contains only check boxes and refers to if the information can
be obtained directly from DPW‟s Foreman System. If checked, this is true and the
information is pulled directly from the Foreman System using the project_code,
task_code, and column_code that are explained in the following three sections.

5.2.2.11 project_code
The “project_code” column is used if the metric for that row can be obtained directly
from DPW‟s Foreman System. The numbers represent the project code in the Foreman
System that a particular metric is reported under. When obtaining information from the
Foreman system is not possible, the column is set to zero (the default).

5.2.2.12 task_code
The task_code number refers to which particular task in the Foreman system correlates to
the metric being reported for CitiStat. It can also be considered the row in a Foreman
report that contains the metric information desired. In some cases, such as “total costs” a
particular metric is not needed but the sum of a particular column from a Foreman
System report. In such cases, a zero is used to signify this. Zero is also used as the
default when the information cannot be obtained from the Foreman System.

5.2.2.13 column_code
The column_code specifies the particular column in a Foreman System Report where the
metric information is located. There are 7 possible numbers that can be used that
correlate to the columns of a Foreman Report. They are as follows:

       1 – Units-Complete
       2 – Hours
       3 – Labor
       4 – OT-Labor
       5 – Matl-Cost
       6 – Equip-Cost
       7 – Total Cost
       8 – Unit Avg

5.2.3 Naming Conventions
The naming conventions of the metric table refer only to the titles of the individual
columns and particularly to the “name” column which specifies the names of the metrics
that appear in the metric tree.

5.2.3.1 Column Headings
The column headings in the Metric table are all in lower case unless that particular
column links to another table in the database. For example “UnitID” links to the “Unit”
table.

5.2.3.2 Metric names
The metrics are named in such a way to ensure consistency and conciseness throughout
the metric tree. To ensure similar form, the following conventions were established:

5.2.3.2.1 Abbreviations
Abbreviations were necessary since the metric tree has limited space and some of the
metric names are very long.
    1. Use “w/in” instead of “within”
    2. Use “24hrs” instead of “24 hours”
    3. Use “avg” instead of “average”
    4. Use “#” instead of “number of”
    5. Use “%” instead of “percentage of”
    6. Use “&” instead of “and”

5.2.3.2.2 Capitalization
To help distinguish between categories of metrics and the actual metrics, capitalization
was used selectively for this purpose.
    1. Categories have mixed caps (e.g. Streets, Forestry)
    2. Metrics are all lower case (e.g. # stop bars & crosswalks painted)

5.2.3.2.3 Units
The units of measure were not included in any metric name to make the maintenance of
the database and metric tree simpler. However, to maintain the meaning of the metrics,
the following conventions were established:
    1. Units of measure will not be used in the metric name or description
    2. Use “per unit amount” or “per length of” for maintenance reasons
    3. Use “amount of” or “length” as general indicator

5.3 “MetricData” Table

5.3.1 Overview
The “MetricData” table is utilized with the input interface. Information submitted in the
input interface is appended to the bottom of this table and utilized in creating graphs.

5.3.2 Column Explanations

5.3.2.1 MetricDataID
The numbers in this column are used solely as identifiers. The numbers are irrelevant
(they start at an arbitrary 760) as long as they are unique. This number is automatically
created when the user submits a metric with the input interface.

5.3.2.2 MetricID
The MetricID column links back to the Metric table to specify the specific metric the data
belongs to. This number is automatically generated when the user submits a new record
using the Input Interface.

5.3.2.3 start_date
The start_date column specifies the starting date for which the data applies and is
automatically created with the data specified in the Input Interface at the time of
submission.

5.3.2.4 end_date
The end_date column specifies the starting date for which the data applies and is
automatically created with the data specified in the Input Interface at the time of
submission.

5.3.2.5 actual
The “actual” column contains only check boxes and is check if the data submitted is the
actual metric value. It is unchecked if the value entered refers to planning data.

5.3.2.6 value_num
The value_num column contains the value of the data being submitted by the Input
Interface and is updated automatically at the time of submission.

5.3.2.7 UnitID
The UnitID column links to the Unit table and refers to what units the metric is recorded
in. Currently, everything in this column is set to the default 1 which means “none.”
However, each of the metrics in this table take on the UnitID of their associated metric in
the Metric table. Therefore, no additional maintenance is needed. However, in the future
if conversion of data units is desired than this column can be used for that purpose.

5.3.3 Naming Conventions
There are no naming conventions for the individual cells of this table. However, the
column headings follow those outlined in section 5.2.3.1.

5.4 “Unit” Table

5.4.1 Overview
The “Unit” table keeps track of the units of measure for each metric. It is linked with the
Metric table.

5.4.2 Column Explanations

5.4.2.1 UnitID
The UnitID number is a unique identifier that is automatically created when a new row is
created. It is also the number that the Metric table refers to in calling for information.

5.4.2.2 long_name
The long_name is the standard name for this unit of measure and is used as the default y-
axis name for the graph created.

5.4.2.3 short_name
The short_name is a shorter, more concise version of the long_name that is used in
reports.

5.4.2.4 kind
The “kind” number is an ID string that the VB code utilizes. See the code file “Unit.vb”
for a list of the acceptable values and to learn more about how this is implemented. The
value of 1, which represents “None” has special importance, since it is used to distinguish
categories (which do not have associated data) from normal metrics.

5.4.3 Naming Conventions
There are no naming conventions for the individual cells of this table. However, the
column headings follow those outlined in section 5.2.3.1.

5.5 Updating

5.5.1 Overview
The database needs to be regularly updated in order to have the most recently available
data from the DPW Foreman System. Otherwise, the graphs that are created may not
have the most recent data to graph or may be incorrect. With each update, the access
database would continue to include the historical data that is needed for creating graphs
from past years. Thus, the database will continue to grow. With the current tree of
approximately 250 metrics, the database will grow at an expected rate of approximately
1MB each 6 months.

5.5.2 General Process
DPWs Foreman System produces reports for a specified time range that provides the data
tracked during that period. With each update the access database Metric table will use
the project_code, task_code, and column_code columns to fetch the most recent
information. Because both DPW and OMB analysts will be utilizing the system, it will
be advantageous to place the MetroViz system on a citywide drive, as opposed to an
internal department drive, and hold access to it.

5.5.3 Recommended Updating Schedule
We recommend maintaining a nightly batch process that has access to both the front end
database of the Foreman System and to the MetroViz access database. This should not
require anything on the Oracle side to change.


6. Future Implementation

6.1 Overview
We envisioned a system that was a starting point – a starting point that may need
additions or further implementation as time and management changes. This section
outlines some of the possible development areas.

6.2 Implementing Another Graph Type
It may be beneficial to add to the existing MetroViz system an additional graph type such
as pie chart, which OMB has used for its briefing books from time to time. To this will
require you to add a new radio button to the two which currently select between line and
bar charts, add a matching menu item, and extend the RecalcGraph() and
ChangeGraphType() methods to setup NPlot appropriately to draw the new type of graph.
This can be accomplished by using one of the other available subclasses of the IPlot
interface.

6.3 Extending to Another Department

6.3.1 Login
First and foremost, we recommend implementing logging in and out. In the long run, this
will make expanding to another department much simpler. Without this, each department
will have to have its own unique MetroViz which would be detrimental to the OMB
analysts.

6.3.2 General Implementation Procedure
For expansion to another department, we recommend creating an entirely new database
for another department. Copying the existing file should be sufficient. Most of the
columns should remain the same but a few will change (see section 6.3.3). After deleting
all of the metrics from the prior department (in this case DPW) leave only the “root”
metric. The users can then use the Change Interface to enter in all metric information
needed, essentially setting up the database on their own. This requires a change to the
app.config that has the connection string for the location of the database. We recommend
setting the app.config at runtime by popping up a dialogue box asking the user which
department they would like to view. By logging in, the user could then have access to as
few or as many departments as necessary. The specifics of this expansion are explained
in the following sections.

6.3.3 Graphing Interface
As a general rule, the graphing interface should have few changes and should be used as
a guideline for the next department‟s interface. The CitiStat CMU team developed
MetroViz with further expansion in mind, so the interface should be the easiest part.

6.3.3.1 Menu Bar
We expect the title bar to change very little through the course of expansion to another
department.

6.3.3.2 Metric Tree Functionality
No additional changes need to be made in the Visual Basic code to update the metric tree
for a new department. Changing metric order, values, names, or adding new can all be
done utilizing the change interface. See documentation on the Input Interface in the User
Document. We do not foresee the search functionality, or collapse and expand all buttons
changing.

6.3.3.3 Time Axis
We do not foresee the time axis functionality needing to change for expansion to another
department.

6.3.3.4 Graphs
We do not foresee the graph functionality needing to change for expansion to another
department. This includes the functionality for data tables and the hide/show table
button.

6.3.3.5 “Graph Data” Group Box
Depending on what another department reports to the OMB and CitiStat the “Graph
Data” group box may require changing. The titles of the group box are easily changed in
the VB form designer. Changes made in this section should also be reflected in the menu
bar (see section 6.3.3.1). The enumeration of data types at the top of the MainForm.vb
file should be updated, and the actual calculation of the new data should be performed in
the aptly-named ComputeData() method.

6.3.3.6 “Graph Type” Group Box
Unless another type of graph is implemented for another department, no changes are
necessary for expanding MetroViz to another department. Adding an additional graph
type is explained in section 6.2. Changes made in this section should also be reflected in
the menu bar (see section 6.3.3.1).

6.3.3.7 “Compare By” Group Box
Depending on what another department reports to the OMB and CitiStat the “Compare
By” group box may require some minor changes. We do not foresee “totals” or “years”
changing, but another department may not be divided into meaningful divisions to graph.
In this situation you may either decide to gray out the option so that it is unclickable or
may want to hide the option all together. In either case, these changes should be easy to
accomplish via the VB form designer and the appropriate Click event handlers.

6.3.4 Input Interface
No changes to the input interface are expected for an extension to another department.

6.3.5 Change Interface
Regardless of the implementation approach taken (see section 6.3.2) a lot of the
expansion to another department can be done in this interface by the eventual users.

6.3.5.1 Adding a New Department‟s Metrics
Once a new database has been set up with a root item (see section 6.3.2 and 6.3.6.1), the
metrics that will be reported can be added by using the “add category” and “add metric”
buttons. This can be done with users of the system and will not require additional
programming time.

6.3.5.2 Metric Tree Functionality
No additional changes need to be made in the Visual Basic code for the metric tree in
order to use this interface to expand to another department. We do not foresee the search
functionality, or collapse and expand all buttons changing.

6.3.5.3 Metric Type
Depending on how the other department reports their metrics to the CitiStat team,
changes in the type may be necessary. Currently there are six options which correspond
to how the metrics are recorded in the CitiStat Template (see section 5.2.2.7). If recorded
differently than (inputs, outputs, etc.) then additional categories will need to be added for
the new department. Adding additional numbers will not affect the “Metric” table of the
access database (see section 5.2.2.7) but will require changing the VB code. To make
these changes, go to „Metric.vb‟ class and add a type to the Metric.Kinds enumeration.
Take note not to change the order of the existing numbers, as that will cause the current
data to be misinterpreted.

6.3.5.4 Labeling Style
It is the hopes that no additional work will be needed on this section to expand to another
department. The nine possible combinations should suffice for almost all other
combinations that are possible in other departments.

6.3.5.5 Unit Options
The CitiStat CMU team has no reference as to the metrics reported by other departments
within the city of Pittsburgh. Therefore, if additional units of measure of the existing
kinds (Length, area, volume, etc) are required in another department, they needed to be
added in the “Unit” table of the access database (see section 5.4). If new units of a kind
different from the existing ones is needed, first assign a number to the new unit kind and
add the new unit kindto the Unit.Kinds enumeration in „Unit.vb‟ class. Then add the unit
using the new unit kind in the “Unit” table of the access database.


6.3.5.6 Automatic Input
Automatic Input will be useful if the next department utilizes a database where CitiStat
reported metrics can be automatically pulled for MetroViz. The Automatic Input section
is currently set up for users to specify from where in DPWs Foreman System a metric can
be found (see sections 5.2.2.11-13). Depending on the database that is used by another
department, the options for automatic input will have to change to reflect what is
necessary to pull data automatically. In addition to changing the “Metric” table in the
access database accordingly, the “HandleSelect()” and “SaveChanges()” functions in the
ChangeInterface.vb code will have to be altered to enable loading saving of those
additional options.

6.3.6 Database
Although the database structure should remain the same, some of the individual tables
will likely require minor adjustments. These are listed in the following sections.

6.3.6.1 “Metric” Table
The “Metric” table should remain mostly intact, but will depend on how the new
department tracks and reports their metrics to the CitiStat team. Begin with a fresh copy
of the database with only the “root” metric included. Otherwise, the columns that are
likely to change are as follows:

6.3.6.1.1 UnitID
The UnitIDs which are used for DPW may not be sufficient to support a new department.
In this case additional numbers can be used once updated to the “Unit” Table (see section
5.4 for a detailed description of the Unit Table).

6.3.6.1.2 Project, Task, and Column Codes
As mentioned above in section 6.3.5.6 these codes are used to describe how data is pulled
automatically from DPW‟s Foreman System. If another department uses a different
database, these columns will likely not be sufficient for describing exactly where the new
data comes from. If this is the case, then these columns will have to change to sometime
that makes more sense for the new department‟s database (to include new names and
less/more columns if necessary).

6.3.6.2 “Unit” Table
Minimal to no updates to the “Unit” table are expected. In expanding MetroViz to
another department if you find that there is not a unit of measure that correctly
corresponds to something needed, simply create a new one based on the guidelines
outline in section 5.4.

6.4 Recommendations for Future Development
Future development or expansion of MetroViz features is certainly possible. Depending
on the direction management or analysts choose, some of the possible areas of future
development are outlined below.

6.4.1 Edit Menu
The Edit Menu was originally built into the main title bar, but was made invisible as
deadlines for delivery approached. To make it visible and start implementing its features,
code must be added to determine which control has the current focus and to trigger the
appropriate type of Copy or Paste operation, etc. The Me.ActiveControl property on each
form should be particularly useful for this purpose.

6.4.2 Notes and Contact Information
One thing the CitiStat CMU team had envisioned was a system that promoted better
communication between DPW and OMB about the particular meanings of metrics and
who to contact if there was a discrepancy. There is a right click context menu
implemented for the metric tree but it was disabled prior to delivery. Additional
functionality can be added to this feature by re-enabling this menu and providing Click
event handlers to perform the appropriate functions. We recommend that contact
information be stored in a separate table in the database and linked to the Metric table via
a foreign key. This relationship would be similar to that used to link Metric and Unit. A
complete implementation would require a new table (named “Contact”, perhaps), a
corresponding VB object, a mapping file for the new object, a new property in
“Metric.vb”, and a corresponding mapping line in “Metric.hbm.xml”. Finally, the
Change Metric interface should be extended with a new group box and appropriate
controls to edit the new Contact information.

								
To top