custom reports guide - jama software

© 2018 Jama Software, Inc.

Custom Reports Guide Version:8.24

build great products

Custom Reports Guide Version: 8.242


Table of Contents

Part I Custom report development 3

................................................................................................................................... 31 Jama Reporting Tools

................................................................................................................................... 42 Custom Reporting Skills

................................................................................................................................... 53 Setting up a Report Development Environment

................................................................................................................................... 54 Report Parameters

................................................................................................................................... 65 Tips & Best Practices

................................................................................................................................... 76 BIRT

.......................................................................................................................................................... 7Install BIRT

.......................................................................................................................................................... 10Data organization

.......................................................................................................................................................... 11Report Libraries

................................................................................................................................... 117 Velocity

.......................................................................................................................................................... 11Get started w ith Velocity

.......................................................................................................................................................... 12Create a simple Velocity report

.......................................................................................................................................................... 13Velocity report syntax

.......................................................................................................................................................... 14Jama API access

.......................................................................................................................................................... 15Jama objects

.......................................................................................................................................................... 18Create a Velocity Word Document

.......................................................................................................................................................... 20MS Excel

................................................................................................................................... 218 External resources

Custom report development 3


1 Custom report development

Note: Hosted customers who wish to develop their own customreports must have a contract with Jama Services for reportvalidation and upload.

Jama provides many built-in reports that are designed to meet most common reporting requirements.

If you have a need that goes beyond built-in reports such as adding a logo, new types of reports oradding custom fields to reports, our custom report solutions are designed to help meet those needs.

Jama Support

Jama support offers assistance with problems running reports from the Jama web interface but does notinclude designing or modifying reports. Troubleshooting is limited to reports built-in to Jama. Forexample, support is unable to assist with writing SQL queries or BIRT report designer specific questions.

Report Design Services

Jama also offers reports development which provides you with turn-key custom reports created to yourspecifications and delivered via email or posted to your account for hosted Jama customers. CustomReport services are a cost effective way to quickly deploy custom reports without the overhead of settingup report development and testing environments and assigning internal resources. Contact your accountowner for more information.

Supported Reporting Tools

For generating reports within Jama, BIRT and Velocity are the only supported formats. For generatingreports outside the Jama web interface, any reporting tool may be used. The reporting tool connects tothe Jama database using a database driver (JDBC) or the Jama API. A user with read-only accessshould be created for the reporting tool.

Note about Rich Text (HTML) – If you do utilize a 3rd party reporting tool, make sure it can report onHTML text stored within database fields. If the reporting tool does not offer that functionality, you can turnoff the rich text capability within Jama.

Common 3rd Party Reporting Tools:

Business Objects

Crystal Reports

Actuate

1.1 Jama Reporting Tools

To generate a report from within Jama you must use either BIRT, Velocity or Office Templates. All ofthese tools have advantages and disadvantages and the chart below should help you understand whichtool is best for your situation.

Velocity BIRT Office

Custom Reports Guide 4


Template

Output to Word X X X

Output to Word using Word's Styles X X

Output to Excel X X X

Output to HTML X X

Output to PDF X

Possible to run report based on data results viewed inJama (current view)

X X

Ability to generate charts and graphs X

Apply programmatic logic and use parameters X X

Ability to re-import in Jama and update existing items X

Access to Jama's API X

Ability to run SQL queries for data X

Embed images into document X X X

Another factor to consider when figuring out which reporting tool to use for a given report is the skill set ofthe designated report designer. Someone that is more comfortable working with databases and SQL willlikely be more productive using BIRT whereas someone with a background in software developmentshould pick up Velocity quickly.

1.2 Custom Reporting Skills

The reporting engine within Jama provide a flexible and robust platform for designing reports - from simplelists to complex calculated charts. You may have individuals within your Organization that can createreports – or you can utilize Jama’s report design services.

If you are considering designing reports in-house, we’ve compiled the following list of key skills needed tocreate reports:

Developer & Tester Mindset – Successful report designers often have solid software engineeringbackgrounds and understand the event model and how to troubleshoot. Reports are a combinationof many moving parts – data sources, queries, parameters and output formats. Thinking like adeveloper and tester readies the stage for successful design, testing and deployment of reports.

