feat: update entity provider schedulers (#827)

* chore(3scale): allow app-config.yaml schedule to take precedence for entity provider

* chore(ocm): allow app-config.yaml schedule for entity provider to take precedence

* chore(aap): update entity provider to allow app-config scheduler to take precedence

* chore(keycloak): update entity provider to allow app-config scheduler to take precedence

* docs(keycloak): update keycloak docs for new schedule config priorities

* docs(ocm): update OCM docs for new schedule config priorities

* docs(aap): update aap docs for new schedule config priorities

* docs(ocm): update OCM README

* docs(keycloak): update keycloak README.md

* docs(3scale): update 3scale docs for new schedule config priorities

* docs(aap): update aap README.md

* fix(aap): update AAP entity provider scheduler logic

* fix(keycloak): update entity provider scheduler logic

* fix(ocm): update entity provider scheduler logic

* fix(3scale): update entity provider scheduler logic

* docs: update entity provider scheduler docs

* docs(3scale): update entity provider documentation

* docs: update entity provider documentation

* docs: update entity provider documentation

* deps: update yarn.lock

* docs(3scale): update 3scale README

* docs(aap): update aap-backend README

* docs(ocm): update ocm-backend README

plugins/3scale-backend/README.md

@@ -16,7 +16,7 @@ yarn workspace backend add @janus-idp/backstage-plugin-3scale-backend
 
 3scale Backstage provider allows configuration of one or multiple providers using the `app-config.yaml` configuration file of Backstage.
 
-**Procedure**
+### Procedure
 
 1. Use a `threeScaleApiEntity` marker to start configuring the `app-config.yaml` file of Backstage:
 
@@ -34,32 +34,80 @@ yarn workspace backend add @janus-idp/backstage-plugin-3scale-backend
              timeout: { minutes: 1 }
    ```
 
-2. Add the following code to `packages/backend/src/plugins/catalog.ts` file:
-
-   ```ts title="packages/backend/src/plugins/catalog.ts"
-   /* highlight-add-next-line */
-   import { ThreeScaleApiEntityProvider } from '@janus-idp/backstage-plugin-3scale-backend';
-
-   export default async function createPlugin(
-     env: PluginEnvironment,
-   ): Promise<Router> {
-     const builder = await CatalogBuilder.create(env);
-
-     /* ... other processors and/or providers ... */
-     /* highlight-add-start */
-     builder.addEntityProvider(
-       ThreeScaleApiEntityProvider.fromConfig(env.config, {
-         logger: env.logger,
-         scheduler: env.scheduler,
-       }),
-     );
-     /* highlight-add-end */
-
-     const { processingEngine, router } = await builder.build();
-     await processingEngine.start();
-     return router;
-   }
-   ```
+2. Configure the scheduler for the entity provider using one of the following methods:
+
+   - **Method 1**: If the scheduler is configured inside the `app-config.yaml` using the schedule config key mentioned previously, add the following code to `packages/backend/src/plugins/catalog.ts` file:
+
+     ```ts title="packages/backend/src/plugins/catalog.ts"
+     /* highlight-add-next-line */
+     import { ThreeScaleApiEntityProvider } from '@janus-idp/backstage-plugin-3scale-backend';
+
+     export default async function createPlugin(
+       env: PluginEnvironment,
+     ): Promise<Router> {
+       const builder = await CatalogBuilder.create(env);
+
+       /* ... other processors and/or providers ... */
+       /* highlight-add-start */
+       builder.addEntityProvider(
+         ThreeScaleApiEntityProvider.fromConfig(env.config, {
+           logger: env.logger,
+           scheduler: env.scheduler,
+         }),
+       );
+       /* highlight-add-end */
+
+       const { processingEngine, router } = await builder.build();
+       await processingEngine.start();
+       return router;
+     }
+     ```
+
+     ***
+
+     **NOTE**
+
+     If you have made any changes to the schedule in the `app-config.yaml` file, then restart to apply the changes.
+
+     ***
+
+   - **Method 2**: Add a schedule directly inside the `packages/backend/src/plugins/catalog.ts` file as follows:
+
+     ```ts title="packages/backend/src/plugins/catalog.ts"
+     /* highlight-add-next-line */
+     import { ThreeScaleApiEntityProvider } from '@janus-idp/backstage-plugin-3scale-backend';
+
+     export default async function createPlugin(
+       env: PluginEnvironment,
+     ): Promise<Router> {
+       const builder = await CatalogBuilder.create(env);
+
+       /* ... other processors and/or providers ... */
+       /* highlight-add-start */
+       builder.addEntityProvider(
+         ThreeScaleApiEntityProvider.fromConfig(env.config, {
+           logger: env.logger,
+           schedule: env.scheduler.createScheduledTaskRunner({
+             frequency: { minutes: 1 },
+             timeout: { minutes: 1 },
+           }),
+         }),
+       );
+       /* highlight-add-end */
+
+       const { processingEngine, router } = await builder.build();
+       await processingEngine.start();
+       return router;
+     }
+     ```
+
+   ***
+
+   **NOTE**
+
+   If both the `schedule` (hard-coded schedule) and `scheduler` (`app-config.yaml` schedule) option are provided in the `packages/backend/src/plugins/catalog.ts`, the `scheduler` option takes precedence. However, if the schedule inside the `app-config.yaml` file is not configured, then the `schedule` option is used.
+
+   ***
 
 ### Troubleshooting
 

plugins/3scale-backend/src/providers/ThreeScaleApiEntityProvider.ts

@@ -60,19 +60,14 @@ export class ThreeScaleApiEntityProvider implements EntityProvider {
 
       let taskRunner;
 
-      if (options.schedule) {
+      if (options.scheduler && providerConfig.schedule) {
+        // Create a scheduled task runner using the provided scheduler and schedule configuration
+        taskRunner = options.scheduler.createScheduledTaskRunner(
+          providerConfig.schedule,
+        );
+      } else if (options.schedule) {
         // Use the provided schedule directly
         taskRunner = options.schedule;
-      } else if (options.scheduler) {
-        if (providerConfig.schedule) {
-          // Create a scheduled task runner using the provided scheduler and schedule configuration
-          taskRunner = options.scheduler.createScheduledTaskRunner(
-            providerConfig.schedule,
-          );
-        } else {
-          // Handle the case where providerConfig.schedule is missing
-          throw new Error('Provider configuration schedule is missing.');
-        }
       } else {
         // Handle the case where both options.schedule and options.scheduler are missing
         throw new Error('Neither schedule nor scheduler is provided.');

plugins/aap-backend/README.md

@@ -36,7 +36,7 @@ The AAP Backstage provider plugin allows the configuration of one or multiple pr
 
 1. Configure the scheduler using one of the following options:
 
-   - Add the following code to the `packages/backend/src/plugins/catalog.ts` file if the scheduler is configured inside the `app-config.yaml` file:
+   - **Method 1**: If the scheduler is configured inside the `app-config.yaml` using the schedule config key mentioned previously, add the following code to `packages/backend/src/plugins/catalog.ts` file:
 
      ```ts title="packages/backend/src/plugins/catalog.ts"
      /* highlight-add-next-line */
@@ -63,7 +63,15 @@ The AAP Backstage provider plugin allows the configuration of one or multiple pr
      }
      ```
 
-   - Add a schedule directly inside the `packages/backend/src/plugins/catalog.ts` file as follows:
+     ***
+
+     **NOTE**
+
+     If you have made any changes to the schedule in the `app-config.yaml` file, then restart to apply the changes.
+
+     ***
+
+   - **Method 2**: Add a schedule directly inside the `packages/backend/src/plugins/catalog.ts` file as follows:
 
      ```ts title="packages/backend/src/plugins/catalog.ts"
      /* highlight-add-next-line */
