Merge branch 'main' into release-notes-860-alpha5

camunda · Sep 3, 2024 · 8efc900 · 8efc900
2 parents 440b5d6 + 4ede447
commit 8efc900
Show file tree

Hide file tree

Showing 103 changed files with 1,679 additions and 1,723 deletions.
diff --git a/.github/workflows/sync-rest-api-docs.yaml b/.github/workflows/sync-rest-api-docs.yaml
@@ -0,0 +1,66 @@
+name: Sync Camunda REST API
+
+on:
+  schedule:
+    - cron: "0 15 * * 4" # Runs every Thursday at 3 PM UTC
+  workflow_dispatch:
+
+jobs:
+  sync-file:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Camunda docs repository
+        uses: actions/checkout@v3
+        with:
+          repository: camunda/camunda-docs
+          path: docs
+
+      - name: Checkout Camunda repository
+        uses: actions/checkout@v3
+        with:
+          repository: camunda/camunda
+          path: rest-spec
+          sparse-checkout: zeebe/gateway-protocol/src/main/proto/rest-api.yaml
+          sparse-checkout-cone-mode: false
+
+      - name: Sync documentation
+        run: |
+          cd docs
+          mv ../rest-spec/zeebe/gateway-protocol/src/main/proto/rest-api.yaml api/camunda/camunda-openapi.yaml
+          npm i
+          npm run api:generate:camunda
+          if git diff-index --quiet HEAD; then
+            echo "No changes to commit."
+            exit 0
+          fi
+
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v5
+        with:
+          token: "${{ secrets.GITHUB_TOKEN }}"
+          path: docs
+          title: Update camunda REST API doc
+          body: |
+            ## Description
+
+            This is an autogenerated PR by the [sync api specs workflow](https://github.com/camunda/camunda-docs/tree/main/.github/workflows/sync-rest-api-docs.yaml).
+            This PR contains every changes made to the REST api specs in the [monorepo](https://github.com/camunda/camunda/blob/main/zeebe/gateway-protocol/src/main/proto/rest-api.yaml) in the last week.
+            This PR contains also all the generated OpenAPI files related to the changes.
+
+            ## When should this change go live?
+
+            - There is **no urgency** with this change and can be released at any time.
+
+            ## PR Checklist
+
+            - My changes are for the **next minor** and are in `/docs` directory (aka `/next/`).
+            - My changes require a [technical writer review](https://github.com/camunda/camunda-docs/blob/main/howtos/documentation-guidelines.md#review-process), and I've assigned @camunda/tech-writers as a reviewer.
+
+          commit-message: "docs: update REST API spec"
+          branch: update-rest-doc
+          delete-branch: true
+          team-reviewers: camunda/tech-writers
+          reviewers: pepopowitz
+          base: main
+          labels: deploy
diff --git a/.husky/pre-commit b/.husky/pre-commit
@@ -1,7 +1,4 @@
 #!/bin/sh
 . "$(dirname "$0")/_/husky.sh"
 
-export NVM_DIR="$HOME/.nvm"
-[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
-
 npx lint-staged
diff --git a/docs/components/components-overview.md b/docs/components/components-overview.md
@@ -9,20 +9,7 @@ keywords: ["process automation tools"]
 
 This section contains product manual content for each component in Camunda 8, including conceptual content. Together, these components comprise the Camunda 8 SaaS experience.
 
-- [Concepts](concepts/what-is-camunda-8.md) - Learn more about a variety of Camunda 8 topics with this conceptual documentation on clusters, processes, job workers, workflow patterns, and more.
-- [Console](console/introduction-to-console.md) - With this management application for the included products, create and delete clusters, manage API clients and alerts, and more.
-- [Modeler](modeler/about-modeler.md) - Design and implement diagrams using Camunda's modeling tools, including Web Modeler and Desktop Modeler.
-- [Connectors](connectors/introduction.md) - Integrate with external systems using these reusable building blocks.
-- [Zeebe](zeebe/zeebe-overview.md) - Define processes graphically in BPMN 2.0, choose any gRPC-supported programming language to implement your workers, build processes that react to events from Apache Kafka, and more using this process automation engine powering Camunda 8.
-- [Operate](operate/operate-introduction.md) - Monitor and troubleshoot process instances running in Zeebe, and carry out key operations such as resolving incidents and updating process instance variables with Operate.
-- [Tasklist](tasklist/introduction-to-tasklist.md) - Implement business processes alongside user tasks in Zeebe, and orchestrate human workflows critical to your business to reduce time-to-value for your process orchestration projects with this interface for manual work.
-- [Optimize]($optimize$/components/what-is-optimize) - Geared toward business stakeholders, Optimize offers business intelligence tooling for Camunda enterprise customers. By leveraging data collected during process execution, users can collaboratively examine areas in business processes for improvement.
-
-:::note
-Additionally, Camunda hosts a section of [Best Practices](./best-practices/best-practices-overview.md). A mix of conceptual and practical implementation information, this section hosts our condensed experience using BPMN and DMN on the Camunda tool stack collected by consulting engagement with our customers and feedback from the community.
-:::
-
-![Architecture diagram for Camunda including all the components for SaaS](./img/ComponentsAndArchitecture_SaaS.png)
+See our [introduction to Camunda](/guides/introduction-to-camunda-8.md) if you are new to Camunda, or visiting the Camunda documentation for the first time.
 
 :::note Looking for deployment guides?
 

diff --git a/docs/components/connectors/manage-connector-templates.md b/docs/components/connectors/manage-connector-templates.md
@@ -39,28 +39,24 @@ After finalizing your Connector, click **Publish** to activate it within the pro
 
 ![Publishing a template](img/connector-templates/create-connector-template-3.png)
 
-As [organization owner or admin](/components/console/manage-organization/manage-users.md#users), you can publish a Connector template version within the organization context, enabling all organization members to use it in their diagrams.
+As a [user with elevated access](/components/modeler/web-modeler/collaboration.md#elevated-access), you can publish a Connector template version within the organization context, enabling all organization members to use it in their diagrams.
 To do so, click **Publish > Publish to organization** on the editor screen or promote a template version via the [milestone history](#versioning-connector-templates).
 
 ![Promoting a template](img/connector-templates/create-connector-template-4.png)
 
-:::info
-Publish to organization is available for Camunda 8 SaaS only.
-:::
-
 ### Manage published Connector templates
 
 After publishing, a Connector template version can be applied across all models within the same project or organization, depending on its publication status. You can review the publication status of template versions in the [milestone history](#versioning-connector-templates).
 
 On the Web Modeler home page, you can find an overview of all shared resources within your organization.
 
-[Organization owners and admins](/components/console/manage-organization/manage-users.md#users) can:
+[Users with elevated access](/components/modeler/web-modeler/collaboration.md#elevated-access) can:
 
 - View additional details about the published version.
 - Open the resource's milestone history (if they are in [super-user mode](/components/modeler/web-modeler/collaboration.md#super-user-mode) or are a [project admin or editor](/components/modeler/web-modeler/collaboration.md#access-rights-and-permissions) of the resource's project).
 - Unpublish a Connector template directly from this view.
 
-![Manage published templates - organization owners and admins](img/connector-templates/manage-connector-templates-org-privileges.png)
+![Manage published templates - elevated access](img/connector-templates/manage-connector-templates-org-privileges.png)
 
 Organization members without special organization permissions can:
 

diff --git a/docs/components/connectors/use-connectors/index.md b/docs/components/connectors/use-connectors/index.md
@@ -136,9 +136,9 @@ In that case, you could declare `Result Expression` as follows:
 
 ```
 = {
-  berlinWeather: response.current_weather.temperature,
-  berlinWindSpeed: response.current_weather.windspeed,
-  berlinWeatherInFahrenheit: response.current_weather.temperature * 1.8 + 32
+  berlinWeather: response.body.current_weather.temperature,
+  berlinWindSpeed: response.body.current_weather.windspeed,
+  berlinWeatherInFahrenheit: response.body.current_weather.temperature * 1.8 + 32
 }
 ```
 
@@ -165,7 +165,11 @@ indicate internal website errors, which is why the website team is informed.
 
 The **Error Expression** property requires a [FEEL](/components/modeler/feel/what-is-feel.md) expression that yields a BPMN error object in the end. The BPMN error object can be an empty [context](/components/modeler/feel/language-guide/feel-data-types.md#context),
 [null](/components/modeler/feel/language-guide/feel-data-types.md#null), or a context containing at least a non-empty `errorType` and a non-empty `code` if the error type is `bpmnError`. You can use all available functionality provided by FEEL to produce this result.
-Use the provided FEEL function [`bpmnError`](#function-bpmnerror) to conveniently create a BPMN error object and the provided FEEL function [`jobError`](#function-jobError) to conveniently create a fail job object.
+
+Use the provided FEEL functions:
+
+- [`bpmnError`](#function-bpmnerror) to create a BPMN error object. This triggers a [ThrowError call](/components/best-practices/development/dealing-with-problems-and-exceptions.md) to the workflow engine.
+- [`jobError`](#function-jobError) to create a fail job object. This triggers a [FailJob call](/components/best-practices/development/dealing-with-problems-and-exceptions.md) to the workflow engine.
 
 The `bpmnError` FEEL function optionally allows you to pass variables as the third parameter. You can combine this with a boundary event to use the variables in condition expressions when handling the error event. Example FEEL expression:
 

diff --git a/docs/components/modeler/about-modeler.md b/docs/components/modeler/about-modeler.md
@@ -1,7 +1,7 @@
 ---
 id: about-modeler
 title: About Modeler
-description: "Any executable process needs a BPMN diagram designed and configured beforehand. Camunda offers Web Modeler and Desktop Modeler to design and implement these."
+description: "Camunda offers Web Modeler and Desktop Modeler to design and implement any executable process using BPMN."
 keywords: ["process mapping tool"]
 ---
 

diff --git a/docs/components/modeler/desktop-modeler/flags/flags.md b/docs/components/modeler/desktop-modeler/flags/flags.md
@@ -30,26 +30,26 @@ Flags passed as command line arguments take precedence over those configured via
 
 ## Available flags
 
-| flag                                                        | default value                       |
-| ----------------------------------------------------------- | ----------------------------------- |
-| ["disable-plugins"](#disable-plug-ins)                      | false                               |
-| "disable-adjust-origin"                                     | false                               |
-| "disable-cmmn"                                              | true                                |
-| "disable-dmn"                                               | false                               |
-| "disable-form"                                              | false                               |
-| ["disable-httl-hint"](#disable-history-time-to-live-hint)   | false                               |
-| ["default-httl"](#default-history-time-to-live)             | false                               |
-| "disable-platform"                                          | false                               |
-| "disable-zeebe"                                             | false                               |
-| "disable-remote-interaction"                                | false                               |
-| "single-instance"                                           | false                               |
-| "user-data-dir"                                             | [Electron default](../search-paths) |
-| ["display-version"](#custom-display-version-label)          | `undefined`                         |
-| ["zeebe-ssl-certificate"](#zeebe-ssl-certificate)           | `undefined`                         |
-| ["c7-engine-version"](#default-execution-platform-version)  | `undefined`                         |
-| ["c8-engine-version"](#default-execution-platform-version)  | `undefined`                         |
-| ["enable-new-context-pad"](#enable-new-context-pad)         | `false`                             |
-| ["enable-connector-templates"](#enable-connector-templates) | `false`                             |
+| flag                                                          | default value                       |
+| ------------------------------------------------------------- | ----------------------------------- |
+| ["disable-plugins"](#disable-plug-ins)                        | false                               |
+| "disable-adjust-origin"                                       | false                               |
+| "disable-cmmn"                                                | true                                |
+| "disable-dmn"                                                 | false                               |
+| "disable-form"                                                | false                               |
+| ["disable-httl-hint"](#disable-history-time-to-live-hint)     | false                               |
+| ["default-httl"](#default-history-time-to-live)               | false                               |
+| "disable-platform"                                            | false                               |
+| "disable-zeebe"                                               | false                               |
+| "disable-remote-interaction"                                  | false                               |
+| "single-instance"                                             | false                               |
+| "user-data-dir"                                               | [Electron default](../search-paths) |
+| ["display-version"](#custom-display-version-label)            | `undefined`                         |
+| ["zeebe-ssl-certificate"](#zeebe-ssl-certificate)             | `undefined`                         |
+| ["c7-engine-version"](#default-execution-platform-version)    | `undefined`                         |
+| ["c8-engine-version"](#default-execution-platform-version)    | `undefined`                         |
+| ["enable-new-context-pad"](#enable-new-context-pad)           | `false`                             |
+| ["disable-connector-templates"](#disable-connector-templates) | `false`                             |
 
 ## Examples
 
@@ -153,14 +153,14 @@ To use the new context pad, configure your `flags.json` as follows:
 
 ![New context pad](./img/new-context-pad.png)
 
-### Enable Connector templates
+### Disable Connector templates
 
-To enable the automatic fetching of Camunda 8 Connector templates, configure your `flags.json` as follows:
+<span class="badge badge--cloud">Camunda 8 only</span>
+
+To [disable automatic Connector template fetching](../use-connectors.md#automatic-connector-template-fetching), configure your `flags.json` as follows:
 
 ```json
 {
-  "enable-connector-templates": true
+  "disable-connector-templates": true
 }
 ```
-
-[Learn more about using Connectors](../use-connectors.md).
diff --git a/docs/components/modeler/desktop-modeler/use-connectors.md b/docs/components/modeler/desktop-modeler/use-connectors.md
@@ -6,29 +6,36 @@ description: "Learn how to use Camunda 8 Connectors in Desktop Modeler."
 
 <span class="badge badge--cloud">Camunda 8 only</span>
 
-To use [Camunda 8 Connectors](../../connectors/out-of-the-box-connectors/available-connectors-overview.md) in Desktop Modeler, enable [automatic fetching](#fetch-camunda-8-connector-templates-automatically) of the respective Connector templates. Alternatively, for greater control, you may [fetch and configure templates manually](#add-camunda-8-connector-templates-manually).
+Use [Camunda 8 Connectors](../../connectors/introduction.md) to access a growing range of external services or communication protocols.
 
-## Fetch Camunda 8 Connector templates automatically
+Desktop Modeler automatically fetches and updates [element templates](./element-templates/about-templates.md) for [pre-built Connectors](../../connectors/out-of-the-box-connectors/available-connectors-overview.md) from the [Camunda Marketplace](https://marketplace.camunda.com/en-US/listing?pl=3038&attr=20486&cat=107792&locale=en-US). This happens automatically, in the background, unless explicitly [disabled](#disable-automatic-connector-template-fetching). Connector templates can also be provided [manually](#add-connector-templates-manually), offering you full control over the building blocks provided by the modeler.
 
-You can enable automatic fetching of Connector templates for [Camunda 8 Connectors](../../connectors/out-of-the-box-connectors/available-connectors-overview.md) through the [`enable-connector-templates` flag](./flags/flags.md#enable-connector-templates). Once set, it will fetch Camunda 8 Connector templates in the background and you'll be able to use them in your BPMN diagrams.
+## Automatic Connector template fetching
 
-On startup, a notification indicates if the templates are up to date or have been updated:
+Automatic Connector template fetching is enabled by default, and notifies you of any updates or errors.
+
+After an update check has concluded, a notification indicates if the templates are up to date or have been updated:
 
 ![Camunda Connector templates up to date notification](./img/use-connectors/up-to-date.png)
 
-In case of an error you'll see a nofication:
+In case of an error you'll see a notification:
 
 ![Error updating Camunda Connector templates notification](./img/use-connectors/error.png)
 
 Once fetched, you can use the templates in the Camunda 8 BPMN editor.
 
 ![Using Camunda Connector templates in the Camunda 8 BPMN editor](./img/use-connectors/apply.png)
 
-## Add Camunda 8 Connector templates manually
+## Disable automatic Connector template fetching
+
+Disable automatic fetching of Connector templates using the `#disable-connector-templates` [feature flag](./flags/flags.md#disable-connector-templates).
+
+## Add Connector templates manually
 
-For greater control, you can download individual Camunda 8 Connector templates manually through the [Camunda Marketplace website](https://marketplace.camunda.com/) and make them available in Desktop Modeler via the [standard element template search paths](./element-templates/configuring-templates.md).
+For full control over the building blocks offered by Desktop Modeler, download element templates for individual Camunda 8 Connectors manually (for example, through the [Camunda Marketplace](https://marketplace.camunda.com/)). Make them available to Desktop Modeler via the element template [search paths](./element-templates/configuring-templates.md).
 
 ## Additional resources
 
-- [Learn about Camunda 8 Connectors](../../connectors/out-of-the-box-connectors/available-connectors-overview.md)
-- [Desktop Modeler flags](./flags/flags.md)
+- [About Camunda 8 Connectors](../../connectors/out-of-the-box-connectors/available-connectors-overview.md)
+- [About Element Templates](./element-templates/about-templates.md)
+- [Desktop Modeler flags](./flags/flags.md#disable-connector-templates)