Step 2. Contextualise your Technical Catalogs

The initially established technical catalogs have value as a central source for key information already, however they establish their full potential only in context. VSM considers a few areas of data key for this:

• Team ownership
• Business product mapping
• Industry & company specific context

Add Team Ownership

Team ownership to turn the technical catalogs actionable by allowing easy tracking of responsibility. As previously recommended you ideally make this part of the initial setup - have the teams claim their services directly out of the inbox. Alternatively you can of course put together a central catalog and have the teams claim their services from their team pages by clicking the "Add Service" button.

Note that an n:n mapping of teams is possible but we recommend keeping this as focused as possible.

Each team page should include also a brief self-description of the team as well as their members connected via email.

Once teams are present, connected to services and detailed with member information VSM can calculate team specific Dora metrics.

📘

Background

The book Accelerate by Nicole Forsgren, Jez Humble & Gene Kim provides a de-facto standard on how to measure development efficiency, supported by clear scientific findings. It identifies four key metrics that are collectively known as DORA metrics and support software delivery performance, namely:

• Lead Time - how long does it take to go from code committed to code successfully running in production
• Deployment Frequency - how often your software team deploy changes to production
• Change Fail Percentage - what percentage of changes to production (software releases and configuration changes) fail
• Mean Time to Recovery (MTTR) - how long it takes to resolve an error or rollback a faulty change in production

By balancing tempo (Lead Time, Deployment Frequency) with stability metrics, it is ensured that increased speed does not result in suffering quality.

The metrics are calculated on the fly each time new change, release and incident events are received and the requirements mentioned above are met. In case the events for services/members that do not exist in VSM are received, no metric can be calculated. In this case, the events are still stored and the metrics will be calculated, when the matching services, teams and members are added. Events can be brought in either via the Github integration or directly through the events API.

Add Business Product Mapping

The product catalog in VSM captures the business view onto your companies' development work. We recommend taking an end-users view for this: what do they consider a specific product, for example because they pay for them specifically.

Mapping your service catalog to your business products allows improved insights into your landscape by tracking which of your services, APIs and libraries have which impact on your landscape.

📘

Integrating Enterprise Architecture

If you are a LeanIX EAM user you likely already have already many of your Products maintained as EAM Applications in the EAM workspace. Through the EAM Integration you can directly pull them into VSM as the baseline for your product catalog.

Add Industry & Company specific context

Now that the core data for the VSM catalogs has been established we look to some of the most important information that we can be layered on top to detail the different catalogs to enable filtering and different views.

Core feature behind this are tags, which can be defined in the Settings:

The below are some of our best practice examples, but note that you own the setup in your workspace and of course free to customise it to the specific needs of your organisation or industry.

Set up API Rating tags

The previous chapter introduced the baseline for the API catalog with relations to services and from their an inherent mapping to products and teams. With tags we focus more on the standalone API catalog, providing better filtering and accessibility for engineers that use it as a shared knowledge base. To this end we recommend the following tag groups:

• Visibility - a basic single select tag for separating the APIs into those that are External and those that are Internal
• Authorization - all tags related to authentication or authorization models used by the API in question. Typical examples are:
  • API Keys - A unique identifier used to authenticate and track API requests, typically passed as a header or parameter in the request.
  • JWT (JSON Web Tokens) - A compact, URL-safe token format that securely represents claims between two parties, often used for authentication and authorization in web applications and APIs.
  • OAuth (Open Authorization) - An authorization framework that allows a user to grant a third-party application access to their resources (e.g., data, profile) without sharing their login credentials, often used by social media and other web platforms.
• Data Format - a multi-select tag that denotes the data formats used by the API, for example CSV, JSON or XML.
• Type - a single select tag to track the protocol of the API, such as GraphQL, REST, SOAP or others.

Set up current lifecycle tags for services

When working with the service catalog, having transparency about the current lifecycle of a service is key. It prevents confusion between the owning team and others using the service. We recommend to use the same five lifecycle stages used in our LeanIX EAM solution:

1. Plan
2. Phase in
3. Active
4. Phase out
5. End of life

Set up Team Grouping tags

The team catalog already provides an overview across all the teams in an organisation, with this type of tagging we want to systematically group for easier access. Typical groupings we have found valuable are by physical location and by tribe/chapter/guild - these easily answer questions such as "Does the team I need to speak to sit in the same location" and can be helpful should you need to reorganise your team structure.