Track+ Developers Manual

Transcription

Release 5.1
Track+
Developers Manual
Track+
Developers Manual
Steinbeis GmbH & Co. KG
Task Management Solutions
Eugen-Ruoff-Str. 30
D-71404 Korb
Germany
Tel.: +49 7151 994 89-60
Fax: +49 7151 994 89-61
Support: [email protected]
No part of this publication may be reproduced, stored in a retrieval system or transmitted in any form or by any means, electronic,
mechanical, photocopying, recoding, scanning or otherwise except as permitted under Sections 107 or 108 of the 1976 United States
Copyright Act, without the prior written permission of the Publisher.
Track+ and the Track+ logo are trademarks of Steinbeis GmbH & Co. KG, and may be registered in certain jurisdictions. The absence
of a trademark from this list does not constitute a waiver of Steinbeis’s intellectual property rights concerning the trademark. All other
company, brand and product names may be trademarks or registered trademarks of their respective holders. Steinbeis disclaims any
responsibility for specifying which marks are owned by which companies or which organizations.
Copyright © 2001-2016 Steinbeis GmbH & Co. KG, All rights reserved
June 2016
If you have any comments or suggestions regarding this document, please send them by e-mail to [email protected].
Contents
1 Introduction
1.1 Target Audience. . . . . . . .
1.2 Getting the Tools . . . . . . .
1.3 Download Executable . . . .
1.4 Download Source Code . . .
1.5 Setting up Your Environment.
1.6 Setting up Eclipse IDE. . . . .
1.7 Build Targets. . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
2 Structure and Behavior
2.1 Basic Structure . . . . . . . . . . . . . . . . .
2.1.1 The main/groovy Directory . . . . . . .
2.1.2 The main/java Directory . . . . . . . .
2.1.3 The main/resources Directory . . . . .
2.1.4 The main/webapp Directory . . . . . .
2.1.5 The main/webapp/dbase Directory . .
2.1.6 The main/webapp/design Directory . .
2.1.7 The main/webapp/js Directory . . . . .
2.1.8 The main/webapp/tiles Directory . . .
2.1.9 The WEB-INF/lib Directory . . . . . . .
2.2 Package Structure Overview . . . . . . . . . .
2.2.1 The persist Package . . . . . . . . . . .
2.2.2 The user Package . . . . . . . . . . . .
2.2.3 The report Package . . . . . . . . . . .
2.2.4 The item Package . . . . . . . . . . . .
2.2.5 The notify Package . . . . . . . . . . .
2.2.6 The lucene Package . . . . . . . . . . .
2.2.7 The admin Package . . . . . . . . . . .
2.2.8 The resources Package . . . . . . . . .
2.2.9 The util Package . . . . . . . . . . . . .
2.2.10 The plugin Package . . . . . . . . . . .
2.2.11 Application Entry Point . . . . . . . . .
2.3 Program Execution . . . . . . . . . . . . . . .
2.3.1 System Initialization . . . . . . . . . . .
2.4 Schema Description . . . . . . . . . . . . . .
2.4.1 Access Control. . . . . . . . . . . . . .
2.4.2 Items and Fields . . . . . . . . . . . . .
2.4.3 Fields and Field Changes . . . . . . . .
2.4.4 Project and Item Type Specific Settings
2.4.5 System . . . . . . . . . . . . . . . . . .
2.4.6 Mask Definitions. . . . . . . . . . . . .
iii
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
1
1
1
2
2
2
2
4
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
5
5
6
6
6
6
7
7
7
7
7
7
8
9
9
9
9
9
9
9
9
9
10
10
11
11
11
11
11
12
12
12
Contents
2.4.7
2.4.8
2.4.9
2.4.10
2.4.11
2.4.12
2.4.13
2.4.14
2.4.15
Cockpit Configuration . . .
Custom Field Configuration
Automail. . . . . . . . . . .
Accounting . . . . . . . . .
Queries . . . . . . . . . . .
Reports . . . . . . . . . . .
Project Configuration . . . .
Obsolete Tables . . . . . . .
Plug-Ins . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
13
13
13
14
14
14
15
16
18
3 Accessing Data
3.1 Overview . . . . . . . . . . . . . . .
3.2 Counting Items . . . . . . . . . . . .
3.3 Retrieving Managers Items . . . . . .
3.4 Adding Custom Field Values to Issues
3.5 Ensuring Access Control . . . . . . .
3.6 Accessing History Data . . . . . . . .
3.7 Adding or Modifying Tables . . . . .
3.8 Adding Pages . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
21
21
21
22
23
24
24
26
26
Index
28
iv
List of Figures
1.1 Configuring the Tomcat server step 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1
2.2
2.3
2.4
2.5
2.6
2.7
2.8
2.9
2.10
2.11
2.12
2.13
2.14
2.15
Top level directory structure . . . . . .
Deployment assembly . . . . . . . . .
Access control. . . . . . . . . . . . . .
Items and Fields. . . . . . . . . . . . .
Fields and field changes . . . . . . . .
Project and item type specific settings.
System. . . . . . . . . . . . . . . . . .
Mask definitions. . . . . . . . . . . . .
Cockpit configuration. . . . . . . . . .
Custom field configuration . . . . . . .
Automail. . . . . . . . . . . . . . . . .
Accounting . . . . . . . . . . . . . . .
Queries . . . . . . . . . . . . . . . . .
Reports . . . . . . . . . . . . . . . . .
Project configuration . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
v
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
3
3
4
5
6
12
13
14
15
15
16
16
17
17
18
19
19
20
1
Introduction
1.1 Target Audience
This manual is for those that like to
• contribute actively to the development of Track+
• write custom plug-ins for Track+
This manual is not written for end users. Familiarity with development of web enabled Java applications and
JavaScript is assumed.
1.2 Getting the Tools
To develop software for Track+ you need the following tools:
1. A recent computer with at least 8 GB main memory and an SSD
2. Java JDK 7 or 8
3. Apache Tomcat Server 7 or 8
4. Gradle
5. Eclipse J2EE Developer Edition or another Java development environment
6. On Windows computers cygwin for decent command line shell
7. Firebird or MySQL Database
8. Database administration tool like Flamerobin for Firebird or MySQL Workbench
If you participate in the core development you need in addition to the above
1. Subversion client like SmartSVN or Tortoise
2. NSIS for the Windows installer
3. A developers license for Sencha ExtJS
Make sure the ”’gradle”’ command is in your command line shell path.
1
1.3. Download Executable
1.3 Download Executable
Download the current version of Track+ and get it to run on your development computer. You can use the
Windows installer for quick setup. You can also do a manual install as described in the installation manual.
Get yourself familiar with the application so you later on have some idea what the system does.
1.4 Download Source Code
When you participate in the core development, you will get access to the source code. The information how
to access the source repository will be provided to you by your mentor. Before you contact him make sure
you have the tools listed above up and running on your computer.
If you are not part of the core development team and your license agreement includes access to the source
code for plug-in and extension development you will get a ZIP or TAR archive with source code and a build
script. This is to enable you to study the Track+ interfaces and implementation behind them and see how
the built-in plug-ins have been realized so that you can build your own.
For the core development you need to obtain the trunk of the repository with all projects. We assume you
have copied it to directory $WSROOT on your computer.
1.5 Setting up Your Environment
Track+ is built using Gradle. All environment variables are contained in a single properties file under $WSROOT/
com.trackplus/build.properties. There are development platform specific settings in files $WSROOT/
com.trackplus/buildwin.properties (for Windows) and $WSROOT/com.trackplus/buildux.properties (for Unix based systems).
Configure $WSROOT/core/com.trackplus/build.properties and the platform-specific build file according to where you have the different tools and your workspace installed. The platform specific property files are copied by the build script two directory levels up if they do not exist there yet. If the files
$WSROOT/buildwin.properties etc. exist you need to change those and not the ones in $WSROOT/
core/com.trackplus.
Check that you have a running database server like MySQL or Firebird. Create an empty database and make
a note of the database user, password, database type, and database name.
1.6 Setting up Eclipse IDE
Before you start Eclipse for the first time make sure that it has sufficient memory available. You can set this in
file eclipse.ini (here an excerpt):
...
--launcher.XXMaxPermSize=768m
...
-XX:MaxPermSize=768m
-Xms256m
-Xmx1024m
2
Chapter 1. Introduction
Obtain and install the Gradle (STS) plugin for Eclipse from the Eclipse market place.
Next start Eclipse and import the projects into your workspace.
Define a new server via File > New > Server. Select ”’Apache Tomcat 7”’ or ”’Apache Tomcat 8”’ as the type
and configure the runtime environment so that it points to the Tomcat server you have installed previously.
Open a terminal window so that you have a command line (shell). Then proceed as follows:
1. Go to $WSROOT/core/com.trackplus.libs/jsonlibs. Execute ”’gradle assemble”’.
2. Go to $WSROOT/core/com.trackplus.libs/daisydiff. Execute ”’gradle assemble”’.
3. Go to $WSROOT/core/com.trackplus.core. Execute ”’gradle tpjar”’.
4. Go to $WSROOT/plugins/com.trackplus.plugins. Execute ”’gradle eclipse”’ and then ”’gradle assemble”’.
5. Repeat the last step for $WSROOT/plugins/com.trackplus.plugins.license and the two scm
plugins.
6. Go to $WSROOT/core/com.trackplus.webservice.core. Execute ”’gradle assemble”’.
7. Go to $WSROOT/core/com.trackplus.webservice.client. Execute ”’gradle assemble”’.
8. Go to $WSROOT/core/com.trackplus.core. Execute ”’gradle eclipse”’.
9. Refresh your Eclipse workspaces and correct any remaining build path problems.
Refresh your Eclipse workspaces and correct any remaining build path problems. In the Eclipse J2EE view
click on the Server tab. Double click on the Tomcat server that should show there.
Figure 1.1: Configuring the Tomcat server step 1
Click on Open launch configuration in the upper left part of the screen. Click on ”’Arguments”’ and make
sure you have the following VM arguments defined in addition to those that are already there:
-XX:PermSize=196M -XX:MaxPermSize=384M -Xms256M -Xmx1024M
3
1.7. Build Targets
Furthermore add the path where all configuration files, templates, and plug-ins are to be stored): -DTRACKPLUS_HOME='/opt/trackplus'.
1.7 Build Targets
During development you would typically compile and deploy directly from within your IDE. If you want to
use the command line go to directory $WSROOT/core/com.trackplus. To get a list of all available build
tasks type
gradle tasks
To execute any task type
gradle <task>
4
2
Structure and Behavior
This chapter gives an overview over the application structure in com.trackplus.core and takes you on a
short tour through the source code of the system. It explains the major parts and roughly how things work.
You should be familiar with general J2EE development.
2.1 Basic Structure
Note: The paths and files mentioned from here on are below $WSROOT/core/com.trackplus.core/
src/main.
Figure 2.1 shows the top level directory structure.
Figure 2.1: Top level directory structure
Figure 2.2 shows how the various source directories are mapped to the servlet containers directory structure.
Track+ uses three main frameworks:
• Struts 2 as a Model-View-Controller Framework
• Apache DB Torque as a persistence layer
• Sencha ExtJS for JavaScript user interface
The main configuration files for these frameworks are
5
2.1. Basic Structure
Figure 2.2: Deployment assembly
• resources/struts.xml for the Struts 2 framework and all pages created with that framework
• torque/schema/track-schema.xml for the Torque persistence layer generator. This file contains
the schema definition for the persistence layer and is only being used by the Torque generator. It is
required when the database schema needs to be modified.
2.1.1 The main/groovy Directory
This directory contains sample Groovy scripts for workflow tasks, like changing a responsible person, copying
items or closing an item.
2.1.2 The main/java Directory
This directory contains all Java source files. For a description of the various packages please refer to the Java
API documentation.
2.1.3 The main/resources Directory
This directory contains resources for the Track+ application like
• Default localization files
• Default mail templates
• The configuration files for Struts, Log4j, and the default Track+ plug-ins (trackplus-plugin.xml)
• Configuration files for JasperReports and JFreeChart
• Images and templates for plug-ins (link type, field type, cockpit tiles, etc.)
• The default plug-in packages (.tpx files)
2.1.4 The main/webapp Directory
This directory contains most of what goes into the applications root context directory on the server, in particular the JSP files, the JavaScript files, style sheets, and the WEB-INF directory containing the web.xml servlet
container configuration file, and the Torque persistence layer and definition of the JDBC database connection
(Torque.properties).
6
Chapter 2. Structure and Behavior
2.1.5 The main/webapp/dbase Directory
The dbase directory contains the initialization and migration SQL scripts for the different database systems.
There is a subdirectory for each supported database system.
Each database server specific directory contains the schema definition files track-schema.sql and id-table-schema.sql
for the current state of the database, and upgrade scripts which are used for upgrading the database from
previous versions.
The id-table-schema.sql file usually does not change between releases, just its content. The track-schema.sql
files are generated by the ”’torque”’ task. This target only needs to be executed when the database structure
in torque/schema/track-schema.xml has been changed.
2.1.6 The main/webapp/design Directory
This directory contains all design related items of Track+ , for example style sheets, images and icons used by
the system. Each design is contained completely in a suitable sub directory of the design directory. Currently,
there is only the”’silver”’ design available.
2.1.7 The main/webapp/js Directory
The js directory contains all JavaScript files used by Track+ . Track+ uses the ExtJS framework for most
JavaScript related code. One of the most important files in there is borderLayout.js.
2.1.8 The main/webapp/tiles Directory
The tiles directory contains JSP files used to render the HTML pages seen in the browser. The overall main
layout which pulls in most JavaScript libraries, resources, and style sheets is in layouts/BorderLayout.jsp.
2.1.9 The WEB-INF/lib Directory
The lib directory contains some of the JAR files with packages that are being used by Track+ . During development it needs to be in the class path. It is placed under WEB-INF/lib in the deployment directory on the
servlet container. Most publicly available libraries are pulled from a Maven repository into the local Gradle
cache. These libraries are being copied into the WAR file during the build process.
The Track+ lib directory contains some JDBC drivers for the different database systems. For those systems
that do not have a ready to use JDBC driver already included (e.g. with Oracle) it needs to be downloaded
and placed into this directory.
2.2 Package Structure Overview
The src directory contains all Java source code of Track+ . It is divided into different packages which are
briefly described below.
The root file of Track+ is a servlet which is started by the servlet container. This file can be found in the
com.aurel.track.dbase package and is named StartServlet.java. Everything is rooted from here.
This servlet is called via web.xml
7
2.2. Package Structure Overview
2.2.1 The persist Package
The persist package contains all classes pertaining to the persistance layer. The persistance layer represents
an object view of the database entities. For each table in the database there are seven classes:
• two classes representing the table, called the peer class (for example TPersonPeer and BaseTPersonPeer)
• two classes representing a single row in a table (for example TPerson and BaseTPerson)
• two classes representing simple beans for each single row in the table (for example TPersonBean and
BaseTPersonBean). These classes are plain Java Beans and have no persistence related functionality.
They are therefore placed in a separate package at com.aurel.track.beans.
• a map class containing the mapping between the object and the database table and attribute names
The map classes and BaseXX classes are automatically generated when executing the torque build target and
should thus not be manually modified. The Txx classes are not overwritten by the torque generation process.
They contain the user defined behaviour of the objects. If new tables are added to the database schema, the
newly generated Txx and map classes need to be manually copied from directory torque/java where they
are generated to the target directory in the persist package.
To facilitate migration to another persistence layer if required, there is an abstraction interface layer for the
actual Torque peer classes. It is best practice to work with the database through the interface rather than with
the persist package classes themselves. The interface is defined in com.aurel.track.dao. The interfaces
should also document the functionality of the persistence API.
In the following we point out some of the central classes when working with issues. These classes and interfaces are located in packages com.aurel.track.dao andcom.aurel.track.beans. When looking for
documentation, these interfaces and classes should be a good starting point. The implementation of the
DAO interfaces can be found in the peer classes in package com.aurel.track.persist.
WorkItemDAO and TWorkItemBean
These are the central classes of the system. Objects of these class represent issues in the system.
PersonDAO and TPersonBean
Objects of this class represent persons and groups registered with the system.
ProjectDAO and TProjectBean
Objects of this class represent projects known to the system.
HistoryTransactionDAO and THistoryTransactionBean
Changes to issue attributes are collected into a history transaction. For example, if at the same time the title
and due date of an issue had been changed, these two attribute changes would be grouped together into a
single history transaction. The actual attribute changes can be found via FieldChangeDAO and TFieldChangeBean.
TAccessControlList (Table TACL)
This class relates users to projects and roles. It is the central class for access control.
8
TRole
This class contains the role definitions including the permission key.
2.2.2 The user Package
This package contains classes pertaining to user handling, password management, and registration.
2.2.3 The report Package
This package contains all classes relating to query and reporting functions, including charting, but excluding
the Track+ Query Language (TQL) functionality.
2.2.4 The item Package
This package is at the heart of the application. Handling of creation, modification, and editing of issues is
contained in these classes.
2.2.5 The notify Package
This package handles all notification related functionality, like automail triggers and automail filters.
2.2.6 The lucene Package
This package contains all functionality related to full text search.
2.2.7 The admin Package
This package contains classes for handling of most administrative features.
2.2.8 The resources Package
This package contains classes to support localized resource handling.
2.2.9 The util Package
This package contains utility classes or classes that did not fit into any of the other packages.
2.2.10 The plugin Package
Track+ provides six extension points via plug-ins:
1. Cockpit tiles
2. Field types
3. Version control plug-ins
9
2.3. Program Execution
4. data-source plug-ins for reporting
5. link type plug-ins for linking items
6. Persistence layer plug-ins for access to other databases
The plugin package contains the base functionality for handling these plug-ins. Track+ comes with a number of plug-ins for the different types already configured. You can find the standard configuration in file
src/main/resources/trackplus-plugin.xml.
For examples of cockpit tiles plug-ins see package com.aurel.track.report.dashboard . The user interface for these types of plug-ins you can find under src/plugins/dashboard.
For examples on field type plug-ins see package com.aurel.track.fieldType. The user interface for
these types of plug-ins you can find under src/plugins/fieldType.
For examples on version control plug-ins see package com.aurel.track.vc. The user interface for these
types of plug-ins you can find under src/plugins/versionControl. Track+ comes with a CVS, a Git, and
a Subversion plug-in.
2.2.11 Application Entry Point
The Track+ application channels all requests from clients through a Struts 2 servlet via a filter. Before the application starts there is some initialization going on in java/com/aurel/track/struts2/filter/Struts
ExtendClasspathPrepareAnExecuteFilter.java. The application itself is started by a second servlet,
which can be found under java/com/aurel/track/StartServlet.java. This is configured in file webapp/
WEB-INF/web.xml. For more information consult the Javadoc API documentation for the com/aurel/track
package and its classes.
2.3 Program Execution
In the following we will describe the process from a clients request (HTTP request) up to the response.
• By submission of an URL through a browser a request is being send to the respective server.
• On the server there is a configuration file called web.xml. In the case of Track+ this file is structured
such that all requests ending with ”’.action’” are being submitted to a Struts 2 filter class.
• The Struts 2 filter looks at the request URL. Based on the URL it decides which Action class and method
is to be called to process the request. Which Action class is responsible for which request URL is configured in file WebContent/WEB-INF/struts.xml. The Struts 2 filter class thus functions as a central
distributor for all requests. There is one filter, but many Action classes in Track+ . The filter also takes
care of access permission control, parameter processing, and a lot of other stuff.
• Inside the Action class the response is generated. This usually involves some call to an application layer
code, which in turn might call persistence layer code.
• The response may be channeled to a JSP page, a Struts tile, or directly into the response output stream.
The latter is mostly the case when a JavaScript request needs to be processed and the response is
returned to the JavaScript handler (Ajax requests). In case of JSP or tiles responses, which JSP or tile is
being used is defined in WebContent/WEB-INF/struts.xml.
10
2.3.1 System Initialization
When the system starts up, the StartServlet class proceeds as follows:
1. The $TRACKPLUS_HOME directory is determined in the following order:
(a) The Java VM argument for Tomcat -DTRACKPLUS_HOME=/xxxx is used
(b) If that is not defined, a system environment variable of the same name is looked for.
(c) If that is empty the current Tomcat working directory is taken.
2. The following files are copied to TRACKPLUS_HOME, unless they already exist there:
• Torque.properties
• quartz-jobs.xml
plus a number of other files like report templates, logos, indexes, etc.
3. The database is checked and updated to the most actual version. In this process, resource files containing the localization are loaded into the database. If there are files called $TRACKPLUS_HOME/
xresources/MyApplicationResources.properties these are loaded as well. The standard
e-mail templates are loaded as well.
4. The Quartz scheduler is started.
2.4 Schema Description
The following sections show the more important entities and their relations. Some table contain a column
called ”’MOREPROPS”’ which is used to store additional attributes for that entity usually in Java properties file
notation.
2.4.1 Access Control
The following diagram shows how access control is handled. Permissions are attached to roles. Persons get
permissions in projects via access control lists that link a person with a role in a project.
2.4.2 Items and Fields
The following diagram shows basic relations between the issue table and other tables. Issues belong to
projects via components or subsystems, stored in table TPROJCAT.
2.4.3 Fields and Field Changes
The following diagram shows how changes to issue attributes are stored in the database.
Because of historical reasons, there is a structural difference between system fields and custom fields. System
fields are stored in table TWORKITEM, while custom field values are stored in table TISSUEATTRIBUTEVALUE.
Changes to fields are held together in a transaction object if they occurred simultaneously. For example,
there will be a single entry in the history table if priority and status were changed at the same time.
11
2.4. Schema Description
Permits to define role based
access to single fields
These tables show how access control is handled.
Permissions are given to persons in projects via roles.
The actual permissions are stored as a string of
1s and 0s in EXTENDEDACCESSKEY in trole.
ACL::trolefield
ACL::trole
User::tperson
«column»
*PK PKEY: INT
FIRSTNAME: VARCHAR(25) = NULL
LASTNAME : VARCHAR(25) = NULL
*
LOGINNAME: VARCHAR(60)
EMAIL: V ARCHAR(60 ) = NULL
PASSWD: VARCHAR(80) = NULL
PHONE: VARCHAR(18) = NULL
FK DEPKE Y: I NT = NULL
VALIDUNTIL: DATE TIME = NULL
PREFERE NCES: TEXT = NULL
*
LASTEDI T: TI MES TAMP = CURRE NT_ TIMESTAMP
DELETED: CHAR(1 ) = 'N'
TOKENPASSWD: VARCHAR(80) = NULL
*
TOKENEX PDATE: TIMES TAMP = '2008-06-12 00:...
EMAILFREQUE NCY: INT = NULL
EMAILL EAD: INT = NULL
*
EMAILL ASTREMINDED: TIMESTAMP = '2 008-0 6-12 0 0:...
EMAILREMINDME: CHAR(1) = 'N'
PREFEMAILTYPE: VARCHA R(15) = 'P lain'
PREFLOCALE: VARCHAR(10) = NULL
FK MYDE FAUL TREP ORT: INT = NULL
NOEMAIL SPLEASE : INT = NULL
REMINDME ASORIGI NATOR: CHAR(1 ) = 'N'
REMINDMEASMANAGER: CHAR(1) = 'Y'
REMINDME ASRESPO NSIBLE: CHAR(1 ) = 'Y'
EMAILREMINDP LEVEL: INT = NULL
EMAILREMINDS LEVEL: INT = NULL
HOURSPERWORKDAY: DOUBLE = NULL
EMPLOYEE ID: VARCHAR(30) = NULL
ISGROUP: CHAR(1) = 'N'
USERLEVE L: INT = NULL
TPUUID: VARCHAR(36) = NULL
«column»
*PK PKEY: INT
*
LABEL: VARCHAR(25)
ACCESSKE Y: INT = NULL
EXTENDEDACCESSKEY: VARCHAR(3 0) = NULL
FK PROJECTTYPE: INT = NULL
(ROL EKE Y =
PKE Y)
«column»
*PK OBJECTI D: INT
*FK ROLEK EY: INT
*FK FIELDKEY: INT
ACCESSRI GHT: INT = NULL
Projec t::tpr oject
(ROLEK EY = PKEY)
ACL::tacl
(PERSO NKEY = PKEY)
«column»
*pfK PERSO NKEY: INT
*pfK ROLEK EY: INT
*pfK PROJK EY: INT
(PROJK EY = PKEY)
«PK»
+
PK_ta cl(I NT, I NT, INT)
«FK»
+
TACL_FK _3(INT)
+
TACL_FK _1(INT)
+
TACL_FK _2(INT)
«column»
*PK PKEY: INT
LABEL: VARCHAR(35) = NULL
FK DEFOWNER: INT = NULL
FK DEFMANAGER: INT = NULL
FK DEFINITSTATE: INT = NULL
VERSIONSYSTEMFIELD0: VARCHAR(2 55) = NULL
*
DELETED: VARCHAR(1) = 'N'
FK STATUS: I NT = NULL
CURRENCYNAME : VARCHAR(255) = NULL
CURRENCYS YMBOL: V ARCHAR(25 5) = NULL
MOREP ROPS: TE XT = NULL
DESCRIPTION: VARCHAR(255) = NULL
PREFIX: VARCHAR(10) = NULL
LASTI D: I NT = NULL
Figure 2.3: Access control
2.4.4 Project and Item Type Specific Settings
It is possible to limit the number of available selections for some fields like statuses, priorities, severities and
issue types based on project type and issue type. The following diagram illustrates that relation.
2.4.5 System
The following figure shows entities that are mostly related to handling application or session specific data.
This is important when the application is running on several servers with the same database (clustered operation).
Table TENTITYCHANGES collects changes to issues so that the Lucene indexing engine, which can only run
on one of the servers, gets notified about changes done by other servers.
2.4.6 Mask Definitions
In Track+ , it is possible to configure any number of input masks (screens). Input masks can be assigned to
action (like edit, change status, copy, new issue, new child issue).
Input masks consists of tabs, which contain panels, where the issue fields are placed.
Screen configurations connect a screen with an action globally, for a specific issue type, for a specific project
type and issue type, or for a project and an issue type.
12
tstate
«column»
*PK PKEY: INT
*FK PROJK EY: INT
(PROJCATKE Y = P KEY)
TCATEGORY defines
the issue type
(PRO JKE Y =
PKE Y)
TPROJCAT
contains project
components or
subsystems
(CLA SSKE Y =
PKE Y)
(PRO JKE Y =
PKE Y)
Proje ct::tclass
«column»
*PK PKEY: INT
*
LABEL: VARCHAR(25)
FK PROJK EY: INT = NULL
«column»
*PK PKEY: INT
*
(PROJK EY = PKEY)
Projec t::tre lease
(RELNO TICEDKEY = PKEY)
(RELSCHE DULEDKEY = PKEY)
tcategory
«column»
*PK PKEY: INT
*
LABEL: VARCHAR(25)
TYPEFL AG: INT = NULL
SORTORDE R: INT = NULL
SYMBOL: V ARCHAR(25 5) = NULL
FK ICONK EY: INT = NULL
Projec t::tpr oject
Projec t::tpr ojcat
Issues ::twor kitem
«column»
«column»
(S TA TE =
*PK WORKITEMKEY: INT
*PK PKEY: INT
PKE Y)
*FK OWNER: INT
*
LABEL: VARCHAR(25)
*FK CHANGEDB Y: INT
STATEFLAG: INT = NULL
FK ORIGINATOR: INT = NULL
FK RESPONSI BLE: INT = NULL
*FK PROJCATK EY: INT
*FK CATEG ORYK EY: INT
PERCE NTCOMPLETE: I NT = NULL
FK CLASSKE Y: INT = NULL
*FK PRIO RITYKEY: INT
FK SEVERITYKE Y: I NT = NULL
SUPERIORWO RKITEM: I NT = NULL
*
PACKAGESYNOPSYS: VA RCHAR(80)
PACKAGE DESCRI PTION: TEXT = NULL
REFERENCE: VARCHAR(20) = NULL
tseve rity
*
(SE VERITYKEY FK RELNOTICEDK EY: INT = NULL
«column»
= PKEY)
FK RELSCHE DULEDKE Y: INT = NULL
*PK PKEY: INT
BUILD: VARCHAR(25) = NULL
FK STATE : I NT = NULL
STARTDATE: DATE TIME = NULL
WLEVEL: INT = NULL
ENDDA TE: DATETIME = NULL
SUBMITTEREMAIL : VARCHAR(60) = NULL
*
CREATED: TIME STAMP = '0000 -00-00 00:...
ACTUA LSTA RTDA TE: DATETIME = NULL
ACTUAL ENDDA TE: DATETIME = NULL
WLEVEL: VARCHAR(14) = NULL
ACCESSLEVEL: INT = NULL
ARCHIVELEVEL: INT = NULL
TASKISMI LESTONE: CHAR(1 ) = 'N'
TASKISSUBPROJECT: CHA R(1) = 'N'
TASKIS SUMMARY: CHAR(1) = 'N'
(CATEGORYKEY = P KEY)
TASKCO NSTRA INT: INT = NULL
TASKCONSTRAINTDATE : DA TETI ME = NULL
PSPCODE: VARCHAR(255) = NULL
IDNUMB ER: INT = NULL
«column»
*PK PKEY: INT
*FK PROJK EY: INT
DUEDA TE: DATETIME = NULL
(PRI ORITYKEY = P KEY)
(WORKITE M =
WORKITEMKEY)
tpriority
«column»
*PK PKEY: INT
WLEVEL: INT = NULL
Issues::tattachment
«column»
*PK OBJECTI D: INT
*FK WORKITE M: INT
FK CHANGEDB Y: INT = NULL
FK DOCUMENTSTATE: INT = NULL
*
FILENAME: V ARCHAR(256)
FILESIZE: VARCHAR(20) = NULL
MIMETYPE: VARCHAR(1 5) = NULL
*
VERSION: VARCHAR(20) = NULL
DESCRIPTIO N: TEXT = NULL
CRYP TKEY: TEXT = NULL
ISENCRYPTED: CHAR(1) = 'N'
ISDELETED: CHAR(1) = 'N'
Figure 2.4: Items and Fields
2.4.7 Cockpit Configuration
Cockpit configurations are stored in TDASHBOARDSCREEN. Each user has a general dashboard configuration,
and one for each project and all releases in that project.
Cockpit screens consists of tabs, which consist of panels, which contain cockpit views (in table TDASHBOARDFIELD.
The behavior and handling is very similar to input masks and their fields.
Each cockpit view can be parameterized. For example there may be several instances for project overview
widget, each configured for another project.
2.4.8 Custom Field Configuration
The following diagram shows the custom field configuration structure.
Custom fields can be assigned at various levels: System wide, project type specific, and project specific, and
underneath each category issue type specific.
2.4.9 Automail
Automail settings comprise automail triggers and automail conditions. Since automail conditions are basically equivalent to standard queries, they are stored in the same table TQUERYREPOSITORY.
13
Self reference for nested
comments.
Issues ::twor kitem
«column»
*PK WORKITEMKEY: INT
*FK OWNER: INT
*FK CHANGEDB Y: INT
FK ORIGINATOR: INT = NULL
FK RESPONSI BLE: INT = NULL
*FK PROJCATK EY: INT
*FK CATEG ORYK EY: INT
FK CLASSKE Y: INT = NULL
*FK PRIO RITYKEY: INT
FK SEVERITYKE Y: I NT = NULL
SUPERIORWO RKITEM: I NT = NULL
*
PACKAGESYNOPSYS: VA RCHAR(80)
PACKAGE DESCRI PTION: TEXT = NULL
REFERENCE: VARCHAR(20) = NULL
*
FK RELNOTICEDK EY: INT = NULL
FK RELSCHE DULEDKE Y: INT = NULL
BUILD: VARCHAR(25) = NULL
STARTDATE: DATE TIME = NULL
ENDDA TE: DATETIME = NULL
SUBMITTEREMAIL : VARCHAR(60) = NULL
*
CREATED: TIME STAMP = '0000 -00-00 00:...
ACTUA LSTA RTDA TE: DATETIME = NULL
ACTUAL ENDDA TE: DATETIME = NULL
WLEVEL: VARCHAR(14) = NULL
ACCESSLEVEL: INT = NULL
ARCHIVELEVEL: INT = NULL
TASKISMI LESTONE: CHAR(1 ) = 'N'
TASKISSUBPROJECT: CHA R(1) = 'N'
TASKIS SUMMARY: CHAR(1) = 'N'
TASKCO NSTRA INT: INT = NULL
TASKCONSTRAINTDATE : DA TETI ME = NULL
PSPCODE: VARCHAR(255) = NULL
IDNUMB ER: INT = NULL
Contains system
field values
Issues::thistorytransaction
(WORKITE M =
WORKITEMKEY)
«column»
*PK OBJECTI D: INT
*FK WORKITE M: INT
*FK CHANGEDB Y: INT
*
Transaction contains a set of
concurrent field changes
(HIS TORYTRANS ACTION
= OBJECTID)
Issues::tfield
«column»
*PK OBJECTI D: INT
*
NAME: VARCHAR(255)
*
FIELDTYP E: VARCHAR(255)
DEPRECATE D: CHAR(1) = 'N'
*
ISCUS TOM: CHAR(1) = 'Y'
*
REQUIRED: CHAR(1) = 'N'
FK OWNER: INT = NULL
(FIE LDKE Y =
OBJECTID)
(WORKITE M =
WORKITEMKEY)
(PA RENTCO MME NT
= OBJECTID)
Issues::tfieldchange
«column»
*PK OBJECTI D: INT
*
FIELDKEY: INT
*FK HISTORYTRANS ACTI ON: INT
NEWTEXTVALUE : VARCHAR(255) = NULL
OLDTEXTVALUE : VARCHAR(255) = NULL
NEWINTEGERVALUE: I NT = NULL
OLDINTEGERVALUE: I NT = NULL
NEWDOUBLEVALUE: DOUBLE = NULL
OLDDOUBLEVALUE: DOUBLE = NULL
NEWDATEVALUE : DATETIME = NULL
OLDDATEVALUE : DATETIME = NULL
NEWCHARACTERVALUE : CHAR(1) = NULL
OLDCHARACTERVALUE : CHAR(1) = NULL
NEWLONGTEXTV ALUE: TEXT = NULL
OLDLONGTEXTV ALUE: TEXT = NULL
NEWSYSTEMO PTIONID: INT = NULL
OLDSYSTEMO PTIONID: INT = NULL
SYSTEMOP TIO NTYP E: INT = NULL
FK NEWCUS TOMOPTIONID: INT = NULL
FK OLDCUS TOMOPTIONID: INT = NULL
PARAME TERCO DE: INT = NULL
VALIDVALUE: INT = NULL
FK PARE NTCO MMENT: INT = NULL
TIMES EDITE D: I NT = NULL
Issues ::tattribute value
«column»
*PK OBJECTI D: INT
*FK FIELDKEY: INT
*FK WORKITE M: INT
TEXTVALUE: VARCHAR(2 55) = NULL
INTEGERVALUE: INT = NULL
DOUBLEVALUE: DOUBLE = NULL
DATEV ALUE : DA TETI ME = NULL
CHARACTERVALUE: CHAR(1) = NULL
LONGTEXTV ALUE: TE XT = NULL
SYSTE MOPTIONID: I NT = NULL
SYSTEMOP TIO NTYP E: INT = NULL
CUSTOMOPTIO NID: INT = NULL
*
Contains custom
field values
Figure 2.5: Fields and field changes
2.4.10 Accounting
The following figure shows tables related to accounting, that is handling of work and cost.
The actual values for each issue are kept in TBUDGET, TACTUALESTIMATEDBUDGET, and TCOST.
2.4.11 Queries
Because of historical reasons, TQL queries (in TPUBLICREPOSITORY, TPROJECTREPOSITORY, and TPRIVATE
REPOSITORY) are stored different from Tree Filter queries.
Tree filter query expressions can be quite lengthy and are stored in a separate table TCLOB, which can also
be used for other large character objects.
The issue overview layout for each query is stored in table TREPORTLAYOUT. This table can also contain entries
for predefined queries, for example from the menu (My items) or from cockpit views.
2.4.12 Reports
Reports consist of JasperReport templates and a reference to a data-source feeding these templates. The
main table is TEXPORTTEMPLATE. The other tables are provided to automatically create and e-mail such
reports to a user on a regular basis, as defined in TRECURRENCEPATTERN.
14
tstate
It is possible to enable or disable specific selection entries for issue
statuses, priorities, and severities based on project type and issue type.
It is possible to enable or disable certain issue types for a project type.
If their are no entries, all entries are enabled.
«column»
*PK PKEY: INT
*
LABEL: VARCHAR(25)
STATEFLAG: INT = NULL
PERCE NTCOMPLETE: I NT = NULL
(S TA TE =
PKE Y)
This is the issue type
Customization::tpstate
«column»
*PK OBJECTI D: INT
FK LISTTYP E: INT = NULL
tcategory
(LI STTYPE =
PKE Y)
«column»
*PK PKEY: INT
*
LABEL: VARCHAR(25)
TYPEFL AG: INT = NULL
(CA TEG ORY =
PKE Y)
(PROJECTTYPE
= OBJECTID)
(PROJECTTYPE
= OBJECTID)
Customization::tppriority
(LI STTYPE =
PKE Y)
«column»
*PK OBJECTI D: INT
FK PRIORITY: INT = NULL
tpriority
(PRIORITY =
PKE Y)
tseve rity
«column»
*PK PKEY: INT
WLEVEL: INT = NULL
«column»
*PK OBJECTI D: INT
NOTIFYOW NERLEVE L: INT = NULL
NOTIFYMANAG ERLEV EL: INT = NULL
(PROJECTTYPE
= OBJECTID)
Customization::tplisttype
«column»
*PK OBJECTI D: INT
FK CATEGO RY: INT = NULL
(LI STTYPE =
PKE Y)
Customization::tprojecttype
(PROJECTTYPE
= OBJECTID)
«column»
*PK PKEY: INT
WLEVEL: INT = NULL
Customization::tpseverity
(SE VERITY =
PKE Y)
«column»
*PK OBJECTI D: INT
FK SEVERI TY: INT = NULL
Figure 2.6: Project and item type specific settings
tloggedinusers
clusternode
«column»
*PK OBJECTI D: INT
NODEADDRESS: VA RCHAR(40) = NULL
NODEURL: VARCHAR(255) = NULL
*
LASTUPDATE : TIME STA MP = CURRE NT_ TIMESTAMP
MASTERNO DE: INT = 0
RELOADCO NFIG: INT = 0
(NODEA DDRESS
= OBJECTID)
«column»
*PK OBJECTI D: INT
FK NODEADDRESS: INT = NULL
SESSIONID: VARCHAR(255) = NULL
*FK LOGGEDUS ER: INT
USERLEVE L: INT = NULL
*
LASTUPDATE : TIME STA MP = CURRE NT_ TIMESTAMP
(CLUSTERNODE
= OBJECTID)
System::tentitychanges
«column»
*PK OBJECTI D: INT
*
ENTITYKE Y: I NT
*
ENTITYTYPE : I NT
FK CLUSTERNODE: INT = NULL
System::tapplicationcontext
«column»
*PK OBJECTI D: INT
LOGGEDFULL USERS: I NT = NULL
LOGGEDL IMITEDUSERS: INT = NULL
*
REFRESHCONFIGURATION: INT = 0
*
FIRS TTI ME: I NT = 0
temailprocessed
«column»
*PK OBJECTI D: INT
*
PROCESSE DDATE: DATE TIME
*
MESSAGEUID: VARCHAR(255)
*
RECEIVEDAT: VARCHAR(255)
These tables are mostly for clustered
environments, to work from several
application server instances on the
same database.
Figure 2.7: System
2.4.13 Project Configuration
The following figure illustrates the project configuration. Entries in tables TCLASS, TPROJCAT, and TRELEASES
are essentially project specific option lists.
15
ScreenConfig::tscreentab
ScreenConfig::tscreen
ScreenConfig::tscreenconfig
«column»
*PK OBJECTI D: INT
NAME: VA RCHAR(255 ) = NULL
FK SCREEN: I NT = NULL
FK ISSUE TYPE : INT = NULL
FK PROJE CT: INT = NULL
*FK ACTIO NKEY: INT
(PA RENT =
OBJECTID)
«column»
*PK OBJECTI D: INT
*
NAME: VARCHAR(255)
LABEL: VARCHA R(255) = NULL
(SCRE EN =
OBJECTID)
«column»
*PK OBJECTI D: INT
*
NAME: VARCHAR(255)
*FK PARE NT: INT
(PA RENT =
OBJECTID)
(ACTIO NKE Y =
OBJECTID)
ScreenConfig::tscreenfield
ScreenConfig::tscreenpanel
ScreenConfig::taction
«column»
*PK OBJECTI D: INT
*
NAME: VARCHAR(255)
«column»
*PK OBJECTI D: INT
*
NAME: VARCHAR(255)
*
ROWSNO: INT
*
COLSNO: INT
*FK PARE NT: INT
(PA RENT =
OBJECTID)
«column»
*PK OBJECTI D: INT
*
NAME: VARCHAR(255)
COLINDEX: INT = NULL
ROWINDEX: INT = NULL
COLSPAN: INT = NULL
ROWSPAN: INT = NULL
*
LABELHALI GN: INT
*
LABELVALI GN: INT
*
VALUEHALIGN: INT
*
VALUEVALIGN: INT
*
ISEMP TY: CHAR(1) = 'N'
*FK PARE NT: INT
FK FIELDK EY: INT = NULL
Figure 2.8: Mask definitions
CockpitConfig::tdashboardscreen
CockpitConfig::tdashboardparameter
«column»
*PK OBJECTI D: INT
*
NAME: VARCHAR(255)
*FK PERSONPKEY: INT
ENTITYTYP E: INT = NULL
«column»
*PK OBJECTI D: INT
*
NAME: VARCHAR(255)
PARAMVALUE : TE XT = NULL
*FK DASHBOARDFIELD: INT
(DASHBOARDFIELD
= OBJECTID)
(PA RENT =
OBJECTID)
CockpitConfig::tdashboardfield
«column»
*PK OBJECTI D: INT
*
NAME: VARCHAR(255)
COLINDEX: INT = NULL
ROWINDEX: INT = NULL
COLSPAN: INT = NULL
ROWSPAN: INT = NULL
*FK PARE NT: INT
*
DASHBOARDID: VARCHAR(255)
THEDESCRIPTI ON: VARCHAR(255) = NULL
CockpitConfig::tdashboardpanel
CockpitConfig::tdashboardtab
(PA RENT =
OBJECTID)
«column»
*PK OBJECTI D: INT
*
NAME: VARCHAR(255)
*
ROWSNO: INT
*
COLSNO: INT
*FK PARE NT: INT
(PA RENT =
OBJECTID)
«column»
*PK OBJECTI D: INT
*
NAME: VARCHAR(255)
*FK PARE NT: INT
Figure 2.9: Cockpit configuration
2.4.14 Obsolete Tables
There are a number of tables that are obsolete and are in the database just to enable upgrade from previous
releases. These tables are
• TATTRIBUTE (never used)
• TATTRIBUTECLASS (never used)
• TATTRIBUTEOPTION (never used)
• TATTRIBUTETYPE (never used)
16
(PARENTLIS T =
OBJECTID)
CustomFields::tfieldconfig
«column»
*PK OBJECTI D: INT
*FK FIELDKEY: INT
*
LABEL: VARCHAR(255)
TOOLTIP: VARCHAR(25 5) = NULL
*
REQUIRED: CHAR(1) = 'N'
*
HISTORY: CHAR(1) = 'N'
FK ISSUE TYPE : INT = NULL
CustomFields::tlist
CustomFields::toptionsettings
«column»
*PK OBJECTI D: INT
*FK LIST: INT
*FK CONFIG: INT
MULTIP LE: CHAR(1) = 'N'
(CONFIG =
OBJECTID)
(LI ST =
OBJECTID)
which list of
tlist is being used
in this context
«column»
*PK OBJECTI D: INT
*
NAME: VARCHAR(255)
FK PARENTLIST: I NT = NULL
LISTTYP E: INT = NULL
CHILDNUMBER: INT = NULL
REPO SITO RYTYPE: INT = NULL
(LI ST =
OBJECTID)
(CONFIGK EY =
OBJECTID)
(CONFIG =
OBJECTID)
CustomFields::tconfigoptionsrole
(CONFIG =
OBJECTID)
CustomFields::ttextboxsettings
«column»
*PK OBJECTI D: INT
*FK CONFIG: INT
*
REQUIRED: VARCHAR(1) = 'N'
DEFAULTTEXT: VARCHA R(255) = NULL
DEFAUL TINTE GER: INT = NULL
DEFAULTDOUBLE: DOUB LE = NULL
DEFAULTDA TE: DATETIME = NULL
DEFAULTCHA R: CHAR(1) = NULL
DEFAUL TOPTI ON: INT = NULL
MINOP TION: INT = NULL
MAXOP TION: INT = NULL
MINTEXTL ENGTH: INT = NULL
MAXTEXTL ENGTH: INT = NULL
MINDATE: DATETIME = NULL
MAXDATE: DATETIME = NULL
MININTEGER: I NT = NULL
MAXINTEGER: I NT = NULL
MINDOUBLE : DOUBL E = NULL
MAXDOUBLE : DOUBL E = NULL
MAXDE CIMAL DIGI T: I NT = NULL
«column»
*PK OBJECTI D: INT
*FK CONFIGKE Y: INT
*FK ROLEK EY: INT
*FK OPTIO NKEY: INT
CustomFields::tgeneralsettings
«column»
*PK OBJECTI D: INT
*FK CONFIG: INT
INTEGERVALUE: INT = NULL
DOUBLEVALUE: DOUBLE = NULL
TEXTVALUE: VARCHAR(2 55) = NULL
DATEV ALUE : DA TETI ME = NULL
CHARACTERVALUE: CHAR(1) = NULL
CustomFields::toption
(OP TIO NKE Y =
OBJECTID)
«column»
*PK OBJECTI D: INT
*FK LIST: INT
*
LABEL: VARCHAR(255)
PARENTOPTI ON: INT = NULL
*
ISDEFAULT: CHAR(1) = 'N'
if not textbox settings
nor option settings,
e.g. user picker
Figure 2.10: Custom field configuration
Automail::tnotifysettings
Automail::tnotifytrigger
«column»
*PK OBJECTI D: INT
FK PERSON: INT = NULL
FK NOTIFYTRI GGER: INT = NULL
FK NOTIFYFIL TER: INT = NULL
(NOTIFYFIL TER
= OBJECTID)
(NOTIFYTRIG GER
= OBJECTID)
These are the
automail conditions
Queries::tqueryrepository
«column»
*PK OBJECTI D: INT
*
QUERYTYP E: INT
*
REPO SITORYTYPE : INT
*FK QUERYKEY: INT
MENUI TEM: CHAR(1) = 'N'
«column»
*PK OBJECTI D: INT
ISSYS TEM: CHAR(1) = 'N'
Automail::tnotifyfield
(NOTIFYTRIG GER
= OBJECTID)
To limit amount of e-mails, send
a summary e-mail (for instance,
once a week). Not yet
implemented.
Automail::tsummarymail
«column»
*PK OBJECTI D: INT
*FK WORKITE M: INT
*FK PERSONFROM: INT
FROMADDRESS : VARCHAR(255) = NULL
MAILSUBJE CT: VARCHAR(255 ) = NULL
WORKITEMLINK: VA RCHAR(255) = NULL
*FK PERSO NTO: INT
*
Figure 2.11: Automail
• TBASELINE (migrated into THISTORYTRANSACTION and TFIELDCHANGE)
• TDISABLEFIELD (never used)
• TDOCSTATE (never used)
• TEFFORTTYPE (never used)
17
«column»
*PK OBJECTI D: INT
FIELD: INT = NULL
*
ACTI ONTYPE: INT
FIELDTYPE : INT = NULL
*FK NOTI FYTRIGGE R: INT
ORIGINATOR: CHAR(1) = 'N'
MANAGER: CHAR(1 ) = 'N'
RESPONSIBLE: CHAR(1) = 'N'
CONSULTANT: CHAR(1) = 'N'
INFORMA NT: CHAR(1) = 'N'
OBSERVER: CHAR(1) = 'N'
single entry of
selection box
Accounting::tprojectaccount
«column»
*pfK ACCOUNT: INT
*pfK PROJE CT: INT
Summarized values either per issue or
per issue and person.
Redundant information, just for faster
access.
Accounting::taccount
(ACCOUNT =
OBJECTID)
«column»
*PK OBJECTI D: INT
*
ACCOUNTNUMBER: VARCHAR(30)
ACCOUNTNAME : VARCHAR(80) = NULL
FK COSTCE NTER: INT = NULL
Accounting::tcomputedvalues
«column»
*PK PKEY: INT
*FK WORKITEMKEY: INT
*
EFFO RTTYPE : INT
*
COMPUTEDVA LUETYPE: INT
COMPUTEDVA LUE: DOUB LE = NULL
MEAS UREMENTUNIT: INT = NULL
(COS TCENTER
= OBJECTID)
Accounting::tcostcenter
(ACCOUNT =
OBJECTID)
«column»
*PK OBJECTI D: INT
*
COSTCENTERNUMBER: V ARCHAR(30)
COSTCENTE RNAME: V ARCHAR(80 ) = NULL
Budget, estimated budget, and
actual cost are recorded per
issue.
Accounting::tbudget
«column»
*PK OBJECTI D: INT
ESTIMA TEDHOURS: DOUBLE = NULL
TIMEUNIT: INT = NULL
ESTIMATEDCOST: DOUB LE = NULL
EFFO RTTYPE: INT = NULL
EFFORTVAL UE: DOUB LE = NULL
CHANGEDESCRIPTION: VARCHAR(255) = NULL
*
Accounting::tactualestimatedbudget
«column»
*PK OBJECTI D: INT
ESTIMA TEDHOURS: DOUBLE = NULL
TIMEUNIT: INT = NULL
ESTIMATEDCOST: DOUB LE = NULL
EFFO RTTYPE: INT = NULL
*
Planned value with history
Accounting::tcost
«column»
*PK OBJECTI D: INT
FK ACCOUNT: INT = NULL
FK WORKITE M: INT = NULL
HOURS: DOUBLE = NULL
COST: DOUBLE = NULL
SUBJECT: VARCHAR(255) = NULL
FK EFFO RTTYPE: INT = NULL
EFFO RTDA TE: DATETIME = NULL
INVOICENUMBE R: VARCHAR(255) = NULL
INVOI CEDATE: DATETI ME = NULL
INVOICEPATH: VARCHAR(255) = NULL
*
Figure 2.12: Accounting
• TEFFORTUNIT (never used)
• TREPOSITORY (never used)
• TSCHEDULER (never used, using Quartz)
• TSTATECHANGE (migrated into THISTORYTRANSACTION and TFIELDCHANGE
• TTRAIL (migrated into THISTORYTRANSACTION and TFIELDCHANGE)
2.4.15 Plug-Ins
There are a number of plug-in interfaces available in Track+ . The plug-ins must be placed as ”’.tpx”’ files in
the $TRACKPLUS_HOME/plugins directory. The .tpx files are ZIP files containing a
• conf
• lib
• classes
• js
directory (all optional). The files are being expanded when the application is started, and the files in these
directories are added to the Java classpath or to the JavaScript ExtJS loaders classpath (for the js directory).
18
Tables just for TQLs. Tree
filters are being kept in
TQUERYREPOSITORY.
Tables for tree filters.
Queries::tpublicreportrepository
Queries::tqueryrepository
tclob
«column»
*PK PKEY: INT
*FK OWNER: INT
*
NAME: VARCHAR(100)
*
QUERY: TEXT
«column»
*PK OBJECTI D: INT
*
QUERYTYP E: INT
*
*FK QUERYKEY: INT
Queries::tprojectreportrepository
(QUERYKEY =
OBJECTID)
«column»
*PK OBJECTI D: INT
CLOBVALUE: TEXT = NULL
«column»
*PK PKEY: INT
*FK PROJE CT: INT
*
NAME: VARCHAR(100)
*
QUERY: TEXT
Queries::treportlayout
«column»
*PK OBJECTI D: INT
*
REPORTFIELD: INT
*
FPOSI TION: INT
*
FWIDTH: INT
FSORTO RDER: INT = NULL
FSORTDIR: VARCHAR(1) = NULL
FIELDTYPE : INT = NULL
EXPANDING: VARCHAR(1) = NULL
LAYO UTKE Y: INT = NULL
QUERYID: INT = NULL
QUERYTYPE : INT = NULL
Queries::tprivate reportrepository
«column»
*PK PKEY: INT
*FK OWNER: INT
*
NAME: VARCHAR(100)
*
QUERY: TEXT
Figure 2.13: Queries
Reports::tex porttemplate
JasperReport
templates
«column»
*PK OBJECTI D: INT
*
NAME: VARCHAR(255)
*
REPORTTYPE: VARCHA R(255)
*
EXPORTFORMAT: VARCHA R(255)
*
*FK PERSON: INT
Reports::tte mplateperson
(RE PO RTTEMPLA TE
= OBJECTID)
«column»
*PK OBJECTI D: INT
*FK REPO RTTEMP LATE : INT
*FK PERSON: INT
RIGHTFLAG: INT = NULL
Who may execute this report.
Not yet implemented.
(RE PO RTTEMPLA TE
= OBJECTID)
Reports::trecurrencepattern
Reports::trepor tpersonsettings
«column»
*PK OBJECTI D: INT
*FK PERSON: INT
FK RECURRENCEPA TTERN: INT = NULL
*FK REPO RTTEMP LATE : INT
(RECURRENCEPATTERN
= OBJECTID)
(REPO RTPE RSONSETTINGS
= OBJECTID)
«column»
*PK OBJECTI D: INT
*
RECURRENCEP ERIOD: INT
PARAM1: I NT = NULL
PARAM2: I NT = NULL
PARAM3: I NT = NULL
DAYS: VA RCHAR(255 ) = NULL
DATEIS ABSOLUTE: CHAR(1) = 'Y'
STARTDA TE: DA TETIME = CURRENT_TIMESTAMP
ENDDATE : DATETIME = '0000 -00-00 00:...
OCCURENCETYPE : INT = NULL
NOOFOCCURENCES: I NT = NULL
Reports::treportparameter
«column»
*PK OBJECTI D: INT
*
NAME: VARCHAR(255)
*FK REPORTPERSO NSETTINGS: INT
In case the report has parameters,
each person can set their parameters
and recurrence pattern.
Figure 2.14: Reports
The nature of the plug-ins is described in a file called trackplus-plugin.xml. Track+ searches for such
files in its classpath when the application is started, and from there derives what plug-ins are available.
19
Proje ct::tclass
«column»
*PK PKEY: INT
*
LABEL: VARCHAR(25)
FK PROJK EY: INT = NULL
Projec t::tpr oject
Project::tversioncontrolparameter
«column»
*PK OBJECTI D: INT
*
NAME: VARCHAR(255)
*FK PROJE CT: INT
(PRO JECT =
PKE Y)
Project::tini tstate
«column»
*PK OBJECTI D: INT
*FK PROJE CT: INT
*FK LIS TTYPE: I NT
*FK STATEKE Y: INT
(PRO JECT =
PKE Y)
«column»
*PK PKEY: INT
*
(PRO JKE Y =
PKE Y)
Projec t::tre lease
(PRO JKE Y =
PKE Y)
«column»
*PK PKEY: INT
*FK PROJK EY: INT
DUEDA TE: DATETIME = NULL
(PRO JKE Y =
PKE Y)
Projec t::tpr ojcat
Subsystem or
component
«column»
*PK PKEY: INT
*FK PROJK EY: INT
Figure 2.15: Project configuration
The structure of the trackplus-plugin.xml files depends on the type of plug-in it describes.
20
3
Accessing Data
This chapter describes briefly how to access data contained in the database. The information contained
here should help you to develop new cockpit views and report data-sources, as described in the following
chapters.
3.1 Overview
In many cases, extending functionality involves access to items or item history. You will find many methods
that are ready to use in package com.aurel.track.dao. Please have a look at the Java API docs to see
if you can fulfill your requirements using any of the functionality available there. Additional classes that are
really helpful are TWorkItemPeer and ReportBeanLoader.
This section shall introduce you into how to create your own data access functionality. It assumes that you
have some familiarity with the Apache Torque persistence layer framework. It takes existing methods from
Track+ and explains their structure.
3.2 Counting Items
The following listing illustrates how to count the total number of items.
This example introduces the Torque Criteria object. The Criteria object permits you to define the
WHERE clause of the SQL SELECT statement. In our example it is empty, that is all records are considered. In
our example we use the Criteria object to define which columns shall be returned in the result set. This is
rather uncommon, typically we return complete objects like TWorkItem or TPerson, not just parts of them.
21
3.3. Retrieving Managers Items
3.3 Retrieving Managers Items
The following listing illustrates how to get a specific users items where he is currently the manager.
Here we return a list with TWorkItemBean objects. In many cases there is a corresponding method that
returns ReportBean objects. The difference lies in the handling of foreign keys. While the TWorkItemBean
object just contains references to other tables like users or statuses or priorities, the ReportBean objects
have these references resolved and localized, so that they are ready for display.
This routine uses an auxiliary method prepareManagerCriteria() to construct the Criteria object
which basically defines the WHERE clause in the emitted SQL. Here it is:
This method takes as parameter the object id of the current manager, an integer for a specific entity to
be considered, and an entity type indicator entityFlag designating the type of entity meant by parameter entity. EntityFlag can be any of SystemFields.PROJECT , SystemFields.RELEASENOTICED ,
SystemFields.RELEASESCHEDULED , SystemFields.SUBPROJECT , or SystemFields.CLASS. If entity
is null, all projects that are not closed are being considered. There are a number of other such auxiliary methods available, please have a look at the Java API documentation or the source code.
This method makes use of another auxiliary method that serves to consider just items that are not closed, as
indicated via their status, and are not deleted or archived, or are contained in archived or deleted projects.
Here is the code for this routine:
Here is the code to consider unclosed statuses:
22
Chapter 3. Accessing Data
The addJoin method creates a join in the WHERE clause like this: WHERE "TWORKITEM.STATE EQUALS
TSTATE.PKEY".
Here is the code to consider just unarchived items:
The code for considering a specific entity in addProjectStateCriteria() is a little bit more lengthy. It
should suffice here to show the section that makes sure only active projects are considered:
It is important to note that items are related to projects only indirectly via components or subsystems in table
TPROJCAT. Thus we first create a join between the projects to be considered and their components, from
where we then can get to the items.
3.4 Adding Custom Field Values to Issues
The standard item bean TWorkItemBean just contains the system fields, like priority, title, description, but
no custom field values. They are stored within a map inside of TWorkItemBean , but this map is usually not
23
3.5. Ensuring Access Control
filled with standard queries as shown above. To fill these maps with the custom field values you can use
ReportBeanLoader.addCustomFields().
3.5 Ensuring Access Control
Result sets can contain items the caller may have no right to read or otherwise access. For this reason the list
of returned items should be passed through an access control filter. This filter is available in AccessControl
ListDAO.filterWorkItemBeans(). A list of TWorkItemBeans is passed to this filter, a users id, and a
right (for example ”read” right). The filter then returns a list of TWorkItemBeans that this user is permitted
to read. It is even possible to consider indirect rights via group memberships. More information is contained
in the Java API documentation.
3.6 Accessing History Data
Sometimes it is required to access data in the history tables, for example if there is the need to find items
that have been in a certain status, or to count how often an item has been in a certain status during the last
month, or to check how many items have been in a certain status each week over the last year.
The application manages history data with two entities:
• THistoryTransactionBean encompasses a number of TFieldChangeBean that have occurred as
part of the same transaction.
• TFieldChangeBean records the actual attribute or field change for a specific item.</H6>
There are a number of helpful methods in HistoryTransActionDAO and FieldChangeDAO.
Here is the inner structure for a method that permits to get for a given set of items all changes to s specific
field (like status) to specific values (like ”opened”, ”implemented”) in a given time interval.
24
The list of items to be considered is seperated into ”chunks”, since it can be quite large, and some database
systems like Oracle don’t like SQL ”IN” statements with a large number of keys.
For each chunk the matching field changes are retrieved.
The construction of the Criteria object for this method looks like this:
25
3.7. Adding or Modifying Tables
This chapter describes briefly how to add new functionality to the Track+ core system. When doing this you
must be aware that future versions of Track+ will overwrite your changes, and you need to merge them back
into the Track+ main development trunk.
3.7 Adding or Modifying Tables
To add or modify tables in the database proceed as follows:
1. Modify track-schema.xml in the torque directory. For a description of the format have a look at
the Jakarta Torque site.
2. Save the top dbase directory to some secure place.
3. Run build.bat with the ”torque” target (./build.bat torque).
4. If you have added tables, manually copy the new Txx.java files from torque/java to their regular place
in the persist package under the src directory. The two Txx files per table are not copied automatically
since they can be and usually are modified by the user later on. If you have just modified a table or
relationship, the ”torque” target does everything automatically.
5. Merge the new SQL files in dbase/<server>/track-schema.sql with the existing ones you have
saved previously. You usually cannot use the auto-generated files since attribute types may not fit
across all database systems (e.g. Date to Datetime, VARCHAR sizes, LONGTEXT, etc.). Always build on
top of the existing files. This you have to do for each supported database.
6. Create an upgrade script that transfers the existing database schema to the new one you have just
created. This you have to do for each supported database.
3.8 Adding Pages
To add new pages under Struts 2 proceed as follows:
1. Create a new action class for the page, derived from com.opensymphony.xwork2.ActionSupport
. The name of this class should be something like XyzAction.java , for example iCalAction.java
. This class contains getters and setters for each field on the page you want ot create.
2. Add at least two methods to the ActionSupport class just created: a prepare() and an execute()
method. The prepare() method is being called before the associated page is rendered, and the
execute() method is being called when the page is submitted to this action.
3. Add the newly created action to the src/struts.xml file. For the page related to the action you can
use a tile definition name, it does not have to be a JSP page (see the following).
4. Create the tile for the new page. This is just a regular JSP. Add it to the appropriate place in the
WebContent/tiles/pages directory.
5. Make sure everything can be localized. Add all text you have used in the JSP to the resource files
src/resources/UserInterface/ApplicationResources_xy.properties , with xy denoting
the locale like ”en” for English, ”de” for German, and so on. Don’t use the file src/resources/ApplicationResources_xy.properties (without the UserInterfaces), it is deprecated.
6. Add a new menu entry and associated content in file WebContent/tiles/tiles-defs-struts2.xml
. Make sure you document everything correctly in this same file so that one can keep an overview.
26
7. Compile everything and check it out. If you need to change the JSP, you do not have to restart the
server in between changes.
27
track
™
Steinbeis-Transferzentrum
Task Management Solutions
Steinbeis GmbH & Co. KG
Task Management Solution
Eugen-Ruoff-Str. 30
71404 Korb
Germany
Tel.: +49 7151 994 89 60
Fax.: +49 7151 994 89 61
E-mail: [email protected]
www.trackplus.com

Track+ Developers Manual

Transcription

Similar documents

Data warehouse generation algorithm explained. - BI

Introduction to Database Communication using ASP.NET Web Forms

Quick start guide - PassMark Software

Autonomous Systems

Power Analysis Overview - East Carolina University

Online Movie Ticket Booking System 1

ORF 245 Fundamentals of Statistics Chapter 8 Hypothesis Testing

amateur-satellite service