From ed7c95a296558ae03c90b76e7429b49c4a72114c Mon Sep 17 00:00:00 2001 From: Bat-Zion Rotman Date: Thu, 21 Nov 2024 20:36:13 +0200 Subject: [PATCH] docs(orchestrator): fix stale links (#2552) docs(orchestrator: fix stale links --- .changeset/nine-emus-happen.md | 2 ++ plugins/orchestrator/README.md | 33 +++++++++++++++++---------------- 2 files changed, 19 insertions(+), 16 deletions(-) create mode 100644 .changeset/nine-emus-happen.md diff --git a/.changeset/nine-emus-happen.md b/.changeset/nine-emus-happen.md new file mode 100644 index 0000000000..a845151cc8 --- /dev/null +++ b/.changeset/nine-emus-happen.md @@ -0,0 +1,2 @@ +--- +--- diff --git a/plugins/orchestrator/README.md b/plugins/orchestrator/README.md index cb2f080e0e..ca2f38302d 100644 --- a/plugins/orchestrator/README.md +++ b/plugins/orchestrator/README.md @@ -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,7 +156,7 @@ 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 @@ -164,7 +164,7 @@ The `orchestrator` plugin includes an extensible form for executing forms. For d 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 @@ -172,22 +172,23 @@ The plugin provides OpenAPI `v2` endpoints definition to facilitate communicatio 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 @@ -195,15 +196,15 @@ Checkout the backstage-plugin `git clone git@github.com: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) => {