File Management / Version Control – You’ll want to implement a procedure for tracking and



versioning report design files as you develop, test and deploy reports to Jama.

In addition to the above skils, each reporting method requires the following additional skills:

BIRT

SQL (Structured Query Language) – BIRT reports are based on SQL queries that pull data fromthe Jama database. You should have a solid understanding of Selects, Inner & Outer Joins, andSub-Selects.

Report / Development IDEs – BIRT is based on Eclipse so familiarity with an IDE (InteractiveDesign Environment) is very helpful. You will need to install, configure and work with the reportdesigner.

JavaScript – Fancy report manipulation, calculated fields and other functions use JavaScriptwithin the BIRT report. A basic understanding of JavaScript functions and syntax will be important,especially for complex reports.

Velocity Reporting

HTML - Velocity reporting is a Java-based reporting engine that uses HTML for displaying thedata. A basic understanding of HTML table structure will be useful in order to properly display yourdata.

1.3 Setting up a Report Development Environment

It’s a good practice to design and test reports against a non-production instance of Jama. This helpsreduce the chance of impacting your production system if you accidentally run a query that slows thesystem. Contact your account manager for information on acquiring a non-production license for Jama.

You can use generic test data in your local database or populate it with a copy of your productiondatabase using a backup and following the standard Jama installation process. If you are using customfields within Jama, you should establish a process for periodically syncing your test database with yourproduction database so you have the same configuration.

1.4 Report Parameters

Note: Hosted customers who wish to develop their own custom reports must have a contractwith Jama Services for report validation and upload.

Once you have created your custom report, you will need to to work with Jama Services to have ituploaded. If you have report parameters, they will be set up at that time. The following parameter typesare available for custom reports.

Parameter types

Jama provides the ability to pass several data types to the report engine.

Release - Will present all of the releases within the project in a Pick List. The user will have theoption to select one release for each release parameter.



Location - Will present the project hierarchy in a Pick List. The user will have the option toselect location for each Location parameter.

Baseline - Will present all of the baselines within the project in a pick list. The user will have theoption to select one baseline for each baseline parameter.

String - Will present the user with a Text Field to enter a string.

Date - Will present the user with a Text Field to enter a date.

Boolean - Will present the user with a Check Box. The value true or false will be sent to thereporting engine.

Test Plan - Will present the user with a Pick List of Test Plans in the selected project. Jamapasses the database ID to the report.

Review - Will present the user with a Pick List of Reviews in the selected project. Jama passesthe ID to the report.

Note: To include tags or relationships in a Velocity report a Boolean parameter for each must becreated. The tags parameter name must be: report_tag. The relationships parameter name must be:report_relate.

Display Name

Each parameter must have a display name. This name is what the user will read when running the reportand should describe the expected input from the user.

Name

Each Parameter must have a name. This name is what the report engine will use to identify theparameter. Each parameter in a report must be unique.

1.5 Tips & Best Practices

Here is a list of Best Practices that we have discovered while developing Jama's reports.

1. Share pick lists across item types when possible. This Best Practice is more for projectadministration than report development, however it is much easier to create and use a report thatincludes several sets within a project. A good example is when there is a field like Priority orStatus that will be used with most sets.

2. Make sure you are familiar with the administration of Jama. Create a new item type and thencreate sets using the item type in a project. Add items, releases and relationships in the project.

3. Develop reports outside of the production environment. Setting up an instance of Jama and asupporting database locally will protect your production environment from possible datacorruption or performance issues. Contact Jama Services to see if this is possible for yourinstance.

Velocity

1. Use Word or any editor that provides the ability to save a file to HTML to create a mockup of thereport. Then open the HTML, add the Velocity syntax and save the file with the .vm extension.

http://help.jamasoftware.com/index.html?velocity_custom_report_guide.htm



2. Not sure what data is available or how to get to it? Only enter the parent object's name and thenext time you run the report it will display everything that the object contains. This can be a lotof data, but it is comma separated with names and values.

3. If you have a custom field within the item type you are reporting on then you must use thegetValueForField method where you can state the name of the field that you are after. This namecan be found in the field column of the item type field configuration within the Admin perspective.

