1

RATIONAL REPORTING UXD GUIDELINES

Proposed guidelinesCharts in dashboard viewsV4 - 2011.10.19

V3 includes Mike Pawlowski’s feedback and adds discussion outcomes from the Oct.19 Report Design Workgroup meeting.

Review status: Oct.19 – Peter/Linda/James reviewed the doc to midway page 13.

Blue text indicates outstanding issues to be resolved.Bold blue text indicates latest comments

Approvers for this document are:BIRT – James MoodyRRDI – Peter HaumerRRDG – Edgar Velazquez MarUXD – Linda Watson

Contents

1. Background 2. Dashboard features3. General guidelines4. Graph guidelines5. Table guidelines6. Summary of development tasks

1. Background

Presentation practices for charts (graphs and tables) in dashboards were informally established for the RTC BIRT reports in late 2008. Since then, some behaviors have changed, but the RTC charts reflect these changes.

To create explicit guidelines for charts in dashboards, we will document the current practices used by the RTC BIRT reports, then adjust as needed based on feedback from the Report Design Workgroup stakeholders for BIRT and RRDI.

Noted: RRDG docs will not be viewed in dashboards. The first discussion outcome was to re-visit for 2013. Subsequently Edgar has advised: “IMHO displaying RRDG documents on dashboards doesn't makes sense since it's all static information - once the report has been generated, the in-formation is outdated practically right after its generation. Also the output is a PDF or Word file. This is not for 2012 only but I think it will keep being the behavior not to show them on the dash-boards.”

<MP>This wiki document I wrote for RQM needs to be reconciled with these proposed guidelines or vice versa:How To Create RQM Micro BIRT Report Templates:https://jazz.net/wiki/bin/view/Main/RQMMicroBIRTReportTemplates

</MP>

2

Ravi’s task to investigate Mike’s RQM Micro BIRT info is 54983 in RQM

2. Dashboard features

This section shows only the presentation and interaction features of viewlets which are relevant to charts in dashboard viewlets. The collapsed state of the viewlet is not shown.

Viewlet – minimized state Peter’s terminology question: “minimized” is really default state with only a “maximize” icon? Linda to check –-> Jen Hayes is investigating whether this current Jazz terminology should be changed. In the meantime this document will use the current terminology where “minimized” refers to the default viewlet state, “maximized” refers to the maximized state. “Collapse/expand” on the viewlet menu replaces the conventional “minimize” action.

<MP>Both ”Minimized” or “Default” state is acceptable terminology. Some people still use the legacy terminology “Unzoomed” and “Zoomed” which is fine too.</MP>

1. default presentation

2. Link to report

3. Maximize icon

3

4. Menu

5. Menu / Settings

4

6. Parameters Shown

7. Pagination (shown) / Scrolling (not shown)

5

Viewlet – maximized state

6

Linked report page

7

3. General guidelines

These are guidelines which apply equally to graphs and tables.

Viewlets should present a single graph or tableWhen there are multiple charts (graphs and/or tables) in a report, display only one chart per viewlet. The design rationale is that the charts can be displayed side by side in the dashboard for comparison, so not only is it not necessary to put more than one chart in a single viewlet, the side by side comparison of single charts in multiple viewlets is the more effective, usable alternative.

Viewlet title nameThe viewlet title name is a link to the full report. The viewlet title should ideally be consis-tent with the title of the report object which the user links to.

Current RTC practice: The viewlet title is (or should be) the same as the title of the report. (The title of the report is different from the title of the report template).

Scenario 1 - If there is only one chart in a report, when the chart displays in a viewlet, the viewlet title should be consistent with the title of the report.

Secnario 2 - When there are multiple charts in a report, and two or more of these charts are displayed together in one dashboard, the viewlet titles should be consistent with the titles of the respective charts.

If Scenario 2 is supported, it would make sense to always display the title of the chart, not the title of the report, in the viewlet title. Requires technical investigation.

<MP>Viewlet Tech Notes:

At development time, this is accomplished by simply naming the title for the viewlet entry accord-ingly when contributing the viewlet via OSGi extensions. When the viewlet is added to the Dash-board / Mini Dashboard, it uses the viewlet entry title as the default (for Trend Report viewlets)

At runtime, this is accomplished similarly by simply naming the title for the viewlet entry accord-ingly when contributing the viewlet via the process specification.

Once, the 'generic trend reports viewlet' is implemented, we can dynamically set the viewlet's pri-mary title depending on the micro report template selected in the viewlet settings area. This is as-suming that the micro report template is named the same as the chart title it represents and that this information is delivered via a Reports REST service. See: 64927: [Trend Reports Viewlet]: Add the ability to easily add a new trend report to a dash-board after deploying a micro report template (at runtime)

Note: The viewlet entry title and the report template / chart title are stored in two separate places and need to be reconciled.

Note: The user can (and do) manually override / rename the viewlet title to something more de-scriptive after configuring it with their custom report parameters (e.g. “All Open Foundation Work Items by Type”)</MP>

BIRT: The above only works for BIRT. RRDI report inserts the whole report into the viewlet, it can’t insert the chart. There is only

a generic viewlet to select from gallery with options; only the report can be selected. In-

8

vestigate terminology for how the viewlet widget in the gallery is named. Currently is “Cognos report” for RRDI vs. “Custom report” in BIRT.

Minimized and maximized viewlet states

These are guidelines which apply equally to graphs and tables in both the minimized and maximized viewlet states.

Alert text and info text elements associated with the chart are not displayed

Navigation links not directly embedded in the chart, e.g. links displayed below the legend of a graph in the report, are not displayed

Navigation links directly embedded in the chart, e.g. links which are data elements in the columns/rows of a table, are displayed. Similar to links to work items, these links are functional in both the minimized and maximized viewlet states. These navigation links do not provide the Jazz Web UI rich hover feature

Charts do not provide the Jazz Web UI rich hover feature

Parameters collapsible show/hide interaction

BIRT practices from James:This is possible for BIRT reports because we have the ability to query the report for infor-mation (metadata) about its parameters (how many parameters do you have? what are their names? what are their values for the current report? etc.). The show/hide and chevron are outside of the report design; it's part of the viewlet implemented in javascript, and uses the report APIs I mentioned to construct the labels.

RRDI can add the RRDI collapsible parameters to the report in a fashion modified for best presentation in the viewlet. The minimized viewlet state is in is in scope for CLM 2012; the maximized is uncertain.

Requires further investigation re consistency of presentation.

<MP>

Assumption: We are talking about this:

9

Problem: The “report parameters section” is not consistently shown for all trend report viewlets across all CLM products.e.g. CCM trend report viewlets always show the section.e.g. QM trend report viewlets never show the section. There is a hack in place for the base QM trend reports viewlet to suppress the built-in section provided by the base trend reports viewlet from Foundation.

Note: The section is rendered independently by the viewlet (using JavaScript on the client) and NOT by the (BIRT) charting engine.

I believe the major sticking point is that none of the values for report parameters have hu-man readable / NLS'd names. So you will end up with an item ID surfaced as a value in the section. (e.g. QM “Timeline: _R0tu8Y8EEd2qYaTbC0aXsg”). In CCM, it just so hap-pens that most of the values are human readable – but some need to be normalized by the viewlet (e.g. '{Current Project Area}' --> 'Current Project Area'). However, same val-ues are shown raw and are considered as bugs. See: 85218: [Trend Reports Viewlet]: Parameter value normalization issues</MP>

RRDI / Peter – action for RQM team – remove the hack that suppresses display of paramters? Requires tech investigation, and report by report analysis re condensing pa-rameters. Work item 57235

BIRT / James - In terms of practices, there's not much; most of our reports have 5 or fewer parameters, so the height is kept to a reasonable size. In terms of parameter val-ues (the width), we restrict it to a certain fixed width, and truncate the value and use el-lipses at the end. We comma-separate the parameter values. Thus:

