Merge branch 'main' into none-start-event-templates-deprecation-notice

api/camunda/generation-strategy.js

@@ -2,47 +2,214 @@ const removeDuplicateVersionBadge = require("../remove-duplicate-version-badge")
 const replace = require("replace-in-file");
 const outputDir = "docs/apis-tools/camunda-api-rest/specifications";
 const specFile = "api/camunda/camunda-openapi.yaml";
+const fs = require("fs");
 
 function preGenerateDocs() {
- hackChangesetDescription();
+ const originalSpec = fs.readFileSync(specFile, "utf8");
+
+ console.log("adjusting C8 spec file...");
+
+ const specUpdates = [
+ addDisclaimer(),
+ ...redefineCreateProcessInstanceRequest(originalSpec),
+ ...redefineEvaluateDecisionRequest(originalSpec),
+ ];
+
+ replace.sync({
+ files: specFile,
+ from: specUpdates.map((x) => x.from),
+ to: specUpdates.map((x) => x.to),
+ });
 }
 
 function postGenerateDocs() {
  removeDuplicateVersionBadge(`${outputDir}/camunda-8-rest-api.info.mdx`);
 }
 
-module.exports = {
- outputDir,
- preGenerateDocs,
- postGenerateDocs,
-};
+function addDisclaimer() {
+ // Adds a disclaimer to the very beginning of the file, so that people know this isn't the true spec.
+ return {
+  from: /^/,
+ to: `# Disclaimer: This is a modified version of the Camunda REST API specification, optimized for the documentation.
 
-function hackChangesetDescription() {
- // This is a temporary hack, until https://github.com/camunda/camunda-docs/issues/3568 is resolved.
- // The OpenAPI generator plugin we're using does not use the correct `description` property
- // for the `UserTaskUpdateRequest` object. Instead of picking up the actual property description,
- // it picks up the description of the first merged schema in the `allOf` property (i.e. from the `Changeset` schema).
- // This adjustment replaces the description of the `Changeset` schema with the current description of
- // the `UserTaskUpdateRequest.changeset` property.
- console.log("hacking changeset description...");
- replace.sync({
- files: `${specFile}`,
- from: /^ description: A map of changes.$/m,
- to: ` description: |
- JSON object with changed task attribute values.
+`,
+ };
+}
 
- The following attributes can be adjusted with this endpoint, additional attributes
- will be ignored:
+function redefineCreateProcessInstanceRequest(originalSpec) {
+ // Redefines the CreateProcessInstanceRequest schema to describe a union of two possible request bodies.
+ // This union type does not work upstream, but we can rewrite it here to more clearly describe the schema.
 
- * \`candidateGroups\` - reset by providing an empty list
- * \`candidateUsers\` - reset by providing an empty list
- * \`dueDate\` - reset by providing an empty String
- * \`followUpDate\` - reset by providing an empty String
+ if (originalSpec.includes("CreateProcessInstanceRequestBase")) {
+ // Make this a repeatable task by checking if it's run already.
+ console.log("skipping redefineCreateProcessInstanceRequest...");
+ return [];
+ }
 
- Providing any of those attributes with a \`null\` value or omitting it preserves
- the persisted attribute's value.
+ // Diff created by these changes:
+ // CreateProcessInstanceRequest:
+ // type: object
+ //+ oneOf:
+ //+ - $ref: "#/components/schemas/CreateProcessInstanceRequestByKey"
+ //+ - $ref: "#/components/schemas/CreateProcessInstanceRequestById"
+ //+ CreateProcessInstanceRequestByKey:
+ //+ type: object
+ //+ allOf:
+ //+ - $ref: "#/components/schemas/CreateProcessInstanceRequestBase"
+ // properties:
+ // processDefinitionKey:
+ // ...
+ //+ CreateProcessInstanceRequestById:
+ //+ type: object
+ //+ allOf:
+ //+ - $ref: "#/components/schemas/CreateProcessInstanceRequestBase"
+ //+ properties:
+ // processDefinitionId:
+ // ...
+ // processDefinitionVersion:
+ // ...
+ //+ CreateProcessInstanceRequestBase:
+ //+ type: object
+ //+ properties:
+ // variables:
+ // ...
+ // tenantId:
+ // ...
+ // ...
 
- The assignee cannot be adjusted with this endpoint, use the Assign task endpoint.
- This ensures correct event emission for assignee changes.`,
- });
+ return [
+ // 1. Convert the main request to a oneOf union and define the first possible type.
+ {
+ // match the start of the CreateProcessInstanceRequest object
+ from: / CreateProcessInstanceRequest:\n type: object/m,
+
+ // append the `oneOf` declaration to define the union type.
+ // Then a definition for the first possible type, so that it includes the `processDefinitionKey` property.
+ to: ` CreateProcessInstanceRequest:
+ type: object
+ oneOf:
+ - $ref: "#/components/schemas/CreateProcessInstanceRequestByKey"
+ - $ref: "#/components/schemas/CreateProcessInstanceRequestById"
+ CreateProcessInstanceRequestByKey:
+ type: object
+ allOf:
+ - $ref: "#/components/schemas/CreateProcessInstanceRequestBase"`,
+ },
+
+ // 2. Define the second possible type, to include the `processDefinitionId` property.
+ {
+ // match the start of the CreateProcessInstanceRequestByKey object, up until the `processDefinitionId` property (non-inclusive).
+ from: / CreateProcessInstanceRequestByKey:[\s\S]*?(?=\s*processDefinitionId:)/m,
+
+ // append the second possible type definition, so that it includes the `processDefinitionId`.
+ to: `$&
+ CreateProcessInstanceRequestById:
+ type: object
+ allOf:
+ - $ref: "#/components/schemas/CreateProcessInstanceRequestBase"
+ properties:`,
+ },
+
+ // 3. Define a base type to contain the common properties, starting before the `variables` property.
+ {
+ // match the start of the CreateProcessInstanceRequestById object, up until the `variables` property (non-inclusive).
+ from: / CreateProcessInstanceRequestById:[\s\S]*?(?=\s*variables:)/m,
+ // append the base type definition, so that it includes all remaining properties.
+ to: `$&
+ CreateProcessInstanceRequestBase:
+ type: object
+ properties:`,
+ },
+ ];
+}
+
+function redefineEvaluateDecisionRequest(originalSpec) {
+ // Redefines the EvaluateDecisionRequest schema to describe a union of two possible request bodies.
+ // This union type does not work upstream, but we can rewrite it here to more clearly describe the schema.
+
+ if (originalSpec.includes("EvaluateDecisionRequestBase")) {
+ // Make this a repeatable task by checking if it's run already.
+ console.log("skipping redefineEvaluateDecisionRequest...");
+ return [];
+ }
+
+ // Diff created by these changes:
+ // EvaluateDecisionRequest:
+ // type: object
+ //+ oneOf:
+ //+ - $ref: "#/components/schemas/EvaluateDecisionRequestByKey"
+ //+ - $ref: "#/components/schemas/EvaluateDecisionRequestById"
+ //+ EvaluateDecisionRequestByKey:
+ //+ type: object
+ //+ allOf:
+ //+ - $ref: "#/components/schemas/EvaluateDecisionRequestBase"
+ // properties:
+ // decisionDefinitionKey:
+ // ...
+ //+ EvaluateDecisionRequestById:
+ //+ type: object
+ //+ allOf:
+ //+ - $ref: "#/components/schemas/EvaluateDecisionRequestBase"
+ //+ properties:
+ // decisionDefinitionId:
+ // ...
+ //+ EvaluateDecisionRequestBase:
+ //+ type: object
+ //+ properties:
+ // variables:
+ // ...
+ // tenantId:
+ // ...
+ // ...
+
+ return [
+ // 1. Convert the main request to a oneOf union and define the first possible type.
+ {
+ // match the start of the EvaluateDecisionRequest object
+ from: / EvaluateDecisionRequest:\n type: object/m,
+
+ // append the `oneOf` declaration to define the union type.
+ // Then a definition for the first possible type, so that it includes the `decisionDefinitionKey` property.
+ to: ` EvaluateDecisionRequest:
+ type: object
+ oneOf:
+ - $ref: "#/components/schemas/EvaluateDecisionRequestByKey"
+ - $ref: "#/components/schemas/EvaluateDecisionRequestById"
+ EvaluateDecisionRequestByKey:
+ type: object
+ allOf:
+ - $ref: "#/components/schemas/EvaluateDecisionRequestBase"`,
+ },
+
+ // 2. Define the second possible type, to include the `decisionDefinitionId` property.
+ {
+ // match the start of the EvaluateDecisionRequestByKey object, up until the `decisionDefinitionId` property (non-inclusive).
+ from: / EvaluateDecisionRequestByKey:[\s\S]*?(?=\s*decisionDefinitionId:)/m,
+
+ // append the second possible type definition, so that it includes the `decisionDefinitionId`.
+ to: `$&
+ EvaluateDecisionRequestById:
+ type: object
+ allOf:
+ - $ref: "#/components/schemas/EvaluateDecisionRequestBase"
+ properties:`,
+ },
+
+ // 3. Define a base type to contain the common properties, starting before the `variables` property.
+ {
+ // match the start of the CreateProcessInstanceRequestById object, up until the `variables` property (non-inclusive).
+ from: / EvaluateDecisionRequestById:[\s\S]*?(?=\s*variables:)/m,
+ // append the base type definition, so that it includes all remaining properties.
+ to: `$&
+ EvaluateDecisionRequestBase:
+ type: object
+ properties:`,
+ },
+ ];
 }