Example: $velocityReportUtil.getValueForField($test.document,$test.documenttypeDto,"custom_rtf1", $dateFormat)

BIRT

1. All elements within a report design or report library can be copy and pasted into another report orlibrary.

2. Users should avoid using spaces in the names of images inserting into rich text fields. BIRTcannot put these images into reports.

3. Insert parameters into the queries after the report works. It is easy to spend a lot of time in BIRTsetting up the parameters and debugging issues which may not be the best use of your timesince Jama does not use these parameters when running the report.

4. If there are Data Connections, Data Sets or Styles that you like in one report but don't want todeal with creating and managing a library you can select the targeted element and the use copyand paste.

1.6 BIRT

Hosted customers who wish to develop their own custom reports must have a contract withJama Services for report validation and upload.

Jama ships with an integrated reporting engine called BIRT (Business Intelligence & Reporting Tools).BIRT is an open source reporting engine sponsored by Actuate & IBM. BIRT was selected for Jama as itwas the only solution that renders rich HTML data such as lists, tables and images that are created byJama’s rich text editor.

Report templates are XML files created by a report designer that formats data retrieved through SQLqueries and renders the results in HTML, PDF, Word and Excel. Once a report template file is uploadedto Jama, users may generate a report through the web-browser without needing to know anything aboutthe designer – they just see the report output.

1.6.1 Install BIRT

Installing the Report Designer

Note: Installing BIRT is outside the scope of support for Jama Support. These links are provided forconvenience.

Download the RCP Designer (BIRT), version 4.4.2. Version 4.4.2 can be downloaded from http://download.eclipse.org/birt/downloads/build.php?build=R-R1-4_4_2-201502171805. Installation instructionsfor the BIRT RCP Designer may be found at http://www.eclipse.org/birt/documentation/install.php.

Note: Jama currently supports version 4.4.2. BIRT reports created on other versions will cause anerror in Jama.

http://download.eclipse.org/birt/downloads/build.php?build=R-R1-4_4_2-201502171805

http://download.eclipse.org/birt/downloads/build.php?build=R-R1-4_4_2-201502171805

http://www.eclipse.org/birt/documentation/install.php



Configuring the Report Designer for Use With Jama

Copy Example reports to your computer

The BIRT reports shipped with Jama can be found on the Jama server, under [Jama installationdirectory]/WEB-INF/reports/BIRT/. Copy all the files in that directory to the location on your computerwhere you want to store your Jama reports during development. (Typically C:\Users\<username>\MyDocuments\Jama Reports\ on Windows, or /Users/<username>/Documents/Jama Reports/ onMacOS.)

To begin using the designer with Jama, configure your resource folder and add a database driver toaccess your database.

1. Launch the BIRT Designer.

2. Select Window > Preferences > Report Design > Resource.

3. Browse to the Jama reports directory (above) and select OK.

Copy JDBC Driver to your computer

From the Jama server, copy the JDBC driver for your database to the Jama reports directory on yourlocal computer. Refer to the Database Drivers Property Reference below to find the appropriate driver.

Configure the Database Driver

In this step you need to configure BIRT to use the specific database driver and connection settings foryour environment.

1. Select File > Open File and Change the Files of type field to "*.rptlibrary".

2. Navigate to the Jama reports directory.

3. Select the file contour_library.rptlibrary and select Open.

4. Within the Outline view (lower left) expand the Data Sources folder.

5. Double-click on the Contour data source.

6. Select the Manage Drivers option.



1. Select Add.

2. Select the JDBC driver that was copied to your Jama Reports directory above, then select Open.

Example: For MySQL, the file would be:

C:\Users\<username>\My Documents\Jama Reports\mysql-connector-java-5.1.32-bin.jar

3. Select the Driver Class per the tables below.

4. In the Driver URL, confirm the URL is correct per examples below. NOTE: The database maybe named differently, the name is "contour" by default.

5. Update the database User Name and Password.

6. Select the Test Connection button and confirm success.

7. Select OK.

Database Driver Properties Reference

MySQL Database

Driver File mysql-connector-java-5.1.xx-bin.jar

Where to obtaindriver

[Jama Installation Directory]\WEB-INF\lib\

