-
Notifications
You must be signed in to change notification settings - Fork 10
Resources linking system
For reference for the team.
We have two kinds of links in our database:
-
Federal Register documents
- Our system automatically pulls in new documents via the FederalRegister.gov API, including automatically populating the "locations" 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.)
- We also use the FR API information to automatically associate new documents with any existing "group" of related documents (such as associating a Final Rule with its NPRM).
- Our system uses each document's docket number to automatically group related items together, although the RIN could serve this function as well.
- Our admin panel allows us to customize the grouping, because sometimes the FR has clerical errors that prevent automatic grouping. Older documents are also less consistent about docket numbers - some have no docket number - so we need to manually group those documents.
- The FR API includes most CMS FR documents from present to 1994. Many of its records for items in the 1990s are incomplete, so we manually corrected them in our database, such as by adding missing locations. We also corrected a lot of the "groups" by hand.
- We manually entered all the documents in our database dated before 1994, including locations.
- Our system automatically pulls in new documents via the FederalRegister.gov API, including automatically populating the "locations" 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.
-
Supplemental content documents
- This includes all documents except FR documents: links to related statutes, subregulatory guidance, technical assistance documents, etc.
- We enter all of this information by hand. SMEs add the locations by hand, based on their professional judgment, using our criteria whitepaper as a guide (also linked on the live site for reader review).
When you view a regulation page on eRegulations, the website "caches" the supplemental content for that page - in other words, it saves a copy of the list in a tiny file on your computer (as part of a hidden browser storage folder). That tiny cache file expires (gets automatically deleted) when it's 8 hours old, so people should see fresh data at least once a day.
How to bypass the cache:
- You can open an incognito window to see new material: Ctrl-Shift-N (Windows) or Command-Shift-N (mac OS) in Chrome or Edge.
- You can go to our cache-clearing tool (add /cache/ to the end of our URL, like this:
https://example.com/cache/
), scroll to the end, and choose "delete all cache items".
Pros:
- If you view a page and then refresh it or load it again in a little while, the supplemental content loads instantly. This is intended to be a good experience for users doing research, especially anyone on a slower internet connection.
Cons:
- When a SME views a regulation page, then tags a piece of supplemental content intended to show up in the supplemental content list for that page, and then views the page again a minute later, it'll show the old version from the cache.
- A user doing research may not see brand-new links until their next work day.
It is easy for the devs to adjust the length of time for caching, for example to change it from 8 hours to 1 hour or 1 day.
You can assign an item to a category or subcategory.
On the site sidebars, categories display a list of subcategories that belong to the category, then a list of items that belong to the category. Subcategories contain items.
The top-level categories and subregulatory guidance subcategories should be arranged in order of authoritativeness.
By default, content items are sorted by most recent first for all items with dates, then items without dates in alphanumeric order. (For an example of alphanumeric order, see call numbers in a library.) Federal Register documents have a special "grouped" ordering, to help people find related rules.
We add and update categories as we work on the content; the following list is an example.
- Statutes
- Federal Register Documents (groups of documents, sorted in date order by the most-recently-published document that each group contains)
- Related Regulations
- Subregulatory Guidance
- State Medicaid Director Letter (SMDL)
- State Health Official Letter (SHO)
- CMCS Informational Bulletin (CIB)
- Frequently Asked Questions (FAQs)
- State Medicaid Manual (SMM)
- Implementation Resources
- State Plan Amendment Resources
- Technical Assistance for States
- Templates
- Toolkits
- Waiver Resources
- Other Resources
Our admin panel enables team members to:
- Create, rename, and delete categories and subcategories
- Associate a subcategory with a parent category
- Add text descriptions for categories, to be displayed under the category name (subcategories don't display descriptions)
- Determine the placement of a category or subcategory in the list, by giving it a numerical value for its order (for example, a category with a weight of "1" would show up first in the list, and a category with a weight of "1000" would show up last)
Approximately once a day, our parser fetches data from eCFR. At that time, our system reads the structure of sections and subparts from eCFR, and it makes that information available to the rest of the system in a convenient format (posts it to a supplemental content endpoint).
The system adds all of the subparts to the subpart menu of the admin panel, and it adds all of the sections to the section menu. For all sections that belong to a subpart, it updates each section to be associated with its subpart. Sections that don’t belong to a subpart (such as 42 CFR 431.1 and 42 CFR 433.1) are not tagged with a subpart. If it finds that a section or subpart already exists and is correct, it skips over it.
If there are sections or subparts in the admin panel that didn’t exist in the eCFR data, they remain in the admin panel (they are skipped, not modified). This typically happens if people had added sections with typos, or if there are old sections that aren't in the latest version of the regulations.
Under "Parser Configuration", we can add parts from any title and declare whether the parser should do one or more of these things with that part:
- Upload the regulation text (so that the part displays in our Table of Contents, people can read it within eRegulations, etc.)
- Upload "locations" (add the subpart and section info to our admin panel, allowing us to associate documents with those locations)
- Upload FR docs (fetch Federal Register rules related to that part and put them into our resources database)
Each item has an item ID and some combination of the following aspects (all are optional):
- Date [can be year, year + month, or year + month + day, such as "2021-10-18"]
- Name [identifier, such as "SHO # 21-005"]
- Description [usually a document title, such as "Re: Medicaid Eligibility for COFA Migrants"]
- Category [such as "State Health Official (SHO) Letter"]
- URL [such as "https://www.medicaid.gov/federal-policy-guidance/downloads/sho21005.pdf"]
- Locations [section or subpart info, such as "42 435.4", "42 435.907", etc.]
Please note that all pages on this GitHub wiki are draft working documents, not complete or polished.
Our software team puts non-sensitive technical documentation on this wiki to help us maintain a shared understanding of our work, including what we've done and why. As an open source project, this documentation is public in case anything in here is helpful to other teams, including anyone who may be interested in reusing our code for other projects.
For context, see the HHS Open Source Software plan (2016) and CMS Technical Reference Architecture section about Open Source Software, including Business Rule BR-OSS-13: "CMS-Released OSS Code Must Include Documentation Accessible to the Open Source Community".
For CMS staff and contractors: internal documentation on Enterprise Confluence (requires login).
- Federal policy structured data options
- Regulations
- Resources
- Statute
- Citation formats
- Export data
- 2021
- Reg content sources
- Default content view
- System last updated behavior
- Paragraph indenting
- Content authoring workflow
- Browser support
- Focus in left nav submenu
- Multiple content views
- Content review workflow
- Wayfinding while reading content
- Display of rules and NPRMs in sidebar
- Empty states for supplemental content
- 2022
- 2023
- 2024
- Medicaid and CHIP regulations user experience
- Initial pilot research outline
- Comparative analysis
- Statute research
- Usability study SOP
- 2021
- 2022
- 2023-2024: 🔒 Dovetail (requires login)
- 🔒 Overview (requires login)
- Authentication and authorization
- Frontend caching
- Validation checklist
- Search
- Security tools
- Tests and linting
- Archive