Skip to content

fix(orchestrator): update orchestrator:workflow:run to use workflow_i… #1012

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
batzionb merged 1 commit into from
Jun 25, 2025
Merged

fix(orchestrator): update orchestrator:workflow:run to use workflow_i… #1012

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions workspaces/orchestrator/.changeset/tricky-peas-help.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
'@red-hat-developer-hub/backstage-plugin-scaffolder-backend-module-orchestrator': patch
---

- update orchestrator:workflow:run to use workflow_id
- update README for scaffolder-backend-module-orchestrator
3 changes: 2 additions & 1 deletion workspaces/orchestrator/entities/yamlgreet.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
name: yamlgreet # matches workflow ID
name: greet
title: Greeting
description: Greeting workflow
tags:
Expand Down Expand Up @@ -35,6 +35,7 @@ spec:
name: Run workflow
action: orchestrator:workflow:run
input:
workflow_id: yamlgreet
parameters: ${{ parameters }}

output:
Expand Down
90 changes: 74 additions & 16 deletions workspaces/orchestrator/plugins/scaffolder-backend-module-orchestrator/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,19 @@ An example of using these actions can be found in the `workspaces/orchestrator/e

## Installation

### As a static plugin
### Static Plugin Installation

In `packages/backend/src/index.ts`:

```
backend.add(import('@red-hat-developer-hub/backstage-plugin-scaffolder-backend-module-orchestrator'));
```ts
backend.add(
import(
'@red-hat-developer-hub/backstage-plugin-scaffolder-backend-module-orchestrator'
),
);
```

# The software template generating templates from workflows - convertWorkflowToTemplate
## convertWorkflowToTemplate: A Software Template for Converting Workflows into Templates

The `workspaces/orchestrator/entities/convertWorkflowToTemplate.yaml` scaffolder software template is used for generating templates to be used to execute a serverless workflow via the Orchestrator.

Expand All @@ -26,7 +30,7 @@ The rest of parameters cover details about the target GitHub repository to eithe

The generated yaml template is accompanied by a README file highlighting instructions how to register the new template in the Backstage catalog.

## Important Note on Template Input Structure
**Important Note on Template Input Structure:**

The structure of the template input differs from that of the page used for collecting input parameters for workflows, despite some similarities. These two pages are supported by distinct implementations. While the set of parameters should remain consistent, their visual representation and especially grouping into steps may vary.

Expand All @@ -35,7 +39,7 @@ The structure of the template input differs from that of the page used for colle
The `[workflowId]` matches the identifier from the workflow definition.
For example, in the [workflow definition](https://github.com/rhdhorchestrator/serverless-workflows/blob/main/workflows/greeting/greeting.sw.yaml) below, the identifier is `greeting`:

```yaml greeting.sw.yaml
```yaml
id: greeting
version: '1.0'
specVersion: '0.8'
Expand All @@ -49,6 +53,52 @@ extensions:
outputSchema: schemas/workflow-output-schema.json
```

## Available Actions

### Action: `orchestrator:workflow:run`

Runs a SonataFlow workflow from a Software Template.

**Input:**

- `workflow_id` (string, required): The workflow ID from the definition.
- `parameters` (object, required): Input parameters for the workflow.

**Dry Run:** Supported — logs the event without executing the call.

**Example:**

```yaml
steps:
- id: runWorkflow
name: Run workflow
action: orchestrator:workflow:run
input:
workflow_id: yamlgreet
parameters: ${{ parameters }}
```

---

### Action: `orchestrator:workflow:get_params`

Retrieves metadata and input schema from a SonataFlow workflow.

**Input:**

- `workflow_id` (string, required): The workflow ID.
- `indent` (number, optional): Indentation level for the resulting YAML.

**Output:**

- `title`
- `description`
- `parameters`

**Dry Run:** Not supported.

---

## GitHub integration

The `convertWorkflowToTemplate.yaml` template pushes the result into a GitHub repository.
Expand Down Expand Up @@ -76,18 +126,26 @@ export GITHUB_TOKEN=.......

- configure `app-config.yaml`:

```
integrations:
github:
- token: ${GITHUB_TOKEN}
```
```yaml
integrations:
github:
- token: ${GITHUB_TOKEN}
```

## Resources
---

## Hints

- [Upstream documentation](https://backstage.io/docs/features/software-templates/builtin-actions)
- When using **Node.js 20+**, add this environment variable **before** running the backend:

# Hints
```bash
export NODE_OPTIONS="${NODE_OPTIONS:-} --no-node-snapshot"
```

Mind using `export NODE_OPTIONS="${NODE_OPTIONS:-} --no-node-snapshot"` before running the Backstage backend app with Node 20+ (per actual [warning in the upstream documentation](https://backstage.io/docs/features/software-templates/#getting-started)) - this might be changed in the future.
[Reference from Backstage documentation](https://backstage.io/docs/features/software-templates/#getting-started)

---

## Resources

Before running the Backstage backend app with **Node 20+**, be sure to execute `export NODE_OPTIONS="${NODE_OPTIONS:-} --no-node-snapshot` as recommended by the [warning in the upstream documentation](https://backstage.io/docs/features/software-templates/#getting-started) (this might be changed in the future).
- [Backstage Template Actions Documentation](https://backstage.io/docs/features/software-templates/builtin-actions)
14 changes: 11 additions & 3 deletions ...es/orchestrator/plugins/scaffolder-backend-module-orchestrator/src/actions/runWorkflow.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,6 @@
* limitations under the License.
*/
import { AuthService } from '@backstage/backend-plugin-api';
import { parseEntityRef } from '@backstage/catalog-model';
import { DiscoveryApi } from '@backstage/plugin-permission-common/index';
import { createTemplateAction } from '@backstage/plugin-scaffolder-node';
import { JsonObject } from '@backstage/types';
Expand All @@ -23,7 +22,10 @@ import { isAxiosError } from 'axios';

import { getOrchestratorApi, getRequestConfigOption } from './utils';

type RunWorkflowTemplateActionInput = { parameters: JsonObject };
type RunWorkflowTemplateActionInput = {
parameters: JsonObject;
workflow_id: string;
};
type RunWorkflowTemplateActionOutput = { instanceUrl: string };

const getError = (err: unknown): Error => {
Expand Down Expand Up @@ -77,9 +79,15 @@ export const createRunWorkflowAction = (
return;
}

if (!ctx.input.workflow_id) {
throw new Error(
"Missing required 'workflow_id' input. Ensure that the step invoking the 'orchestrator:workflow:run' action includes an explicit 'workflow_id' field in its input.",
);
}

try {
const { data } = await api.executeWorkflow(
parseEntityRef(entity).name,
ctx.input.workflow_id,
{ inputData: ctx.input.parameters },
undefined,
reqConfigOption,
Expand Down