Driver Class com.mysql.jdbc.Driver (v5.1)



Database URL jdbc:mysql://DATABASE_HOSTNAME/contour?useUnicode=true&characterEncoding=UTF8

Microsoft SQL Server

Driver File jtds-1.3.x-jama-custom.jar

Where to obtaindriver

[Jama Installation Directory]\WEB-INF\lib\

Driver Class net.sourceforge.jtds.jdbc.Driver

Database URL jdbc:jtds:sqlserver://DATABASE_HOSTNAME:1433/contour

Note: Micorsoft's URL format for specifying an instance("jdbc:jtds:sqlserver://host\instance:port/

database") is not supported. See the jTDS FAQ for more information on configuring a named instance inthe database URL.

1.6.2 Data organization

It is important to have a clear understanding about how your data is managed within Jama prior tocreating a report. A good place to start understanding how the data is organized is by reviewing thetargeted data within Jama’s Admin menu and comparing that with the database schema.

Note: A copy of the database schema is available upon request.

Within this view you can discover which fields are included in each item type and specific informationabout each field.

http://jtds.sourceforge.net/faq.html#instanceName



Item type - Stored in the documenttype table, these provide the template for project sets whichare stored within the table documentgroup which translates to sets in Jama.

Field - This is the database column name from the document table where the user entered datawill be saved. The document is the starting place for all reports because it holds all of thepredefined fields. The list of the fields used by each item type is maintained in the table documenttypefielddefinition. If you come across a name in the field that is not in the documenttable that means it is a custom field that can be found in the table documentfield.

Field type - Describes the type of data stored within the field.

Pick List - The name of the pick list group that can be found within the table lookuptype. Theactual list of items that are shown in Jama's drop-down are stored within the lookup table and it isthat ID value that is recorded within the above described document table.

1.6.3 Report Libraries

BIRT provides the ability to create libraries which contain reusable reporting elements. This includes dataconnections, data sets (queries) and styles. Jama provides a reporting library with Jama that includes areusable connection to the Jama database. In order to use this library, once you have updated thedatabase connection information, you can start using the library in your reports.

You can also create new libraries for your Organization with database connection information and otherreusable components that makes it quick to create reports.

1.7 Velocity

Hosted customers who wish to develop their own custom reports must have a contract withJama Services for report validation and upload.

Velocity is a java based template engine that allows report designers to use a simple template languageto work with objects provided by Jama. The template is an XML file that can be created with any texteditor and while there is not a WYSIWYG designer available similar to BIRT, there are plugins for Eclipseand Textpad that highlight the syntax.

Warning: Velocity has direct access to an item's internal properties in the Jama database.Changing data from a Velocity report is not recommended.

Velocity is useful because it runs within Jama and can report on conceptual data such as folders in theexplorer or filters. Jama will pass to the velocity template the data you are currently viewing, includingresults not necessarily in view such as a grid that only shows the first 100 items. Velocity reports can beviewed in HTML, MS Word and/or MS Excel, depending on the options chosen when the report iscreated in Jama.

The Velocity user guide can be found at http://velocity.apache.org/engine/devel/user-guide.html.

1.7.1 Get started with Velocity

The Velocity file is an XML document that is made up of 3 main sections.

1. Declarations - This includes pieces such as the Microsoft specific Excel style as well as CSSstyles that can be used in the HTML.

2. Velocity Syntax - All text that is prefixed with # and $ are for the Velocity engine. (# = functions, $= variables)

http://velocity.apache.org/engine/devel/user-guide.html



3. HTML - The report layout is done with HTML.

Below is a report that is installed with Jama and can be accessed at ..\webapps\contour\WEB-INF\reports\velocity\allFieldsExcel.vm.

1.7.2 Create a simple Velocity report

In order to create a Velocity report, open a text editor, such as Notepad or Notepad++.

1. To create a simple velocity file, add some HTML:



2. Save the file with a .vm file extension, such as Test Report.vm.

3. Add your new report to Jama. Choose HTML as the Report Format (although Microsoft World orMicrosoft Excel may be selected as well).

4. As a Jama user, go to Reports and view your report.

5. To modify the report code, you can change the original .vm file and re-upload it to the Jama report.

