release: 0.14.0 (#120)

### Description

**Release 0.14.0** introduces support for multi-account configuration.
With this release, admins will be able to specify multiple PagerDuty
accounts in the same Backstage instance. Support was added across all
the components of the plugin:

- **Backend:** All API routes exposed take account as an optional
parameter so you can create and query information from different
PagerDuty Accounts. If admins leverage the Entity Mapping feature, the
account is now persisted into the plugin database.
- **Scaffolder Actions:** When the scaffolder action is used on a
template it now lists Escalation Policies from all accounts configured
so the user can easily select the one they want. The Scaffolder action
also outputs the account so it can be replaced in the `app-config.yaml`
annotations.
- **Entity Processor:** If an entity mapping stored in the plugin
database contains the `account` property, the processor will add an
annotation to the entity with its information.

This release solves an existing problem for many large organizations
that have several PagerDuty accounts for segregation purposes or that
result from company acquisitions.

## Acknowledgement

By submitting this pull request, I confirm that you can use, modify,
copy, and redistribute this contribution, under the terms of your
choice.

**Disclaimer:** We value your time and bandwidth. As such, any pull
requests created on non-triaged issues might not be successful.

config.d.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { PagerDutyOAuthConfig } from "@pagerduty/backstage-plugin-common";
+import { PagerDutyAccountConfig, PagerDutyOAuthConfig } from '@pagerduty/backstage-plugin-common';
 
 export interface Config {
   /**
@@ -28,9 +28,24 @@ export interface Config {
      */
     eventsBaseUrl?: string;
     /**
-         * Optional API Base URL to override the default.
-         * @visibility frontend
-         */
+     * Optional API Base URL to override the default.
+     * @visibility frontend
+     */
     apiBaseUrl?: string;
+    /**
+     * Optional PagerDuty API Token used in API calls from the backend component.
+     * @visibility secret
+     */
+    apiToken?: string;
+    /**
+     * Optional PagerDuty Scoped OAuth Token used in API calls from the backend component.
+     * @deepVisibility secret
+     */
+    oauth?: PagerDutyOAuthConfig;
+    /**
+     * Optional PagerDuty multi-account configuration
+     * @deepVisibility secret
+     */
+    accounts?: PagerDutyAccountConfig[];
   };
 }

package.json

@@ -48,7 +48,7 @@
     "@mui/icons-material": "^5.15.19",
     "@mui/material": "^5.15.19",
     "@mui/x-date-pickers": "^7.6.1",
-    "@pagerduty/backstage-plugin-common": "0.1.5",
+    "@pagerduty/backstage-plugin-common": "0.2.0",
     "@tanstack/react-query": "^5.40.1",
     "classnames": "^2.2.6",
     "luxon": "^3.4.1",

src/api/client.ts