10

Team Area                  Team1, Team2, Team3, ... I don't recall the point size of the font we use, but it's smaller than the standard body font.LW: the font size is 8 pt.

TECH NOTES

o BIRT – our dashboard reports have a zoom parameter and that controls whether you see the small version of the chart or the max version of whatever graph or ta-ble is in the viewlet.

o RRDI – we cover both states from style guide vs. technical support for the min and max state. The min(default) state will be supported in CLM 2012, need to de-cide if max state (zoom parameter or alternative) will be supported (not likely re time constraints)

11

Minimized viewlet state

Parameter Show/Hide LinksThe style of the Show/Hide Parameter links for the Trend Reports viewlet is being up-dated in … https://jazz.net/jazz/web/projects/Rational%20Team%20Concert#action=com.ibm.team.workitem.viewWorkItem&id=179487… as follows:

Show/Hide Parameters links in reports viewlets should be Secondary Action Hy-perlink green:

Regular- Arial regular- Green Hex # 6DA903- 8pt

Hover:- Arial regular- Text-decoration: underline- Green Hex # 6DA903- 8pt

Show Parameters: grn-double-chev-down.pngHide Parameters: grn-double-chev-up.png

RRDI – Show Hide is provided in the RRDI report, not the viewlet, Need the icons for 2012. Future enhancement post 2012.

BIRT (James): This is possible for BIRT reports because we have the ability to query the report for information (metadata) about its parameters (how many pa-rameters do you have? what are their names? what are their values for the cur-rent report? etc.). The show/hide and chevron are outside of the report design; it's part of the viewlet implemented in javascript, and uses the report APIs I men-tioned to construct the labels.

Pagination Need to establish usage guidelines for pagination (Linda will refer to Jazz UXD guidelines and note exceptions).

BIRT charts currently don’t use pagination. BIRT won't support pagination for 2012.

RRDI charts: The RRDI pagination setting is on by default. Jazz pagination is not used.

Ravi to investigate viewlet pagination. (done) Linda to provide mockup for RRDI pagination in both full report

and viewlet states

<MP>I think Jen has already established guidelines for all use cases (including viewlets) within the wiki document: “User Interface Pattern & Style Guide for Jazz Web Applications”https://jazz.net/wiki/bin/view/Main/PaginationGuideline</MP>(Linda will refer to Jazz UXD pagination guidelines and note exceptions).

ScrollingNeed to establish usage guidelines for scrolling – when they are published, reference the Jazz UXD guidelines and note exceptions.

BIRT charts currently don’t use scrolling. In the past scrolling was not available.

12

o (Linda) Jennifer Hayes’ feedback on the Jazz viewlet scrolling feature:

JH > We haven't used scrolling widely in viewlets because it's preferable to use the pagination mechanism when the amount of content exceeds the physical space of the viewlet window. However, scrollbars are available in viewlets when the content dictates it. For example, the viewlet below pulls in an external site where pagination would not be suitable at all. The scrollbars kick in automatically.

Minimized:

13

Maximized:Fyi: There are some issues when viewlets are maximized where they aren't using the full vertical space.

o Requires further investigation

RRDI charts Horizontal and vertical scrollbars are available in the Cognos viewlet.o Note there are redundant scrollbars: Cognos viewlet scrollbars + report scrollbars

(see example on next page) Needs investigation.------ Oct. 19 review ends here ---------------------------------------------------------------------------------

<MP>One of the cardinal rules of viewlet development is that viewlets should never show or rely upon scroll bars to manage their content area.

In an ideal world:(a) Table-based viewlets should rely on pagination.(b) Chart-based viewlets should detect the dimensions (width and/or height) of the viewlet content area and render a chart that best fits the available space (e.g. maintains acceptable proportions).

