Chapter 8: Report Generation

• Search Result Report
• Object Report
• Report Template Customization
  • Template Directory Structure
• Header/Footer Customization
• Embedded Coding
  • Coding Syntax
  • Calendar Fields
  • Timesheet Fields
  • Project Fields
  • Test Case Fields
  • Issue/Risk Fields

Search Result Report

• User search
  • Users Project Allocation report displays the % allocation of each user to each project as a pie chart.
• Project search
  • Project List report displays the project search result as a table.
  • Requirements List report displays requirements across projects.
• Test case search
  • Test List report displays the test case search result as a table.
• Issue search
  • Issue List report displays the issue search result as a table.
• Risk search
  • Risk List report displays the risk search result as a table.

The Report File Name contains the name of the report file to be generated. You can change this.

The Report drop-down list contains a list of available report templates you can choose from. You can customize the currently-selected report template by pressing the Report button. You can also customize the page header/footer for a report by pressing the Header/Footer button.

The Options tab provides a list of options applicable to the currently-selected report template. To enable/disable an option, click in the tick column to toggle it.

The Filters tab is enabled only for certain reports, and allows you to filter the report data.

Press the Generate button to generate the report. The report is generated as an RTF document and immediately opened with your RTF viewer (usually Microsoft Word).

Object Report

• Calendar
• Timesheet
• Project
• Project Dashboard
• Test Case
• Issue
• Risk

Make your choices from the dialog and press Generate to generate the report.

The Filters tab is enabled only for reports that provide filtering functionality. Project Review is one such report.

This report includes issues and risks. The filters allow you to decide which issues/risks should be included/excluded based on the selected criteria.

Report Template Customization

To customize a report template, bring up the report generation dialog, choose the report you wish to customize from the Report drop-down list, and press the Report button. The following dialog will appear.

Report templates are classified into three kinds:

• A standard template is one provided with the product and cannot be changed by users. These are listed in italics.
• A shared template is one that has been customized by a user for shared use by multiple users. These are listed in normal font.
• A custom template is one that has been customized by a user for their private use. These are listed in bold.

To be able to create/access shared reports, you must nominate a shared directory where shared report templates reside. To do this, press the Shared Directory button, and navigate to and select a directory accessible by multiple users (e.g., on a network drive). The directory name will appear in the field to the right of the button. You can also clear this field by pressing the Clear button.

When you view the report customization dialog for the first time, it will only contain standard report template(s). To customize a template, select it in the list and press the Duplicate button. The following dialog will appear.

The Existing Name field depicts the name of the template you're duplicating, and the Duplicate As field depicts the name of the duplicated template. The Duplicate As Shared check box gives you the option of creating the template either as shared or as private (the check box is disabled if you haven't specified a shared directory yet). Enter the desired template name and press the OK button. The duplicate is created and immediately opened in your RTF editor, ready for editing.

To edit a shared or custom template, select it from the list and press the Edit button, or simply double-click its row. The template is opened, ready for editing.

To rename a shared or custom template, select it from the list and press the Rename button. The following dialog will appear, allowing you to rename the template.

To delete a shared or custom template, select it from the list and press the Delete button. You will be asked to confirm this operation.

The New button is reserved for future use and is, therefore, disabled at all times.

While editing a report template, you can modify two things:

• The report format (fonts, paragraphs, styles, static text, etc).
• The embedded code which controls what POMS data is inserted into the report when it is generated. To do this, you must adhere to the embedded coding rules.

Header/Footer Customization

The procedure for customizing header/footer templates is the same as that for customizing report templates. Press the Header/Footer button in the report generation dialog, and follow the customization procedure.

Template Directory Structure

Custom report templates (along with standard templates auto-downloaded from the server) are stored on the client-side in the following directory:

<root>/prag/po/report/plate/

For each report type, a sub-directory named after the report template exists within the above directory, which in turn contains two sub-directories, one for standard templates, and one for custom templates. For example, for Project List and Project List B, the locations of the template files are:

<root>/prag/po/report/plate/ProjectList/standard/Project List.rtf <root>/prag/po/report/plate/ProjectList/custom/Project List B.rtf

Shared report templates are held in your nominated shared directory under a sub-directory named after the report template. For example, the location of Project List A is:

<shared>/ProjectList/Project List A.rtf

Embedded Coding

• Static text. These will appear in generated reports verbatim, exactly as formatted in the report template.
• Embedded code. These are delimited in one of two ways:
  • <<code>>. These code fragments have useful side-effects (e.g., local variables, loops, calculations). They are executed during report generation but do not leave any trace in the generated report.
  • <?code?>. These code fragments are evaluated during report generation and the result of evaluation is inserted in the generated report at the exact point they appear (e.g., name of a project).

Coding Syntax

Within each report template, the variable repData is predefined. All report data is passed by POMS to the report engine via this variable. This variable is a nested structure, containing two sub-structures:

• repData.bo refers to the business object for a report.
• repData.extra provides additional report information:
  • criteria. For search result reports, this structure contains the search criteria as a structure.
  • info. Contains two fields: name denotes the licensee and org denotes the licensee's organization.
  • options. Contains a field for each of the report options.
  • filters. Contains a field for each of the report filters.
  • attach. Contains a vector of report attachments.
  • images. Contains a vector of report images.

Calendar Fields

• id (calendar object ID).
• name (calendar name).
• predefined (whether calendar is predefined).
• from (first year of the calendar).
• to (last year of the calendar).

Timesheet Fields

