Define (and use) custom component "RestRef"

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: <RestRef operation="setJobDuedate" text="Job/operation/setJobDuedate" tag="Job" />
   * 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.

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 <a target="_blank" href={siteConfig.customFields.restApiDocUrl}>here</a>
-}
-
-You can find the RestApi Specification <RestApiDocLink/>.
+You can find the REST API specification <RestRef text="here" />.

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
+<RestRef operation="deleteDeployment" text="REST API" tag="Deployment" />, 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 <RestRef operation="createDeployment" text="REST API" tag="Deployment" /> are still possible.
 
 ## Configure Operaton Run
 

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 <RestRef operation="createDeployment" text="REST API" tag="Deployment" />, or declaratively for resources of a [Process Application](../process-applications/index.md). This section covers advanced deployment concepts.
 
 ## Deployments in a Clustered Scenario
 

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 <RestRef operation="getTelemetryData" text="Get Telemetry Data" tag="Telemetry" /> endpoint.
 
 ## Collected data
 

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 <RestRef text="REST API documentation" tag="External-Task" /> 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 <RestRef operation="fetchAndLock" text="REST API documentation" tag="External-Task" />.
 
 #### Unique Worker Request
 By default, multiple workers can use the same `workerId`. In order to ensure `workerId` uniqueness on server-side, the

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 <RestRef operation="updateHistoryTimeToLiveByProcessDefinitionKeyAndTenantId" text="REST API" tag="Process-Definition" />.
 
 For decision and case definitions, TTL can be defined in a similar way.
 

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 <RestRef operation="queryUserOperationEntries" text="exposed in the REST API" tag="Historic-User-Operation-Log" />.
 
 
 ## 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 <RestRef operation="setAnnotationUserOperationLog" text="setting" tag="Historic-User-Operation-Log" /> and
+<RestRef operation="clearAnnotationUserOperationLog" text="clearing" tag="Historic-User-Operation-Log" /> annotations.
 
 ## Glossary of operations logged in the user operation log
 

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 <RestRef operation="createIncident" text="created" tag="Execution" /> and <RestRef operation="resolveIncident" text="resolved" tag="Incident" /> 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
-<a class="javadocref" href="https://docs.operaton.org/reference/latest/javadoc/org/operaton/bpm/engine/impl/incident/CompositeIncidentHandler.html">Composite Incident Handler</a>.
+<a class="javadocref" href="https://docs.operaton.org/reference/latest/javadoc/org/operaton/bpm/engine/impl/incident/CompositeIncidentHandler.html">Composite Incident Handler</a>.

docs/documentation/user-guide/process-engine/process-engine-concepts.md

@@ -43,7 +43,7 @@ List<ProcessDefinition> 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 <RestRef operation="getProcessDefinitions" text="query for process definitions using the REST API" tag="Process-Definition" />.
 
 
 ### 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 <RestRef operation="startProcessInstance" text="start a process instance using the REST API" tag="Process-Definition" />.
 
 ### 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 <RestRef operation="getProcessInstances" text="query for process instances using the REST API" tag="Process-Instance" />.
 
 
 ### 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 <RestRef operation="getExecutions" text="query for executions using the REST API" tag="Execution" />.
 
 
 ## 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 <RestRef operation="getActivityInstanceTree" text="retrieve the activity instance tree using the REST API" tag="Process-Instance" /> as well.
 
 
 ### Identity & Uniqueness

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 <RestRef text="REST" tag="Migration" />.
 
 ### Creating a Migration Plan
 

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: <RestRef operation="restartProcessInstance" text="Restart Process Instance" tag="Process-Definition" /> and <RestRef operation="restartProcessInstanceAsyncOperation" text="Restart Process Instance (async)" tag="Process-Definition" />.
 
 ## Process Instance Restart by Example
 

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. <RestRef operation="startProcessInstance" text="when starting a new process instance" tag="Process-Definition" />.
 
 ### Set Multiple Typed Values
 

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 <RestRef operation="putLocalExecutionVariable" text="REST API endpoint" tag="Execution" /> 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).
 

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.
+<RestRef operation="submit" text="Submit Task Form" tag="Task" /> 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.
+<RestRef operation="submit" text="Submit Task Form" tag="Task" /> REST API.
 Form fields can be used on top of the task completion API to render forms and validate submitted values.
 :::
 

docs/documentation/webapps/cockpit/batch/monitoring.md

@@ -58,6 +58,6 @@ Clicking the <button class="btn btn-xs btn-danger"><i class="glyphicon glyphicon
 
 ### Completed Batch Details
 
-The displayed information corresponds to the response of the restref page="getBatch" text="REST API query" tag="Batch.
+The displayed information corresponds to the response of the <RestRef operation="getBatch" text="REST API query" tag="Batch" />.
 
-Clicking the <button class="btn btn-xs btn-danger"><i class="glyphicon glyphicon-trash"></i></button> button above the details table deletes the batch history.
+Clicking the <button class="btn btn-xs btn-danger"><i class="glyphicon glyphicon-trash"></i></button> button above the details table deletes the batch history.

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

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 (
+    <a target="_blank" rel="noreferrer" href={href}>{text}</a>
+  );
+}
+
+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(/^\/+/, "");
+}

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,
 };