Naming Conventions for Reports and Queries

Purpose of establishing naming conventions:

  • organization should be simple, clear, and logical
  • need to be useful for end users
  • organization of reports, queries should be logical and simple as possible; library technology right now has incredible complexity, explodes in every corner; would like to organize things so it's clear and simple for people coming in
  • what we're really doing is taxonomy, which is both organization and naming

Elements relevant to naming:


Value for Example Report


Requirements IDID401
JIRA TicketREP-103
Name of Report
  • Circulation Transaction Detail
  • Circulation Transactions
  • Loans with Material Type
  • Circulation Transactions with Bibliographic Detail
  • Loans with Material Type and Bibliographic Detail
  • Loans with Item Detail

The report itself is focused on how the report is going to be used, not about how to get the data.

This will also be the name of the JIRA issue.

Report Naming Construct

  • by = filter or focus; appropriate for reports that aggregate transactions, not for transaction-level reports
  • with = what the report includes, details
  • only include as many extra clauses as is necessary to distinguish this report; if "bibliographic detail" is expected, don't need to list it

Note: we should create a markdown file for each report that would live in a reports folder on GitHub; it should include original purpose of the report, description of the different queries, links to queries

Can also link to report markdown files from the main ldp-analytics markdown file

Question: how to keep track of work on things like this in JIRA

Name(s) of query(ies)ex.: Count Loans for Locations

The query is how to get the data. Possible naming convention for short names:

verb, source data, function
example: count loans for locations

or maybe noun, verb, function

example: Loans - Count by Location with Material Type

Will likely create JIRA issues for all queries, maybe in LDP project; then can link from LDP query issue to report(s) that contain(?) that query

Idea from Angela:

  • for noun, what is each row in the resulting table? is it a loan? a general circ transaction? a patron?
  • for verb, either count or list?
  • for modifiers, focus on with and by? only add ones that change between versions of queries?
Short name(s) of query(ies)ex.: count_loans_locations
  • needs to be machine-readable, usable as a variable
    • underscores are better than dashes because some programs don't like dashes in variable names
  • may or may not need to look like the regular name; might need to be shorter
  • use as GitHub folder name
  • if adding something to indicate aggregation (_counts, _detail), add to end so you can sort
  • like with short name, maybe use verb after nouns so things can be sorted by main topic of interest
Umbrella category for reportCirculation

Group reports by the 5 most used apps of FOLIO that reports will be generated for:

  • users
  • circulation (check out, check in, requests)
  • inventory
  • finance and orders
  • resource management

just use umbrella category to organize reports, not to name them (could be the directory structure in LDP GitHub)

use tagging (e.g., in GitHub?) to help organize reports, maybe to add original functional area to query

Additional information that would be useful when browsing reports in, e.g., GitHub:

  • date of query
  • tag indicating original functional area

Clustering Reports

The report generation process has resulted in reports with a great deal of overlap. As part of the naming/prototyping process, the Reporting SIG and Report Prototype Working Group will be reviewing reports to identify reports that are exact duplicates or that have a similar purpose and many data elements in common. This process is called "clustering."

Clustering reports involves conversations with stakeholders and review by RPWG members. The basic steps are:

  1. Identify a member of the Reporting SIG to take a leadership role on the clustering project
  2. Clustering leader should identify one or more members of the relevant SIG (e.g., RA) to review the current reports
  3. Meet with SIG members (SMEs) to go through the reports one by one and brainstorm a "cluster name" - something that is short and summarizes the primary purpose of the report. Eventually, this name might need to conform to the naming conventions for "Report" listed above
  4. If reports are identified with similar properties, use the same cluster name for all of them. If the report is distinct, generate a new name.
  5. Also note any reports that may no longer meet the expectations for LDP reports, as well as any reports that may be more appropriate for a different functional area. Those reports should be removed or moved so they can be clustered with the correct functional area reports.
  6. A second pass through the clusters by another SME might be useful, especially if there were any questions about report purpose.
  7. Send final clusters back to functional area SIG for prioritization.
  8. Once all reports have a cluster assignment, the clustering leader should review each cluster individually, with help from another RPWG member as needed.
    1. Take a look all of the reports in a single cluster.
    2. Verify that reports all have similar enough purpose to be called a cluster.
    3. Compile a full list of the data elements required by the clusters.
    4. Specify any major differences between the reports requested that might require slightly different queries. For example, if one report requests individual transactions and another requests aggregate counts, it might be worth specifying two separate queries for that cluster.
  9. Each cluster will need a UXPROD issue to organize work on the required query or queries. Only a PO or a designated Reporting SIG member can create issues in the UXPROD project, so you will need to send the following information for each cluster:
    1. Name of cluster
    2. Full list of elements required for a comprehensive query that covers all cluster reports
    3. Subqueries that might be useful, in addition to the comprehensive query
    4. Final list of the REP issues that should be associated with this cluster
  10. After the clusters are finalized, the clusters can be treated like individual reports - they can be prioritized by the Reporting SIG and then assigned to members of RPWG for prototyping and query development.