VIEWS: 125 PAGES: 25 POSTED ON: 11/11/2011
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. 220.127.116.11 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. 18.104.22.168 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. 22.214.171.124 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. 126.96.36.199 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. 188.8.131.52 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. 184.108.40.206 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. 220.127.116.11 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. 18.104.22.168 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. 22.214.171.124 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. 126.96.36.199 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. 188.8.131.52 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. 184.108.40.206 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. 220.127.116.11 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”. 18.104.22.168 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 22.214.171.124 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. 126.96.36.199 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 188.8.131.52 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. 184.108.40.206 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 220.127.116.11 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. 18.104.22.168 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. 22.214.171.124 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. 126.96.36.199 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. 188.8.131.52 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. 184.108.40.206 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. 220.127.116.11 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. 18.104.22.168 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. 22.214.171.124 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. 126.96.36.199 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. 188.8.131.52 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). 184.108.40.206 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. 220.127.116.11 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. 18.104.22.168 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. 22.214.171.124 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: 126.96.36.199.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” 188.8.131.52.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) 184.108.40.206.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 220.127.116.11 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. 18.104.22.168 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. 22.214.171.124 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. 126.96.36.199 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. 188.8.131.52 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. 184.108.40.206 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. 220.127.116.11 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 18.104.22.168. 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 22.214.171.124 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. 126.96.36.199 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. 188.8.131.52 short_name The short_name is a shorter, more concise version of the long_name that is used in reports. 184.108.40.206 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 220.127.116.11. 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. 18.104.22.168 Menu Bar We expect the title bar to change very little through the course of expansion to another department. 22.214.171.124 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. 126.96.36.199 Time Axis We do not foresee the time axis functionality needing to change for expansion to another department. 188.8.131.52 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. 184.108.40.206 “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 220.127.116.11). 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. 18.104.22.168 “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 22.214.171.124). 126.96.36.199 “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. 188.8.131.52 Adding a New Department‟s Metrics Once a new database has been set up with a root item (see section 6.3.2 and 184.108.40.206), 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. 220.127.116.11 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. 18.104.22.168 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 22.214.171.124). 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 126.96.36.199) 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. 188.8.131.52 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. 184.108.40.206 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. 220.127.116.11 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 18.104.22.168-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. 22.214.171.124 “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: 126.96.36.199.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). 188.8.131.52.2 Project, Task, and Column Codes As mentioned above in section 184.108.40.206 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). 220.127.116.11 “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.
Pages to are hidden for
"maintenance"Please download to view full document