Decorators (via the UI) and Fragments (via the API) allow you to easily extend the information associated with your catalog entities by storing it within Roadie, and not written to the catalog-info.yaml file. This accelerates the catalog enrichment process by not requiring the owners of the entities to modify files in the repository in order to add the relevant information; while long term move this information into a source control solution. This can be difficult to track the information stored as a decorator or fragment which you would like to be tracked.

With Roadie’s Tech Insights feature, there’s an easy way. In this tutorial, we’re going to:

1. Automatically scan entities in the Backstage catalog and record the fragments associated with them.
2. Create a check that tells us which components have decorations we want to track and manage.

As we go through this process, you’ll learn:

1. How to create Data Sources and Checks with Tech Insights.
2. How to parse files with JSONata in Roadie and extract facts from the Roadie Fragments API.
3. How to detect which catalog entities which have an Owner defined in a decoration.

Let’s get started.

(Read our blog post “Decorators for rich Team pages” for more information on Decorators.)

Prerequisite: Fragments API Proxy

Please see our guide on How to create a Proxy to create the proxy referenced in the steps below.

Create Data Source for Entity Fragments

1. Navigate to your Roadie tenant

2. Click “Tech Insights”

3. Click “DATA”

4. Click “ADD DATA SOURCE”

5. Click the “Name” field. Type “Entity Fragments”

6. Click the “Description (Optional)” field. Type “Imports fragments data from the catalog entities which can be used to create Tech Insights checks.”

7. Click the “Proxy” field Click “/fragments” Click the “Path Extension” field Type ?entityRef={{entityRef}}

8. Click the “Select Entity to test data source against” field

9. Click the catalog entity you would like to test against

10. Click “TEST”

11. Results are displayed

12. Click the “Fact name” field Type “Fragments Count” Click the “JSONata query” field. Type $count($.items[*].fragment.*.*) Click the “Type” field Click “Number”

13. Click “ADD FACT”

14. Click the “Fact name” field Type “Fragments List” Click the “JSONata query” field Type $map($.items[*].fragment.*, $string) Click the “Type” field Click “String”

15. Click “ADD FACT”

16. Click the “Fact name” field. Type “Has Fragments” Click the “JSONata query” field Type [$count($.items[*].fragment.*.*) > 0] Click the “Type” field Click “Boolean”

17. Click “CHECK FACTS”

18. The results are displayed

19. Click the “Has Annotation” field

20. Click the “roadie.io/applied-fragments” annotation

21. Click “SAVE”

22. The Data Source Facts Visualization shows the breakdown of the fact data in graph form

23. The results of the facts are displayed on the Results table of the Data Source

Create a Check that Shows if Owner is Defined as a Decoration

1. Navigate to your Roadie tenant

2. Click “Tech Insights”

3. Click “CHECKS”

4. Click “ADD CHECK”

5. Click the “Name” field Type “Owners should not be defined in Fragment”

6. Click the “Description” field Type “Catalog entities owner should be defined in the catalog-info.yaml file.”

7. Click the “Data Source” field
Click “Entity Fragments”
Click the “Fact” field
Click “Has Fragments”
Click the “Fact operator” field
Click “Is True”

8. Click “ADD CONDITION”

9. Click the “Data Source” field Click “Entity Fragments” Click the “Fact” field Click “Fragments List” Click the “Fact operator” field Click “Does not contain” Click the “Value” field Type “owner”

10. Click “DRY RUN”

11. Click the “Select Entity to run check against” field

12. Click entity you want to test

13. Dry run results are displayed

14. Click “CLOSE”

15. Click the “Has Annotation” field Check the “roadie.io/applied-fragments” field

16. Click “SAVE”

17. The percent of entities the check are shown as a graph

18. Click “BY ENTITY”

19. Choose an entity to examine

20. The results of the checks are displayed