-
Notifications
You must be signed in to change notification settings - Fork 153
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs(orchestrator): fix stale links (#2552)
docs(orchestrator: fix stale links
- Loading branch information
Showing
2 changed files
with
19 additions
and
16 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,2 @@ | ||
| --- | ||
| --- |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -57,7 +57,7 @@ The Orchestrator plugin is composed of the following packages: | |
|
|
||
| #### Setting up the Orchestrator as a dynamic plugin in a Helm deployment | ||
|
|
||
| Please follow this link for instructions: https://github.com/janus-idp/backstage-showcase/blob/main/showcase-docs/dynamic-plugins.md#helm-deployment | ||
| Please follow this link for instructions: https://github.com/janus-idp/backstage-showcase/blob/main/docs/dynamic-plugins/installing-plugins.md#installing-external-dynamic-plugins. | ||
|
|
||
| #### Setting up the configuration for the Orchestrator plugin | ||
|
|
||
|
|
@@ -84,7 +84,7 @@ orchestrator: | |
| - When interacting with an existing SonataFlow infrastructure, the `sonataFlowService` config section must be entirely omitted and the `dataIndexService.url` must point to the existing Data Index Service. | ||
|
|
||
| For more information about the configuration options, including other optional properties, see the [config.d.ts](../orchestrator-common/config.d.ts) file. | ||
| For more information about the configuration options, including other optional properties, see the [config.d.ts](https://github.com/janus-idp/backstage-plugins/blob/release-1.3/plugins/orchestrator-common/config.d.ts) file. | ||
|
|
||
| #### Setting up the Orchestrator backend package | ||
|
|
||
|
|
@@ -156,54 +156,55 @@ For more information about the configuration options, including other optional p | |
|
|
||
| ### Extensible Workflow Execution Form | ||
|
|
||
| The `orchestrator` plugin includes an extensible form for executing forms. For detailed guidance see the [Extensible Workflow Execution Form Documentation](./docs/extensibleForm.md). | ||
| The `orchestrator` plugin includes an extensible form for executing forms. For detailed guidance see the [Extensible Workflow Execution Form Documentation](https://github.com/janus-idp/backstage-plugins/blob/release-1.3/plugins/orchestrator/docs/extensibleForm.md). | ||
|
|
||
| ## For users | ||
|
|
||
| ### Using the Orchestrator plugin in Backstage | ||
|
|
||
| The Orchestrator plugin enhances the Backstage with the execution of developer self-service flows. It provides a graphical editor to visualize workflow definitions, and a dashboard to monitor the execution of the workflows. | ||
|
|
||
| Refer to the [Quick start](https://github.com/janus-idp/backstage-plugins/blob/main/plugins/orchestrator/docs/quickstart.md) to install the Orchestrator using the helm chart and execute a sample workflow through the Red Hat Developer Hub orchestrator plugin UI. | ||
| Refer to the [Quick start](https://github.com/janus-idp/backstage-plugins/blob/release-1.3/plugins/orchestrator/docs/quickstart.md) to install the Orchestrator using the helm chart and execute a sample workflow through the Red Hat Developer Hub orchestrator plugin UI. | ||
|
|
||
| ## OpenAPI | ||
|
|
||
| The plugin provides OpenAPI `v2` endpoints definition to facilitate communication between the frontend and backend. This approach minimizes the data that needs to be sent to the frontend, provides flexibility and avoids dependencies on changes in the [CNCF serverless specification](https://github.com/serverlessworkflow/specification/blob/main/specification.md). It also allows for a seamless transition if there's a need to replace the backend implementation. | ||
|
|
||
| In addition, by leveraging on OpenAPI spec, it is possible to generate clients and create CI steps. | ||
|
|
||
| OpenAPI specification [file](https://github.com/janus-idp/backstage-plugins/blob/main/plugins/orchestrator-common/src/openapi/openapi.yaml) is available in [orchestrator-common](https://github.com/janus-idp/backstage-plugins/blob/main/plugins/orchestrator-common). | ||
| OpenAPI specification documentation is available [here](https://github.com/janus-idp/backstage-plugins/blob/main/plugins/orchestrator-common/src/generated/docs/markdown/README.md) | ||
|
|
||
| > **NOTE:**\ | ||
| > While the OpenAPI specification is available in the Orchestrator plugin, the UI currently does not rely on this spec. \ | ||
| > We plan to incorporate v2 endpoints into the UI in the near future. | ||
| OpenAPI specification [file](https://github.com/janus-idp/backstage-plugins/blob/release-1.3/plugins/orchestrator-common/src/openapi/openapi.yaml) is available in [orchestrator-common](https://github.com/janus-idp/backstage-plugins/blob/release-1.3/plugins/orchestrator-common). | ||
| OpenAPI specification documentation is available [here](https://github.com/janus-idp/backstage-plugins/blob/release-1.3/plugins/orchestrator-common/src/generated/docs/markdown/README.md) | ||
|
|
||
| ### orchestrator-common | ||
|
|
||
| The typescript schema is generated in [auto-generated](https://github.com/janus-idp/backstage-plugins/blob/main/plugins/orchestrator-common/src/auto-generated/api/models/schema.ts) folder from openapi.yaml specification file. | ||
| The typescript client is generated in [generated](https://github.com/janus-idp/backstage-plugins/blob/release-1.3/plugins/orchestrator-common/src/generated/client) folder from openapi.yaml specification file. | ||
|
|
||
| ### orchestrator-backend | ||
|
|
||
| The orchestrator backend can use the generated schema to validate the HTTP requests and responses. | ||
|
|
||
| > NOTE: Temporary the validation has been disabled. It will be enabled when the orchestrator frontend will switch to the use of v2 endpoints only. | ||
| ### audit log | ||
|
|
||
| The orchestrator backend has audit logs for all incoming requests. | ||
|
|
||
| For more information about audit logs in RHDH, please refer to [the official documentation](https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.2/html/getting_started_with_red_hat_developer_hub/assembly-audit-log#con-audit-log-config_assembly-audit-log). | ||
| [The official Log storage OpenShift documentation](https://docs.openshift.com/container-platform/4.15/observability/logging/log_storage/about-log-storage.html) may also be of interest. | ||
|
|
||
| #### Development instruction | ||
|
|
||
| Checkout the backstage-plugin | ||
|
|
||
| `git clone [email protected]:janus-idp/backstage-plugins.git` | ||
|
|
||
| If you need to change the OpenAPI spec, edit the [openapi.yaml](https://github.com/janus-idp/backstage-plugins/blob/main/plugins/orchestrator-common/src/openapi/openapi.yaml) according to your needs and then execute from the project root folder: | ||
| If you need to change the OpenAPI spec, edit the [openapi.yaml](https://github.com/janus-idp/backstage-plugins/blob/release-1.3/plugins/orchestrator-common/src/openapi/openapi.yaml) according to your needs and then execute from the project root folder: | ||
|
|
||
| `yarn --cwd plugins/orchestrator-common openapi` | ||
|
|
||
| This command updates the [auto-generated files](https://github.com/janus-idp/backstage-plugins/blob/main/plugins/orchestrator-common/src/auto-generated/api/) and the [auto-generated docs](https://github.com/janus-idp/backstage-plugins/tree/main/plugins/orchestrator-common/src/auto-generated/docs). | ||
| This command updates the [generated files](https://github.com/janus-idp/backstage-plugins/blob/release-1.3/plugins/orchestrator-common/src/generated) including API, client and docs. | ||
|
|
||
| > NOTE: Do not manually edit auto-generated files | ||
|
|
||
| If you add a new component in the spec, then you need to export the generated typescript object [here](https://github.com/janus-idp/backstage-plugins/blob/main/plugins/orchestrator-common/src/openapi/types.ts). For example, if you define | ||
| If you add a new component in the spec, then you need to export the generated typescript object [here](https://github.com/janus-idp/backstage-plugins/blob/release-1.3/plugins/orchestrator-common/src/generated/client/api.ts). For example, if you define | ||
|
|
||
| ```yaml | ||
| components: | ||
|
|
@@ -245,7 +246,7 @@ paths: | |
| $ref: '#/components/schemas/Person' | ||
| ``` | ||
|
|
||
| Then you can implement the endpoint in [router.ts](https://github.com/janus-idp/backstage-plugins/blob/main/plugins/orchestrator-backend/src/service/router.ts) referring the operationId `getNames`: | ||
| Then you can implement the endpoint in [router.ts](https://github.com/janus-idp/backstage-plugins/blob/release-1.3/plugins/orchestrator-backend/src/service/router.ts) referring the operationId `getNames`: | ||
|
|
||
| ```typescript | ||
| api.register('getNames', async (_c, _req, res: express.Response, next) => { | ||
|
|
||