RFC: PagerDuty Service Import/Mapping capabilities

[t1agob]

🔖 Need

The PagerDuty plugin provides a software project scaffolder custom action that enables the integration between Backstage and PagerDuty for new services but it is not possible to do the same for existing services.

I would like to have an easy way where I could see a list of Backstage entities and the PagerDuty services and easily map them together. The goal would be to have an easy way to map services without requiring the integration to be setup on each individual service.

This RFC is my proposal to solve issue (#80) but looking for different perspectives from the community.

🎉 Proposal

My proposal is to have a PagerDuty page that can be used used to import all PagerDuty Services to a list inside Backstage. From there you can use the UI to map PagerDuty services to existing Backstage entities.

The mappings will be stored on a database and will be checked for updates the next time a Backstage entity is loaded or when another import operation takes place. If the data is not in sync it will show on-screen. This might happen because the entity config was updated in source code. If this happens, the user will need to use the UI to select the new mapping or the old one.

All these mappings will only be persisted when the user clicks the "Save" button on the screen.

Example UI  👇

〽️ Alternatives

We have considered two alternatives instead of the UI-based approach mentioned above. 1. Providing a CLI tool to allow a fast mapping between PagerDuty and Backstage services This would provide a similar approach to the one proposed above but instead of providing a UI-based interface to the user it would be done through CLI. For each mapping specified a PR would be created in the source code of that same service.

2. Create PRs to Backstage service code instead of storing the mapping on a database This approach is similar to the one mentioned in the proposal section but instead of storing the mappings on a database and implement conflict management capabilities we would create PRs for every single mapping update.

The downside for these two approaches is that those PRs would require permissions to GitHub/GitLab/Azure DevOps and would still need to be approved and merged in every single service.

❌ Risks

We are introducing a database dependency that we didn't have before. This means that for service mapping capabilities the pagerduty.com/service-id is no longer the only option to configure the mapping between services in PagerDuty and Backstage.

Also, potentially in future changes, the database schema might change and therefore introduce the need for database migrations which adds up to the complexity of the plugin and its dependency management and versioning.