Extend plugin functionality to create an integration along with service

[chauvm]

Is your feature request related to a problem? Please describe.
I want to create an integration along with the service.

Hi there! I would like to seek advice before I go down the path to create a new plugin for my current task. This question is not specific to this Pagerduty plugin, butI have posted this question in Backstage but got no response, so I post here instead.

I want to create a Template that 1) creates a PagerDuty service and, 2) adds an integration for the service such that its integration key can be used in another tool like Grafana.

I have created the PagerDuty service successfully using this guide: https://pagerduty.github.io/backstage-plugin-docs/advanced/create-service-software-template/, but the plugin doesn't support actions to create a service's integration.

I looked into the project's roadmap and it doesn't seem like adding an integration is on the list.

Describe alternatives you've considered
I wonder what's the best route to take from here:

• Approach 1: Create a local plugin in my Backstage app based on the PagerDuty plugin, then extend the ability to create an integration.
• Approach 2: Create a separate plugin with the ability to create an integration. Then create a Template to use actions from both plugins.
• Approach 3: Somehow make a curl request from the software template. I'm looking at this plugin to make HTTP request (https://github.com/RoadieHQ/roadie-backstage-plugins/blob/main/plugins/scaffolder-actions/scaffolder-backend-module-http-request/README.md), but not sure if it's meant to make any arbitrary requests or just backend's endpoints

I'm new to Backstage in general, please advise me on the most preferable approach. Thank you very much!

[t1agob]

Hello @chauvm! Thanks for raising this feature request. I believe this feature would improve user experience greatly.

We have actually a feature request open for a while that matches this request but is was created on on backend component repo (PagerDuty/backstage-plugin-backend#41) as this will most certainly not have a frontend component by itself.

It will require the necessary API endpoints to be exposed on @pagerduty/backstage-plugin-backend and new parameters to be added to @pagerduty/backstage-plugin-scaffolder-actions which, at this point in time, have their owns GitHub repos.

If I could suggest another approach... 😄

Approach 4: Fork the backend and scaffolder actions projects, add this feature and contribute back to the community. What do you say?

The project is open source so we welcome contributions from the community. If you feel comfortable doing that, we would appreciate. If not, I will add this feature to our backlog and work on it when possible because I do believe it adds a lot of value.

[chauvm]

Hi @t1agob !

Thank you very much for the new direction! I wasn't aware that there are multiple repos for the frontend, backend, and scaffolder.
I'm open to implement this feature and contribute back to the community, but would love to have more guidance as I'm new to Typescript/Javascript.

I'm reading the code in the backend and scaffolder repos. Because my objective is to be able to create a Pagerduty service along with one (or a few) integrations from a scaffolder template, I imagine I'll need to add an input field to get the integration list. Then, I can create integrations similarly to how the Backstage-Pagerduty integration is created here.

Do you think that's all I need to accomplish my objective? I guess I don't understand what I should add to the backend repo.

[t1agob]

Great! Thanks for offering your help on this one.

My high level task list on this one would be:

1. Create a backend api endpoint that queries the PagerDuty REST API for all the vendors available

2. Provide a UI component on your software template that points to the endpoint you created previously (use our documentation as a reference).

   👇 This is how we do it for the escalation policies, you should be able to replicate that easily.

   escalation_policy_id:
          title: Escalation Policy ID
          type: string
          description: The ID of the escalation policy to associate with the service
          ui:field: SelectFieldFromApi 
          ui:options: 
            title: PagerDuty Escalation Policy
            description: Select an escalation policy from PagerDuty
            path: 'pagerduty/escalation_policies' 
            labelSelector: 'label'
            valueSelector: 'value'
            placeholder: '---'

3. Add a new input parameter in your scaffolder action here.

4. Call the createServiceIntegration method for all the integrations you wish to add like you mentioned in your previous post.

5. Go back to the template and add your new input to the following section

   - id: pagerdutyService
     name: Create PagerDuty Service
     action: pagerduty:service:create
     input:
       name: ${{ parameters.service_name }}
       description: ${{ parameters.description }}
       escalationPolicyId: ${{ parameters.escalation_policy_id }}
       alertGrouping: ${{ parameters.alert_grouping }} 
       <-- ADD INTEGRATIONS LIST HERE -->

Another option that slightly changes points 3 and 4 would be to create a new separate scaffolder action inside @pagerduty/backstage-plugin-scaffolder-actions. This would be pretty useful if you want to allow users to just add integrations to existing services as part of Backstage's self-service capabilities and not create a service.

You could still use it in the main template but would be optional. If you decide to go this route (which I personally find more valuable) you would just duplicate the existing scaffolder action update it's inputs, outputs and logic to just focus on creating the integrations. The template would also need to be update because now you have two actions instead of one but, the logic in points 1 and 2 would still remain.

Let me know if this helps.

[chauvm]

Hi @t1agob !

Thanks a lot for the detailed instructions! Most of the steps make sense except for 1. getting the vendors.

The integration I'm trying to create is a Events API V2, which I believe doesn't come with a vendor ID. (for more context, I'm trying to create an integration key to work with Grafana alerts).
What can I do differently in this step to create this Grafana-Pagerduty integration?

Regarding creating a separate action, I'm new to Backstage and typescript, so I'd go with modifying the existing action first. I'll clone your plugins to my Backstage project and let you know when I have something working.

Thanks!

[t1agob]

Hey! It's a great point.

For products that PagerDuty doesn't have a built-in integration with you need to use the generic Events API V2 integration. This integration doesn't have a vendor ID. To create this integration in a service using the REST API you would need to update the createServiceIntegration method to support this. The payload would be something like this:

{
    "integration": {
        "name": "Grafana",
        "service": {
            "id": "PPCEC3U",
            "type": "service_reference"
        },
        "type": "events_api_v2_inbound_integration"
    }
}

The first step will still make sense because you need to retrieve a list of available integrations if you want to show them, but you probably need to append this one to the retrieved list.