@@ -93,6 +101,14 @@ The AAP Backstage provider plugin allows the configuration of one or multiple pr
      }
      ```
 
+   ***
+
+   **NOTE**
+
+   If both the `schedule` (hard-coded schedule) and `scheduler` (`app-config.yaml` schedule) option are provided in the `packages/backend/src/plugins/catalog.ts`, the `scheduler` option takes precedence. However, if the schedule inside the `app-config.yaml` file is not configured, then the `schedule` option is used.
+
+   ***
+
 ### Troubleshooting
 
 When you start your Backstage application, you can see the following log lines:

plugins/aap-backend/src/providers/AapResourceEntityProvider.ts

@@ -43,12 +43,12 @@ export class AapResourceEntityProvider implements EntityProvider {
 
     return providerConfigs.map(providerConfig => {
       let taskRunner;
-      if (options.schedule) {
-        taskRunner = options.schedule;
-      } else if (options.scheduler && providerConfig.schedule) {
+      if (options.scheduler && providerConfig.schedule) {
         taskRunner = options.scheduler.createScheduledTaskRunner(
           providerConfig.schedule,
         );
+      } else if (options.schedule) {
+        taskRunner = options.schedule;
       } else {
         throw new Error(
           `No schedule provided neither via code nor config for AapResourceEntityProvider:${providerConfig.id}.`,

plugins/keycloak-backend/README.md

@@ -35,88 +35,107 @@ yarn workspace backend add @janus-idp/backstage-plugin-keycloak-backend
            clientSecret: ${KEYCLOAK_CLIENTSECRET}
    ```
 
