From c99c0c4ffc29d5962962946705b53f9589c90de6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= Date: Wed, 17 Jun 2026 12:56:46 +0300 Subject: [PATCH 1/3] Define (and use) custom component "RestRef". --- .../reference/rest/specification.md | 10 +---- .../process-engine/external-tasks.md | 4 +- docusaurus.config.ts | 2 +- src/components/RestRef.jsx | 39 +++++++++++++++++++ src/theme/MDXComponents.js | 9 +++-- 5 files changed, 48 insertions(+), 16 deletions(-) create mode 100644 src/components/RestRef.jsx diff --git a/docs/documentation/reference/rest/specification.md b/docs/documentation/reference/rest/specification.md index 19b1d874..21ef757b 100644 --- a/docs/documentation/reference/rest/specification.md +++ b/docs/documentation/reference/rest/specification.md @@ -5,12 +5,4 @@ sidebar_position: 20 --- -import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; - -export function RestApiDocLink() { - const { siteConfig } = useDocusaurusContext(); - - return here -} - -You can find the RestApi Specification . \ No newline at end of file +You can find the RestApi Specification . diff --git a/docs/documentation/user-guide/process-engine/external-tasks.md b/docs/documentation/user-guide/process-engine/external-tasks.md index 58f894fd..7e300ee6 100644 --- a/docs/documentation/user-guide/process-engine/external-tasks.md +++ b/docs/documentation/user-guide/process-engine/external-tasks.md @@ -89,7 +89,7 @@ Further information on the functionality of error event definitions on external ### Rest API -See the restref text="REST API documentation" tag="External-Task for how the API operations can be accessed via HTTP. +See the for how the API operations can be accessed via HTTP. ### Long Polling to Fetch and Lock External Tasks @@ -106,7 +106,7 @@ configurable period of time (timeout). Long polling significantly reduces the number of requests and enables using resources more efficiently on both the server and the client side. -Please also see the restref page="fetchAndLock" text="REST API documentation" tag="External-Task. +Please also see the . #### Unique Worker Request By default, multiple workers can use the same `workerId`. In order to ensure `workerId` uniqueness on server-side, the diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 3d93fde7..569e9135 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -37,7 +37,7 @@ const config: Config = { customFields: { javaDocUrl: '/reference/latest/javadoc', - restApiDocUrl: '/reference/latest/rest-api' + restApiDocUrl: 'https://docs.operaton.org/reference/latest/rest-api' }, // Even if you don't use internationalization, you can use this field to set // useful metadata like html lang. For example, if your site is Chinese, you diff --git a/src/components/RestRef.jsx b/src/components/RestRef.jsx new file mode 100644 index 00000000..cf6b9292 --- /dev/null +++ b/src/components/RestRef.jsx @@ -0,0 +1,39 @@ +import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; + +export default function RestRef({ text, section, operation }) { + const { siteConfig } = useDocusaurusContext(); + const hrefBase = siteConfig.customFields.restApiDocUrl; + + if (!hrefBase) { + // Will fail loudly. + throw new Error('RestRef: "restApiDocUrl" is missing from customFields in "docusaurus.config.js"'); + } + + if (!text) { + // Will fail loudly. + throw new Error('RestRef: "text" is required'); + } + + if (!section && operation) { + // Will fail loudly. + throw new Error('RestRef: "section" is required when "operation" is provided'); + } + + const href = buildHref({ hrefBase, section, operation }); + + return ( + {text} + ); +} + +function buildHref({hrefBase, section, operation}) { + if (!section) { + return hrefBase; + } + + if (!operation) { + return `${hrefBase}/#tag/${section}`; + } + + return `${hrefBase}/#tag/${section}/operation/${operation}`; +} diff --git a/src/theme/MDXComponents.js b/src/theme/MDXComponents.js index 2421820e..16c14061 100644 --- a/src/theme/MDXComponents.js +++ b/src/theme/MDXComponents.js @@ -6,17 +6,18 @@ * * @see https://docusaurus.io/docs/markdown-features/react#mdx-component-scope */ -import React from 'react'; -import MDXComponents from '@theme-original/MDXComponents'; import BpmnViewer from '@site/src/components/BpmnViewer'; +import RestRef from '@site/src/components/RestRef'; +import MDXComponents from '@theme-original/MDXComponents'; export default { // Spread the default components ...MDXComponents, - + // Add custom components that can be used in any MDX file without importing BpmnViewer, - + RestRef, + // You can also add aliases for convenience // 'bpmn-viewer': BpmnViewer, }; From f6e58277ca869277014950eff6368965641ce262 Mon Sep 17 00:00:00 2001 From: Julian Haupt Date: Wed, 17 Jun 2026 17:57:45 +0200 Subject: [PATCH 2/3] Migrate remaining REST reference snippets --- .../reference/rest/specification.md | 2 +- .../user-guide/operaton-bpm-run.md | 4 ++-- .../user-guide/process-engine/deployments.md | 2 +- .../process-engine/diagnostics-data.md | 2 +- .../process-engine/external-tasks.md | 2 +- .../process-engine/history/history-cleanup.md | 4 ++-- .../history/user-operation-log.md | 6 +++--- .../user-guide/process-engine/incidents.md | 4 ++-- .../process-engine/process-engine-concepts.md | 10 +++++----- .../process-instance-migration.md | 2 +- .../process-instance-restart.md | 4 ++-- .../user-guide/process-engine/variables.md | 2 +- docs/documentation/user-guide/security.md | 2 +- .../user-guide/task-forms/index.md | 4 ++-- .../webapps/cockpit/batch/monitoring.md | 4 ++-- src/components/RestRef.jsx | 20 ++++++++++--------- 16 files changed, 38 insertions(+), 36 deletions(-) diff --git a/docs/documentation/reference/rest/specification.md b/docs/documentation/reference/rest/specification.md index 21ef757b..2654f1f7 100644 --- a/docs/documentation/reference/rest/specification.md +++ b/docs/documentation/reference/rest/specification.md @@ -5,4 +5,4 @@ sidebar_position: 20 --- -You can find the RestApi Specification . +You can find the REST API specification . diff --git a/docs/documentation/user-guide/operaton-bpm-run.md b/docs/documentation/user-guide/operaton-bpm-run.md index 3e110d8e..a9856a57 100644 --- a/docs/documentation/user-guide/operaton-bpm-run.md +++ b/docs/documentation/user-guide/operaton-bpm-run.md @@ -137,7 +137,7 @@ However, the example application will not be started. Disabling the example application with any of those mechanisms will **NOT** delete any deployments or process instances from Operaton Run once they are created. You have to delete this data manually through the [web apps](../webapps/cockpit/deployment-view.md#delete), the -restref page="deleteDeployment" text="REST API" tag="Deployment, or by cleaning the database +, or by cleaning the database [configured in the application properties](#database). ### Choose between default and production configuration @@ -169,7 +169,7 @@ In the unpacked distro, you will find a `resources` folder. All files (including You can reference forms and scripts in the BPMN diagram with `embedded:deployment:/my-form.html`, `operaton-forms:deployment:/myform.form`, or `deployment:/my-script.js`. The deployment requires adding an extra `/` as a prefix to the filename. -Deployments via the restref page="createDeployment" text="REST API" tag="Deployment are still possible. +Deployments via the are still possible. ## Configure Operaton Run diff --git a/docs/documentation/user-guide/process-engine/deployments.md b/docs/documentation/user-guide/process-engine/deployments.md index bc81a5f9..cd490944 100644 --- a/docs/documentation/user-guide/process-engine/deployments.md +++ b/docs/documentation/user-guide/process-engine/deployments.md @@ -10,7 +10,7 @@ menu: --- -Before a process (or case, or decision) can be executed by the process engine, it has to be deployed. A deployment is a logical entity that groups multiple resources that are deployed together. Deployments can be made programmatically via Java API or restref page="createDeployment" text="REST API" tag="Deployment, or declaratively for resources of a [Process Application](../process-applications/index.md). This section covers advanced deployment concepts. +Before a process (or case, or decision) can be executed by the process engine, it has to be deployed. A deployment is a logical entity that groups multiple resources that are deployed together. Deployments can be made programmatically via Java API or , or declaratively for resources of a [Process Application](../process-applications/index.md). This section covers advanced deployment concepts. ## Deployments in a Clustered Scenario diff --git a/docs/documentation/user-guide/process-engine/diagnostics-data.md b/docs/documentation/user-guide/process-engine/diagnostics-data.md index 01423969..2c2f9db7 100644 --- a/docs/documentation/user-guide/process-engine/diagnostics-data.md +++ b/docs/documentation/user-guide/process-engine/diagnostics-data.md @@ -32,7 +32,7 @@ String jdkVersion = productInternals.getJdk().getVersion(); ### REST API -You can fetch the collected data via the REST API by calling the restref page="getTelemetryData" text="Get Telemetry Data" tag="Telemetry endpoint. +You can fetch the collected data via the REST API by calling the endpoint. ## Collected data diff --git a/docs/documentation/user-guide/process-engine/external-tasks.md b/docs/documentation/user-guide/process-engine/external-tasks.md index 7e300ee6..60f46615 100644 --- a/docs/documentation/user-guide/process-engine/external-tasks.md +++ b/docs/documentation/user-guide/process-engine/external-tasks.md @@ -87,7 +87,7 @@ The expression is evaluated on invocations of `ExternalTaskService#complete` and Further information on the functionality of error event definitions on external tasks can be found in the [expression language user guide](../process-engine/expression-language.md#external-task-error-handling). -### Rest API +### REST API See the for how the API operations can be accessed via HTTP. diff --git a/docs/documentation/user-guide/process-engine/history/history-cleanup.md b/docs/documentation/user-guide/process-engine/history/history-cleanup.md index 042b7e3a..01c29b74 100644 --- a/docs/documentation/user-guide/process-engine/history/history-cleanup.md +++ b/docs/documentation/user-guide/process-engine/history/history-cleanup.md @@ -174,7 +174,7 @@ Once deployed, TTL can be updated via Java API: processEngine.getRepositoryService().updateProcessDefinitionHistoryTimeToLive(processDefinitionId, 5); ``` -Setting the value to `null` clears the TTL. The same can be done via restref page="updateHistoryTimeToLiveByProcessDefinitionKeyAndTenantId" text="REST API" tag="Process-Definition. +Setting the value to `null` clears the TTL. The same can be done via . For decision and case definitions, TTL can be defined in a similar way. @@ -344,4 +344,4 @@ related to the cleanup execution since the particular node ignores them. **Please Note:** The history cleanup configuration properties that are unrelated to the cleanup execution (e.g., time to live, removal time strategy) still need to be defined among all nodes. -[configuration-options]: ../../../reference/deployment-descriptors/tags/process-engine.mdx#history-cleanup-configuration-parameters \ No newline at end of file +[configuration-options]: ../../../reference/deployment-descriptors/tags/process-engine.mdx#history-cleanup-configuration-parameters diff --git a/docs/documentation/user-guide/process-engine/history/user-operation-log.md b/docs/documentation/user-guide/process-engine/history/user-operation-log.md index 9c5a20e4..4d408032 100644 --- a/docs/documentation/user-guide/process-engine/history/user-operation-log.md +++ b/docs/documentation/user-guide/process-engine/history/user-operation-log.md @@ -19,7 +19,7 @@ If it is desired that operations are logged regardless whether they are performe ## Access the user operation log -The user operation log can be accessed via the Java API. The history service can be used to execute a `UserOperationLogQuery` by calling `historyService.createUserOperationLogQuery().execute()`. The query can be restricted with various filtering options. The query is also restref page="queryUserOperationEntries" text="exposed in the REST API" tag="Historic-User-Operation-Log. +The user operation log can be accessed via the Java API. The history service can be used to execute a `UserOperationLogQuery` by calling `historyService.createUserOperationLogQuery().execute()`. The query can be restricted with various filtering options. The query is also . ## User operation log entries @@ -68,8 +68,8 @@ historyService.clearAnnotationForOperationLogById(operationId); **Please note:** Annotations are present on all entries that belong to an operation log. -Please also see the REST API reference for restref page="setAnnotationUserOperationLog" text="setting" tag="Historic-User-Operation-Log and -restref page="clearAnnotationUserOperationLog" text="clearing" tag="Historic-User-Operation-Log annotations. +Please also see the REST API reference for and + annotations. ## Glossary of operations logged in the user operation log diff --git a/docs/documentation/user-guide/process-engine/incidents.md b/docs/documentation/user-guide/process-engine/incidents.md index 11b7d701..bdfc3680 100644 --- a/docs/documentation/user-guide/process-engine/incidents.md +++ b/docs/documentation/user-guide/process-engine/incidents.md @@ -52,7 +52,7 @@ Custom incidents must always be related to an existing Execution. An incident of any type, except for **failedJob** and **failedExternalTask**, can be resolved by calling `RuntimeService#resolveIncident`. -Incidents can be restref page="createIncident" text="created" tag="Execution and restref page="resolveIncident" text="resolved" tag="Incident through the REST API as well. +Incidents can be and through the REST API as well. ## (De-)Activate Incidents @@ -120,4 +120,4 @@ All additional incident handlers will be added as sub handlers to the `Composite By default, the main handler is `DefaultIncidentHandler`. To override the main handler, create a `CompositeIncidentHandler` with your own main `IncidentHandler` and initialize the incident handlers in the engine configuration before setting up the engine. See javadoc for more details -Composite Incident Handler. \ No newline at end of file +Composite Incident Handler. diff --git a/docs/documentation/user-guide/process-engine/process-engine-concepts.md b/docs/documentation/user-guide/process-engine/process-engine-concepts.md index 372510b4..de82f5cb 100644 --- a/docs/documentation/user-guide/process-engine/process-engine-concepts.md +++ b/docs/documentation/user-guide/process-engine/process-engine-concepts.md @@ -43,7 +43,7 @@ List processDefinitions = repositoryService.createProcessDefi The above query returns all deployed process definitions for the key `invoice` ordered by their `version` property. -You can also restref page="getProcessDefinitions" text="query for process definitions using the REST API" tag="Process-Definition. +You can also . ### Keys and Versions @@ -89,7 +89,7 @@ You may optionally pass in a couple of variables: Process variables are available to all tasks in a process instance and are automatically persisted to the database in case the process instance reaches a wait state. -It is also possible to restref page="startProcessInstance" text="start a process instance using the REST API" tag="Process-Definition. +It is also possible to . ### Start Process Instances via Tasklist @@ -153,7 +153,7 @@ You can query for all currently running process instances using the `ProcessInst The above query would select all process instances for the `invoice` process where the `creditor` is `Nice Pizza Inc.`. -You can also restref page="getProcessInstances" text="query for process instances using the REST API" tag="Process-Instance. +You can also . ### Interact With a Process Instance @@ -207,7 +207,7 @@ runtimeService.createExecutionQuery() The above query returns all executions for a given process instance. -You can also restref page="getExecutions" text="query for executions using the REST API" tag="Execution. +You can also . ## Activity Instances @@ -273,7 +273,7 @@ Currently, activity instances can only be retrieved for a process instance: ActivityInstance rootActivityInstance = runtimeService.getActivityInstance(processInstance.getProcessInstanceId()); ``` -You can restref page="getActivityInstanceTree" text="retrieve the activity instance tree using the REST API" tag="Process-Instance as well. +You can as well. ### Identity & Uniqueness diff --git a/docs/documentation/user-guide/process-engine/process-instance-migration.md b/docs/documentation/user-guide/process-engine/process-instance-migration.md index 3780cb5f..f1930588 100644 --- a/docs/documentation/user-guide/process-engine/process-instance-migration.md +++ b/docs/documentation/user-guide/process-engine/process-instance-migration.md @@ -114,7 +114,7 @@ From the accountant's perspective, migration is completely transparent while wor ## API The following gives a structured overview of the Java API for process instance migration. Note that these operations are also available -via restref text="REST" tag="Migration. +via . ### Creating a Migration Plan diff --git a/docs/documentation/user-guide/process-engine/process-instance-restart.md b/docs/documentation/user-guide/process-engine/process-instance-restart.md index a3ce7555..e62f998f 100644 --- a/docs/documentation/user-guide/process-engine/process-instance-restart.md +++ b/docs/documentation/user-guide/process-engine/process-instance-restart.md @@ -18,7 +18,7 @@ This can, for example, be useful when termination did not proceed in a desired w To perform such an operation the process engine offers *the process instance restart API*, that is entered via `RuntimeService.restartProcessInstances(...)`. This API allows to specify multiple instantiation instructions in one call by using a fluent builder. -Note that these operations are also available via REST: restref page="restartProcessInstance" text="Restart Process Instance" tag="Process-Definition and restref page="restartProcessInstanceAsyncOperation" text="Restart Process Instance (async)" tag="Process-Definition +Note that these operations are also available via REST: and . ## Process Instance Restart by Example @@ -240,4 +240,4 @@ If a restart job fails, it is retried by the job executor and, if no retries are left, an incident is created. In this case, manual action is necessary to complete the batch restart: The job's retries can be incremented or the job can be deleted. Deletion cancels restart of the specific instance but -does not affect the batch beyond that. \ No newline at end of file +does not affect the batch beyond that. diff --git a/docs/documentation/user-guide/process-engine/variables.md b/docs/documentation/user-guide/process-engine/variables.md index 157fac6d..11496196 100644 --- a/docs/documentation/user-guide/process-engine/variables.md +++ b/docs/documentation/user-guide/process-engine/variables.md @@ -343,7 +343,7 @@ TypedValue typedTransientFileValue = Variables.fileValue("file.txt", true) .create(); ``` -Transient variables can be used via REST API, e.g. restref page="startProcessInstance" text="when starting a new process instance" tag="Process-Definition. +Transient variables can be used via REST API, e.g. . ### Set Multiple Typed Values diff --git a/docs/documentation/user-guide/security.md b/docs/documentation/user-guide/security.md index 628af8da..9dd3d8b9 100644 --- a/docs/documentation/user-guide/security.md +++ b/docs/documentation/user-guide/security.md @@ -285,7 +285,7 @@ about the several headers, the defaults and how to configure the HTTP headers ac ### Variable Values from Untrusted Sources Process variables can be submitted as Java objects using the JDK built-in `application/x-java-serialized-object` data format, JSON or XML along with a Java class name via the Operaton REST API and web applications. -On server side, they can then be deserialized into Java objects, so that Java code can work with them in a native way. See [Operaton Spin](../user-guide/data-formats/configuring-spin-integration.md) for details and this restref page="putLocalExecutionVariable" text="REST API endpoint" tag="Execution for an example. +On server side, they can then be deserialized into Java objects, so that Java code can work with them in a native way. See [Operaton Spin](../user-guide/data-formats/configuring-spin-integration.md) for details and this for an example. If an attacker can access these endpoints, they can exploit so-called _serialization gadgets_, i.e. classes that run vulnerable code during deserialization resulting in remote code execution in the general case. For example, consider a class constructor that makes a REST request based on a field value. An attacker could submit a forged variable value so that during deserialization, when the constructor is called, the application server would make an arbitrary REST request to a destination of the attacker's choice. For details, see [OWASP's description of Deserialization of untrusted data](https://www.owasp.org/index.php/Deserialization_of_untrusted_data). diff --git a/docs/documentation/user-guide/task-forms/index.md b/docs/documentation/user-guide/task-forms/index.md index bce6217d..ec76637c 100644 --- a/docs/documentation/user-guide/task-forms/index.md +++ b/docs/documentation/user-guide/task-forms/index.md @@ -90,7 +90,7 @@ Operaton Forms are created as separate files using the Camunda Modeler and can b :::warning[Process variables access] Defining forms does not introduce any permissions on process variables. Users can still submit any variables via APIs for form completion like the -restref page="submit" text="Submit Task Form" tag="Task REST API. + REST API. Forms can be used on top of the task completion API to render form fields and validate submitted values. ::: @@ -309,7 +309,7 @@ A form data can have following attributes: :::warning[Process variables access] Defining form fields does not introduce any permissions on process variables. Users can still submit any variables via APIs for form completion like the -restref page="submit" text="Submit Task Form" tag="Task REST API. + REST API. Form fields can be used on top of the task completion API to render forms and validate submitted values. ::: diff --git a/docs/documentation/webapps/cockpit/batch/monitoring.md b/docs/documentation/webapps/cockpit/batch/monitoring.md index 954a5a2e..34ab27c5 100644 --- a/docs/documentation/webapps/cockpit/batch/monitoring.md +++ b/docs/documentation/webapps/cockpit/batch/monitoring.md @@ -58,6 +58,6 @@ Clicking the button above the details table deletes the batch history. \ No newline at end of file +Clicking the button above the details table deletes the batch history. diff --git a/src/components/RestRef.jsx b/src/components/RestRef.jsx index cf6b9292..57bf7d9f 100644 --- a/src/components/RestRef.jsx +++ b/src/components/RestRef.jsx @@ -1,8 +1,10 @@ import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; -export default function RestRef({ text, section, operation }) { +export default function RestRef({ text, section, tag, operation, page }) { const { siteConfig } = useDocusaurusContext(); const hrefBase = siteConfig.customFields.restApiDocUrl; + const restTag = tag ?? section; + const restOperation = operation ?? page; if (!hrefBase) { // Will fail loudly. @@ -14,26 +16,26 @@ export default function RestRef({ text, section, operation }) { throw new Error('RestRef: "text" is required'); } - if (!section && operation) { + if (!restTag && restOperation) { // Will fail loudly. - throw new Error('RestRef: "section" is required when "operation" is provided'); + throw new Error('RestRef: "tag" or "section" is required when "operation" or "page" is provided'); } - const href = buildHref({ hrefBase, section, operation }); + const href = buildHref({ hrefBase, tag: restTag, operation: restOperation }); return ( - {text} + {text} ); } -function buildHref({hrefBase, section, operation}) { - if (!section) { +function buildHref({ hrefBase, tag, operation }) { + if (!tag) { return hrefBase; } if (!operation) { - return `${hrefBase}/#tag/${section}`; + return `${hrefBase}/#tag/${tag}`; } - return `${hrefBase}/#tag/${section}/operation/${operation}`; + return `${hrefBase}/#tag/${tag}/operation/${operation}`; } From f1b07a14e806ec638e77dc0bb0e5209d41d8e718 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andrei=20B=C4=83ncioiu?= Date: Thu, 18 Jun 2026 21:41:01 +0300 Subject: [PATCH 3/3] Fixes after review. --- .../reference/bpmn20/events/timer-events.md | 2 +- .../user-guide/operaton-bpm-run.md | 4 +-- .../user-guide/process-engine/deployments.md | 2 +- .../process-engine/diagnostics-data.md | 2 +- .../process-engine/external-tasks.md | 4 +-- .../process-engine/history/history-cleanup.md | 2 +- .../history/user-operation-log.md | 6 ++-- .../user-guide/process-engine/incidents.md | 2 +- .../process-engine/process-engine-concepts.md | 10 +++--- .../process-instance-restart.md | 2 +- .../user-guide/process-engine/variables.md | 2 +- docs/documentation/user-guide/security.md | 2 +- .../user-guide/task-forms/index.md | 4 +-- .../webapps/cockpit/batch/monitoring.md | 2 +- docusaurus.config.ts | 3 +- src/components/RestRef.jsx | 34 +++++++++++-------- 16 files changed, 45 insertions(+), 38 deletions(-) diff --git a/docs/documentation/reference/bpmn20/events/timer-events.md b/docs/documentation/reference/bpmn20/events/timer-events.md index 771f8cf0..6bac6054 100644 --- a/docs/documentation/reference/bpmn20/events/timer-events.md +++ b/docs/documentation/reference/bpmn20/events/timer-events.md @@ -130,7 +130,7 @@ To enforce an immediate re-evaluation of a time cycle, follow the steps: 1. Change the expression of the time cycle (e.g., Adjust the Spring bean that resolves the cycle). 1. Update the current timer job due date: * via Java API: javadocref page="org/operaton/bpm/engine/ManagementService.html#setJobDuedate%28java.lang.String,java.util.Date%29" text="ManagementService#setJobDuedate" - * via REST API: page="setJobDuedate" text="Job/operation/setJobDuedate" tag="Job" + * via REST API: * via Cockpit: Navigate to the Job view of the currently running process instance and select "Change due date for this Job" button. After this job is executed, the next jobs will be created with adjusted time cycle. diff --git a/docs/documentation/user-guide/operaton-bpm-run.md b/docs/documentation/user-guide/operaton-bpm-run.md index a9856a57..fd0073fc 100644 --- a/docs/documentation/user-guide/operaton-bpm-run.md +++ b/docs/documentation/user-guide/operaton-bpm-run.md @@ -137,7 +137,7 @@ However, the example application will not be started. Disabling the example application with any of those mechanisms will **NOT** delete any deployments or process instances from Operaton Run once they are created. You have to delete this data manually through the [web apps](../webapps/cockpit/deployment-view.md#delete), the -, or by cleaning the database +, or by cleaning the database [configured in the application properties](#database). ### Choose between default and production configuration @@ -169,7 +169,7 @@ In the unpacked distro, you will find a `resources` folder. All files (including You can reference forms and scripts in the BPMN diagram with `embedded:deployment:/my-form.html`, `operaton-forms:deployment:/myform.form`, or `deployment:/my-script.js`. The deployment requires adding an extra `/` as a prefix to the filename. -Deployments via the are still possible. +Deployments via the are still possible. ## Configure Operaton Run diff --git a/docs/documentation/user-guide/process-engine/deployments.md b/docs/documentation/user-guide/process-engine/deployments.md index cd490944..a0c06085 100644 --- a/docs/documentation/user-guide/process-engine/deployments.md +++ b/docs/documentation/user-guide/process-engine/deployments.md @@ -10,7 +10,7 @@ menu: --- -Before a process (or case, or decision) can be executed by the process engine, it has to be deployed. A deployment is a logical entity that groups multiple resources that are deployed together. Deployments can be made programmatically via Java API or , or declaratively for resources of a [Process Application](../process-applications/index.md). This section covers advanced deployment concepts. +Before a process (or case, or decision) can be executed by the process engine, it has to be deployed. A deployment is a logical entity that groups multiple resources that are deployed together. Deployments can be made programmatically via Java API or , or declaratively for resources of a [Process Application](../process-applications/index.md). This section covers advanced deployment concepts. ## Deployments in a Clustered Scenario diff --git a/docs/documentation/user-guide/process-engine/diagnostics-data.md b/docs/documentation/user-guide/process-engine/diagnostics-data.md index d1b541cf..ed87bd9c 100644 --- a/docs/documentation/user-guide/process-engine/diagnostics-data.md +++ b/docs/documentation/user-guide/process-engine/diagnostics-data.md @@ -32,7 +32,7 @@ String jdkVersion = productInternals.getJdk().getVersion(); ### REST API -You can fetch the collected data via the REST API by calling the endpoint. +You can fetch the collected data via the REST API by calling the endpoint. ## Collected data diff --git a/docs/documentation/user-guide/process-engine/external-tasks.md b/docs/documentation/user-guide/process-engine/external-tasks.md index 60f46615..ffab5698 100644 --- a/docs/documentation/user-guide/process-engine/external-tasks.md +++ b/docs/documentation/user-guide/process-engine/external-tasks.md @@ -89,7 +89,7 @@ Further information on the functionality of error event definitions on external ### REST API -See the for how the API operations can be accessed via HTTP. +See the for how the API operations can be accessed via HTTP. ### Long Polling to Fetch and Lock External Tasks @@ -106,7 +106,7 @@ configurable period of time (timeout). Long polling significantly reduces the number of requests and enables using resources more efficiently on both the server and the client side. -Please also see the . +Please also see the . #### Unique Worker Request By default, multiple workers can use the same `workerId`. In order to ensure `workerId` uniqueness on server-side, the diff --git a/docs/documentation/user-guide/process-engine/history/history-cleanup.md b/docs/documentation/user-guide/process-engine/history/history-cleanup.md index 48e9fb2c..bfd32a28 100644 --- a/docs/documentation/user-guide/process-engine/history/history-cleanup.md +++ b/docs/documentation/user-guide/process-engine/history/history-cleanup.md @@ -174,7 +174,7 @@ Once deployed, TTL can be updated via Java API: processEngine.getRepositoryService().updateProcessDefinitionHistoryTimeToLive(processDefinitionId, 5); ``` -Setting the value to `null` clears the TTL. The same can be done via . +Setting the value to `null` clears the TTL. The same can be done via . For decision and case definitions, TTL can be defined in a similar way. diff --git a/docs/documentation/user-guide/process-engine/history/user-operation-log.md b/docs/documentation/user-guide/process-engine/history/user-operation-log.md index 4d408032..9d95da1a 100644 --- a/docs/documentation/user-guide/process-engine/history/user-operation-log.md +++ b/docs/documentation/user-guide/process-engine/history/user-operation-log.md @@ -19,7 +19,7 @@ If it is desired that operations are logged regardless whether they are performe ## Access the user operation log -The user operation log can be accessed via the Java API. The history service can be used to execute a `UserOperationLogQuery` by calling `historyService.createUserOperationLogQuery().execute()`. The query can be restricted with various filtering options. The query is also . +The user operation log can be accessed via the Java API. The history service can be used to execute a `UserOperationLogQuery` by calling `historyService.createUserOperationLogQuery().execute()`. The query can be restricted with various filtering options. The query is also . ## User operation log entries @@ -68,8 +68,8 @@ historyService.clearAnnotationForOperationLogById(operationId); **Please note:** Annotations are present on all entries that belong to an operation log. -Please also see the REST API reference for and - annotations. +Please also see the REST API reference for and + annotations. ## Glossary of operations logged in the user operation log diff --git a/docs/documentation/user-guide/process-engine/incidents.md b/docs/documentation/user-guide/process-engine/incidents.md index bdfc3680..d06ad11b 100644 --- a/docs/documentation/user-guide/process-engine/incidents.md +++ b/docs/documentation/user-guide/process-engine/incidents.md @@ -52,7 +52,7 @@ Custom incidents must always be related to an existing Execution. An incident of any type, except for **failedJob** and **failedExternalTask**, can be resolved by calling `RuntimeService#resolveIncident`. -Incidents can be and through the REST API as well. +Incidents can be and through the REST API as well. ## (De-)Activate Incidents diff --git a/docs/documentation/user-guide/process-engine/process-engine-concepts.md b/docs/documentation/user-guide/process-engine/process-engine-concepts.md index d03c0129..549d4f0b 100644 --- a/docs/documentation/user-guide/process-engine/process-engine-concepts.md +++ b/docs/documentation/user-guide/process-engine/process-engine-concepts.md @@ -43,7 +43,7 @@ List processDefinitions = repositoryService.createProcessDefi The above query returns all deployed process definitions for the key `invoice` ordered by their `version` property. -You can also . +You can also . ### Keys and Versions @@ -89,7 +89,7 @@ You may optionally pass in a couple of variables: Process variables are available to all tasks in a process instance and are automatically persisted to the database in case the process instance reaches a wait state. -It is also possible to . +It is also possible to . ### Start Process Instances via Tasklist @@ -153,7 +153,7 @@ You can query for all currently running process instances using the `ProcessInst The above query would select all process instances for the `invoice` process where the `creditor` is `Nice Pizza Inc.`. -You can also . +You can also . ### Interact With a Process Instance @@ -207,7 +207,7 @@ runtimeService.createExecutionQuery() The above query returns all executions for a given process instance. -You can also . +You can also . ## Activity Instances @@ -273,7 +273,7 @@ Currently, activity instances can only be retrieved for a process instance: ActivityInstance rootActivityInstance = runtimeService.getActivityInstance(processInstance.getProcessInstanceId()); ``` -You can as well. +You can as well. ### Identity & Uniqueness diff --git a/docs/documentation/user-guide/process-engine/process-instance-restart.md b/docs/documentation/user-guide/process-engine/process-instance-restart.md index afeac57a..7cf82e6b 100644 --- a/docs/documentation/user-guide/process-engine/process-instance-restart.md +++ b/docs/documentation/user-guide/process-engine/process-instance-restart.md @@ -18,7 +18,7 @@ This can, for example, be useful when termination did not proceed in a desired w To perform such an operation, the process engine offers *the process instance restart API*, which is entered via `RuntimeService.restartProcessInstances(...)`. This API allows you to specify multiple instantiation instructions in one call by using a fluent builder. -Note that these operations are also available via REST: and . +Note that these operations are also available via REST: and . ## Process Instance Restart by Example diff --git a/docs/documentation/user-guide/process-engine/variables.md b/docs/documentation/user-guide/process-engine/variables.md index 11496196..d5736662 100644 --- a/docs/documentation/user-guide/process-engine/variables.md +++ b/docs/documentation/user-guide/process-engine/variables.md @@ -343,7 +343,7 @@ TypedValue typedTransientFileValue = Variables.fileValue("file.txt", true) .create(); ``` -Transient variables can be used via REST API, e.g. . +Transient variables can be used via REST API, e.g. . ### Set Multiple Typed Values diff --git a/docs/documentation/user-guide/security.md b/docs/documentation/user-guide/security.md index 9dd3d8b9..b4788b0b 100644 --- a/docs/documentation/user-guide/security.md +++ b/docs/documentation/user-guide/security.md @@ -285,7 +285,7 @@ about the several headers, the defaults and how to configure the HTTP headers ac ### Variable Values from Untrusted Sources Process variables can be submitted as Java objects using the JDK built-in `application/x-java-serialized-object` data format, JSON or XML along with a Java class name via the Operaton REST API and web applications. -On server side, they can then be deserialized into Java objects, so that Java code can work with them in a native way. See [Operaton Spin](../user-guide/data-formats/configuring-spin-integration.md) for details and this for an example. +On server side, they can then be deserialized into Java objects, so that Java code can work with them in a native way. See [Operaton Spin](../user-guide/data-formats/configuring-spin-integration.md) for details and this for an example. If an attacker can access these endpoints, they can exploit so-called _serialization gadgets_, i.e. classes that run vulnerable code during deserialization resulting in remote code execution in the general case. For example, consider a class constructor that makes a REST request based on a field value. An attacker could submit a forged variable value so that during deserialization, when the constructor is called, the application server would make an arbitrary REST request to a destination of the attacker's choice. For details, see [OWASP's description of Deserialization of untrusted data](https://www.owasp.org/index.php/Deserialization_of_untrusted_data). diff --git a/docs/documentation/user-guide/task-forms/index.md b/docs/documentation/user-guide/task-forms/index.md index dc8b77ab..f0591b9b 100644 --- a/docs/documentation/user-guide/task-forms/index.md +++ b/docs/documentation/user-guide/task-forms/index.md @@ -90,7 +90,7 @@ Operaton Forms are created as separate files using the Camunda Modeler and can b :::warning[Process variables access] Defining forms does not introduce any permissions on process variables. Users can still submit any variables via APIs for form completion like the - REST API. + REST API. Forms can be used on top of the task completion API to render form fields and validate submitted values. ::: @@ -309,7 +309,7 @@ A form data can have following attributes: :::warning[Process variables access] Defining form fields does not introduce any permissions on process variables. Users can still submit any variables via APIs for form completion like the - REST API. + REST API. Form fields can be used on top of the task completion API to render forms and validate submitted values. ::: diff --git a/docs/documentation/webapps/cockpit/batch/monitoring.md b/docs/documentation/webapps/cockpit/batch/monitoring.md index 34ab27c5..c7796e51 100644 --- a/docs/documentation/webapps/cockpit/batch/monitoring.md +++ b/docs/documentation/webapps/cockpit/batch/monitoring.md @@ -58,6 +58,6 @@ Clicking the button above the details table deletes the batch history. diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 9f8f05bb..a8f83aca 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -39,7 +39,8 @@ const config: Config = { customFields: { javaDocUrl: '/reference/latest/javadoc', - restApiDocUrl: 'https://docs.operaton.org/reference/latest/rest-api' + restApiDocSiteUrl: '', + restApiDocBasePath: '/reference/latest/rest-api' }, // Even if you don't use internationalization, you can use this field to set // useful metadata like html lang. For example, if your site is Chinese, you diff --git a/src/components/RestRef.jsx b/src/components/RestRef.jsx index 57bf7d9f..2ac42c48 100644 --- a/src/components/RestRef.jsx +++ b/src/components/RestRef.jsx @@ -1,34 +1,32 @@ import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; -export default function RestRef({ text, section, tag, operation, page }) { +export default function RestRef({ text, tag, operation }) { const { siteConfig } = useDocusaurusContext(); - const hrefBase = siteConfig.customFields.restApiDocUrl; - const restTag = tag ?? section; - const restOperation = operation ?? page; - - if (!hrefBase) { - // Will fail loudly. - throw new Error('RestRef: "restApiDocUrl" is missing from customFields in "docusaurus.config.js"'); - } + const restApiDocSiteUrl = siteConfig.customFields.restApiDocSiteUrl || ""; + const restApiDocBasePath = siteConfig.customFields.restApiDocBasePath || "/"; if (!text) { // Will fail loudly. throw new Error('RestRef: "text" is required'); } - if (!restTag && restOperation) { + if (!tag && operation) { // Will fail loudly. - throw new Error('RestRef: "tag" or "section" is required when "operation" or "page" is provided'); + throw new Error('RestRef: "tag" is required when "operation" is provided'); } - const href = buildHref({ hrefBase, tag: restTag, operation: restOperation }); - + const href = buildHref({ restApiDocSiteUrl, restApiDocBasePath, tag, operation }); + return ( {text} ); } -function buildHref({ hrefBase, tag, operation }) { +function buildHref({ restApiDocSiteUrl, restApiDocBasePath, tag, operation }) { + const siteUrl = stripTrailingSlashes(restApiDocSiteUrl); + const basePath = stripLeadingSlashes(restApiDocBasePath); + const hrefBase = stripTrailingSlashes(`${siteUrl}/${basePath}`); + if (!tag) { return hrefBase; } @@ -39,3 +37,11 @@ function buildHref({ hrefBase, tag, operation }) { return `${hrefBase}/#tag/${tag}/operation/${operation}`; } + +function stripTrailingSlashes(input) { + return input.replace(/\/+$/, ""); +} + +function stripLeadingSlashes(input) { + return input.replace(/^\/+/, ""); +}