RE: (b). The “Work Item Statistics” viewlet's Bar/Column/Pie Flash-based chart presentations ex-emplifies the ideal behaviour well.I have a story defined for this release to make the Trend Reports viewlet render SVG-based BIRT charts (instead of static PNG image-based charts):150505: [Trend Reports Viewlet]: Report charts should dynamically fill all available space in the viewlet content areaNote: I need to discuss the feasibility of this with James and do a corresponding exploration.

14

Work-arounds:

RE: (a). The “Work Item Statistics” viewlet's table presentation does not use pagination.Instead, it groups excess entries (>10) into an “Other” category. When the “Other” category is clicked, a Jazz UI Dialog is opened with a scrollable area containing the other entries not ren-dered in the viewlet content area (See image below).

RRDI / Peter: for pagination just focus on re-styling the RRDI current implementation; other ques-tions are low priority.

……Oct.5 & 19 document reviewed to here. ………………………………………………

</MP>

15

Example: RRDI pagination and scrolling

16

Content reduction

In the minimized viewlet, the general strategy is to reduce the amount of content dis-played to only the most important data. Here’s an example applied to a table:

When reducing information, keep the content in the same order as it appears in the maxi-mized and report page views. (Note the example above incorrectly switches the order.)

<MP>Opened the following bug against myself:179334: [Build Queue Viewlet]: "Progress" & "Label" result columns in minimized / maximized state are inconsistent</MP>

As needed, condense the parameters information so it is readable and provides the mini-mum amount of data required to support the chart

BIRT / James - In terms of practices, there's not much; most of our reports have 5 or fewer parameters, so the height is kept to a reasonable size. In

17

terms of parameter values (the width), we restrict it to a certain fixed width, and truncate the value and use ellipses at the end. We comma-separate the parameter values. Thus:Team Area                  Team1, Team2, Team3, ... I don't recall the point size of the font we use, but it's smaller than the stan-dard body font.Linda – the font size is 8 pt.

o RRDI - won’t be addressed in this release; continue to discuss as a guideline item for future direction. Should work in the same way whether custom, BIRT or RRDI. Requires more development work on the RRDI side.

Maximized state

The maximized state displays more of the chart’s data than the minimized view, but does not display related information such as Alert Text, Information Text, Navigation links which is exterior to the chart.

The maximized state only displays the basic chart elements; it does not display any of the other components of the report page

18

4. Graph guidelines

Minimized state

Examples

Guidelines

The size of text labels for the graph changes to 8 pt.

For most scenarios, display only the x and y axis lines, the data objects (lines, points, or bars), the lowest and highest quantitative values, and the legend

19

There may be exception cases where different or more data needs to be added, but as a gen-eral rule of thumb remove all extraneous detail and allow the parameters to provide neces-sary supplementary information. But identify any such scenarios so we can create exceptions in the guidelines

<MP>As a general rule, I strongly suggest always including the following chart elements in the mini-mized and maximized states (based on user feedback):

(a) X-axis / Y-axis lines

(b) X-axis labels / Y-axis labels - Without the labels, the chart is missing critical contextual information (users have no idea what they are looking at without drilling-in or maximizing the chart). - Only specifying the start / end numeric range numbers does not look proper (haven't seen a precedent for this anywhere else) - Use natural numeric intervals. The interval scale should be a factor of either 1, 2, or 5. (e.g. In the above chart, 90 should be used instead of 81) - The charting engine should attempt to use the tightest interval scale that fits the data given the available chart area. BIRT does this computation well automatically (e.g. In the above chart, the interval scale should be 0, 10, 20, ..., 90 rather than 0, 50, 100) - Long labels must be truncated with ellipses if they exceed ~20% of the total horizontal report area (I had to add a BIRT script hack to accomplish this because BIRT's axis label ellipsis support is broken)

(c) X-axis / Y-axis ticks (only for numeric axis values) - Omitted for long labels and dates

More details in this Wiki document I wrote for RQM micro reports:https://jazz.net/wiki/bin/view/Main/RQMMicroBIRTReportTemplates

e.g. RQM Micro Reports