Once you have created a basic HTML file, velocity code, as well as styling for Microsoft Excel and Worddocuments can be added.

1.7.3 Velocity report syntax

Velocity comes with its own syntax that allows the report designer to apply logic to the data returned.Information regarding the syntax is available in the Apache VTL Reference Guide. Longer examples canbe found in the Velocity User Guide.

Velocity Commands

Here are the primary commands that will be used to create your own Velocity report:

#foreach - Loops through a given object so that you can work with each item from Jama.

#if/#elseif/#else - Output conditional statements to help determine when and how data is outputto your report.

#set - Establishes a user variable and sets its value.

$ - The dollar sign prefixes objects that come from Jama, such as documentList, and the usercreated variables, such as $vDoc in the example below.

Example:

#foreach($vDoc in $documentList)

http://velocity.apache.org/engine/devel/vtl-reference.html




${vDoc.document.name} ${vDoc.document.description}

#foreach($relate in $vDoc.relationships)${relate.documentKey}

#end#foreach($tag in $vDoc.tags)

${tag.tag.tagName}#end

#end

Macros

Often, one or more reports use the same piece of code to complete a task, such as sorting orcomputing. If this is the case, you can use a macro in your Velocity report. However, there are a fewthings to note about macro use in Velocity:

1. In order for the macro (or its changes) to be recognized by the server, the Tomcat service must berestarted every time a change to the macro is made. If you do not have access to the Tomcat Service,an alternative is to change the macro name every time you make a change.

2. The server only recognizes one macro with a specific name. This means that if you have two reports,each containing a macro with the same name, only the one loaded first will be recognized. This canbe a problem if at some point you edit one of the macros, or if they do not contain the same code.

3. References are passed to Velocity macros by name. In other words, changing the value of avariable inside a macro will change it outside the macro as well. Unlike a programminglanguage like Java or C, the reference is not evaluated at macro invocation time but at everyoccurrence inside the macro. Do not treat macros as procedures or methods! See the VelocityUser Guide for more information.

Macros are typically found at the top of a velocity document. The following example adds an item to anarray:

#macro ( addToArray $array $value)#if( $array.add( $value )) #end

#end

To call that macro, use the following syntax in the body of your report:

#addToArray( $list, $foo)

1.7.4 Jama API access

Application context

Advanced Report Designers with Java experience can access the Jama API. This provides access tomore than the default data passed by directly calling Jama’s Data Access Layer (DAO’s). Jama usesSpring as its underlying architecture. In Spring there is an “applicationContext” which is the object usedto get access to the DAO’s. Once a DAO is accessed it is possible to call different methods within. TheJama API documentation is available online at http://www.jamasoftware.com/api/latest/.

http://velocity.apache.org/engine/devel/user-guide.html#velocimacros

http://velocity.apache.org/engine/devel/user-guide.html#velocimacros

http://www.jamasoftware.com/api/latest/



Example: Get the documentDao object and sets it into a variable called $documentDao to be usedlater.

#set($documentDao = $applicationContext.getBean("documentDao"))

Data access objects (DAO)

The Data Access Object provides methods for retrieving data from the database.

Example: Get a “document” object from the documentDao. The new $doc object is then used tooutput the data.

#set($doc = $documentDao.getDocument($documentId))

$doc.name

$doc.status.name

$doc.lookup1.name

$doc.release1.name

$doc.assignedTo.firstName

Note: this example applies no formatting so the data would appear in a straight line.

1.7.5 Jama objects

Once you have an understanding of the Velocity syntax, the next step is to manipulate the data Jamahas passed to the template. Below is a partial list of the fields and methods available within a Velocityreport. The list below is being provided only as an overview of the commonly used items and the JamaAPI should be referenced if you want the complete list: http://www.jamasoftware.com/api/latest/

Note: The $documentList object will only be passed into a velocity report if the report has beenset up in reports administration to run as Context Sensitive. This means that the report can only berun from the Export menu. Reports run from the Reports link on the top right-hand side of Jama will havean empty $documentList object. Global reports (the ones run from the Reports link) will need to containcode that gets any necessary documents using code similar to the following:

#####Get the docs in the project ##########set($projectDocIds =$contourItemDao.getContourItemIdsForProject($mathTool.toInteger($project.id)))