@@ -71,7 +71,7 @@ export class PagerDutyClient implements PagerDutyApi {
   async getServiceByPagerDutyEntity(
     pagerDutyEntity: PagerDutyEntity,
   ): Promise<PagerDutyServiceResponse> {
-    const { integrationKey, serviceId } = pagerDutyEntity;
+    const { integrationKey, serviceId, account } = pagerDutyEntity;
 
     let response: PagerDutyServiceResponse;
     let url: string;
@@ -80,6 +80,10 @@ export class PagerDutyClient implements PagerDutyApi {
       url = `${await this.config.discoveryApi.getBaseUrl(
         'pagerduty',
       )}/services?integration_key=${integrationKey}`;
+
+      if(account) {
+        url = `${url}&account=${account}`;
+      }
       const serviceResponse = await this.findByUrl<PagerDutyServiceResponse>(url);
 
       if (serviceResponse.service === undefined) throw new NotFoundError();
@@ -90,6 +94,10 @@ export class PagerDutyClient implements PagerDutyApi {
         'pagerduty',
       )}/services/${serviceId}`;
 
+      if (account) {
+        url = `${url}?account=${account}`;
+      }
+
       response = await this.findByUrl<PagerDutyServiceResponse>(url);
     } else {
       throw new NotFoundError();
@@ -106,12 +114,13 @@ export class PagerDutyClient implements PagerDutyApi {
     return await this.findByUrl<PagerDutyEntityMappingsResponse>(url);
   }
 
-  async storeServiceMapping(serviceId: string, integrationKey: string, backstageEntityRef: string): Promise<Response> {
+  async storeServiceMapping(serviceId: string, integrationKey: string, backstageEntityRef: string, account: string): Promise<Response> {
 
     const body = JSON.stringify({
       entityRef: backstageEntityRef,
       serviceId: serviceId,
       integrationKey: integrationKey,
+      account: account,
     });
 
     const options = {
@@ -134,62 +143,91 @@ export class PagerDutyClient implements PagerDutyApi {
     return await this.getServiceByPagerDutyEntity(getPagerDutyEntity(entity));
   }
 
-  async getServiceById(serviceId: string): Promise<PagerDutyServiceResponse> {
-    const url = `${await this.config.discoveryApi.getBaseUrl(
+  async getServiceById(serviceId: string, account?: string): Promise<PagerDutyServiceResponse> {
+    let url = `${await this.config.discoveryApi.getBaseUrl(
       'pagerduty',
     )}/services/${serviceId}`;
 
+    if(account) {
+      url = url.concat(`?account=${account}`);
+    }
+
     return await this.findByUrl<PagerDutyServiceResponse>(url);
   }
 
   async getIncidentsByServiceId(
     serviceId: string,
+    account?: string,
   ): Promise<PagerDutyIncidentsResponse> {
-    const url = `${await this.config.discoveryApi.getBaseUrl(
+    let url = `${await this.config.discoveryApi.getBaseUrl(
       'pagerduty',
     )}/services/${serviceId}/incidents`;
 
+    if(account) {
+      url = url.concat(`?account=${account}`);
+    }
+
     return await this.findByUrl<PagerDutyIncidentsResponse>(url);
   }
 
   async getChangeEventsByServiceId(
     serviceId: string,
+    account?: string,
   ): Promise<PagerDutyChangeEventsResponse> {
-    const url = `${await this.config.discoveryApi.getBaseUrl(
+    let url = `${await this.config.discoveryApi.getBaseUrl(
       'pagerduty',
     )}/services/${serviceId}/change-events`;
 
+    if(account) {
+      url = url.concat(`?account=${account}`);
+    }
+
     return await this.findByUrl<PagerDutyChangeEventsResponse>(url);
   }
 
   async getServiceStandardsByServiceId(
     serviceId: string,
+    account?: string
   ): Promise<PagerDutyServiceStandardsResponse> {
-    const url = `${await this.config.discoveryApi.getBaseUrl(
+    let url = `${await this.config.discoveryApi.getBaseUrl(
       'pagerduty',
     )}/services/${serviceId}/standards`;
 
+    if(account) {
+      url = url.concat(`?account=${account}`);
+    }
+
     return await this.findByUrl<PagerDutyServiceStandardsResponse>(url);
   }
 
   async getServiceMetricsByServiceId(
     serviceId: string,
+    account?: string
   ): Promise<PagerDutyServiceMetricsResponse> {
-    const url = `${await this.config.discoveryApi.getBaseUrl(
+    let url = `${await this.config.discoveryApi.getBaseUrl(
       'pagerduty',
     )}/services/${serviceId}/metrics`;
 
+    if (account){
+      url = url.concat(`?account=${account}`);
+    }
+
     return await this.findByUrl<PagerDutyServiceMetricsResponse>(url);
   }
 
   async getOnCallByPolicyId(
     policyId: string,
+    account?: string,
   ): Promise<PagerDutyUser[]> {
     const params = `escalation_policy_ids[]=${policyId}`;
-    const url = `${await this.config.discoveryApi.getBaseUrl(
+    let url = `${await this.config.discoveryApi.getBaseUrl(
       'pagerduty',
     )}/oncall-users?${params}`;
 
+    if (account) {
+      url = url.concat(`&account=${account}`);
+    }
+
     const response: PagerDutyOnCallUsersResponse = await this.findByUrl<PagerDutyOnCallUsersResponse>(url);
     return response.users;
   }

src/api/types.ts

@@ -45,6 +45,7 @@ export type PagerDutyCardServiceResponse = {
   policyLink: string;
   policyName: string;
   status?: string;
+  account?: string;
   standards?: PagerDutyServiceStandards;
   metrics?: PagerDutyServiceMetrics[];
 }
@@ -61,7 +62,7 @@ export interface PagerDutyApi {
    * Stores the service mapping in the database.
    * 
    */
-  storeServiceMapping(serviceId: string, integrationKey: string, entityRef: string): Promise<Response>;
+  storeServiceMapping(serviceId: string, integrationKey: string, entityRef: string, account: string): Promise<Response>;
 
   /**
    * Fetches the service for the provided pager duty Entity.
@@ -83,6 +84,7 @@ export interface PagerDutyApi {
    */
   getServiceById(
     serviceId: string,
+    account?: string,
   ): Promise<PagerDutyServiceResponse>;
 
   /**
@@ -91,6 +93,7 @@ export interface PagerDutyApi {
    */
   getIncidentsByServiceId(
     serviceId: string,
+    account?: string,
   ): Promise<PagerDutyIncidentsResponse>;
 
   /**
@@ -99,6 +102,7 @@ export interface PagerDutyApi {
    */
   getChangeEventsByServiceId(
     serviceId: string,
+    account?: string,
   ): Promise<PagerDutyChangeEventsResponse>;
 
   /**
@@ -107,6 +111,7 @@ export interface PagerDutyApi {
    */
   getServiceStandardsByServiceId(
     serviceId: string,
+    account?: string,
   ): Promise<PagerDutyServiceStandardsResponse>;
 
   /**
@@ -115,13 +120,14 @@ export interface PagerDutyApi {
    */
   getServiceMetricsByServiceId(
     serviceId: string,
+    account?: string,
   ): Promise<PagerDutyServiceMetricsResponse>;
 
   /**
    * Fetches the list of users in an escalation policy.
    *
    */
-  getOnCallByPolicyId(policyId: string): Promise<PagerDutyUser[]>;
+  getOnCallByPolicyId(policyId: string, account?: string): Promise<PagerDutyUser[]>;
 
   /**
    * Triggers an incident to whoever is on-call.

src/components/ChangeEvents/ChangeEvents.tsx

@@ -28,15 +28,16 @@ import { Alert } from '@material-ui/lab';
 
 type Props = {
   serviceId: string;
+  account?: string;
   refreshEvents: boolean;
 };
 
-export const ChangeEvents = ({ serviceId, refreshEvents }: Props) => {
+export const ChangeEvents = ({ serviceId, account, refreshEvents }: Props) => {
   const api = useApi(pagerDutyApiRef);
 
   const [{ value: changeEvents, loading, error }, getChangeEvents] = useAsyncFn(
     async () => {
-      const { change_events } = await api.getChangeEventsByServiceId(serviceId);
+      const { change_events } = await api.getChangeEventsByServiceId(serviceId, account);
       return change_events;
     },
   );

src/components/Escalation/Escalation.test.tsx

@@ -49,7 +49,10 @@ describe("Escalation", () => {
     expect(
       getByText("No one is on-call. Update the escalation policy.")
     ).toBeInTheDocument();
-    expect(mockPagerDutyApi.getOnCallByPolicyId).toHaveBeenCalledWith("456");
+    expect(mockPagerDutyApi.getOnCallByPolicyId).toHaveBeenCalledWith(
+      "456",
+      undefined
+    ); // undefined is the default value for the optional account parameter
   });
 
   it("Renders a forbidden state when change events is undefined", async () => {
@@ -109,7 +112,10 @@ describe("Escalation", () => {
 
     expect(getByText("person1")).toBeInTheDocument();
     expect(getByText("person1@example.com")).toBeInTheDocument();
-    expect(mockPagerDutyApi.getOnCallByPolicyId).toHaveBeenCalledWith("abc");
+    expect(mockPagerDutyApi.getOnCallByPolicyId).toHaveBeenCalledWith(
+      "abc",
+      undefined
+    ); // undefined is the default value for the optional account parameter
   });
 
   it("Renders a user with profile picture", async () => {
@@ -147,7 +153,10 @@ describe("Escalation", () => {
       "src",
       "https://gravatar.com/avatar/205e460b479e2e5b48aec07710c08d50?f=y"
     );
-    expect(mockPagerDutyApi.getOnCallByPolicyId).toHaveBeenCalledWith("abc");
+    expect(mockPagerDutyApi.getOnCallByPolicyId).toHaveBeenCalledWith(
+      "abc",
+      undefined
+    ); // undefined is the default value for the optional account parameter
   });
 
   it("Handles errors", async () => {

src/components/Escalation/EscalationPolicy.tsx

@@ -31,6 +31,7 @@ type Props = {
   policyId: string;
   policyUrl: string;
   policyName: string;
+  account?: string;
 };
 const useStyles = makeStyles<BackstageTheme>(() =>
   createStyles({
@@ -44,6 +45,7 @@ export const EscalationPolicy = ({
   policyId,
   policyUrl,
   policyName,
+  account,
 }: Props) => {
   const api = useApi(pagerDutyApiRef);
   const classes = useStyles();
@@ -53,7 +55,7 @@ export const EscalationPolicy = ({
     loading,
     error,
   } = useAsync(async () => {
-    return await api.getOnCallByPolicyId(policyId);
+    return await api.getOnCallByPolicyId(policyId, account);
   });
 
   if (error) {

src/components/Incident/Incidents.tsx

@@ -28,16 +28,18 @@ import { IncidentForbiddenState } from './IncidentForbiddenState';
 
 type Props = {
   serviceId: string;
+  account?: string;
   refreshIncidents: boolean;
 };
 
-export const Incidents = ({ serviceId, refreshIncidents }: Props) => {
+export const Incidents = ({ serviceId, account, refreshIncidents }: Props) => {
   const api = useApi(pagerDutyApiRef);
 
   const [{ value: incidents, loading, error }, getIncidents] = useAsyncFn(
     async () => {
       const { incidents: foundIncidents } = await api.getIncidentsByServiceId(
         serviceId,
+        account
       );
       return foundIncidents;
     },