Table of Contents
The Platform Console’s Catalog is similar to a library catalog, in that it provides a list of people, teams, apps, services, APIs, forms, and infrastructure resources. These resources are known as “entities” in Backstage (the platform the Console is built on).
Through the Catalog, users can conceptualize and navigate the VA.gov ecosystem. The Catalog can connect to GitHub (and other code hosts) to display a page for every user, team, system, API, microservice, web app, form, or infrastructure resource.
The teams responsible for these entities can customize the pages with dependencies, links, monitoring tools, documentation, and more.
See example Catalog pages below (click an image to enlarge it):
*See Entity Types in the Catalog (below) for a definition of Components.
Entity Types in the Catalog
The Catalog has eight (8) entity types, which can be navigated to via a submenu:
A collection of systems with a common purpose or context
A collection of components or APIs with common purpose or context
A software component or “unit of software”, typically linked to the source code that constitutes the component
Not to be confused with Design System components.
Typically a functional portion of vets-api, but also includes external services
A piece of infrastructure a system needs to operate
A Catalog entry that defines (1) the parameters that are rendered in the front end part of the scaffolding wizard, and (2) the steps that are executed when scaffolding a component. Used with the “Software Template” system
A GitHub team made up of GitHub users
A GitHub user in the VA org
Information Displayed on Entity Pages
Each entity page (except Group and User pages) has multiple tabs along the top. Here is what you can find under each tab:
The overview tab has overall information about the entity, such as a description, relationships to other entities, and links related to the entity.
The overview tab has an About card that includes the following:
A link to the entity’s source code repo (“VIEW SOURCE”)
A link to the entity’s technical documentation (“VIEW TECHDOCS”)
A description of the entity
The entity’s owner, system, type, lifecycle, and tags (such as programming language)
The overview tab has a Relations graph that can show relationships to other entities, such as
Owned by / Owner of
Has part / Part of
Depends on / Dependency of
Has member / Member of
Consumes API / API Consumed By
It also links to a graph of the entire Catalog where a user can navigate the parts and relationships of the VA ecosystem and Shift+Click to see the Catalog page for any entity. The graph can also be filtered to show only certain types of relationships or entities.
The overview tab has a Links card that can be customized to include links to anything related to the entity, such as analytics reports, monitoring tools, or anything else with a URL.
If a component has multiple subparts, they will be listed in the Subcomponents card on the overview tab.
This tab has a list of recent CI/CD jobs in GitHub actions.
This tab shows feature toggles for the entity. Users can see the status and go to Flipper to make changes.
This tab shows how complete a Catalog entry is. It checks to see if the entity’s page has a title, an owner, a link to technical documentation, and a GitHub annotation.
Creating and Updating Catalog Entity Pages
Entity pages are created via
catalog-info.yaml and other metadata files that tell the Console what information to display for a given entity, including:
Its source code repository
Its relationships to other entities (e.g., dependencies)
Links related to the entity
Configuration for tools found in the entity page tabs
catalog-info.yaml files are usually stored in an entity’s GitHub repo.
For most APIs and components (parts of vets-api and vets-website),
catalog-info.yaml files have already been generated in GitHub repos to create basic pages in the Catalog. It is the responsibility of individual teams make sure their entities'
catalog-info.yaml files are correct, complete, and up to date.
Instructions for creating and updating Catalog entity pages can be viewed in the Console’s documentation viewer (Docs > Tech Docs > Platform Console UI > Users > Building a Catalog Entry) or in GitHub.
Connecting Technical Documentation to Entity Pages
Once an entity’s
catalog-info.yaml file is complete, a user can click View Tech Docs (or open the DOCS tab) to read documentation from the entity’s repository. Users may use the Tech Docs plugin to configure their documentation.
Instructions for setting up Tech Docs for an entity can be found in the Console (Docs > Tech Docs > Platform Console UI > Users > Setting up Technical Documentation) or in GitHub.
Customizing Team Pages
Entity pages for teams (“Groups” in the Catalog) can also be customized with links that are relevant to the team. Instructions for updating team pages can be found in the Console (Docs > Tech Docs > Platform Console UI > Users > Customizing your team's catalog page) or in GitHub.
Help and feedback
Create an issue ticket to suggest changes to this page