diff --git a/.changeset/new-poets-promise.md b/.changeset/new-poets-promise.md new file mode 100644 index 0000000000..206bf3e0d8 --- /dev/null +++ b/.changeset/new-poets-promise.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-scaffolder-backend-module-notifications': patch +--- + +Add a new scaffolder action to allow sending notifications from templates diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 9fc63fbd04..9cd3bc0690 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -61,6 +61,7 @@ yarn.lock @backstage/maintainers @backst /plugins/linguist-common @backstage/maintainers @backstage/reviewers @awanlin /plugins/notifications @backstage/maintainers @backstage/notifications-maintainers /plugins/notifications-* @backstage/maintainers @backstage/notifications-maintainers +/plugins/scaffolder-backend-module-notifications @backstage/maintainers @backstage/notifications-maintainers /plugins/octopus-deploy @backstage/maintainers @backstage/reviewers @jmezach /plugins/permission-* @backstage/permission-maintainers /plugins/playlist @backstage/maintainers @backstage/reviewers @kuangp diff --git a/packages/backend/package.json b/packages/backend/package.json index ea37121492..7f42df6681 100644 --- a/packages/backend/package.json +++ b/packages/backend/package.json @@ -50,6 +50,7 @@ "@backstage/plugin-scaffolder-backend": "workspace:^", "@backstage/plugin-scaffolder-backend-module-confluence-to-markdown": "workspace:^", "@backstage/plugin-scaffolder-backend-module-gitlab": "workspace:^", + "@backstage/plugin-scaffolder-backend-module-notifications": "workspace:^", "@backstage/plugin-scaffolder-backend-module-rails": "workspace:^", "@backstage/plugin-search-backend": "workspace:^", "@backstage/plugin-search-backend-module-catalog": "workspace:^", diff --git a/plugins/scaffolder-backend-module-notifications/.eslintrc.js b/plugins/scaffolder-backend-module-notifications/.eslintrc.js new file mode 100644 index 0000000000..e2a53a6ad2 --- /dev/null +++ b/plugins/scaffolder-backend-module-notifications/.eslintrc.js @@ -0,0 +1 @@ +module.exports = require('@backstage/cli/config/eslint-factory')(__dirname); diff --git a/plugins/scaffolder-backend-module-notifications/README.md b/plugins/scaffolder-backend-module-notifications/README.md new file mode 100644 index 0000000000..49a363a994 --- /dev/null +++ b/plugins/scaffolder-backend-module-notifications/README.md @@ -0,0 +1,5 @@ +# @backstage/plugin-scaffolder-backend-module-notifications + +The notifications backend module for the scaffolder plugin. + +_This plugin was created through the Backstage CLI_ diff --git a/plugins/scaffolder-backend-module-notifications/api-report.md b/plugins/scaffolder-backend-module-notifications/api-report.md new file mode 100644 index 0000000000..8b12210fe9 --- /dev/null +++ b/plugins/scaffolder-backend-module-notifications/api-report.md @@ -0,0 +1,32 @@ +## API Report File for "@backstage/plugin-scaffolder-backend-module-notifications" + +> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). + +```ts +import { BackendFeature } from '@backstage/backend-plugin-api'; +import { JsonObject } from '@backstage/types'; +import { NotificationService } from '@backstage/plugin-notifications-node'; +import { NotificationSeverity } from '@backstage/plugin-notifications-common'; +import { TemplateAction } from '@backstage/plugin-scaffolder-node'; + +// @public (undocumented) +export function createSendNotificationAction(options: { + notifications: NotificationService; +}): TemplateAction< + { + recipients: string; + entityRefs?: string[] | undefined; + title: string; + info?: string | undefined; + link?: string | undefined; + severity?: NotificationSeverity | undefined; + scope?: string | undefined; + optional?: boolean | undefined; + }, + JsonObject +>; + +// @public +const scaffolderModuleNotifications: () => BackendFeature; +export default scaffolderModuleNotifications; +``` diff --git a/plugins/scaffolder-backend-module-notifications/catalog-info.yaml b/plugins/scaffolder-backend-module-notifications/catalog-info.yaml new file mode 100644 index 0000000000..640cd1ad6f --- /dev/null +++ b/plugins/scaffolder-backend-module-notifications/catalog-info.yaml @@ -0,0 +1,10 @@ +apiVersion: backstage.io/v1alpha1 +kind: Component +metadata: + name: backstage-plugin-scaffolder-backend-module-notifications + title: '@backstage/plugin-scaffolder-backend-module-notifications' + description: The notifications module for @backstage/plugin-scaffolder-backend +spec: + lifecycle: experimental + type: backstage-backend-plugin-module + owner: maintainers diff --git a/plugins/scaffolder-backend-module-notifications/package.json b/plugins/scaffolder-backend-module-notifications/package.json new file mode 100644 index 0000000000..11974049a1 --- /dev/null +++ b/plugins/scaffolder-backend-module-notifications/package.json @@ -0,0 +1,45 @@ +{ + "name": "@backstage/plugin-scaffolder-backend-module-notifications", + "version": "0.0.0", + "description": "The notifications backend module for the scaffolder plugin.", + "backstage": { + "role": "backend-plugin-module" + }, + "publishConfig": { + "access": "public", + "main": "dist/index.cjs.js", + "types": "dist/index.d.ts" + }, + "repository": { + "type": "git", + "url": "https://github.com/backstage/backstage", + "directory": "plugins/scaffolder-backend-module-notifications" + }, + "license": "Apache-2.0", + "main": "src/index.ts", + "types": "src/index.ts", + "files": [ + "dist" + ], + "scripts": { + "build": "backstage-cli package build", + "clean": "backstage-cli package clean", + "lint": "backstage-cli package lint", + "prepack": "backstage-cli package prepack", + "postpack": "backstage-cli package postpack", + "start": "backstage-cli package start", + "test": "backstage-cli package test" + }, + "dependencies": { + "@backstage/backend-common": "workspace:^", + "@backstage/backend-plugin-api": "workspace:^", + "@backstage/plugin-notifications-common": "workspace:^", + "@backstage/plugin-notifications-node": "workspace:^", + "@backstage/plugin-scaffolder-node": "workspace:^", + "octokit": "^3.0.0" + }, + "devDependencies": { + "@backstage/cli": "workspace:^", + "@backstage/plugin-scaffolder-node-test-utils": "workspace:^" + } +} diff --git a/plugins/scaffolder-backend-module-notifications/src/actions/index.ts b/plugins/scaffolder-backend-module-notifications/src/actions/index.ts new file mode 100644 index 0000000000..9d708282dd --- /dev/null +++ b/plugins/scaffolder-backend-module-notifications/src/actions/index.ts @@ -0,0 +1,16 @@ +/* + * Copyright 2024 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +export { createSendNotificationAction } from './sendNotification'; diff --git a/plugins/scaffolder-backend-module-notifications/src/actions/sendNotification.test.ts b/plugins/scaffolder-backend-module-notifications/src/actions/sendNotification.test.ts new file mode 100644 index 0000000000..efd1377cae --- /dev/null +++ b/plugins/scaffolder-backend-module-notifications/src/actions/sendNotification.test.ts @@ -0,0 +1,93 @@ +/* + * Copyright 2024 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +import { createSendNotificationAction } from './sendNotification'; +import { NotificationService } from '@backstage/plugin-notifications-node'; +import { TemplateAction } from '@backstage/plugin-scaffolder-node'; +import { createMockActionContext } from '@backstage/plugin-scaffolder-node-test-utils'; + +describe('notification:send', () => { + const notificationService: jest.Mocked = { + send: jest.fn(), + }; + + let action: TemplateAction; + + beforeEach(() => { + jest.resetAllMocks(); + action = createSendNotificationAction({ + notifications: notificationService, + }); + }); + + const mockContext = createMockActionContext({ + input: { + recipients: 'broadcast', + title: 'Test notification', + }, + }); + + it('should send broadcast notification', async () => { + const ctx = Object.assign({}, mockContext, { + input: { recipients: 'broadcast', title: 'Test notification' }, + }); + await action.handler(ctx); + expect(notificationService.send).toHaveBeenCalledWith({ + recipients: { type: 'broadcast' }, + payload: { + title: 'Test notification', + }, + }); + }); + + it('should send entity notification', async () => { + const ctx = Object.assign({}, mockContext, { + input: { + recipients: 'entity', + entityRefs: ['user:default/john.doe'], + title: 'Test notification', + }, + }); + await action.handler(ctx); + expect(notificationService.send).toHaveBeenCalledWith({ + recipients: { type: 'entity', entityRef: ['user:default/john.doe'] }, + payload: { + title: 'Test notification', + }, + }); + }); + + it('should throw error if entity refs are missing', async () => { + const ctx = Object.assign({}, mockContext, { + input: { + recipients: 'entity', + title: 'Test notification', + }, + }); + await expect(action.handler(ctx)).rejects.toThrow(); + }); + + it('should not throw error if entity refs are missing but optional is true', async () => { + const ctx = Object.assign({}, mockContext, { + input: { + recipients: 'entity', + title: 'Test notification', + optional: true, + }, + }); + await expect(action.handler(ctx)).resolves.not.toThrow(); + expect(notificationService.send).not.toHaveBeenCalled(); + }); +}); diff --git a/plugins/scaffolder-backend-module-notifications/src/actions/sendNotification.ts b/plugins/scaffolder-backend-module-notifications/src/actions/sendNotification.ts new file mode 100644 index 0000000000..f50e178174 --- /dev/null +++ b/plugins/scaffolder-backend-module-notifications/src/actions/sendNotification.ts @@ -0,0 +1,146 @@ +/* + * Copyright 2024 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +import { + NotificationRecipients, + NotificationService, +} from '@backstage/plugin-notifications-node'; +import { + NotificationPayload, + NotificationSeverity, +} from '@backstage/plugin-notifications-common'; +import { createTemplateAction } from '@backstage/plugin-scaffolder-node'; + +/** + * @public + */ +export function createSendNotificationAction(options: { + notifications: NotificationService; +}) { + const { notifications } = options; + return createTemplateAction<{ + recipients: string; + entityRefs?: string[]; + title: string; + info?: string; + link?: string; + severity?: NotificationSeverity; + scope?: string; + optional?: boolean; + }>({ + id: 'notification:send', + description: 'Sends a notification using NotificationService', + schema: { + input: { + type: 'object', + required: ['recipients', 'title'], + properties: { + recipients: { + title: 'Recipient', + enum: ['broadcast', 'entity'], + description: + 'The recipient of the notification, either broadcast or entity. If using entity, also entityRef must be provided', + type: 'string', + }, + entityRefs: { + title: 'Entity references', + description: + 'The entity references to send the notification to, required if using recipient of entity', + type: 'array', + items: { + type: 'string', + }, + }, + title: { + title: 'Title', + description: 'Notification title', + type: 'string', + }, + info: { + title: 'Description', + description: 'Notification description', + type: 'string', + }, + link: { + title: 'Link', + description: 'Notification link', + type: 'string', + }, + severity: { + title: 'Severity', + type: 'string', + description: `Notification severity`, + enum: ['low', 'normal', 'high', 'critical'], + }, + scope: { + title: 'Scope', + description: 'Notification scope', + type: 'string', + }, + optional: { + title: 'Optional', + description: + 'Do not fail the action if the notification sending fails', + type: 'boolean', + }, + }, + }, + }, + async handler(ctx) { + const { + recipients, + entityRefs, + title, + info, + link, + severity, + scope, + optional, + } = ctx.input; + + ctx.logger.info(`Sending notification to ${recipients}`); + if (recipients === 'entity' && !entityRefs) { + if (optional !== true) { + throw new Error('Entity references must be provided'); + } + return; + } + + const notificationRecipients: NotificationRecipients = + recipients === 'broadcast' + ? { type: 'broadcast' } + : { type: 'entity', entityRef: entityRefs! }; + const payload: NotificationPayload = { + title, + description: info, + link, + severity, + scope, + }; + + try { + await notifications.send({ + recipients: notificationRecipients, + payload, + }); + } catch (e) { + ctx.logger.error(`Failed to send notification: ${e}`); + if (optional !== true) { + throw e; + } + } + }, + }); +} diff --git a/plugins/scaffolder-backend-module-notifications/src/index.ts b/plugins/scaffolder-backend-module-notifications/src/index.ts new file mode 100644 index 0000000000..05a356cc71 --- /dev/null +++ b/plugins/scaffolder-backend-module-notifications/src/index.ts @@ -0,0 +1,23 @@ +/* + * Copyright 2024 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * The notifications backend module for the scaffolder plugin. + * + * @packageDocumentation + */ +export * from './actions'; +export { scaffolderModuleNotifications as default } from './module'; diff --git a/plugins/scaffolder-backend-module-notifications/src/module.ts b/plugins/scaffolder-backend-module-notifications/src/module.ts new file mode 100644 index 0000000000..e8b6823e99 --- /dev/null +++ b/plugins/scaffolder-backend-module-notifications/src/module.ts @@ -0,0 +1,39 @@ +/* + * Copyright 2024 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +import { createBackendModule } from '@backstage/backend-plugin-api'; +import { notificationService } from '@backstage/plugin-notifications-node'; +import { scaffolderActionsExtensionPoint } from '@backstage/plugin-scaffolder-node/alpha'; +import { createSendNotificationAction } from './actions'; + +/** + * @public + * The Notifications module for the Scaffolder Backend + */ +export const scaffolderModuleNotifications = createBackendModule({ + pluginId: 'scaffolder', + moduleId: 'notifications', + register(reg) { + reg.registerInit({ + deps: { + notifications: notificationService, + scaffolder: scaffolderActionsExtensionPoint, + }, + async init({ notifications, scaffolder }) { + scaffolder.addActions(createSendNotificationAction({ notifications })); + }, + }); + }, +}); diff --git a/yarn.lock b/yarn.lock index 3cf5a79175..f46996d52f 100644 --- a/yarn.lock +++ b/yarn.lock @@ -6695,6 +6695,21 @@ __metadata: languageName: unknown linkType: soft +"@backstage/plugin-scaffolder-backend-module-notifications@workspace:^, @backstage/plugin-scaffolder-backend-module-notifications@workspace:plugins/scaffolder-backend-module-notifications": + version: 0.0.0-use.local + resolution: "@backstage/plugin-scaffolder-backend-module-notifications@workspace:plugins/scaffolder-backend-module-notifications" + dependencies: + "@backstage/backend-common": "workspace:^" + "@backstage/backend-plugin-api": "workspace:^" + "@backstage/cli": "workspace:^" + "@backstage/plugin-notifications-common": "workspace:^" + "@backstage/plugin-notifications-node": "workspace:^" + "@backstage/plugin-scaffolder-node": "workspace:^" + "@backstage/plugin-scaffolder-node-test-utils": "workspace:^" + octokit: ^3.0.0 + languageName: unknown + linkType: soft + "@backstage/plugin-scaffolder-backend-module-rails@workspace:^, @backstage/plugin-scaffolder-backend-module-rails@workspace:plugins/scaffolder-backend-module-rails": version: 0.0.0-use.local resolution: "@backstage/plugin-scaffolder-backend-module-rails@workspace:plugins/scaffolder-backend-module-rails" @@ -24249,6 +24264,7 @@ __metadata: "@backstage/plugin-scaffolder-backend": "workspace:^" "@backstage/plugin-scaffolder-backend-module-confluence-to-markdown": "workspace:^" "@backstage/plugin-scaffolder-backend-module-gitlab": "workspace:^" + "@backstage/plugin-scaffolder-backend-module-notifications": "workspace:^" "@backstage/plugin-scaffolder-backend-module-rails": "workspace:^" "@backstage/plugin-search-backend": "workspace:^" "@backstage/plugin-search-backend-module-catalog": "workspace:^"