Managing Reports and QA Checks

Overview

Documents process for creating, editing, and deleting Reports and QA Checks and attaching them to map projects.

Creating Report and QA Check Definitions

Reports and QA Checks share the same basic structure, but behave differently in the application.  There are three types of report:

• Basic reports
  • Calculates the cumulative count of items returned by some defined query criteria.
  • These reports are saved and can be viewed from the Reports widget.
  • Examples:  Specialist Productivity, Concepts Mapped
• Difference Report
  • Calculates the change in cumulative count from two basic reports (of the same type) over some specified time period.
  • These reports are saved and can be viewed from the Reports widget.
  • Examples:  Weekly Specialist Productivity, Monthly Concepts Mapped
• QA Check
  • An on-demand query which returns an item list for some defined query criteria.
  • These reports are only used at the time of creation, and cannot be retrieved through the Tool.
  • Results from these queries can be inserted into the workflow for QA Review (see QA Workflow Path).
  • Examples:  Target codes in error, Change in default preferred name

Reports, Difference Reports, and QA Checks can be defined via the Application Administration widget.  To create definitions:

• Log in as a map administrator user
• Go to the Application Administration tab
• Basic Reports and Difference Reports are managed through the tab labeled Report Definitions
• QA Checks are managed through the tab labeled QA Check Definitions
  
  

Creating Report and Difference Report Definitions

Open the tab labeled Report Definitions and scroll down below the paged list of existing definitions until you see this blank form:

Basic Report Parameters

For both basic Reports and Difference Reports, the following parameters must be specified:

• Name –  This is the name of the report, also referred to as the Report Type, e.g. "Specialist Productivity"
• Frequency –  How often the report is run.  The available values are:
  • DAILY – runs every day
  • Day of week:  MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY – runs weekly on the specified day
  • Day of month:  FIRST_OF_MONTH, MID_MONTH (defined as the 15th), LAST_OF_MONTH – runs monthly on the specified day
  • ON_DEMAND – only run when a user requests report data
• Role Required – The role a user must have in order to view report results
• Result Type – The type of object this report is counting.  The available options are:
  • CONCEPT – This report counts based on terminology ids
  • MAP_RECORD – This report counts based on individual map records, where multiple records may exist/have existed for a particular concept.
• Is Diff Report? – If true, this is a difference Report Definition;  if false, this is a basic Report.
• Description – Optional.  A brief description of what this report returns.

Note that the Query parameter has no input box;  this only appears once a non-difference/basic Report is specified.

Non-Difference Report Parameters

If a non-difference (basic) report (i.e., "Is Diff Report?" is set to "false"), an additional parameter appears:

where Query Type can be set to the following values:

• SQL – Server Query Language
• HQL – Hibernate Query Language
• Lucene – Indexed-text search through Lucene Engine.  Note:  This is not currently supported.

Constructing Queries

When a non-difference report is specified, the Query input area becomes available.  Queries are required to return a list of three items:

• value – the text value by which all results will be grouped, e.g. user name, date, type of concept, etc.
• itemId – the Hibernate-managed id of the concept or map record returned by the query
• itemName – the name of the concept or map record returned by the query

For SQL, the query format must follow the following pattern:

select [RESULT] value, [RESULT] itemId, [RESULT] itemName
from table1 table_abbr1, table2 table_abbr2, ...
where [CRITERIA] 

For HQL, the query format must follow the following pattern:

select [RESULT] as value, [RESULT] as itemId, [RESULT] as itemName
from object1 object_abbr1, object2 object_abbr2, ...
where [CRITERIA]

Dynamic parameters are available for query criteria.  All are of the format :NAME:.  The available dynamic parameters are:

An example is shown below, for the "Specialist Productivity" report.  This report returns, by user name, the list of concepts for which editing is complete and that user participated in the editing process

select mu.userName value, mr.conceptId itemId, mr.conceptName itemName 
from map_records mr, map_projects mp, map_records_origin_ids mroi, map_records_AUD mra, map_users mu 
where mp.id = :MAP_PROJECT_ID: 							
  and mra.mapProjectId = mp.id 								
  and mr.id = mroi.id and 								
  mroi.originIds = mra.id 							
  and mra.owner_id = mu.id 
  and mr.workflowStatus IN ('READY_FOR_PUBLICATION') 
  and mu.userName != 'loader' 				
  and mr.lastModified <= :TIMESTAMP: 					
  and mr.lastModified >= :EDITING_CYCLE_BEGIN_DATE:    
  group by mu.userName, mr.lastModified 				
  order by 1,2;											

Note that the "group" and "order" commands are included only for visual inspection of query output, and are not necessary for constructing reports.

Adding the Report Definition

For Difference Report Definitions, simply click "Submit" to add the definition.  For basic Report Definitions, the query must be tested for successful result retrieval before the Report Definition can be added.

 Until the query successfully completes, the "Submit" button is disabled and the "Test" button is enabled, as shown:

If a query fails to complete, a red alert box containing the reason for failure will be displayed.  For example:

Once the query successfully passes testing, a green alert box will appear prompting you to save the Report Definition, and the "Submit" button will be enabled:

Click "Submit" to add the Report Definition.  Note that altering either "Query Type" or "Query" after testing will require re-testing the modified query.

Difference Report Parameters

If a difference report is specified (i.e. "Is Diff Report?" is set to "true"), two additional parameters become available:

where Diff Report Time Period specifies the time period over which differences are calculated, and can be set to:

• DAILY
• WEEKLY
• MONTHLY
• ANNUALLY

and Diff Report Base Definition specifies the basic report from which differences will be calculated, e.g. "Specialist Productivity").  All non-difference/non-QA Check report definitions appear in a picklist for selection.

Queries are automatically constructed for difference reports, and do not require user entry.

Editing a report definition

To edit a previously created report definition, open the Reports tab and search/scroll to the desired definition.  

Editing any parameter other than "Query Type" or "Query" will cause a "Save" and "Cancel" button to appear on the right.  Click "Save" to update the definition, or "Cancel" to revert any changes.

When "Query Type" or "Query" are changed, a "Test" button appear in the same fashion as described for creating a Report Definition.  Once the query returns successfully, click "Save" to update the report definition, or "Cancel" to revert your changes.

Deleting a report definition

WARNING:  Deleting a report definition will also delete any reports created from this definition, and remove the definition from any projects it is currently attached to.

To delete a report definition, search/scroll to its entry on the paged list of report definitions and click the "X" at the top right of the entry.  A prompt will appear requesting confirmation. If a report definition is currently attached to existing projects, a second prompt will require additional confirmation.

QA Checks

Creating QA Checks is similar to the process for creating Report Definitions, except that:

• Queries are required
• Only Name, Role Required, Result Type, and Query Type parameters need to be set.

Queries for QA Checks must also be tested before submitting the definition;  see Adding a Report Definition for details.

Editing and deleting QA Checks is performed in the same way as editing or deleting Report Definitions.

Attaching Report and QA Check Definitions to Projects

Reports and QA Checks are considered project metadata.  Once created, they can be added to the project from the Project Details widget (see Adding Metadata to a New Project).

References/Links

• n/a