+
+module.exports = {
+ outputDir,
+ preGenerateDocs,
+ postGenerateDocs,
+};

api/zeebe/generation-strategy.js

@@ -1,3 +1,4 @@
+const replace = require("replace-in-file");
 const removeDuplicateVersionBadge = require("../remove-duplicate-version-badge");
 
 const outputDir = "docs/apis-tools/zeebe-api-rest/specifications";

docs/apis-tools/administration-api/authentication.md

@@ -8,11 +8,11 @@ description: "Learn about access tokens and client credentials and scopes to get
 
 All Administration API requests require authentication. To authenticate, generate a [JSON Web Token (JWT)](https://jwt.io/introduction/) and include it in each request.
 
-## Generating a token
+## Generate a token
 
 1. Create client credentials by clicking **Console > Organization > Administration API > Create new credentials**.
 2. Add permissions to this client for [the needed scopes](#client-credentials-and-scopes).
-3. Upon creating the client, capture the following values required to generate a token:
+3. Once you have created the client, capture the following values required to generate a token:
  <!-- this comment convinces the markdown processor to still treat the table as a table, but without adding surrounding paragraphs. 🤷 -->
  | Name | Environment variable name | Default value |
  | ------------------------ | -------------------------------- | -------------------------------------------- |
@@ -21,7 +21,7 @@ All Administration API requests require authentication. To authenticate, generat
  | Authorization Server URL | `CAMUNDA_OAUTH_URL` | `https://login.cloud.camunda.io/oauth/token` |
  | Audience | `CAMUNDA_CONSOLE_OAUTH_AUDIENCE` | `api.cloud.camunda.io` |
  <!-- this comment convinces the markdown processor to still treat the table as a table, but without adding surrounding paragraphs. 🤷 -->
- :::tip
+ :::caution
  When client credentials are created, the `Client Secret` is only shown once. Save this `Client Secret` somewhere safe.
  :::
 4. Execute an authentication request to the token issuer:
@@ -33,7 +33,7 @@ All Administration API requests require authentication. To authenticate, generat
  --data-urlencode "client_id=${CAMUNDA_CONSOLE_CLIENT_ID}" \
  --data-urlencode "client_secret=${CAMUNDA_CONSOLE_CLIENT_SECRET}"
  ```
-5. A successful authentication response looks like the following:
+  A successful authentication response looks like the following:
  ```json
  {
  "access_token": "<TOKEN>",
@@ -43,9 +43,9 @@ All Administration API requests require authentication. To authenticate, generat
  "not-before-policy": 0
  }
  ```
-6. Capture the value of the `access_token` property and store it as your token.
+5. Capture the value of the `access_token` property and store it as your token.
 
-## Using a token
+## Use a token
 
 Include the previously captured token as an authorization header in each request: `Authorization: Bearer <TOKEN>`.
 

docs/apis-tools/administration-sm-api/administration-sm-api-authentication.md

@@ -7,7 +7,7 @@ description: "The Administration API for Self-Managed is a REST API and provides
 
 All Administration Self-Managed API requests require authentication. To authenticate, generate a [JSON Web Token (JWT)](https://jwt.io/introduction/) and include it in each request.
 
-## Generating a token
+## Generate a token
 
 1. [Add an M2M application in Identity](/self-managed/identity/user-guide/additional-features/incorporate-applications.md).
 2. [Add permissions to this application](/self-managed/identity/user-guide/additional-features/incorporate-applications.md) for **Administration Self-Managed API**.
@@ -20,7 +20,7 @@ All Administration Self-Managed API requests require authentication. To authenti
  --data-urlencode "client_secret=${CLIENT_SECRET}" \
  --data-urlencode 'grant_type=client_credentials'
  ```
-5. A successful authentication response looks like the following:
+  A successful authentication response looks like the following:
  ```json
  {
  "access_token": "<TOKEN>",
@@ -30,13 +30,13 @@ All Administration Self-Managed API requests require authentication. To authenti
  "not-before-policy": 0
  }
  ```
-6. Capture the value of the `access_token` property and store it as your token.
+5. Capture the value of the `access_token` property and store it as your token.
 
-## Using a token
+## Use a token
 
 Include the previously captured token as an authorization header in each request: `Authorization: Bearer <TOKEN>`.
 
-For example, to send a request to the ["Get current clusters" endpoint](./specifications/get-clusters.api.mdx):
+For example, to send a request to the ["Get current clusters"](./specifications/get-clusters.api.mdx) endpoint:
 
 :::tip
 The `${CAMUNDA_BASE_URL}` variable below represents the URL of the Self-Managed environment. You can configure this value in your Self-Managed installation. The default value is `http://localhost:8080`.

docs/apis-tools/camunda-api-rest/camunda-api-rest-authentication.md

@@ -9,7 +9,7 @@ import TabItem from "@theme/TabItem";
 
 All Camunda 8 REST API requests require authentication. To authenticate, generate a [JSON Web Token (JWT)](https://jwt.io/introduction/) depending on your environment and include it in each request.
 
-## Generating a token
+## Generate a token
 
 <Tabs groupId="environment" defaultValue="saas" queryString values={
 [
@@ -21,7 +21,7 @@ All Camunda 8 REST API requests require authentication. To authenticate, generat
 
 1. [Create client credentials](/guides/setup-client-connection-credentials.md) in the **Clusters > Cluster name > API** tab of [Camunda Console](https://console.camunda.io/).
 2. Add permissions to this client for **Zeebe**.
-3. Upon creating the client, capture the following values required to generate a token:
+3. Once you have created the client, capture the following values required to generate a token:
  <!-- this comment convinces the markdown processor to still treat the table as a table, but without adding surrounding paragraphs. 🤷 -->
  | Name | Environment variable name | Default value |
  | ------------------------ | -------------------------------- | -------------------------------------------- |
@@ -31,7 +31,7 @@ All Camunda 8 REST API requests require authentication. To authenticate, generat
  | Audience | `ZEEBE_TOKEN_AUDIENCE` | `zeebe.camunda.io` |
  | Zeebe REST Address | `ZEEBE_REST_ADDRESS` | - |
  <!-- this comment convinces the markdown processor to still treat the table as a table, but without adding surrounding paragraphs. 🤷 -->
- :::tip
+ :::caution
  When client credentials are created, the `Client Secret` is only shown once. Save this `Client Secret` somewhere safe.
  :::
 4. Execute an authentication request to the token issuer:
@@ -43,7 +43,7 @@ All Camunda 8 REST API requests require authentication. To authenticate, generat
  --data-urlencode "client_id=${ZEEBE_CLIENT_ID}" \
  --data-urlencode "client_secret=${ZEEBE_CLIENT_SECRET}"
  ```
-5. A successful authentication response looks like the following:
+  A successful authentication response looks like the following:
  ```json
  {
  "access_token": "<TOKEN>",
@@ -53,7 +53,7 @@ All Camunda 8 REST API requests require authentication. To authenticate, generat
  "not-before-policy": 0
  }
  ```
-6. Capture the value of the `access_token` property and store it as your token.
+5. Capture the value of the `access_token` property and store it as your token.
 
 </TabItem>
 
@@ -70,7 +70,7 @@ All Camunda 8 REST API requests require authentication. To authenticate, generat
  --data-urlencode "client_secret=${CLIENT_SECRET}" \
  --data-urlencode 'grant_type=client_credentials'
  ```
-5. A successful authentication response looks like the following:
+  A successful authentication response looks like the following:
  ```json
  {
  "access_token": "<TOKEN>",
@@ -80,13 +80,13 @@ All Camunda 8 REST API requests require authentication. To authenticate, generat
  "not-before-policy": 0
  }
  ```
-6. Capture the value of the `access_token` property and store it as your token.
+5. Capture the value of the `access_token` property and store it as your token.
 
 </TabItem>
 
 </Tabs>
 
-## Using a token
+## Use a token
 
 Include the previously captured token as an authorization header in each request: `Authorization: Bearer <TOKEN>`.