-2. Register the plugin in the `packages/backend/src/plugins/catalog.ts` file. You can also configure a schedule in this step. However, there are possible ways of configuration, such as:
-
-   - Configure a schedule inside the `app-config.yaml` file:
-
-     ```yaml title="app-config.yaml"
-     catalog:
-       providers:
-         keycloakOrg:
-           default:
-             # ...
-             # highlight-add-start
-             schedule: # optional; same options as in TaskScheduleDefinition
-               # supports cron, ISO duration, "human duration" as used in code
-               frequency: { minutes: 1 }
-               # supports ISO duration, "human duration" as used in code
-               timeout: { minutes: 1 }
-               initialDelay: { seconds: 15 }
-               # highlight-add-end
-     ```
-
-     Use the configured scheduler inside the `packages/backend/src/plugins/catalog.ts` as follows:
-
-     ```ts title="packages/backend/src/plugins/catalog.ts"
-     /* highlight-add-start */
-     import { KeycloakOrgEntityProvider } from '@janus-idp/backstage-plugin-keycloak-backend';
-
-     /* highlight-add-end */
-
-     export default async function createPlugin(
-       env: PluginEnvironment,
-     ): Promise<Router> {
-       const builder = await CatalogBuilder.create(env);
-
-       /* ... other processors and/or providers ... */
-       /* highlight-add-start */
-       builder.addEntityProvider(
-         KeycloakOrgEntityProvider.fromConfig(env.config, {
-           id: 'development',
-           logger: env.logger,
-           scheduler: env.scheduler,
-         }),
-       );
-       /* highlight-add-end */
-
-       const { processingEngine, router } = await builder.build();
-       await processingEngine.start();
-       return router;
-     }
-     ```
-
-   - Add a schedule directly inside the `packages/backend/src/plugins/catalog.ts` file as follows:
-
-     ```ts title="packages/backend/src/plugins/catalog.ts"
-     + import { KeycloakOrgEntityProvider } from '@janus-idp/backstage-plugin-keycloak-backend';
-
-     export default async function createPlugin(
-       env: PluginEnvironment,
-     ): Promise<Router> {
-       const builder = await CatalogBuilder.create(env);
-
-       /* ... other processors and/or providers ... */
-       builder.addEntityProvider(
-         KeycloakOrgEntityProvider.fromConfig(env.config, {
-           id: 'development',
-           logger: env.logger,
-           /* highlight-add-start */
-           schedule: env.scheduler.createScheduledTaskRunner({
-             frequency: { minutes: 1 },
-             timeout: { minutes: 1 },
-             initialDelay: { seconds: 15 }
-           }),
-           /* highlight-add-end */
-         }),
-       )
-
-       const { processingEngine, router } = await builder.build();
-       await processingEngine.start();
-       return router;
-     }
-     ```
-
-3. Optional: override the default Keycloak query parameters. Configure the parameters inside the `app-config.yaml` file:
+1. Register the plugin in the `packages/backend/src/plugins/catalog.ts` file. You can also configure a schedule in this step. However, there are possible ways of configuration, such as:
+
+   1. Configure a schedule inside the `app-config.yaml` file:
+
+      ```yaml title="app-config.yaml"
+      catalog:
+        providers:
+          keycloakOrg:
+            default:
+              # ...
+              # highlight-add-start
+              schedule: # optional; same options as in TaskScheduleDefinition
+                # supports cron, ISO duration, "human duration" as used in code
+                frequency: { minutes: 1 }
+                # supports ISO duration, "human duration" as used in code
+                timeout: { minutes: 1 }
+                initialDelay: { seconds: 15 }
+                # highlight-add-end
+      ```
+
+      Then use the configured scheduler by adding the following to the `packages/backend/src/plugins/catalog.ts`:
+
+      ```ts title="packages/backend/src/plugins/catalog.ts"
+      /* highlight-add-start */
+      import { KeycloakOrgEntityProvider } from '@janus-idp/backstage-plugin-keycloak-backend';
+
+      /* highlight-add-end */
+
+      export default async function createPlugin(
+        env: PluginEnvironment,
+      ): Promise<Router> {
+        const builder = await CatalogBuilder.create(env);
+
+        /* ... other processors and/or providers ... */
+        /* highlight-add-start */
+        builder.addEntityProvider(
+          KeycloakOrgEntityProvider.fromConfig(env.config, {
+            id: 'development',
+            logger: env.logger,
+            scheduler: env.scheduler,
+          }),
+        );
+        /* highlight-add-end */
+
+        const { processingEngine, router } = await builder.build();
+        await processingEngine.start();
+        return router;
+      }
+      ```
+
+      ***
+
+      **NOTE**
+
+      If you have made any changes to the schedule in the `app-config.yaml` file, then restart to apply the changes.
+
+      ***
+
+   1. Add a schedule directly inside the `packages/backend/src/plugins/catalog.ts` file as follows:
+
+      ```ts title="packages/backend/src/plugins/catalog.ts"
+      /* highlight-add-start */
+      import { KeycloakOrgEntityProvider } from '@janus-idp/backstage-plugin-keycloak-backend';
+
+      /* highlight-add-end */
+
+      export default async function createPlugin(
+        env: PluginEnvironment,
+      ): Promise<Router> {
+        const builder = await CatalogBuilder.create(env);
+
+        /* ... other processors and/or providers ... */
+        builder.addEntityProvider(
+          KeycloakOrgEntityProvider.fromConfig(env.config, {
+            id: 'development',
+            logger: env.logger,
+            /* highlight-add-start */
+            schedule: env.scheduler.createScheduledTaskRunner({
+              frequency: { minutes: 1 },
+              timeout: { minutes: 1 },
+              initialDelay: { seconds: 15 },
+            }),
+            /* highlight-add-end */
+          }),
+        );
+
+        const { processingEngine, router } = await builder.build();
+        await processingEngine.start();
+        return router;
+      }
+      ```
+
+   ***
+
+   **NOTE**
+
+   If both the `schedule` (hard-coded schedule) and `scheduler` (`app-config.yaml` schedule) option are provided in the `packages/backend/src/plugins/catalog.ts`, the `scheduler` option takes precedence. However, if the schedule inside the `app-config.yaml` file is not configured, then the `schedule` option is used.
+
+   ***
+
+1. Optional: override the default Keycloak query parameters. Configure the parameters inside the `app-config.yaml` file:
 
    ```yaml title="app-config.yaml"
    catalog:
@@ -130,7 +149,7 @@ yarn workspace backend add @janus-idp/backstage-plugin-keycloak-backend
            # highlight-add-end
    ```
 
-4. Optional: provide a transformer function for user/group to mutate the entity before their ingestion into catalog. Extend `packages/backend/src/plugins/catalog.ts` with custom `userTransformer` and `groupTransformer` functions:
+1. Optional: provide a transformer function for user/group to mutate the entity before their ingestion into catalog. Extend `packages/backend/src/plugins/catalog.ts` with custom `userTransformer` and `groupTransformer` functions:
 
    ```ts title="packages/backend/src/plugins/catalog.ts"
    /* highlight-add-start */