20

</MP>

Notice the legend is placed below the graph, consistent with the report page design guide-lines. If the legend was placed to the right of the graph, in the minimized viewlet it would cause the graph to be compressed and distort its visualization.

<MP>The legend area should not exceed 25% of the total vertical report area; otherwise, the chart area will have insufficient space and be constrained / disproportional.

Long legend entry labels should utilize ellipses to truncate their length and allow more legend en-tries to be rendered in the available space (As you can see in the above charts, BIRT's ellipses support in legends is broken and it elects to just omit additional legend entries that can't fit in the available space).</MP>

21

Maximized state

Examples

22

Guidelines

In the maximized state, add back all the x and y axis label data. Add back tick marks to the quantitative axis. (In general, x axis category labels do not require tick marks; use tick marks only when the relationship between the category label and the data objects in the graph is un-clear.)

23

5. Table guidelines

Minimized state

Guidelines

Condense the information to display only the most important data; eliminate extraneous col-umns and rows

Keep the condensed information in the same order as it appears in the original table Eliminate column headings and separator lines

Maximized state

24

Guidelines

The maximized state displays all the data within the table add back all the columns and rows, column headings, separator lines.

25

6. Summary of development tasks

Done (All) RRDG – In next meeting, confirm future direction re Edgar’s comment that RRDG content is not suitable for dashboard viewlets (page 1)

(Linda) UXD - check with Jen re viewlet state terminology re Peter’s question that “minimized” is not really minimized (page 2) - Jen will investigate

(James) BIRT BIRT only: Investigate technical issues re display of report title and/or chart title in the viewlet title, so that the user has a consistent experience when linking from the dashboard views to the report (page 6)

Parameters collapsible show/hide interaction (page 6)(Ravi) RRDI

Provide example to Linda re: RRDI can add the RRDI collapsible parameters to the re-port in a fashion modified for best presentation in the viewlet.

(Peter) RRDI Confirm status for maximized view re: The minimized viewlet state is in is in scope for CLM 2012; the maximized is uncertain.

(All) Requires further investigation wrt consistency of presentation

(Peter) RRDI – decide whether the maximized state will be supported for CLM 2012 (page 7)

Pagination (page 8)(Ravi) RRDI

To investigate viewlet pagination(Linda) RRDI

Done Provide mockup of pagination for full report and viewlet states(All) Need to establish usage guidelines for pagination

Scrolling (page 8)Linda, James) BIRT

Done Linda check with Jen, how is scrolling available (it was not available in the past). (Linda) Follow up with James, requires further investigation

(Ravi) RRDI Why are there redundant scrollbars – viewlet scrollbars + report scrollbars

Determine what practices apply for condensing the parameters information so it is readable and provides the minimum amount of data required to support the chart (page 9)(Linda, James) BIRT

Done Linda get input on current BIRT practices from James (Peter) RRDI

won’t be addressed in this release; continue to discuss as a guideline item for future di-rection. Should work in the same way whether custom, BIRT or RRDI. Requires more de-velopment work on the RRDI side

from Oct.5 workgroup meeting:

RQM 54983 - Ravi investigate Mike’s process for converting BIRT reports to micro: https://jazz.net/wiki/bin/view/Main/RQMMicroBIRTReportTemplates

Investigate terminology for how the viewlet widget in the gallery is named. Current termi-nology is “Cognos report” for RRDI vs. “Custom report” in BIRT.

26

RRDI / Peter – action for RQM team – remove the hack that suppresses display of paramters in viewlet? Requires tech investigation, and report by report analysis re con-densing parameters. Work item 57235

(Linda’s question) RRDI - Will the styling for Show-Hide parameters be automatically in-herited in the Cognos Viewlet?; if not, needs to be included in styles work. Also note I am checking font size for the Show-Hide text with Jen Hayes.

(Linda) for pagination guidelines, refer to Jazz UXD pagination guidelines and note ex-ceptions). Add to separate pagination task.