##Get the Contour Items by DocId and add to the ProjectDocs array#foreach ($projectDocId in $projectDocIds)

#set ($z =$contourItemDao.getContourItem($mathTool.toInteger($projectDocId)))

#if( $z.active )#if( $projectDocs.add($z))#end

#end#end

$documentList

document - the actual document which could be a requirement, use case, test case etc.id (Integer)

http://www.jamasoftware.com/api/latest/



documentGroupDisplay (String)documentUrl (String)createdDate (Date)modifiedDate (Date)documentKey (String)name (String)description (String)assignedTo (UserInfoDTO)status (Lookup)priority (Lookup)release (Release)detail (String)originalEstimate (String)

remainingEstimate (String) timeSpent (String)

documentTypeDtofieldList ArrayList()id (Integer)name (String)description (String)

relationships - All the directly related Items to the document. Includes both upstream anddownstream relationships. (Only available when parameter is configured)traceId (Integer)forward (boolean)traceType (Lookup)traceStatus (Lookup)traceDescription (String)suspect (boolean)relationshipType (RelationshipsType)documentId (Integer)documentName (String)documentGroup (String)documentType (String)documentStatus (Lookup)documentRelease (Release)assignedTo (String)projectName (String)

tags - All tags that are applied to this item. (Only available when parameter is configured) The tagsobject has a list of tags. Each tag has a tag object which has the tag and the document. So,when you use this object it will seem redundant to have to say tag.tag.tagName to get the nameof the tag. If you call your variable something different it's a bit better. obj.tag.tagName but onlyby a little bit.

documentFieldDTOid (Integer)label (String)showInList (Boolean)

$documentList functionsgetDocument()getValueForField() - There are four ways to call method depending on whether you want to state



the field or if the report is going to excel. See the API documentation.

$project

id (Integer)name (String)description (String)statusId (Lookup)isFolder (Boolean)projectManager (UserInfoDTO)projectGroup (Lookup)projectTypeDto (DocumentTypeDTO)createdDate (Date)modifiedDate (Date)createdBy (UserInfoDTO)modifiedBy (UserInfoDTO)

$dateFormat

convertStringToDate()calculateTimePast()

$textUtil

normalizeXML()replaceBreakForExcel()encodeTextForHTML()cleanWord()

$velocityReportUtil

getValueForField() - Best used for custom fields. The fieldID is the API-ID found on the item typeconfiguration.

Velocity Tools - Velocity API http://velocity.apache.org/tools/devel/generic/

mathToolsortTooldateToolescapeToollistTool

Velocity Tool Examples

In this example the math tool is used to cast the parameter $report_Set1 to an integer so it can be usedby the Jama API to return the set name.

#set($documentGroupDao =$applicationContext.getBean("documentGroupDao"))#set($toSet =

$documentGroupDao.getDocumentGroup($mathTool.toInteger($report_Set1)).displayPlural)

The sort tool takes in group of sets and sorts them in the order they are displayed in the Explorer.

#set($documentGroup =$documentGroupDao.getDocumentGroupListForProject($vList.document.project.Id)) #foreach($set in $sortTool.sort($documentGroup,"sortOrder"))

Current date examples.

$dateTool.date - returns full current date and time $dateTool.getDay() - returns current day

1.7.6 Create a Velocity Word Document

Velocity reports can be created with Microsoft Word styling and features such as table of contents,headers and footers.

1. In order to create this Word Document, create a mockup of your report document in Word, using theformatting and styling you wish to see in your autogenerated report.

2. Once the document has been created, save it as an .html document.

3. Outside of Microsoft Word, change the document suffix from .html to .vm. This file can now beuploaded into Jama, and edited in a Notepad editor.

4. Force the Word version to display the Print View instead of the HTML view by pasting this code in the<head> section - below the meta tags:



5. Remove the references to any outside file. Search for the words “url” and “file” – especially in the@page section. This file path is referring to other files that Word created when you created an HTMLdocument. Usually, this is the file that holds the header information. When it says:

mso-footnote-continuation-separator: (url:”filepathinthisfolder”) fcs;

Remove everything in the parenthesis to get:

mso-footnote-continuation-separator: fcs;

Headers and Footers

When you created a header and/or footer in the original Word document, Word put them into a separatefile in a nearby folder. The HTML for the header/footer now needs to be put into this .vm file.

1. Find the header.htm file in near where you originally saved the .doc to .htm. Open header.htm andsearch for "h1". Copy the entire header text from “<div style=’mso-element:header’ id=h1> down to the</div>.

2. In the .vm file, search for <div class=WordSection 1>. At the very very end of the div section, beforethe </div> and </body> tags, paste that header text from above into it (you can search for the next </div>).

3. The above can be repeated for the footer (using f1).

4. Once you have copied the header and footers in, they often show up twice on the last page. In order tomake them “disappear”, we put them into a table that has a very large margin. Right above the headertag at the bottom “<div style='mso-element:header' id=h1>”, put the following html:

##Next 2 lines help the header and footer not appear at the bottom ofthe last page<table style="margin-left:10in;"><tr><td>

Then go to the very bottom of the code and put the following html right above the </body> tag:

##End of the table that helps the header and footer not repeat printing</td></tr></table>

Table of Contents

To add a table of contents, put the following code where you would like the table of contents to display:

#####TOC#####

<span style='mso-break-type:section-break></span>



<p class=MsoNormal> <span style='mso-break-type:section-break'></span>

#############

Images in Velocity (such as a logo in the header)

To upload images, such as logos, you will need to upload the .png or .jpeg to the project in Jama. To dothis, go to Admin > Manage all projects. Select the project, then Configure project. On theAttachments tab, upload the file. Once it’s been uploaded, you can select the view link and copy the urlon that new webpage. When you put the image in, it would look something like:

<img width=390 height=160 img width=390 height=160src="http://localhost:8080/contour/attachment/79/v/CustomerLogo.png"alt="Description: customerlogo" >

Note: Because this image is stored inside of Jama, only users who have rights to this project in Jamawill see the logo. If they do not have rights to the project (such as a report recipient who does not haverights to Jama), the image will appear broken. Saving the report as a .pdf before sending it to those whodo not have project rights will allow them to view the image.

Page Numbers

To add Page N of M page numbering to the report, add the following code (usually to the footer):

Page  of 

1.7.7 MS Excel

The Velocity reports can be output to several formats: HTML, Word, PowerPoint and Excel. The designof the reports is similar; however, when you create a report for Excel there are two considerations youneed to take into account. We suggest you review the Velocity reports packaged with your Jamainstallation available with the directory ..\webapps\contour\WEB-INF\reports\velocity\.

Microsoft Schema

Velocity can be exported to Microsoft Excel quite easily. If the report being exported is very simple,using only one worksheet and no Excel functionality, setting Excel as an option is all that needs to bedone. However, if the report needs to use more complex Excel functionality such as multiple worksheets,the following declaration is required:

<html xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:x="urn:schemas-microsoft-com:office:excel" xmlns="http://www.w3.org/TR/REC-html40">

<head>



getValueForField() exportToExcel Boolean

The method getValueForField() can include the variable exportToExcel. When this is set to "true" Jamawill format any rich text fields to fit within one cell.

1.8 External resources

Eclipse BIRT Resources

The Eclipse BIRT product has a large community of developers and users with lots of informationavailable on the web. The BIRT product home page is: http://www.eclipse.org/birt/.

BIRTDocumentation

http://www.eclipse.org/birt/documentation/

BIRTCommunityForum

http://developer.actuate.com/community/forum/

SQLReference

http://www.w3schools.com/sql/default.asp

Velocity Resources

The Apache Velocity project home page is http://velocity.apache.org/.

Velocity UserGuide


Velocity Wiki http://wiki.apache.org/velocity/FrontPage

HTML &JavaScript

http://www.w3schools.com/HTML/

http://www.w3schools.com/js/default.asp

http://www.eclipse.org/birt/

http://www.eclipse.org/birt/documentation/

http://developer.actuate.com/community/forum/

http://www.w3schools.com/sql/default.asp

http://velocity.apache.org/


http://wiki.apache.org/velocity/FrontPage

http://www.w3schools.com/HTML/

http://www.w3schools.com/js/default.asp