From 129e0f7797531ff4d63487809bb90d87afae025c Mon Sep 17 00:00:00 2001
From: Alex Crome <afscrome@users.noreply.github.com>
Date: Tue, 14 Nov 2023 19:07:32 +0000
Subject: [PATCH] Backend Migration Docs for Microsoft Graph Entity Provider

Added section to the migration guide specifically around how to migrate the Microsoft Graph Entity Provider.

Updated current documentation to recommend setting schedule in config rather than code.
Whilst not strictly nessescarry for the migration docs, documenting this way of setting the schedule eases migrations later (since the new backend system only allows setting schedules via config and not code)

Signed-off-by: Alex Crome <afscrome@users.noreply.github.com>
---
 .../building-backends/08-migrating.md         | 61 +++++++++++++++++++
 docs/integrations/azure/org.md                |  9 ++-
 2 files changed, 65 insertions(+), 5 deletions(-)

diff --git a/docs/backend-system/building-backends/08-migrating.md b/docs/backend-system/building-backends/08-migrating.md
index 1e30d0aa9e..98dde46d38 100644
--- a/docs/backend-system/building-backends/08-migrating.md
+++ b/docs/backend-system/building-backends/08-migrating.md
@@ -262,6 +262,67 @@ If you have other customizations made to `plugins/catalog.ts`, such as adding
 custom processors or entity providers, read on. Otherwise, you should be able to
 just delete that file at this point.
 
+#### Microsoft Graph
+
+Import the Microsoft Graph catalog module
+
+```ts title="packages/backend/src/index.ts"
+backend.add(import('@backstage/plugin-catalog-backend/alpha'));
+/* highlight-add-start */
+backend.add(import('@backstage/plugin-catalog-backend-module-msgraph/alpha'));
+/* highlight-add-end */
+```
+
+If you were providng a `schedule` programtically, this now needs to be set via configuration
+
+```yaml title="app-config.yaml"
+catalog:
+  providers:
+    microsoftGraphOrg:
+      provider:
+        /* highlight-add-start */
+        schedule:
+          frequency: PT4H
+          timeout: PT30M
+        /* highlight-add-end */
+
+```
+
+If you were providing transformers, these can be configured by extending `microsoftGraphOrgEntityProviderTransformExtensionPoint`
+
+```ts title="packages/backend/src/index.ts"
+import { createBackendModule } from '@backstage/backend-plugin-api';
+import { microsoftGraphOrgEntityProviderTransformExtensionPoint } from '@backstage/plugin-catalog-backend-module-msgraph/alpha';
+
+backend.add(
+  createBackendModule({
+    pluginId: 'catalog',
+    moduleId: 'microsoftGraphExtensions',
+    register(env) {
+      env.registerInit({
+        deps: {
+          /* highlight-add-start */
+          microsoftGraphTransformers:
+            microsoftGraphOrgEntityProviderTransformExtensionPoint,
+          /* highlight-add-end */
+        },
+        async init({ microsoftGraphTransformers }) {
+          /* highlight-add-start */
+          microsoftGraphTransformers.setUserTransformer(myUserTransformer);
+          microsoftGraphTransformers.setGroupTransformer(myGroupTransformer);
+          microsoftGraphTransformers.setOrganizationTransformer(
+            myOrganizationTransformer,
+          );
+          /* highlight-add-end */
+        },
+      });
+    },
+  }),
+);
+```
+
+#### Other Catalog Extensions
+
 You will use the [extension points](../architecture/05-extension-points.md)
 mechanism to extend or tweak the functionality of the plugin. To do that,
 you'll make your own bespoke [module](../architecture/06-modules.md) which
diff --git a/docs/integrations/azure/org.md b/docs/integrations/azure/org.md
index c4968b0399..061baf7301 100644
--- a/docs/integrations/azure/org.md
+++ b/docs/integrations/azure/org.md
@@ -34,6 +34,9 @@ catalog:
             securityEnabled eq false
             and mailEnabled eq true
             and groupTypes/any(c:c+eq+'Unified')
+        schedule:
+          frequency: PT1H
+          timeout: PT50M
 ```
 
 Finally, register the plugin in `catalog.ts`.
@@ -52,11 +55,7 @@ export default async function createPlugin(
   builder.addEntityProvider(
     MicrosoftGraphOrgEntityProvider.fromConfig(env.config, {
       logger: env.logger,
-      schedule: env.scheduler.createScheduledTaskRunner({
-        frequency: { hours: 1 },
-        timeout: { minutes: 50 },
-        initialDelay: { seconds: 15 },
-      }),
+      scheduler: env.scheduler,
     }),
   );
   /* highlight-add-end */