The Console Catalog

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:

		Definition	Examples
	Domain	A collection of systems with a common purpose or context	Platform VFS
	System	A collection of components or APIs with common purpose or context	Vets API VA.gov
	Component	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.	10-10CG application VA Profile Facility Locator
	API	Typically a functional portion of vets-api, but also includes external services	VA Notify API Appeals API
	Resource	A piece of infrastructure a system needs to operate	Amazon EKS Amazon S3
	Template	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	Create VFS App in vets-website repo
	Group	A GitHub team made up of GitHub users	VFS VAOS
	User	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:

Overview Tab

The overview tab has overall information about the entity, such as a description, relationships to other entities, and links related to the entity.

About Card

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)

Relations Card

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.

Links Card

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.

Subcomponents Card

If a component has multiple subparts, they will be listed in the Subcomponents card on the overview tab.

CI/CD Tab

This tab has a list of recent CI/CD jobs in GitHub actions.

Feature Toggles

This tab shows feature toggles for the entity. Users can see the status and go to Flipper to make changes.

Scorecards

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

These 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

• Suggest content changes to this page.

• Submit new Platform Website content.

• Get help from the Platform Support Team in Slack.

• Submit a feature idea to the Platform.