RHIDP-8632: Update the Bulk Import Plugin to Integrate with Existing Backstage Templates and Orchestrator Workflows

assemblies/assembly-bulk-importing-from-github.adoc

@@ -15,3 +15,8 @@ include::modules/importing-repositories/procedure-managing-the-imported-reposito
 
 include::modules/importing-repositories/procedure-understanding-bulk-import-audit-logs.adoc[leveloffset=+1]
 
+include::modules/importing-repositories/concept-bulk-import-scaffolder-template.adoc[leveloffset=+1]
+
+include::modules/importing-repositories/procedure-integrating-bulk-import-with-orchestrator-workflows.adoc[leveloffset=+1]
+
+include::modules/importing-repositories/concept-data-handoff-and-custom-workflow-design.adoc[leveloffset=+1]

modules/importing-repositories/concept-bulk-import-scaffolder-template.adoc

@@ -0,0 +1,58 @@
+:_mod-docs-content-type: CONCEPT
+
+[id="bulk-import-scaffolder-template"]
+= Input parameters for Bulk Import Scaffolder template
+
+As an administrator, you can use the Bulk Import plugin to run a Scaffolder template task with specified parameters, which you must define within the template.
+
+The Bulk Import plugin analyzes Git repository information and provides the following parameters for the Scaffolder template task:
+
+`repoUrl`:: Normalized repository URL in the following format:
++
+[source,yaml]
+----
+  ${gitProviderHost}?owner=${owner}&repo=${repository-name}
+----
+
+`name`:: The repository name.
+
+`organization`:: The repository owner, which can be a user nickname or organization name.
+
+`branchName`:: The proposed repository branch. By default, the proposed repository branch is `bulk-import-catalog-entity`.
+
+`targetBranchName`:: The default branch of the Git repository.
+
+`gitProviderHost`:: The Git provider host parsed from the repository URL. You can use this parameter to write `Git-provider-agnostic` templates.
+
+Example of a Scaffolder template:
+[source,yaml]
+----
+parameters:
+  - title: Repository details
+    required:
+      - repoUrl
+      - branchName
+      - targetBranchName
+      - name
+      - organization
+    properties:
+      repoUrl:
+        type: string
+        title: Repository URL (Backstage format)
+        description: github.com?owner=Org&repo=repoName
+      organization:
+        type: string
+        title: Owner of the repository
+      name:
+        type: string
+        title: Name of the repository
+      branchName:
+        type: string
+        title: Branch to add the catalog entity to
+      targetBranchName:
+        type: string
+        title: Branch to target the PR/MR to
+      gitProviderHost:
+        type: string
+        title: Git provider host
+----

modules/importing-repositories/concept-data-handoff-and-custom-workflow-design.adoc

@@ -0,0 +1,13 @@
+:_mod-docs-content-type: CONCEPT
+
+[id="full-data-handoff-and-custom-workflow-design"]
+
+= Data handoff and custom workflow design
+
+When you configure the Bulk Import plugin by setting the importAPI field to `scaffolder`, the Bulk Import Backend passes all necessary context directly to the Scaffolder API.
+
+As an administrator, you can define the Scaffolder template workflow and structure the workflow to do the following:
+
+Define template parameters to consume input:: Structure the Scaffolder template to receive the repository data as template parameters for the current workflow run. The template must be generic, and not specific to a single repository, so that it can successfully run for every repository in the bulk list.
+
+Automate processing for each repository:: Implement the custom logic needed for a single repository within the template. The Orchestrator iterates through the repository list, launching the template once for each repository and passes only the data for that single repository to the template run. This allows you to automate tasks such as creating the `catalog-info.yaml`, running compliance checks, or registering the entity with the catalog.

modules/importing-repositories/procedure-integrating-bulk-import-with-orchestrator-workflows.adoc

@@ -0,0 +1,57 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="integrating-bulk-import-with-orchestrator-workflows"]
+= Setting up a custom Scaffolder workflow for Bulk Import
+
+As an administrator, you can create a custom Scaffolder template in line with the repository conventions of your organization and add the template into the {product} catalog for use by the Bulk Import plugin on multiple selected repositories.
+
+You can define various custom tasks, including, but not limited to the following:
+
+* Importing existing catalog entities from a repository
+* Creating pull requests for cleanup
+* Calling webhooks for external system integration
+
+.Prerequisites
+
+* You created a custom Scaffolder template for the Bulk Import plugin.
+
+* You have run your {product-very-short} instance with the following environment variable enabled to allow the use of the Scaffolder functionality:
++
+[source,yaml]
+----
+export NODE_OPTIONS=--no-node-snapshot
+----
+
+.Procedure
+
+* Configure your {my-app-config-file} configuration to instruct the Bulk Import plugin to use your custom template as shown in the following example:
++
+[source,yaml]
+----
+bulkImport:
+  importTemplate: <your_template_entity_reference_or_template_name>
+  importAPI: `open-pull-requests` | `scaffolder`;
+----
++
+where:
+
+`importTemplate:`::
+Enter your Scaffolder template entity reference.
+
+`importAPI`::
+Set the API to 'scaffolder' to trigger the defined workflow for high-fidelity automation. This field defines the import workflow and currently supports two following options:
+
+`open-pull-requests`:: This is the default import workflow, which includes the logic for creating pull requests for every selected repository.
+
+`scaffolder`:: This workflow uses an import scenario defined in the Scaffolder template to create import jobs. Select this option to use the custom import scenario defined in your Scaffolder template.
++
+Optional: You can direct the Bulk Import plugin to hand off the entire list of selected repositories to a custom Orchestrator workflow.
++
+[IMPORTANT]
+====
+The Scaffolder template must be generic and not specific to a single repository if you want your custom Scaffolder template to run successfully for every repository in the bulk list.
+====
+
+.Verification
+
+* The Bulk Import plugin runs the custom Scaffolder template for the list of repositories using the `/task-imports` API endpoint.