feat(catalog/msgraph): Add backend plugin

Add `microsoftGraphOrgEntityProviderCatalogModule` (new backend-plugin-api, alpha).

Relates-to: PR #13859
Relates-to: PR #14034
Signed-off-by: Patrick Jungermann <Patrick.Jungermann@gmail.com>

.changeset/mean-files-fly.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-backend-module-msgraph': patch
+---
+
+Add `microsoftGraphOrgEntityProviderCatalogModule` (new backend-plugin-api, alpha).

plugins/catalog-backend-module-msgraph/api-report.md

@@ -3,6 +3,7 @@
 > 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 { CatalogProcessor } from '@backstage/plugin-catalog-backend';
 import { CatalogProcessorEmit } from '@backstage/plugin-catalog-backend';
 import { Config } from '@backstage/config';
@@ -133,6 +134,20 @@ export class MicrosoftGraphOrgEntityProvider implements EntityProvider {
   read(options?: { logger?: Logger }): Promise<void>;
 }
 
+// @alpha
+export const microsoftGraphOrgEntityProviderCatalogModule: (
+  options?: MicrosoftGraphOrgEntityProviderCatalogModuleOptions | undefined,
+) => BackendFeature;
+
+// @alpha
+export interface MicrosoftGraphOrgEntityProviderCatalogModuleOptions {
+  groupTransformer?: GroupTransformer | Record<string, GroupTransformer>;
+  organizationTransformer?:
+    | OrganizationTransformer
+    | Record<string, OrganizationTransformer>;
+  userTransformer?: UserTransformer | Record<string, UserTransformer>;
+}
+
 // @public @deprecated
 export interface MicrosoftGraphOrgEntityProviderLegacyOptions {
   groupTransformer?: GroupTransformer;

plugins/catalog-backend-module-msgraph/package.json

@@ -7,6 +7,7 @@
   "license": "Apache-2.0",
   "publishConfig": {
     "access": "public",
+    "alphaTypes": "dist/index.alpha.d.ts",
     "main": "dist/index.cjs.js",
     "types": "dist/index.d.ts"
   },
@@ -23,20 +24,22 @@
     "backstage"
   ],
   "scripts": {
-    "build": "backstage-cli package build",
+    "start": "backstage-cli package start",
+    "build": "backstage-cli package build --experimental-type-build",
     "lint": "backstage-cli package lint",
     "test": "backstage-cli package test",
     "prepack": "backstage-cli package prepack",
     "postpack": "backstage-cli package postpack",
-    "clean": "backstage-cli package clean",
-    "start": "backstage-cli package start"
+    "clean": "backstage-cli package clean"
   },
   "dependencies": {
     "@azure/identity": "^2.1.0",
+    "@backstage/backend-plugin-api": "workspace:^",
     "@backstage/backend-tasks": "workspace:^",
     "@backstage/catalog-model": "workspace:^",
     "@backstage/config": "workspace:^",
     "@backstage/plugin-catalog-backend": "workspace:^",
+    "@backstage/plugin-catalog-node": "workspace:^",
     "@microsoft/microsoft-graph-types": "^2.6.0",
     "@types/node-fetch": "^2.5.12",
     "lodash": "^4.17.21",
@@ -55,8 +58,9 @@
     "msw": "^0.47.0"
   },
   "files": [
-    "dist",
-    "config.d.ts"
+    "alpha",
+    "config.d.ts",
+    "dist"
   ],
   "configSchema": "config.d.ts"
 }

plugins/catalog-backend-module-msgraph/src/index.ts

@@ -20,5 +20,7 @@
  * @packageDocumentation
  */
 
-export * from './processors';
 export * from './microsoftGraph';
+export * from './processors';
+export { microsoftGraphOrgEntityProviderCatalogModule } from './service/MicrosoftGraphOrgEntityProviderCatalogModule';
+export type { MicrosoftGraphOrgEntityProviderCatalogModuleOptions } from './service/MicrosoftGraphOrgEntityProviderCatalogModule';

plugins/catalog-backend-module-msgraph/src/service/MicrosoftGraphOrgEntityProviderCatalogModule.test.ts

