Resources linking system
Purpose: Describe how resources work and how they are used on the website, for reference for developers and designers. This document focuses on explaining the structure of resources data and how the data gets into the system.
In eRegs, resources generally represent a document and metadata about that document.
This includes all public documents except Federal Register documents, such as links to related statutes, subregulatory guidance, technical assistance documents, etc.
SMEs enter all of this information by hand in the admin panel. For determining how to associate related regulation citations, they use our criteria whitepaper as a guide (also linked on the live site for reader review).
Our system automatically pulls in new documents via the FederalRegister.gov API, including automatically populating the regulation citations list (associated sections and subparts). New documents are automatically marked "approved", since the parser does a good job at importing accurate info for new documents.
By default, we only pull in documents that are marked in the FR doc metadata as associated with our parts in scope. So, for example, if a FR doc is only related to 42 CFR 413, we won't pull it in, since that's not a part in our scope. (See "Configuration of subpart and section info" below for more details.)
Our system groups FR documents as described in Federal Register link grouping.
The FR API includes most Medicaid-and-CHIP-related FR documents from 1994 to the present. Many of its records for items in the 1990s are incomplete, so we manually corrected them in our database, such as by adding missing citations. We also corrected a lot of the groups by hand.
We manually entered all the FR documents in our database dated before 1994, including citations. See the new regulation part checklist for details on how this data entry process works.
These documents are links to CMCS destinations like Box, SharePoint, etc. Only logged-in users with access can see them, but authenticating to see the content is managed by those systems. These are entered by hand.
These uploaded files are entered by hand in the admin panel. Only logged in users with access can see them.
Each resource item can have the following fields:
-
URL or File Upload – The answer to "how do I see the document?"
- For public items this is an external URL, such as a page on cms.gov
- For internal items this can be:
- An uploaded file
- An internal URL, such as a page on CMS Sharepoint
-
Document ID – The answer to "what’s the unique identifier for citing that document, if it has one?" Examples:
- SMDL number
- Federal Register citation number
- State Medicaid Manual section number
-
Title – The answer to "what’s this document called?"
- Typically the official title of the document
- Sometimes the official title is terse and vague, so we may add a brief summary to the description as well
- A document's official title may be extremely long and rarely used, so the description may be a common name used among CMCS staff
- Some documents don't have official titles, so the title may be written by the person adding the resource, or it may be the filename if it is an uploaded document
- We could add the “Summary” field to FR docs & public links. This would enable us to distinguish between official titles and handwritten information.
-
Document Date – The answer to "when is this document from?"
- This can be: - Year (2021) - Year + month (2021-10) - Year + month + day (2021-10-18)
- For public documents, this is typically the publication date
- We leave this blank if unknown or not applicable
- For internal documents, we expect this to be the created or published date. Examples:
- Email: date the email was sent (or the send date of the most recent email, if it’s a saved chain of emails)
- Training: date when the training was given for the first time
- SOP: date of creation or last major revision
- Internal memo: date of creation or last major revision
-
Category (and Subcategory) – The answer to "what kind of document is that?" A document category can hold public items or internal items; it cannot contain both kinds of items. An item can only have one category or subcategory. Examples:
- Public document category: Subregulatory Guidance
- Public document subcategory: State Medicaid Director Letters
- Internal document category: OGC Opinions
- Internal document subcategory: OGC Informal Guidance
- Example edge case: Some ARA Memos are public and some are not. We have a public subcategory for “Associate Regional Administrator (ARA) Memo” and an internal category for “Memos/Letters to States”.
- See our Categorizing resources for more details.
- Public document category: Subregulatory Guidance
-
Subjects – Creates the answer to "if I'm trying to look up information about a subject, what documents should I see?" Hand-curated. You can add as many as you want. Examples:
- Dentures
- COVID-19
- Sufficiency
- See our Categorizing resources for more details.
-
Regulation citations – Creates the answer to "when I’m looking at a regulation section or subpart, what documents should I see for reference?"
- For Federal Register links, this is automatically generated – it’s the list of sections that the document changed (or proposed to change)
- For other documents, this information is hand-curated
- See the Population of regulation citations page for more details
-
Statute citations – The answer to "what statute section or paragraph is closely tied to this document, if any?"
- This is most important for documents not closely tied to any regulations.
- This is hand-curated.
- Editor notes – While the contents of this field are not displayed outside the admin panel, it can be useful to provide information for other editors
- Document Status – A checkbox for whether the document is approved for display on eRegulations
We can automatically detect:
- File type – Such as web page, PDF, Word doc, Outlook message, etc.
- File size
Django defaults to logging admin panel actions. This data hasn’t been important to us, so we haven’t tried to preserve it, so it’s missing for lots of older documents due to data migrations, restores from backup, etc. We also haven’t expanded the specificity of what is logged when a document changes, but we could.
-
Actions include:
- Add (create) item
- Update item, which can be:
- Change the information in a field
- Upload a new version of a file
- Delete item
- Date and time of the action
- User who did the action
- Docket Number – This comes from the document. Automated, corrected by hand as needed. See Federal Register docket number structure for more details.
- Document Groups – We automatically generate the initial piece of information, using the docket number prefixes, to group together documents that impacted each other. We correct, and can expand, this by hand as needed. See our Federal Register link grouping for more details.
- Document Number – This comes from the document. Automated, corrected by hand as needed.
-
Action type: NPRM, Final, or RFI. Automated, corrected by hand as needed. All of these documents belong to the category “Proposed and Final Rules”, but we use this additional detail as a special kind of subcategory.
- Correction or withdrawal – Checkboxes – not automated, we edit these by hand as needed.
-
Summary, which enables providing additional context because many internal documents have titles that are vague or terse.
- We could add “Summary” to FR docs & supplemental content. This would enable us to distinguish between official titles and handwritten information.
- Document visibility, which answers what Division a user needs to be associated with to see the document. A Division belongs to a Group. [Not yet active as of August 2024.]
The eRegs homepage loads the three most recent Subregulatory Guidance and Federal Register documents and displays them in separate tabs.
Documents in the Recent Subregulatory Guidance section display with their subcategory, date and identifier if present, and title.
Recent Rules display with their Action Type, date and citation number, and title.
Regulation sidebars display each designated category, or category that contains subcategories, set to display with that citation. Usually this means the category or subcategory has a document related to that citation, unless the category is set to show even if it is empty.
Subcategories display first, followed by items that are not in a subcategory. Federal Register links are displayed in groups, as described in Federal Register link grouping. Categories and subcategories are collapsed by default, and expand when clicked to show resources in them.
Individual items display with bold dates and identifiers. This gives a bigger click target to items that don’t have, or don’t display, a title. We haven’t yet displayed file type icons for public resources, but will do that soon. Resources that link to a URL outside of eRegs have an external link icon.
If a user is signed in to eRegs, the sidebar resources are grouped by Public (resources associated with a citation that anyone on eRegs can access) and Internal (resources that the signed in user can access). Once authentication and document visibility are available to all relevant users, we will make a separate page to document those features.
Search result and subject pages display additional metadata about each resource when it is available: whether it is public or internal, a link for each subject associated with a resource, and a link for each regulation citation. Resources that have a summary (currently applies to some internal resources) display that summary on subject pages.
We haven’t yet displayed file type icons for public resources, but will do that soon. Resources that link to a URL outside of eRegs have an external link icon. We haven’t yet enabled the display of statute citations, but likely will soon.
Resources on subject pages, regulation sidebars, and homepage recent lists (with the exception of grouped FR links - see Federal Register link grouping) are sorted according to this algorithm:
- All items with dates are sorted in reverse-chronological order (most recent first) by date.
- If multiple items have the same date, use the next step to order.
- Then all items without dates but with document IDs are sorted in order by Document ID. (Alphabetical order and numeric order.)
- If multiple items have the same document ID, use the next step to order.
- Then all items without dates or document IDs are sorted in alphanumeric order by title.
- If multiple items have the same title, sort them in any order. Doesn't matter at that point.
Search result pages display resources by relevance (refer to our search documentation for details about relevance and display of search results). We hope to add the ability to sort by date to search results.