Merge pull request #17 from PagerDuty/feat/DEVECO-328-update-docs-after-service-mappings-release

feat: [DEVECO-328] Update docs after the release of service mappings

Author: sandornagy517

docs/advanced/service-entity-mapping.md

@@ -6,8 +6,6 @@ This can of course be automated through the use of PagerDuty's APIs but it's sti
 
 For that reason, we created a `PagerDutyPage` component that is intended to be the single place for advanced configurations related to this plugin.
 
-> At this point in time the `PagerDutyPage` only allows Admins to map existing PagerDuty services to Backstage entities. Other features will be released in the future.
-
 ## Installing dependencies
 
 In order to set this up in your Backstage instance you should install the necessary packages first by running the following command. This command will install the entity processor module that we will configure later on.
@@ -92,16 +90,23 @@ Now, Backstage Admins will have the option to configure the mapping between Page
 
 ## Mapping services to entities
 
-Once you navigate to the new `/pagerduty` route will see a page similar to the one below. On the table you will see a list of all your PagerDuty services, their current mapping, and the mapping status.
+Once you navigate to the new `/pagerduty` route you will see a page similar to the one below. On the table you will see a list of all your Backstage entities, their current mapping, and the mapping status.
 
 ![service-entity-mapping](../images/service-entity-mapping.png)
 
-To define the mapping between existing PagerDuty services and Backstage entities you need to select the edit option on the right. Once you do so, a new modal screen will pop up. Here, you can choose from a list of available Backstage entities that you want to map to the PagerDuty service.
+To define the mapping between existing PagerDuty services and Backstage entities you need to select the edit option on the right. Once you do so, a new modal screen will pop up. Here, you can choose from a list of suggested PagerDuty services that you want to map to the Backstage entity. Use Auto-Mapping to receive intelligent suggestions that will help you quickly find and map services.
+
+![service-auto-mapping-modal](../images/service-entity-auto-mapping-modal.png)
+
+### Editing a mapping
+
+Click the pencil icon to open the mapping editor with enhanced search and filtering. Quickly locate the right entity by searching for service names or IDs, or filter by team to see contextually relevant suggestions.
+
+![service-mapping-edit](../images/service-entity-mapping-modal.png)
 
-!!! warning
-    Currently we only support 1:1 mapping between PagerDuty services and Backstage entities due to a limitation on the `PagerDutyCard` that only supports one service at a time. There is work in progress to overcome this limitation.
+### Removing a mapping
 
-![service-mapping-modal](../images/service-entity-mapping-modal.png)
+To unmap a service, click the pencil icon and select "None" from the dropdown.
 
 Once you select a new mapping, Backstage Entity Processor will be instructed to run and update the Backstage entity configuration. This is a best-effort action and the configuration update might not be immediate.
 

docs/capabilities.md

@@ -53,14 +53,13 @@ The PagerDuty plugin allows users to create incidents directly from Backstage. Y
 
 ### Map existing PagerDuty services to Backstage entities
 
-The PagerDuty plugin for Backstage allows Admins to add a `PagerDutyPage` component to their Backstage installation in order to easily map their existing PagerDuty services to Backstage entities without the need to make code changes to the service configuration.
+The PagerDuty plugin for Backstage allows Admins to add a `PagerDutyPage` component to their Backstage installation to easily map their PagerDuty services to Backstage entities without needing code changes to the service configuration.
 
-!!! warning
-    This feature currently supports 1:1 mapping between services and entities due to a limitation on the `PagerDutyCard` that only allows one service to be configured at a time.
+The mapping interface includes intelligent service suggestions, searchable drop-downs, and team-based recommendations to streamline the setup process, especially for organizations with large service catalogs.
 
 ![service-entity-mapping](images/service-entity-mapping.png)
 
-This feature leverages the entity processor module to make the necessary updates to each Backstage entity configuration. The `PagerDutyPage` allows admins to see the status of each entity and decide whether to make the necessary change in source code to ensure the configuration is in sync.
+This feature leverages the entity processor module to make the necessary updates to each Backstage entity automatically. The searchable interface and intelligent suggestions help you quickly find and map services, especially useful for large service catalogs with hundreds or thousands of services. Admins can decide whether to make the necessary changes in source code to ensure the mapping stays in sync.
 
 ### Sync service dependencies between Backstage and PagerDuty
 

docs/images/service-entity-auto-mapping-modal.png

@@ -62,8 +62,8 @@ We are working on some cool new features and capabilities. Here are some of them
 - [x] Improving UI for the existing PagerDuty Card
 - [x] Adding support for multiple PagerDuty accounts in the same Backstage instance
 - [x] Enabling service dependency sync between Backstage and PagerDuty
-- [ ] Adding support for multiple services on the same card
-- [ ] Adding support for a Team PagerDuty card
-- [ ] And many more ...
+- [x] Service Mapping
+- [ ] Service Custom Field Mapping
+- [ ] Runbook Automation integration
 
 For more details on what is in progress and what we are considering refer to the [project page](https://github.com/orgs/PagerDuty/projects/22) on GitHub.