@@ -0,0 +1,89 @@
+/*
+ * Copyright 2022 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 { getVoidLogger } from '@backstage/backend-common';
+import {
+  configServiceRef,
+  loggerServiceRef,
+  schedulerServiceRef,
+} from '@backstage/backend-plugin-api';
+import {
+  PluginTaskScheduler,
+  TaskScheduleDefinition,
+} from '@backstage/backend-tasks';
+import { startTestBackend } from '@backstage/backend-test-utils';
+import { ConfigReader } from '@backstage/config';
+import { catalogProcessingExtensionPoint } from '@backstage/plugin-catalog-node';
+import { Duration } from 'luxon';
+import { microsoftGraphOrgEntityProviderCatalogModule } from './MicrosoftGraphOrgEntityProviderCatalogModule';
+import { MicrosoftGraphOrgEntityProvider } from '../processors';
+
+describe('awsS3EntityProviderCatalogModule', () => {
+  it('should register provider at the catalog extension point', async () => {
+    let addedProviders: Array<MicrosoftGraphOrgEntityProvider> | undefined;
+    let usedSchedule: TaskScheduleDefinition | undefined;
+
+    const extensionPoint = {
+      addEntityProvider: (providers: any) => {
+        addedProviders = providers;
+      },
+    };
+    const runner = jest.fn();
+    const scheduler = {
+      createScheduledTaskRunner: (schedule: TaskScheduleDefinition) => {
+        usedSchedule = schedule;
+        return runner;
+      },
+    } as unknown as PluginTaskScheduler;
+
+    const config = new ConfigReader({
+      catalog: {
+        providers: {
+          microsoftGraphOrg: {
+            customProviderId: {
+              target: 'target',
+              tenantId: 'tenantId',
+              clientId: 'clientId',
+              clientSecret: 'clientSecret',
+              schedule: {
+                frequency: 'PT30M',
+                timeout: 'PT3M',
+              },
+            },
+          },
+        },
+      },
+    });
+
+    await startTestBackend({
+      extensionPoints: [[catalogProcessingExtensionPoint, extensionPoint]],
+      services: [
+        [configServiceRef, config],
+        [loggerServiceRef, getVoidLogger()],
+        [schedulerServiceRef, scheduler],
+      ],
+      features: [microsoftGraphOrgEntityProviderCatalogModule()],
+    });
+
+    expect(usedSchedule?.frequency).toEqual(Duration.fromISO('PT30M'));
+    expect(usedSchedule?.timeout).toEqual(Duration.fromISO('PT3M'));
+    expect(addedProviders?.length).toEqual(1);
+    expect(addedProviders?.pop()?.getProviderName()).toEqual(
+      'MicrosoftGraphOrgEntityProvider:customProviderId',
+    );
+    expect(runner).not.toHaveBeenCalled();
+  });
+});

plugins/catalog-backend-module-msgraph/src/service/MicrosoftGraphOrgEntityProviderCatalogModule.ts

@@ -0,0 +1,93 @@
+/*
+ * Copyright 2022 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 {
+  configServiceRef,
+  createBackendModule,
+  loggerServiceRef,
+  loggerToWinstonLogger,
+  schedulerServiceRef,
+} from '@backstage/backend-plugin-api';
+import { catalogProcessingExtensionPoint } from '@backstage/plugin-catalog-node';
+import {
+  GroupTransformer,
+  OrganizationTransformer,
+  UserTransformer,
+} from '../microsoftGraph';
+import { MicrosoftGraphOrgEntityProvider } from '../processors';
+
+/**
+ * Options for {@link microsoftGraphOrgEntityProviderCatalogModule}.
+ *
+ * @alpha
+ */
+export interface MicrosoftGraphOrgEntityProviderCatalogModuleOptions {
+  /**
+   * The function that transforms a user entry in msgraph to an entity.
+   * Optionally, you can pass separate transformers per provider ID.
+   */
+  userTransformer?: UserTransformer | Record<string, UserTransformer>;
+
+  /**
+   * The function that transforms a group entry in msgraph to an entity.
+   * Optionally, you can pass separate transformers per provider ID.
+   */
+  groupTransformer?: GroupTransformer | Record<string, GroupTransformer>;
+
+  /**
+   * The function that transforms an organization entry in msgraph to an entity.
+   * Optionally, you can pass separate transformers per provider ID.
+   */
+  organizationTransformer?:
+    | OrganizationTransformer
+    | Record<string, OrganizationTransformer>;
+}
+
+/**
+ * Registers the MicrosoftGraphOrgEntityProvider with the catalog processing extension point.
+ *
+ * @alpha
+ */
+export const microsoftGraphOrgEntityProviderCatalogModule = createBackendModule(
+  {
+    pluginId: 'catalog',
+    moduleId: 'microsoftGraphOrgEntityProvider',
+    register(
+      env,
+      options?: MicrosoftGraphOrgEntityProviderCatalogModuleOptions,
+    ) {
+      env.registerInit({
+        deps: {
+          catalog: catalogProcessingExtensionPoint,
+          config: configServiceRef,
+          logger: loggerServiceRef,
+          scheduler: schedulerServiceRef,
+        },
+        async init({ catalog, config, logger, scheduler }) {
+          catalog.addEntityProvider(
+            MicrosoftGraphOrgEntityProvider.fromConfig(config, {
+              groupTransformer: options?.groupTransformer,
+              logger: loggerToWinstonLogger(logger),
+              organizationTransformer: options?.organizationTransformer,
+              scheduler,
+              userTransformer: options?.userTransformer,
+            }),
+          );
+        },
+      });
+    },
+  },
+);

yarn.lock

@@ -4642,12 +4642,14 @@ __metadata:
   dependencies:
     "@azure/identity": ^2.1.0
     "@backstage/backend-common": "workspace:^"
+    "@backstage/backend-plugin-api": "workspace:^"
     "@backstage/backend-tasks": "workspace:^"
     "@backstage/backend-test-utils": "workspace:^"
     "@backstage/catalog-model": "workspace:^"
     "@backstage/cli": "workspace:^"
     "@backstage/config": "workspace:^"
     "@backstage/plugin-catalog-backend": "workspace:^"
+    "@backstage/plugin-catalog-node": "workspace:^"
     "@microsoft/microsoft-graph-types": ^2.6.0
     "@types/lodash": ^4.14.151
     "@types/node-fetch": ^2.5.12