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/reference/rest/specification.md b/docs/documentation/reference/rest/specification.md index 19b1d874..2654f1f7 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 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..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 -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..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 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 93094d8b..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 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 58f894fd..ffab5698 100644 --- a/docs/documentation/user-guide/process-engine/external-tasks.md +++ b/docs/documentation/user-guide/process-engine/external-tasks.md @@ -87,9 +87,9 @@ 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 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/docs/documentation/user-guide/process-engine/history/history-cleanup.md b/docs/documentation/user-guide/process-engine/history/history-cleanup.md index 4db4a04a..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 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. 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..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 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..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 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 5d3f6768..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 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 fc3d80cc..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: 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 diff --git a/docs/documentation/user-guide/process-engine/variables.md b/docs/documentation/user-guide/process-engine/variables.md index 157fac6d..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. 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..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 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 b1c60b57..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 -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..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. \ No newline at end of file +Clicking the button above the details table deletes the batch history. diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 2c782fec..a8f83aca 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -39,7 +39,8 @@ const config: Config = { customFields: { javaDocUrl: '/reference/latest/javadoc', - restApiDocUrl: '/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 new file mode 100644 index 00000000..2ac42c48 --- /dev/null +++ b/src/components/RestRef.jsx @@ -0,0 +1,47 @@ +import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; + +export default function RestRef({ text, tag, operation }) { + const { siteConfig } = useDocusaurusContext(); + const restApiDocSiteUrl = siteConfig.customFields.restApiDocSiteUrl || ""; + const restApiDocBasePath = siteConfig.customFields.restApiDocBasePath || "/"; + + if (!text) { + // Will fail loudly. + throw new Error('RestRef: "text" is required'); + } + + if (!tag && operation) { + // Will fail loudly. + throw new Error('RestRef: "tag" is required when "operation" is provided'); + } + + const href = buildHref({ restApiDocSiteUrl, restApiDocBasePath, tag, operation }); + + return ( + {text} + ); +} + +function buildHref({ restApiDocSiteUrl, restApiDocBasePath, tag, operation }) { + const siteUrl = stripTrailingSlashes(restApiDocSiteUrl); + const basePath = stripLeadingSlashes(restApiDocBasePath); + const hrefBase = stripTrailingSlashes(`${siteUrl}/${basePath}`); + + if (!tag) { + return hrefBase; + } + + if (!operation) { + return `${hrefBase}/#tag/${tag}`; + } + + return `${hrefBase}/#tag/${tag}/operation/${operation}`; +} + +function stripTrailingSlashes(input) { + return input.replace(/\/+$/, ""); +} + +function stripLeadingSlashes(input) { + return input.replace(/^\/+/, ""); +} 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, };