diff --git a/docs/getting-started/search-catalog.md b/docs/getting-started/search-catalog.md index 5c767b0164..f2514f1907 100644 --- a/docs/getting-started/search-catalog.md +++ b/docs/getting-started/search-catalog.md @@ -1,74 +1,74 @@ ---- -id: search-catalog -title: Searching the Catalog -description: Searching the Catalog. ---- - -Audience: Developers - -## Overview - -The Catalog can be searched by any combination of owner, kind, type, lifecycle, processing status, namespace, and name. [Customize Filters](../features/software-catalog/catalog-customization.md#customize-filters) provides information on how to modify the available search criteria. - -![Catalog search options](../assets/uiguide/catalog-search-options.png) - -The [Technical Overview](../overview/technical-overview.md) provides greater detail, but the catalog displays two main types of entities: - -- Core Entities - - - `Components` - Individual pieces of software that can be tracked in source control and can implement APIs for other components to consume. - - `APIs` - Implemented by components and form the boundaries between different components. The API can be either public, restricted, or private. - - `Resources` - The physical or virtual infrastructure needed to operate a component. - -- Organizational Entities - - - `User` - A person, such as an employee, contractor, or similar. - - `Group` - An organizational entity, such as a team, business unit, and so on. - -There are three additional items that can be part of the system model: - -- `Location` - A marker that references other places to look for catalog data. -- `Type` - It has no set meaning. You can assign your own types and use them as desired. -- `Template` - Describes both the parameters that are rendered in the frontend part of the scaffolding wizard, and the steps that are executed when scaffolding that component. - -## Searching for an entity - -You can search for an entity using a combination of the following: - -- **Search by name** - - Enter one or more consecutive letters into the `Filter` field. As you type the letters, the entities whose names do not contain that string will be filtered out of the displayed list. - - ![Search catalog by name](../assets/uiguide/search-by-name.png) - -- **Search by kind** - - Use the `Kind` dropdown list to select which kind of entity to show in the list: - - - API - - Component - - Group - - Location - - System - - Template - - User - -- **Search by Type** - - Use the `Type` dropdown list to select which type of entity to show in the list. The selections available in the dropdown list depend on the kind of entity selected in the `Kind` list, and the types of entity you have registered for that kind. - -- **Search by Owner** - - Use the`Owner` dropdown to filter the catalog list by who owns the entity. - -- **Search by Lifecycle** - - Use the `Lifecycle` dropdown to filter the catalog list by lifecycle. - -- **Search by Processing Status** - - Use the `Processing Status` dropdown to restrict the displayed list to only include those entities which are [orphaned](../features/software-catalog/life-of-an-entity.md#orphaning) or [in error](../features/software-catalog/life-of-an-entity.md#errors). - -- **Search by Namespace** - - Use the `Namespace` dropdown to filter the catalog list by namespace associated with the entity. +--- +id: search-catalog +title: Searching the Catalog +description: Searching the Catalog. +--- + +Audience: Developers + +## Overview + +The Catalog can be searched by any combination of owner, kind, type, lifecycle, processing status, namespace, and name. [Customize Filters](../features/software-catalog/catalog-customization.md#customize-filters) provides information on how to modify the available search criteria. + +![Catalog search options](../assets/uiguide/catalog-search-options.png) + +The [Technical Overview](../overview/technical-overview.md) provides greater detail, but the catalog displays two main types of entities: + +- Core Entities + + - `Components` - Individual pieces of software that can be tracked in source control and can implement APIs for other components to consume. + - `APIs` - Implemented by components and form the boundaries between different components. The API can be either public, restricted, or private. + - `Resources` - The physical or virtual infrastructure needed to operate a component. + +- Organizational Entities + + - `User` - A person, such as an employee, contractor, or similar. + - `Group` - An organizational entity, such as a team, business unit, and so on. + +There are three additional items that can be part of the system model: + +- `Location` - A marker that references other places to look for catalog data. +- `Type` - It has no set meaning. You can assign your own types and use them as desired. +- `Template` - Describes both the parameters that are rendered in the frontend part of the scaffolding wizard, and the steps that are executed when scaffolding that component. + +## Searching for an entity + +You can search for an entity using a combination of the following: + +- **Search by name** + + Enter one or more consecutive letters into the `Filter` field. As you type the letters, the entities whose names do not contain that string will be filtered out of the displayed list. + + ![Search catalog by name](../assets/uiguide/search-by-name.png) + +- **Search by kind** + + Use the `Kind` dropdown list to select which kind of entity to show in the list: + + - API + - Component + - Group + - Location + - System + - Template + - User + +- **Search by Type** + + Use the `Type` dropdown list to select which type of entity to show in the list. The selections available in the dropdown list depend on the kind of entity selected in the `Kind` list, and the types of entity you have registered for that kind. + +- **Search by Owner** + + Use the`Owner` dropdown to filter the catalog list by who owns the entity. + +- **Search by Lifecycle** + + Use the `Lifecycle` dropdown to filter the catalog list by lifecycle. + +- **Search by Processing Status** + + Use the `Processing Status` dropdown to restrict the displayed list to only include those entities which are [orphaned](../features/software-catalog/life-of-an-entity.md#orphaning) or [in error](../features/software-catalog/life-of-an-entity.md#errors). + +- **Search by Namespace** + + Use the `Namespace` dropdown to filter the catalog list by namespace associated with the entity. diff --git a/docs/getting-started/unregister-delete-component.md b/docs/getting-started/unregister-delete-component.md index f9de7a7096..3516daf8e0 100644 --- a/docs/getting-started/unregister-delete-component.md +++ b/docs/getting-started/unregister-delete-component.md @@ -1,67 +1,66 @@ ---- -id: unregister-delete-component -title: Unregistering and deleting a component -description: Unregistering and deleting a component from the catalog ---- - -Audience: Developers - -## Overview - -URLs to YAML files that you registered either using the `Create` button or by adding to your app-config file are both handled by entity providers. - -[Implicit deletion](../features/software-catalog/life-of-an-entity.md#implicit-deletion) occurs when an entity provider issues a deletion of an entity. That entity, as well as the entire tree of entities processed out of it are considered for immediate deletion. - -However, you are also able to manually unregister an entity from the catalog or perform a direct, [explicit deletion](../features/software-catalog/life-of-an-entity.md#explicit-deletion), of individual entities. This is especially useful for removing [orphaned entities](../features/software-catalog/life-of-an-entity.md#orphaning). - -## Unregistering an entity - -You can unregister an entity so it will not be displayed in the Catalog but still keep its `catalog-info.yaml` file in the repository. This provides the ability to register the entity with the Catalog again in the future. - -To unregister an entity: - -1. In the Catalog, select the entity you want to unregister. In this example, `mytutorial` is being unregistered. - -2. Select the three dots. - -3. Select `Unregister entity` in the dropdown menu. - - ![Screenshot of selecting unregister entity.](../assets/uiguide/select-unregister-entity-from-three-dots.png) - -4. Select `UNREGISTER LOCATION`. The entity is removed from the Catalog. - - ![Screenshot of confirming unregister entity.](../assets/uiguide/confirm-unregister-entity.png) - -## Deleting an entity - -You can also delete an entity from the catalog. However, this requires that you also delete the `catalog-info.yaml` entity definition file associated with the entity. - -To delete an entity: - -1. Delete the following entity definition files for the entity in the repository: - - - catalog-info.yaml - - index.js - - package.json - -2. In the Backstage App Catalog view, select the entity being deleted. In this example, `mytutorial` is being deleted. - - Since you have deleted the entity definition files, an error is displayed that states the `catalog-info.yaml` file cannot be found. - - ![Screenshot of error finding catalog info yaml file.](../assets/uiguide/error-message-catalog-info-file-deleted.png) - -3. Select the three dots. -4. Select `Unregister entity` in the dropdown menu. - - ![Screenshot of selecting unregister entity.](../assets/uiguide/select-unregister-entity-from-three-dots.png) - -5. Select `ADVANCED OPTIONS`. - - ![Screenshot of selecting advanced options.](../assets/uiguide/select-advanced-options.png) - -6. Select `DELETE ENTITY`. - - ![Screenshot of selecting delete entity.](../assets/uiguide/select-delete-entity.png) - -A confirmation message that the entity has been successfully deleted is briefly displayed.The entity is no longer displayed in the Catalog. - +--- +id: unregister-delete-component +title: Unregistering and deleting a component +description: Unregistering and deleting a component from the catalog +--- + +Audience: Developers + +## Overview + +URLs to YAML files that you registered either using the `Create` button or by adding to your app-config file are both handled by entity providers. + +[Implicit deletion](../features/software-catalog/life-of-an-entity.md#implicit-deletion) occurs when an entity provider issues a deletion of an entity. That entity, as well as the entire tree of entities processed out of it are considered for immediate deletion. + +However, you are also able to manually unregister an entity from the catalog or perform a direct, [explicit deletion](../features/software-catalog/life-of-an-entity.md#explicit-deletion), of individual entities. This is especially useful for removing [orphaned entities](../features/software-catalog/life-of-an-entity.md#orphaning). + +## Unregistering an entity + +You can unregister an entity so it will not be displayed in the Catalog but still keep its `catalog-info.yaml` file in the repository. This provides the ability to register the entity with the Catalog again in the future. + +To unregister an entity: + +1. In the Catalog, select the entity you want to unregister. In this example, `mytutorial` is being unregistered. + +2. Select the three dots. + +3. Select `Unregister entity` in the dropdown menu. + + ![Screenshot of selecting unregister entity.](../assets/uiguide/select-unregister-entity-from-three-dots.png) + +4. Select `UNREGISTER LOCATION`. The entity is removed from the Catalog. + + ![Screenshot of confirming unregister entity.](../assets/uiguide/confirm-unregister-entity.png) + +## Deleting an entity + +You can also delete an entity from the catalog. However, this requires that you also delete the `catalog-info.yaml` entity definition file associated with the entity. + +To delete an entity: + +1. Delete the following entity definition files for the entity in the repository: + + - catalog-info.yaml + - index.js + - package.json + +2. In the Backstage App Catalog view, select the entity being deleted. In this example, `mytutorial` is being deleted. + + Since you have deleted the entity definition files, an error is displayed that states the `catalog-info.yaml` file cannot be found. + + ![Screenshot of error finding catalog info yaml file.](../assets/uiguide/error-message-catalog-info-file-deleted.png) + +3. Select the three dots. +4. Select `Unregister entity` in the dropdown menu. + + ![Screenshot of selecting unregister entity.](../assets/uiguide/select-unregister-entity-from-three-dots.png) + +5. Select `ADVANCED OPTIONS`. + + ![Screenshot of selecting advanced options.](../assets/uiguide/select-advanced-options.png) + +6. Select `DELETE ENTITY`. + + ![Screenshot of selecting delete entity.](../assets/uiguide/select-delete-entity.png) + +A confirmation message that the entity has been successfully deleted is briefly displayed.The entity is no longer displayed in the Catalog. diff --git a/docs/getting-started/update-a-component.md b/docs/getting-started/update-a-component.md index f8768c879b..588f8d137c 100644 --- a/docs/getting-started/update-a-component.md +++ b/docs/getting-started/update-a-component.md @@ -1,33 +1,33 @@ ---- -id: update-a-component -title: Update a Component -description: Update an existing component. ---- - -Audience: Developers - -## Overview - -Components in the software catalog are created using a software template. The template generates a `catalog-info.yaml` file in either GitHub or GitLab that defines the entity. To update the component, you must edit its corresponding `catalog-info.yaml` entity definition file. - -## Updating the component - -To update a component using the Backstage UI: - -1. Select the "Edit" icon associated with the component. In this example, the `tutorial` entity is selected. - - ![select edit icon for component](../assets/uiguide/select-edit-icon-for-component.png) - - The associated `catalog-info.yaml` file is displayed. - - ![tutorial component catalog-info.yaml file](../assets/uiguide/tutorial-catalog-info-yaml-file.png) - -2. Make your changes to the YAML file. In this example, the name of the component is changed to `mytutorial`. - - ![component name updated](../assets/uiguide/component-name-updated.png) - -3. Select `Commit changes` to commit your changes to the appropriate branch and go through your normal PR review procedure. - -4. Once the updated `catalog-info.yaml` file has been merged into the branch associated with the component, then you will see the updated information in the software catalog. - - ![updated component name in ui](../assets/uiguide/updated-component-name-in-ui.png) +--- +id: update-a-component +title: Update a Component +description: Update an existing component. +--- + +Audience: Developers + +## Overview + +Components in the software catalog are created using a software template. The template generates a `catalog-info.yaml` file in either GitHub or GitLab that defines the entity. To update the component, you must edit its corresponding `catalog-info.yaml` entity definition file. + +## Updating the component + +To update a component using the Backstage UI: + +1. Select the "Edit" icon associated with the component. In this example, the `tutorial` entity is selected. + + ![select edit icon for component](../assets/uiguide/select-edit-icon-for-component.png) + + The associated `catalog-info.yaml` file is displayed. + + ![tutorial component catalog-info.yaml file](../assets/uiguide/tutorial-catalog-info-yaml-file.png) + +2. Make your changes to the YAML file. In this example, the name of the component is changed to `mytutorial`. + + ![component name updated](../assets/uiguide/component-name-updated.png) + +3. Select `Commit changes` to commit your changes to the appropriate branch and go through your normal PR review procedure. + +4. Once the updated `catalog-info.yaml` file has been merged into the branch associated with the component, then you will see the updated information in the software catalog. + + ![updated component name in ui](../assets/uiguide/updated-component-name-in-ui.png) diff --git a/docs/getting-started/view-what-you-own.md b/docs/getting-started/view-what-you-own.md index b8efbc6693..d609192658 100644 --- a/docs/getting-started/view-what-you-own.md +++ b/docs/getting-started/view-what-you-own.md @@ -1,22 +1,22 @@ ---- -id: view-what-you-own -title: Viewing what you own -description: View the entities that you own either directly or through a group ---- - -Audience: Developers - -You can own entities either directly or through a group that you're part of. - -To view the entities that you own: - -1. Select `Home` in the sidebar. -2. Select `User` in the `Kind` dropdown list. -3. Select your username in the `All Users` list. - -A page is displayed that shows the entities of which you have ownership, either directly, or through a group of which you are a member. You can toggle between showing: - -- `Direct Relations` - entities that you directly own -- `Aggregated Relations `- entities that you own through your group - -![Screenshot of the Backstage portal entities owned by guest user.](../assets/uiguide/entities-owned-by-me.png) +--- +id: view-what-you-own +title: Viewing what you own +description: View the entities that you own either directly or through a group +--- + +Audience: Developers + +You can own entities either directly or through a group that you're part of. + +To view the entities that you own: + +1. Select `Home` in the sidebar. +2. Select `User` in the `Kind` dropdown list. +3. Select your username in the `All Users` list. + +A page is displayed that shows the entities of which you have ownership, either directly, or through a group of which you are a member. You can toggle between showing: + +- `Direct Relations` - entities that you directly own +- `Aggregated Relations `- entities that you own through your group + +![Screenshot of the Backstage portal entities owned by guest user.](../assets/uiguide/entities-owned-by-me.png) diff --git a/docs/getting-started/viewing-catalog.md b/docs/getting-started/viewing-catalog.md index 8468463833..6726a35a4c 100644 --- a/docs/getting-started/viewing-catalog.md +++ b/docs/getting-started/viewing-catalog.md @@ -1,95 +1,95 @@ ---- -id: viewing-catalog -title: Viewing the Catalog -sidebar_label: Viewing the Catalog -description: Viewing the Catalog ---- - -Audience: Developers - -## Overview - -When you first log into your standalone Backstage App, `Home` is selected in the sidebar, which displays the Catalog in the main panel. - -![Portal with annotations.](../assets/uiguide/portal-with-annotations.png) - -The [Technical Overview](../overview/technical-overview.md) provides greater detail, but the catalog displays two main kinds of registered entities: - -- **Core Entities** - - - `Components` - Individual pieces of software that can be tracked in source control and can implement APIs for other components to consume. - - `APIs` - Implemented by components and form the boundaries between different components. The API can be either public, restricted, or private. - - `Resources` - The physical or virtual infrastructure needed to operate a component. - -- **Organizational Entities** - - - `User` - A person, such as an employee, contractor, or similar. - - `Group` - An organizational entity, such as a team, business unit, and so on. - -There are three additional items that can be part of the system model: - -- `Location` - A marker that references other places to look for catalog data. -- `Type` - It has no set meaning. You can assign your own types and use them as desired. -- `Template` - Describes both the parameters that are rendered in the frontend part of the scaffolding wizard, and the steps that are executed when scaffolding that component. - -It should be noted that you can also [create your own kinds of entities](../features/software-catalog/extending-the-model.md#adding-a-new-kind), if you need to model something in your organization that does not map to one of the existing entity types. - -Initially, the Catalog displays registered entities matching the following filter settings: - -- `Kind` - Component -- `Type` - all -- `Owner` - Owned -- `Lifecycle` - list of lifecycle values of entities in the Catalog -- `Processing Status` - normal -- `Namespace` - The ID of a [namespace](../features/software-catalog/descriptor-format.md#namespace-optional) to which the entity belongs - -You can change the initial setting for the [Owner](../features/software-catalog/catalog-customization.md#initially-selected-filter) and [Kind](../features/software-catalog/catalog-customization.md#initially-selected-kind) filters. - -## Informational columns for each entity - -For each kind of entity, a set of columns display information regarding the entity. For example, the default set of information for a `Component` is: - -- `Name` - the name of the component -- `System` - an optional field that references the system to which the component belongs -- `Owner` - the owner of the component -- `Type` - common types are as follows, but you can [create a new type](../features/software-catalog/extending-the-model.md#adding-a-new-kind) to meet your organization's needs - - `service` - a backend service, typically exposing an API - - `website` - a website - - `library` - a software library, such as an npm module or a Java library -- `Lifecyle` - - `experimental` - an experiment or early, non-production component, signaling - that users may not prefer to consume it over other more established - components, or that there are low or no reliability guarantees - - `production` - an established, owned, maintained component - - `deprecated` - a component that is at the end of its lifecycle, and may - disappear at a later point in time -- `Description` - an optional field that describes the component. -- `Tags` - an optional field that can be used for searching -- `Actions` - see [Catalog Actions](#catalog-actions) - -You can modify the columns associated with each kind of entity, following the instructions in [Customize Columns](../features/software-catalog/catalog-customization.md#customize-actions). - -## Catalog Actions - -For each entity, there are a set of actions that are available. - -- View - View the `catalog-info.yaml` file that defines the entity. -- Edit - Edit the `catalog-info.yaml` file that defines the entity. See [Updating a Component](../getting-started/update-a-component.md) -- Star - Designate the entity as a favorite. You can filter and [search](../getting-started/search-catalog.md) for starred entities. - -![Screenshot explaining entity actions.](../assets/uiguide/entity-actions.png) - -[Customize Actions](../features/software-catalog/catalog-customization.md#customize-actions) describes how you can modify the actions that are displayed. - -## Viewing entity details - -Selecting a entity in the main panel displays details of the entity. The type of details depends on the type of entity. For example, selecting a Component, such as `example-website`, displays the following details: - -- `About` - Metadata for the entity, such as description, owner,tags,and domain. -- `Relations` - see [Viewing entity relations](#viewing-entitiy-relationships) -- `Links` - any links associated with the entity -- `Has subcomponents` - An entity reference to another component of which the component is a part - -Selecting a System, such as `examples`, displays `About`, `Relations`, and `Links` similar to a Component, but it also includes `Has components`, `APIs` and `Has Resources`. - -![Details of system entity.](../assets/uiguide/details-system-entity.png) +--- +id: viewing-catalog +title: Viewing the Catalog +sidebar_label: Viewing the Catalog +description: Viewing the Catalog +--- + +Audience: Developers + +## Overview + +When you first log into your standalone Backstage App, `Home` is selected in the sidebar, which displays the Catalog in the main panel. + +![Portal with annotations.](../assets/uiguide/portal-with-annotations.png) + +The [Technical Overview](../overview/technical-overview.md) provides greater detail, but the catalog displays two main kinds of registered entities: + +- **Core Entities** + + - `Components` - Individual pieces of software that can be tracked in source control and can implement APIs for other components to consume. + - `APIs` - Implemented by components and form the boundaries between different components. The API can be either public, restricted, or private. + - `Resources` - The physical or virtual infrastructure needed to operate a component. + +- **Organizational Entities** + + - `User` - A person, such as an employee, contractor, or similar. + - `Group` - An organizational entity, such as a team, business unit, and so on. + +There are three additional items that can be part of the system model: + +- `Location` - A marker that references other places to look for catalog data. +- `Type` - It has no set meaning. You can assign your own types and use them as desired. +- `Template` - Describes both the parameters that are rendered in the frontend part of the scaffolding wizard, and the steps that are executed when scaffolding that component. + +It should be noted that you can also [create your own kinds of entities](../features/software-catalog/extending-the-model.md#adding-a-new-kind), if you need to model something in your organization that does not map to one of the existing entity types. + +Initially, the Catalog displays registered entities matching the following filter settings: + +- `Kind` - Component +- `Type` - all +- `Owner` - Owned +- `Lifecycle` - list of lifecycle values of entities in the Catalog +- `Processing Status` - normal +- `Namespace` - The ID of a [namespace](../features/software-catalog/descriptor-format.md#namespace-optional) to which the entity belongs + +You can change the initial setting for the [Owner](../features/software-catalog/catalog-customization.md#initially-selected-filter) and [Kind](../features/software-catalog/catalog-customization.md#initially-selected-kind) filters. + +## Informational columns for each entity + +For each kind of entity, a set of columns display information regarding the entity. For example, the default set of information for a `Component` is: + +- `Name` - the name of the component +- `System` - an optional field that references the system to which the component belongs +- `Owner` - the owner of the component +- `Type` - common types are as follows, but you can [create a new type](../features/software-catalog/extending-the-model.md#adding-a-new-kind) to meet your organization's needs + - `service` - a backend service, typically exposing an API + - `website` - a website + - `library` - a software library, such as an npm module or a Java library +- `Lifecyle` + - `experimental` - an experiment or early, non-production component, signaling + that users may not prefer to consume it over other more established + components, or that there are low or no reliability guarantees + - `production` - an established, owned, maintained component + - `deprecated` - a component that is at the end of its lifecycle, and may + disappear at a later point in time +- `Description` - an optional field that describes the component. +- `Tags` - an optional field that can be used for searching +- `Actions` - see [Catalog Actions](#catalog-actions) + +You can modify the columns associated with each kind of entity, following the instructions in [Customize Columns](../features/software-catalog/catalog-customization.md#customize-actions). + +## Catalog Actions + +For each entity, there are a set of actions that are available. + +- View - View the `catalog-info.yaml` file that defines the entity. +- Edit - Edit the `catalog-info.yaml` file that defines the entity. See [Updating a Component](../getting-started/update-a-component.md) +- Star - Designate the entity as a favorite. You can filter and [search](../getting-started/search-catalog.md) for starred entities. + +![Screenshot explaining entity actions.](../assets/uiguide/entity-actions.png) + +[Customize Actions](../features/software-catalog/catalog-customization.md#customize-actions) describes how you can modify the actions that are displayed. + +## Viewing entity details + +Selecting a entity in the main panel displays details of the entity. The type of details depends on the type of entity. For example, selecting a Component, such as `example-website`, displays the following details: + +- `About` - Metadata for the entity, such as description, owner,tags,and domain. +- `Relations` - see [Viewing entity relations](#viewing-entitiy-relationships) +- `Links` - any links associated with the entity +- `Has subcomponents` - An entity reference to another component of which the component is a part + +Selecting a System, such as `examples`, displays `About`, `Relations`, and `Links` similar to a Component, but it also includes `Has components`, `APIs` and `Has Resources`. + +![Details of system entity.](../assets/uiguide/details-system-entity.png) diff --git a/docs/getting-started/viewing-entity-relationships.md b/docs/getting-started/viewing-entity-relationships.md index f5f3f968f2..358bc4c1b2 100644 --- a/docs/getting-started/viewing-entity-relationships.md +++ b/docs/getting-started/viewing-entity-relationships.md @@ -1,71 +1,71 @@ ---- -id: viewing-entity-relationships -title: Viewing entity relationships -description: View the relationships between the entities in the Catalog ---- - -Audience: Developers - -Each of the entities in the Catalog have various relationships to each other. For example, the demo data includes an API that provides data to a website. `guests` is the owner of the API and the website, and anyone signed in as part of the `guests` group can maintain them. - -To see these relationships: - -1. Select the name of the component in the main panel, in this example, `example-website`. - - ![Screenshot of the Backstage portal with example-website selected.](../assets/uiguide/select-example-website.png) - -A page is displayed that includes a `Relations` section. This section displays the selected entity and any other types of entities to which it is related. Each relationship is also designated, such as `hasPart/partOf` and `apiProvidedBy/providesApi`. [Well-known Relations between Catalog Entities](../features/software-catalog/well-known-relations.md) describes the most common relationships but you can also [create your own relationships](../features/software-catalog/extending-the-model.md#adding-a-new-relation-type). - -Selecting any of the related entities allows you to drill down further through the system model. - -![Screenshot of the example-website Relations panel.](../assets/uiguide/example-website-relationships.png) - -## Filtering the relationships - -You can also view the relationships in the [Catalog Graph](../features/software-catalog/creating-the-catalog-graph.md). This view allows you to filter what entities and relationships to display. - -To display the Catalog Graph: - -1. Select the name of the component in the main panel, in this example, `example-website`. - - A page is displayed that includes a `Relations` section. - -2. Select `View graph` in the `Relations` section. - - ![Select View graph.](../assets/uiguide/select-view-graph.png) - -The `Catalog Graph` is displayed. - -![Screenshot of Catalog Graph.](../assets/uiguide/catalog-graph.png) - -You can set the following filters: - -- `MAX DEPTH` - 1 or infinite - - ![Max Depth at 1 and infinite.](../assets/uiguide/max-depth-1-and-infinite.png) - -- `KINDS` - select what kinds of entities you want to view, default is all kinds -- `RELATIONS` - select which relationships you want to view, default is all relationships -- `Direction`- orientation in which you want to view the entity and its associated nodes - - Top to bottom - - Bottom to top - - Left to right - - Right to left -- `Curve` - - - Monotone - - Step Before - - ![Curve at Monotone and Step Before.](../assets/uiguide/curve-monotone-step-before.png) - -You can also toggle: - -- `Simplified` -- On = simple view -- Off = detailed view -- `Merge relations` - - - On = You see the relationship from the selected entity to the nodes and from the nodes to the selected entity. - - Off = You only see relations from the selected entity to its nodes. - - ![Graphic showing results of toggling Merge relations.](../assets/uiguide/simplify-merge-relations-on-off.png) +--- +id: viewing-entity-relationships +title: Viewing entity relationships +description: View the relationships between the entities in the Catalog +--- + +Audience: Developers + +Each of the entities in the Catalog have various relationships to each other. For example, the demo data includes an API that provides data to a website. `guests` is the owner of the API and the website, and anyone signed in as part of the `guests` group can maintain them. + +To see these relationships: + +1. Select the name of the component in the main panel, in this example, `example-website`. + + ![Screenshot of the Backstage portal with example-website selected.](../assets/uiguide/select-example-website.png) + +A page is displayed that includes a `Relations` section. This section displays the selected entity and any other types of entities to which it is related. Each relationship is also designated, such as `hasPart/partOf` and `apiProvidedBy/providesApi`. [Well-known Relations between Catalog Entities](../features/software-catalog/well-known-relations.md) describes the most common relationships but you can also [create your own relationships](../features/software-catalog/extending-the-model.md#adding-a-new-relation-type). + +Selecting any of the related entities allows you to drill down further through the system model. + +![Screenshot of the example-website Relations panel.](../assets/uiguide/example-website-relationships.png) + +## Filtering the relationships + +You can also view the relationships in the [Catalog Graph](../features/software-catalog/creating-the-catalog-graph.md). This view allows you to filter what entities and relationships to display. + +To display the Catalog Graph: + +1. Select the name of the component in the main panel, in this example, `example-website`. + + A page is displayed that includes a `Relations` section. + +2. Select `View graph` in the `Relations` section. + + ![Select View graph.](../assets/uiguide/select-view-graph.png) + +The `Catalog Graph` is displayed. + +![Screenshot of Catalog Graph.](../assets/uiguide/catalog-graph.png) + +You can set the following filters: + +- `MAX DEPTH` - 1 or infinite + + ![Max Depth at 1 and infinite.](../assets/uiguide/max-depth-1-and-infinite.png) + +- `KINDS` - select what kinds of entities you want to view, default is all kinds +- `RELATIONS` - select which relationships you want to view, default is all relationships +- `Direction`- orientation in which you want to view the entity and its associated nodes + - Top to bottom + - Bottom to top + - Left to right + - Right to left +- `Curve` + + - Monotone + - Step Before + + ![Curve at Monotone and Step Before.](../assets/uiguide/curve-monotone-step-before.png) + +You can also toggle: + +- `Simplified` +- On = simple view +- Off = detailed view +- `Merge relations` + + - On = You see the relationship from the selected entity to the nodes and from the nodes to the selected entity. + - Off = You only see relations from the selected entity to its nodes. + + ![Graphic showing results of toggling Merge relations.](../assets/uiguide/simplify-merge-relations-on-off.png)