From 2bbd24f58fd1ff666e34710378978ae7fb413d33 Mon Sep 17 00:00:00 2001
From: Hellgren Heikki <heikki.hellgren@op.fi>
Date: Fri, 22 Aug 2025 10:37:53 +0300
Subject: [PATCH] feat(catalog): processor priority

This change enables the ordering of catalog processors by their priority,
allowing for more control over the catalog processing sequence.
The default priority is set to 20, and processors can be assigned a custom
priority to influence their execution order. Lower number indicates higher priority.
The priority can be set by implementing the `getPriority` method in the processor class
or by adding a `catalog.processors.<processorName>.priority` configuration
in the `app-config.yaml` file. The configuration takes precedence over the method.

closes #30963

Signed-off-by: Hellgren Heikki <heikki.hellgren@op.fi>
---
 .changeset/curvy-terms-jam.md                 | 14 ++++++++++
 .../software-catalog/life-of-an-entity.md     |  4 +++
 plugins/catalog-backend/config.d.ts           |  6 +++++
 .../src/service/CatalogBuilder.ts             | 27 ++++++++++++++++++-
 plugins/catalog-node/report.api.md            |  1 +
 plugins/catalog-node/src/api/processor.ts     |  8 ++++++
 6 files changed, 59 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/curvy-terms-jam.md

diff --git a/.changeset/curvy-terms-jam.md b/.changeset/curvy-terms-jam.md
new file mode 100644
index 0000000000..d8070bc8ce
--- /dev/null
+++ b/.changeset/curvy-terms-jam.md
@@ -0,0 +1,14 @@
+---
+'@backstage/plugin-catalog-backend': patch
+'@backstage/plugin-catalog-node': patch
+---
+
+Order catalog processors by priority.
+
+This change enables the ordering of catalog processors by their priority,
+allowing for more control over the catalog processing sequence.
+The default priority is set to 20, and processors can be assigned a custom
+priority to influence their execution order. Lower number indicates higher priority.
+The priority can be set by implementing the `getPriority` method in the processor class
+or by adding a `catalog.processors.<processorName>.priority` configuration
+in the `app-config.yaml` file. The configuration takes precedence over the method.
diff --git a/docs/features/software-catalog/life-of-an-entity.md b/docs/features/software-catalog/life-of-an-entity.md
index 15f30210e8..628b083ed2 100644
--- a/docs/features/software-catalog/life-of-an-entity.md
+++ b/docs/features/software-catalog/life-of-an-entity.md
@@ -132,6 +132,10 @@ in the registration order, but this does not apply over multiple catalog modules
 the order of registration depends on the order in which the modules are loaded
 by the framework.
 
+It's possible to customize the order of the processors by modifying the
+`catalog.processors.<processorName>.priority` configuration option.
+The default priority is `20`, and lower value means that the processor runs earlier.
+
 :::
 
 Each step has the opportunity to optionally modify the entity, and to optionally
diff --git a/plugins/catalog-backend/config.d.ts b/plugins/catalog-backend/config.d.ts
index 659cf82280..f1b72e5b45 100644
--- a/plugins/catalog-backend/config.d.ts
+++ b/plugins/catalog-backend/config.d.ts
@@ -251,6 +251,12 @@ export interface Config {
          * Whether the processor is enabled or not. Defaults to true.
          */
         enabled?: boolean;
+        /**
+         * The priority of the processor, which is used to determine the order in which
+         * processors are run. The default priority is 20, and lower value means
+         * that the processor runs earlier.
+         */
+        priority?: number;
       };
     };
   };
diff --git a/plugins/catalog-backend/src/service/CatalogBuilder.ts b/plugins/catalog-backend/src/service/CatalogBuilder.ts
index 1e2957dadd..dcd677152e 100644
--- a/plugins/catalog-backend/src/service/CatalogBuilder.ts
+++ b/plugins/catalog-backend/src/service/CatalogBuilder.ts
@@ -727,7 +727,32 @@ export class CatalogBuilder {
 
     this.checkMissingExternalProcessors(processors);
 
-    return this.filterProcessors(processors);
+    const filteredProcessors = this.filterProcessors(processors);
+
+    // Lastly sort the processors by priority. Config can override the
+    // priority of a processor to allow control of 3rd party processors.
+    filteredProcessors.sort((a, b) => {
+      const getProcessorPriority = (processor: CatalogProcessor) => {
+        try {
+          return (
+            config.getOptionalNumber(
+              `catalog.processors.${processor.getProcessorName()}.priority`,
+            ) ??
+            processor.getPriority?.() ??
+            20
+          );
+        } catch (_) {
+          // In case the processor config is not an object, just return default priority
+          return 20;
+        }
+      };
+
+      const aPriority = getProcessorPriority(a);
+      const bPriority = getProcessorPriority(b);
+      return aPriority - bPriority;
+    });
+
+    return filteredProcessors;
   }
 
   private filterProcessors(processors: CatalogProcessor[]) {
diff --git a/plugins/catalog-node/report.api.md b/plugins/catalog-node/report.api.md
index 25ab9145ef..9a9f91865c 100644
--- a/plugins/catalog-node/report.api.md
+++ b/plugins/catalog-node/report.api.md
@@ -60,6 +60,7 @@ export type CatalogProcessor = {
     emit: CatalogProcessorEmit,
     cache: CatalogProcessorCache,
   ): Promise<Entity>;
+  getPriority?(): number;
 };
 
 // @public
diff --git a/plugins/catalog-node/src/api/processor.ts b/plugins/catalog-node/src/api/processor.ts
index e43fdef071..3aa5bf0fa7 100644
--- a/plugins/catalog-node/src/api/processor.ts
+++ b/plugins/catalog-node/src/api/processor.ts
@@ -100,6 +100,14 @@ export type CatalogProcessor = {
     emit: CatalogProcessorEmit,
     cache: CatalogProcessorCache,
   ): Promise<Entity>;
+
+  /**
+   * Returns a processor priority, which is used to determine the order in which
+   * processors are run. The default priority is 20, and lower value means
+   * that the processor runs earlier.
+   * @returns A number representing the priority of the processor.
+   */
+  getPriority?(): number;
 };
 
 /**