• id (timesheet object ID).
• userId (user ID of the timesheet owner).
• weekBegin (the date on which the week begins).
• status (timesheet status).
• monTot, tueTot, wedTot, thuTot, friTot, satTot, sunTot (worked total hours for each week day).
• totTsHours (total timesheet hours for the week).
• tasks is a vector of sub-structures, one for each timesheet task. The sub-structures have the following fields:
• name (task name).
• project (project name).
• alloc (percentage time allocation to the task).
• mon, tue, wed, thu, fri, sat, sun (hours spent on the task for each week day).
• totTsHours (total task hours for the week).

Project Fields

• id (project object ID).
• name (project name).
• archived (whether the project has been archived).
• bu (project business unit).
• trafficLight (project traffic light status).
• category (project category).
• status (project status).
• priority (project priority).
• calenOverlay (project calendar overlay).
• runBy (the party who runs the project).
• forClient (the client for whom the project is run)
• dependencies (project dependencies)
• requiredStart (required project start date).
• requiredFinish (required project finish date).
• startDate (actual project start date).
• finishDate (actual project finish date).
• duration (total project duration, in days).
• effort (total project effort, in person-days).
• estEffort (estimated total project effort, in person-days).
• complete (project percentage completion).
• estComplete (estimated project percentage completion).
• createdBy (user who created the project).
• createdOn (creation date).
• editedBy (user who last edited the project).
• editedOn (last edit date).
• description (project description).

• requirements is a vector of structures, each having the following fields.
  • id (requirement ID)
  • projectId (ID of project containing this requirement).
  • title (requirement title).
  • category (requirement category).
  • complexity (requirement complexity).
  • status (requirement status).
  • descWhere (where requirement is described).
  • description (requirement description).
  • attachId (ID of project attachment describing the requirement).
  • attachName (name of project attachment describing the requirement).
• resources is a vector of structures, each having the following fields.
  • resource (ID of resource allocated to project).
  • role (resource role).
  • scMember (whether a member of steering committee).
• tasks is a vector of structures, each having the following fields.
  • id (task ID).
  • projectId (ID of project containing this task).
  • name (task name).
  • milestone (whether it's a milestone).
  • requiredEffort (required task effort).
  • requiredStart (required task start date).
  • requiredFinish (required task finish date).
  • startType (task start type).
  • finishType (task finish type).
  • effort (scheduled task effort).
  • start (scheduled task start date).
  • finish (scheduled task finish date).
  • complete (task percentage complete).
  • status (task status).
  • priority (task priority).
  • notes (task notes).
  • resource is a vector of structures, each having the following fields.
    • id (resource ID).
    • name (resource name).
    • alloc (percentage task allocation).
• account is a sub-structure, having the following fields.
  • budget is a vector of structures, having the following fields.
    • name (budget item name).
    • original (original item amount).
    • revised (revised item amount).
    • variance (item variance).
  • origBudget (original budget total).
  • revBudget (revised budget total).
  • varBudget (budget total variance).
  • totActual (total actual expenditure).
  • txns is a vector of structures, having the following fields.
    • date (transaction date).
    • createdBy (ID of user who created the transaction).
    • type (transaction type).
    • description (transaction description).
    • amount (transaction amount).
  • reviews is a vector of structures, having the following fields.
    • date (review date).
    • createdBy (ID of user who did the review).
    • trafficLight (traffic light status after review).
    • planEffort (planned effort).
    • actEffort (actual effort).
    • complete (percentage complete).
    • revEffort (revised effort).
    • planSpend (planned spend).
    • actSpend (actual spend).
    • revBudget (revised budget).
    • comment (review comment)

Test Case Fields

• id (test case ID).
• title (test case title).
• archived (whether the test case has been archived).
• bu (test case business unit).
• project (project to which the test case applies).
• module (module to which the test case applies).
• build (build number to which the test case applies).
• category (test case category).
• type (test case type).
• phase (testing phase).
• priority (test case priority).
• createdBy (ID of user who created the test case).
• createdOn (test case creation date).
• editedBy (user who last edited the test case).
• editedOn (last edit date).
• instructions (instructions for running the test case).
• expResult (expected result for a successful test run).

• runs is a sub-structure of the following fields.
  • id (test run ID).
  • date (test run date).
  • runBy (ID of user who performed the test run).
  • build (build number to which the test run applies).
  • cycle (test cycle number).
  • phase (testing phase).
  • outcome (test run outcome).
  • issues (vector of issue IDs raised for this test run).

Issue/Risk Fields

• kind (an ISSUE or a RISK).
• id (issue/risk ID).
• title (issue/risk title).
• bu (issue/risk business unit).
• project (project to which the issue/risk applies).
• module (module to which the issue applies).
• build (build number to which the issue applies).
• type (issue type).
• severity (issue severity).
• state (issue/risk state).
• priority (issue priority).
• impact (risk impact).
• likelihood (likelihood of risk impact).
• cycle (risk review cycle).
• raisedBy (ID of user who created the issue/risk).
• raisedOn (issue/risk creation date).
• description (issue/risk description).
• assignedTo (ID of user to whom the issue is assigned).
• assignedOn (issue assign date).
• testCase (ID of issue's associated test case).

• history is a sub-structure of the following fields.
  • date (action date).
  • actBy (ID of user who did the action).
  • oldSt (issue/risk state before the action).
  • act (the action).
  • newSt (issue/risk state after the action).
  • note (action note).
  • summary (short version of action note).
• progress (issue/risk progress to-date).