Merge branch 'main' into elastic-search-upgrade-guide

docs/components/best-practices/operations/versioning-process-definitions.md

@@ -13,8 +13,6 @@ For real-life applications, it's crucial to understand how Camunda deals with ev
 
 By default, deploying a process or decision definition means that the workflow engine will check if the version has changed. If it has, it will register that deployment as a new version of the definition. By default, running instances will continue to run on the basis of the version they started with, new instances will be created based on the latest version of that definition.
 
-As a consequence, when looking directly at Camunda database tables you can observe different versions in the process definition table and the running process instances which are linked to these versions:
-
 ![Versions](versioning-process-definitions-assets/database-versions.png)
 
 ## Selecting the best versioning approach

docs/components/connectors/out-of-the-box-connectors/available-connectors-overview.md

@@ -76,8 +76,9 @@ import TabItem from "@theme/TabItem";
 ## Protocol Connectors
 
 - [GraphQL Connector](/components/connectors/protocol/graphql.md) - Execute a [GraphQL](https://graphql.org/) query or mutation from your BPMN process.
-- [REST Connector](/components/connectors/protocol/rest.md) - Make a request to a REST API and use the response in the next steps of your process.
 - [HTTP Webhook Connector](/components/connectors/protocol/http-webhook.md) - Start a process instance with your custom webhook configuration.
+- [Polling Connector](/components/connectors/protocol/polling.md) - The HTTP Polling Connector polls an endpoint at regular intervals, enabling periodic data fetching as an intermediate step in your BPMN processes.
+- [REST Connector](/components/connectors/protocol/rest.md) - Make a request to a REST API and use the response in the next steps of your process.
 
 </TabItem>
 

docs/components/connectors/protocol/polling.md

@@ -0,0 +1,168 @@
+---
+id: polling
+title: HTTP Polling Connector
+sidebar_label: HTTP Polling Connector
+description: The HTTP Polling Connector polls an endpoint at regular intervals, enabling periodic data fetching as an intermediate step in your BPMN processes.
+---
+
+The **HTTP Polling Connector** polls an endpoint at regular intervals, enabling periodic data fetching as an intermediate step in your BPMN processes. This Connector is built on top of the [REST Connector](../protocol/rest.md), ensuring consistent functionality and reliability.
+
+:::caution
+If you use the HTTP Polling Connector, ensure you do not have any instance variable named in the list below, as these are reserved words for this connector:
+
+- body, url, method, headers, authentication, queryParameters, connectionTimeoutInSeconds, httpRequestInterval
+
+:::
+
+## Prerequisites
+
+Ensure that you have:
+
+- An HTTP endpoint that supports polling.
+- Necessary credentials if the endpoint demands authentication.
+
+:::note Execution Exception Handling
+If the HTTP Polling Connector encounters an execution exception while polling, it will ignore the exception and attempt to execute the request again after the next interval delay. Ensure to monitor your logs for any recurring issues.
+
+:::
+
+## Setting up the HTTP Polling Connector
+
+1. Add an **Intermediate Event** to your BPMN diagram.
+2. Change its template to the **HTTP Polling Connector**.
+3. Populate all mandatory fields, like the endpoint URL, polling interval, and required headers.
+4. Complete your BPMN diagram.
+5. Deploy the diagram to activate the **HTTP Polling Connector**.
+
+## Configuring the HTTP Polling Connector
+
+### Authentication
+
+Navigate to the **Authentication** section and select your desired **Authentication type** (e.g., Basic, OAuth). Refer to the [Authentication section of the REST Connector documentation](docs/components/connectors/protocol/rest.md#authentication) for a comprehensive guide.
+
+### HTTP polling configuration
+
+- **Method**: Choose the HTTP method for your request, e.g., GET, POST, PUT.
+- **URL**: Enter the URL of the targeted HTTP endpoint.
+- **Headers** (Optional): Input required headers as per the external service. Learn more about headers in the [REST Connector headers](docs/components/connectors/protocol/rest.md#http-headers) section.
+- **Query Parameters** (Optional): Add necessary query parameters for the endpoint. More details can be found in the [REST Connector query parameters](docs/components/connectors/protocol/rest.md#query-parameters) section.
+- **Interval** (Optional): Set the frequency for polling the endpoint in ISO 8601 durations format. The default interval is 50 seconds. Review [how to configure a time duration](../../modeler/bpmn/timer-events/timer-events.md#time-duration) for details.
+- **Connection Timeout**: Define how long (in seconds) the Connector waits before timing out. Further information on this can be found [here](docs/components/connectors/protocol/rest.md#connection-timeout).
+
+### Payload configuration (optional)
+
+In the **Payload** section, you can include a **request body**. Learn more about this [here](docs/components/connectors/protocol/rest.md#request-body).
+
+### Condition to proceed
+
+1. **Correlation key (process)**: Defines the correlation key based on the process instance.
+
+   - **Example**: Using a process variable named `orderId`:
+     ```
+     Correlation key (process): =orderId
+     ```
+
+2. **Correlation key (payload)**: Extracts the correlation key from the polled data.
+
+   - **Example**: With data like `{"orderId": "123"}`:
+     ```
+     Correlation key (payload): =body.orderId
+     ```
+
+3. **Activation Condition**: Checks if the polled data meets criteria to activate the intermediate catch event.
+   - **Example**: If the data should have a `status` of "OK":
+     ```
+     Activation Condition: =(body.status = "OK")
+     ```
+
+For more information about correlation keys, review the [messages guide](../../../concepts/messages).
+
+## Handling HTTP Connector responses
+
+The response from any HTTP Connector contains the status, headers, and body. Learn more about the response structure [here](docs/components/connectors/protocol/rest.md#response).
+
+To structure and utilize the response:
+
+1. Set a **Result Variable** to store the HTTP response, e.g., `pollingData`.
+2. Use a **Result Expression** to extract specific fields from the `={fieldProperty:body.fieldProperty}`.
+
+## Examples
+
+### Scenario 1: Monitoring GitHub issues
+
+Monitor a GitHub issue to see when it's closed and if it has a specific label ('needs review').
+
+#### Steps
+
+1. Drag an intermediate event onto your BPMN diagram.
+2. Choose the HTTP Polling Connector template.
+3. Configure the connector with the relevant details:
+   - **URL**: `https://api.github.com/repos/[YourRepoOwner]/[YourRepoName]/issues/[IssueNumber]`
+   - **Authorization Type**: Bearer token
+   - **Bearer token**: `{{secrets.BEARER_TOKEN}}`
+   - **Method**: `GET`
+   - **Headers**: `={"Content-Type": "application/vnd.github+json","X-GitHub-Api-Version": "2022-11-28"}`
+   - **Interval**: `PT10M` (Every 10 minutes) – This checks the GitHub issue every 10 minutes.
+   - **Correlation Key (process)**: `=issueNumber`
+   - **Correlation Key (payload)**: `=body.number`
+   - **Activation Condition**: `=(body.state = "closed")`
+   - **Result Expression**: `={issueUrl:body.html_url, needsReview: list contains((body.labels).name, "needs review")}` - Extract the issue URL and check if the label 'needs review' is present.
+
+#### Example response
+
+```json
+{
+  "status": 200,
+  "body": {
+    "number": 212,
+    "title": "Important Issue",
+    "labels": [{ "name": "bug" }, { "name": "needs review" }],
+    "state": "closed",
+    "html_url": "https://github.com/YourRepoOwner/YourRepoName/issues/212"
+  }
+}
+```
+
+In this scenario, once the issue #212 titled **Important Issue** is closed, the process will proceed. If the issue is also labeled **needs review**, this label can be leveraged in the next steps of the process. For instance, it can trigger the creation of a new issue for review or initiate other related actions.
+
+### Scenario 2: Monitoring product stock levels
+
+Suppose you're overseeing an e-commerce platform. It's vital to ensure certain popular products remain stocked to guarantee user satisfaction. Avoiding stock-outs is essential to prevent lost sales and keep customers happy. With Camunda's HTTP Polling Connector, you can maintain a real-time stock level check.
+
+#### Steps
+
+1. Drag an intermediate event onto your BPMN diagram.
+2. Choose the HTTP Polling Connector template.
+3. Configure the Connector as follows:
+   - **URL**: `https://inventory.yourstore.com/api/v2/products/12345/stock`
+   - **Authorization Type**: Basic Authentication
+   - **Username**: `[YourInventoryAPIUsername]`
+   - **Password**: `{{secrets.PASSWORD}}`
+   - **Interval**: `PT1H` (Every hour)
+   - **Correlation Key (process)**: `=productID`
+   - **Correlation Key (payload)**: `=body.productID`
+   - **Activation Condition**: `=(body.stockLevel < 10)`
+   - **Result Expression**: `={stockLevelResponse:body.stockLevel}`
+
+#### Example response
+
+```json
+{
+  "status": 200,
+  "body": {
+    "productID": 12345,
+    "productName": "Wireless Bluetooth Earbuds",
+    "stockLevel": 8,
+    "lastUpdated": "2023-09-17T11:20:32Z"
+  }
+}
+```
+
+Whenever the stock level of this particular product goes below 10 units, the BPMN process can be set up to perform tasks such as notifying the supply chain, alerting marketing teams, or showcasing a "Low in Stock" badge on the product's webpage.
+
+## Next steps
+
+- Dive deeper into the [REST Connector](docs/components/connectors/protocol/rest.md) to understand its capabilities and configurations.
+- Explore [other Connectors available](../out-of-the-box-connectors/available-connectors-overview.md) in Camunda to integrate with various systems and services.
+- Get a comprehensive understanding of how to use Connectors in your BPMN processes [here](../use-connectors/index.md).
+- Learn about the specifics of inbound Connectors and how they can be used [here](../use-connectors/inbound.md).

docs/components/connectors/use-connectors/inbound.md

@@ -5,27 +5,62 @@ description: Learn how to use inbound Connectors
 ---
 
 [Inbound Connectors](/components/connectors/connector-types.md#inbound-connectors) enable workflows to receive data or messages from external systems or services.
+Check out our [list of existing inbound Connectors](/components/connectors/out-of-the-box-connectors/available-connectors-overview.md) for more information.
 
-### Creating the Connector event
+## Creating the Connector event
 
 Inbound Connectors are modeled as **catch events** in BPMN. Connectors that trigger a process instance are modeled as **start events**, and Connectors that send messages to an already running process instance are modeled as **intermediate catch events**.
 
-1. Start building your BPMN diagram with a **Start Event** or an **Intermediate Catch Event** building block.
-2. Change its template to an inbound Connector of your choice (e.g., HTTP webhook, or a message queue subscription).
-3. Fill in all required properties.
-4. Complete your BPMN diagram.
-5. Deploy it to your Camunda 8 instance.
-
 When you **deploy** such a BPMN diagram with an inbound Connector, the Connector becomes ready to receive incoming requests. The outcome depends on the Connector type:
 
 - The webhook endpoint becomes available.
 - Subscription Connectors start listening to the message queue.
 - Polling Connectors start polling the external system.
 
+### Modeling the Connector start event
+
+:::caution
+Inbound Connector start events are on deprecation path. Please use inbound Connector message start event instead.
+:::
+
+1. Start building your BPMN diagram with a **Start Event** building block.
+2. Change its template to an inbound Connector of your choice (e.g., HTTP webhook, or a message queue subscription).
+3. Fill in all required properties.
+4. Complete your BPMN diagram.
+5. Deploy it to your Camunda 8 instance.
+
 :::note
 You can still start instances of that process manually via the modeler, which is sometimes useful during testing.
 :::
 
+### Modeling the Connector intermediate message catch event
+
+1. Start building your BPMN diagram with an **Intermediate Catch Event** building block.
+2. Change its template to an inbound Connector of your choice (e.g., HTTP webhook, or a message queue subscription).
+3. Fill in all required properties.
+4. Complete your BPMN diagram.
+5. Deploy it to your Camunda 8 instance.
+
+### Modeling the Connector boundary event
+
+1. Start building your BPMN diagram with any **Task** building block.
+2. Attach a **Boundary event** to a **Task** at your diagram.
+3. Change its template to an inbound Connector of your choice (e.g., HTTP webhook, or a message queue subscription).
+4. Fill in all required properties.
+5. Complete your BPMN diagram.
+6. Deploy it to your Camunda 8 instance.
+
+### Modeling the Connector non-interrupting message start event
+
+1. Start building your BPMN diagram with an **Event Sub Process**.
+2. Add a plain **Message Start Event (non-interrupting)** into an **Event Sub Process**.
+3. Change its template to an inbound Connector of your choice (e.g., HTTP webhook, or a message queue subscription).
+4. Fill in all required properties.
+5. Select **Correlation required** in the **Subprocess correlation** section.
+6. Specify both **Correlation key (process)** and **Correlation key (payload)** values.
+7. Complete your BPMN diagram.
+8. Deploy it to your Camunda 8 instance.
+
 ### Example: Configuring an HTTP webhook
 
 Different Connector types have different configuration options, but parts like **Result expression**, or **Correlation key** are common for all of them. Let's take a look at an example of configuring an HTTP webhook.

docs/components/operate/operate-introduction.md

@@ -20,7 +20,7 @@ dark: useBaseUrl('img/operate-introduction_dark.png'),
 
 In addition to providing visibility into active and completed process instances, Operate also makes it possible to carry out key operations such as resolving [incidents](./userguide/resolve-incidents-update-variables.md), and updating process instance variables.
 
-![operate-introduction](img/operate-introduction.png)
+![operate-introduction](../../images/operate/operate-introduction.png)
 
 Learn how to use Operate to monitor process instances and more features in the [Operate user guide](/components/operate/userguide/basic-operate-navigation.md).
 

docs/components/operate/userguide/basic-operate-navigation.md

@@ -16,24 +16,24 @@ To view a deployed process, take the following steps:
 
 1. In the **Process Instances by Name** panel on your dashboard, note the list of your deployed processes and running instances.
 
-![operate-view-process](../img/operate-introduction.png)
+![operate-view-process](../../../images/operate/operate-introduction.png)
 
 2. When you click on the name of a deployed process in the **Process Instances by Name** panel, you’ll navigate to a view of that process model and all running instances.
 
-![operate-view-process](./img/operate-view-process.png)
+![operate-view-process](../../../images/operate/operate-view-process.png)
 
 3. From this **Processes** tab, you can cancel a single running process instance.
 
-![operate-cancel-process-instance](./img/operate-view-process-cancel.png)
+![operate-cancel-process-instance](../../../images/operate/operate-view-process-cancel.png)
 
 ## Inspect a process instance
 
 Running process instances appear in the **Instances** section below the process model. To inspect a specific instance, click on the instance id.
 
-![operate-inspect-instance](./img/operate-process-instance-id.png)
+![operate-inspect-instance](../../../images/operate/operate-process-instance-id.png)
 
 Here, observe details about the process instance, including the instance history and the variables attached to the instance.
 
-![operate-view-instance-detail](./img/operate-view-instance-detail.png)
+![operate-view-instance-detail](../../../images/operate/operate-view-instance-detail.png)
 
 To visualize the performance of process instances, we recommend utilizing [Optimize]($optimize$/components/what-is-optimize).

docs/components/operate/userguide/delete-finished-instances.md

@@ -12,40 +12,40 @@ To delete a process instance from the **Processes** page, take the following ste
 
 1. On the **Processes** page, apply the **Finished Instances** filter.
 
-![operate-view-finished-instances](./img/operate-instances-finished-instances.png)
+![operate-view-finished-instances](../../../images/operate/operate-instances-finished-instances.png)
 
-1. Click the trash can icon on any process instance you want to delete.
+1. Click the **Delete** button on any process instance you want to delete.
 
-![operate-perform-delete-operation](./img/operate-instances-click-delete-operation.png)
+![operate-perform-delete-operation](../../../images/operate/operate-instances-click-delete-operation.png)
 
 1. Confirm the delete operation by clicking **Delete**.
 
-![operate-confirm-delete-operation](./img/operate-instances-delete-operation-confirm.png)
+![operate-confirm-delete-operation](../../../images/operate/operate-instances-delete-operation-confirm.png)
 
 4. In the **Operations** panel on the right side of the screen, view the deleted process instance.
 
-![operate-view-delete-operation](./img/operate-operations-panel-delete-operation.png)
+![operate-view-delete-operation](../../../images/operate/operate-operations-panel-delete-operation.png)
 
 ## Delete process instance from instance detail page
 
 1. On the **Processes** page, apply the **Finished Instances** filter.
 
-![operate-view-finished-instances-instance-detail](./img/operate-instance-detail-finished-instances.png)
+![operate-view-finished-instances-instance-detail](../../../images/operate/operate-instance-detail-finished-instances.png)
 
-2. Navigate to the instance detail page by clicking the **Instance id** of the process instance you want to delete.
+2. Navigate to the instance detail page by clicking the **Instance key** of the process instance you want to delete.
 
-![operate-navigate-finished-instance-detail](./img/operate-instance-detail-finished-instances-navigate.png)
+![operate-navigate-finished-instance-detail](../../../images/operate/operate-instance-detail-finished-instances-navigate.png)
 
-3. Click the delete icon.
+3. Click the delete button.
 
-![operate-instance-detail-perform-delete](./img/operate-finished-instance-detail.png)
+![operate-instance-detail-perform-delete](../../../images/operate/operate-finished-instance-detail.png)
 
 1. Confirm the delete operation by clicking **Delete**.
 
-![operate-instance-detail-confirm-delete-operation](./img/operate-instance-detail-delete-operation-confirm.png)
+![operate-instance-detail-confirm-delete-operation](../../../images/operate/operate-instance-detail-delete-operation-confirm.png)
 
 :::note
 Use caution as the process instance is now deleted and you may not access it again.
 :::
 
-![operate-instance-deleted-notification](./img/operate-instance-deleted-notification.png)
+![operate-instance-deleted-notification](../../../images/operate/operate-instance-deleted-notification.png)