Skip to end of banner
Go to start of banner

Naming Conventions for Reports and Queries

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

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:

Element

Value for Example Report

Description

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


  • No labels