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.
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:
For HQL, the query format must follow the following pattern:
Dynamic parameters are available for query criteria. All are of the format :NAME:. The available dynamic parameters are:
|:MAP_PROJECT_ID:||Restricts results to the project this definition is attached to. WARNING: If not specified, results may include erroneous results from other projects.|
|:SOURCE_TERMINOLOGY:||The source terminology of the map project|
|:SOURCE_TERMINOLOGY_VERSION:||The source terminology version of the map project|
|:DESTINATION_TERMINOLOGY:||The destination terminology of the map project|
|:DESTINATION_TERMINOLOGY_VERSION:||The destination terminology version of the map project|
|:EDITING_CYCLE_BEGIN_DATE:||The date when this particular editing cycle began|
|:LATEST_PUBLICATION_DATE:||The date at which all previous editing cycle work was completed and released|
Adds a timestamp restriction to the query. This is only meaningful when constructing historical data, i.e. running reports for dates other than today.
|:PREVIOUS_SOURCE_TERMINOLOGY_VERSION:||The last version of the source terminology before the latest version currently in use for the map project|
|:PREVIOUS_DESTINATION_TERMINOLOGY_VERSION:||The last version of the destination terminology before the latest version currently in use for the map project.|
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
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:
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.
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).