[WIP] Add the Durable Workflows documentation section

en/docs/develop/integration-artifacts/integration-artifacts.md

@@ -2,12 +2,12 @@
 sidebar_position: 1
 title: Integration Artifacts
 description: Choose the right artifact type to expose APIs, react to events, process files, run scheduled jobs, or power AI agents in WSO2 Integrator.
-keywords: [wso2 integrator, integration artifacts, http service, event handler, automation, file integration]
+keywords: [wso2 integrator, integration artifacts, http service, event handler, automation, file integration, durable workflow]
 ---
 
 # Integration Artifacts
 
-Integration artifacts are the building blocks of every integration. Each type is designed for a specific trigger and communication pattern: receiving HTTP requests, reacting to messages, processing files, running on a schedule, or serving AI agent tools. Choosing the right artifact for the job keeps your integration logic focused and your project easy to navigate.
+Integration artifacts are the building blocks of every integration. Each type is designed for a specific trigger and communication pattern: receiving HTTP requests, reacting to messages, processing files, running on a schedule, driving a long-running process, or serving AI agent tools. Choosing the right artifact for the job keeps your integration logic focused and your project easy to navigate.
 
 ## Artifact categories
 
@@ -28,6 +28,15 @@ Build AI-powered integrations that use large language models to reason, respond,
 | AI Chat Agent | An LLM-backed agent accessible via a chat interface or API. Covered in the [AI Integrations](../../genai/overview.md) section. |
 | MCP Service | Exposes integration capabilities as tools via the Model Context Protocol for use by AI assistants. Covered in the [AI Integrations](../../genai/overview.md) section. |
 
+### Durable workflows
+
+Model long-running business processes that survive restarts, wait for human decisions, and retry failed steps.
+
+| Artifact | Description |
+|---|---|
+| Durable Workflow | A flow of activities that records every completed step and resumes where it left off after a crash or restart. Use for approvals, multi-step transactions, and processes that wait on people or external events. Covered in the [Durable Workflows](../../workflows/overview.md) section. |
+| Durable Agentic Workflow | An AI agent that runs on the same durable runtime, so it gets crash safety, human tasks, timers, and retries. Use when the steps are branchy and hard to enumerate up front. Covered in the [Durable Workflows](../../workflows/overview.md) section. |
+
 ### Integration as API
 
 Expose your integration logic as a callable endpoint. Clients send a request and receive a response.

en/docs/workflows/develop/activities.md

@@ -0,0 +1,103 @@
+---
+sidebar_position: 3
+title: "Activities"
+description: Activities are the recorded units of work in a WSO2 Integrator durable workflow — exactly-once on replay, retryable on failure, and shared by workflows and durable agents alike.
+keywords: [wso2 integrator, durable workflow, activity, call activity, exactly once, replay, idempotency, retry]
+---
+
+import ThemedImage from '@theme/ThemedImage';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+# Activities
+
+An **activity** is a single unit of work that the durable runtime records and its modeled as a function. Anything that touches the outside world — an API call, a database write, a payment, an email — belongs in an activity rather than in the workflow body. That split is what makes a workflow crash-safe: the workflow function can be replayed from the start after a restart, while the work already done inside activities is read back from the record instead of being repeated.
+
+<ThemedImage
+    alt="A workflow diagram made of three activity nodes in sequence: reserveInventory capturing inventoryResult, chargePayment capturing paymentResult, and sendConfirmationEmail capturing emailResult"
+    sources={{
+        light: useBaseUrl('/img/workflows/develop/activities/workflow-activities-light.png'),
+        dark: useBaseUrl('/img/workflows/develop/activities/workflow-activities-dark.png'),
+    }}
+/>
+
+## Why the split matters
+
+When a workflow resumes after a crash or a restart, the runtime replays the workflow function to rebuild its state. During that replay:
+
+- A **completed activity is never re-executed.** Its recorded result is handed straight back, so the card is not charged twice and the email is not sent twice.
+- A **failed activity can be retried** on its own, without repeating the steps that already succeeded.
+
+:::warning Keep the workflow body deterministic
+Everything **outside** an activity is ordinary code that runs again on replay. No direct API calls, no random values, and no wall-clock reads in the workflow body — put that work in an activity so its result is recorded instead of recomputed.
+:::
+
+## Define an activity
+
+To create an activity, click **+** on **Workflow Activities** in the left sidebar.
+
+![The left sidebar with the + button on the Workflow Activities entry](/img/workflows/develop/activities/add-workflow-activity.png)
+
+**Create Activity** form provides the following fields for defining the activity function:
+
+| Field | Required | Description |
+|---|---|---|
+| **Activity Name** | Yes | The name of the activity function. This is the name the workflow calls and the name shown on the activity's node in the execution graph. |
+| **Description** | No | Explains what the activity does. |
+| **Parameters** | No | Defines the inputs of the activity function. Each parameter has a name and a type. Selecting **+ Add Parameter** adds a new parameter definition row. |
+| **Return Type** | No | The type of the value the activity returns, for example `string` or `string\|error`. Leave it empty for an activity that returns nothing. |
+
+After clicking **Create**, you will be directed to design its body in the same flow diagram used for any other function.
+
+:::tip Check the prebuilt ones first
+REST calls, SOAP calls, and SMTP email already have durable wrappers that ship with the runtime, so there is nothing to write for those. See [Prebuilt activities](prebuilt-activities/index.md).
+:::
+
+## Call an activity from a workflow
+
+To call an activity from a workflow, click **+** on the workflow diagram and select **Call Activity** from the palette's **Workflow → Steps** group. Then select the activity function you want to call.
+Call Activity form provides the following fields for calling an activity function:
+
+| Field                  | Required                                         | Description                                                                                                                                                                                        |
+|------------------------|--------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **Activity Arguments** | Yes                                              | Form field will appear for each activity function parameter. Provide the relevent arguments for each required parameter                                                                            |
+| **Retry Policy**       | Yes                                              | When an activity call failied, how should the workflow handle it. No Automatic Retry, Auto Retry, Human Review. See [Error handling and review activities](review-activity-and-error-handling.md). |
+| **Result**             | Only if the output of the activity is not `null` | Name of the result variable to capture the activity's output.                                                                                                                                      |
+| **Result type**        | Only if the output of the activity is not `null` | Type of the resulting data of the activity function.                                                                                                                                               |
+| **Check Error**        | No                                               | Under **Advanced Configurations**. Adds `check` to the call so a failure automatically propagates out from the workflow. Clear it to handle the error yourself. Defaults to `checked`. See [Error handling in the workflow logic](review-activity-and-error-handling.md#error-handling-in-the-workflow-logic). |
+
+![Call an activity from a workflow](/img/workflows/develop/activities/activity-call.gif)
+
+:::tip Idempotent side effects
+A *completed* activity never runs twice, but a *failed* attempt may run again once retries are on. Make the side effect idempotent — pass an idempotency key to the payment gateway, upsert instead of insert — so a repeated attempt cannot double-charge or duplicate a record.
+:::
+
+## Activities on a durable agent
+
+A durable agent uses the same activities. Instead of you wiring the call order, the model chooses which activity to call and when, and each call is recorded exactly as it is in a hand-wired workflow.
+
+To give an agent an activity, click **+** on the activity icon at the right bottom of the agent node and select the activity. The register form provides the following fields for registering the activity as a durable agent activity:
+
+| Field | Required | Description |
+|---|---|---|
+| **Retry Policy** | Yes | Engine retry strategy when the activity fails: no automatic retry (an AI agent may still re-invoke it), automatic backoff retries, or a human review task. See [Error handling and review activities](review-activity-and-error-handling.md). |
+| **Reviewer Roles** | Only for **Human Review** | Roles permitted to decide the human review, for example `"manager"` or `["finance", "manager"]`. |
+| **Advanced Configurations** | No | Approval settings for the registered activity, collapsed by default. |
+| ↳ **Requires Approval** | No | Gate the activity: before the agent runs it, a review activity is created and the agent suspends durably until a reviewer proceeds (optionally editing the arguments) or rejects. |
+| ↳ **Reviewer Roles** | Only with **Requires Approval** | Roles permitted to decide the approval review of this activity, for example `"support-lead"` or `["finance", "manager"]`. |
+
+![Register a workflow activity as a durable agent activity](/img/workflows/develop/activities/register-activity-as-agent-activity.png)
+
+Registering the activity is what makes it available to the agent. See [Durable agentic workflows](durable-agentic-workflow.md).
+
+## Watching activities run
+
+Each activity call appears as an `ACTIVITY` node in the instance's execution graph in the [Integration Control Plane](../icp/managing-workflows.md), so you can see which step an instance is on, which activities have completed, and which one failed. The same graph is available over the [Management API](../reference/management-api.md).
+
+[//]: # (Add a screenshot of the execution graph with an activity node highlighted.)
+
+## Next steps
+
+- [Prebuilt activities](prebuilt-activities/index.md) — durable REST, SOAP, and email calls with no wrapper to write.
+- [Durable timers](durable-timers.md) — pause between activities without holding resources.
+- [Error handling and review activities](review-activity-and-error-handling.md) — retry policies and approval gates.
+- [Build an order processing workflow](../getting-started/build-an-order-processing-workflow.md) — activities wired into a complete flow.

en/docs/workflows/develop/create-workflow.md

@@ -0,0 +1,54 @@
+---
+sidebar_position: 1
+title: "Create a Workflow"
+description: Add a durable workflow artifact in WSO2 Integrator, give it an input type, and design its steps on the workflow diagram.
+keywords: [wso2 integrator, durable workflow, create workflow, workflow artifact, workflow input type, workflow context]
+---
+
+# Create a Workflow
+
+A **durable workflow** is an artifact in your integration, the same as a service or an automation. You create it once, give it the shape of the data it starts with, and then design its steps on a diagram.
+
+## Launching the wizard 
+
+1. In the design view, click **+ Add Artifact**.
+2. On the **Artifacts** page, under **Durable Workflow**, click **Durable Workflow**.
+
+   ![The Artifacts page with the Durable Workflow card under the Durable Workflow section](/img/workflows/develop/create-workflow/add-artifact.png)
+
+   **Durable Agentic Workflow** beside it produces the same kind of artifact, but you describe the goal and let a model choose the steps instead of wiring them yourself. See [Durable agentic workflows](durable-agentic-workflow.md).
+
+3. Fill in the **Create New Durable Workflow** form:
+
+   | Field | Required | Description |
+   |---|---|---|
+   | **Name** | Yes | The workflow's identifier. It is how the workflow is referenced when it is started, and the name it appears under in workflow management. |
+   | **Workflow Input Data Type** | No | The type of the data the workflow starts with, usually a record. See [Types](../../develop/integration-artifacts/supporting/types.md). |
+
+   :::tip Design it for the launcher
+   Whatever you put in this type is what every caller has to supply, including the form the [Integration Control Plane](../icp/start-workflow.md) generates for starting a run by hand. Keep it to the data the process actually needs.
+   :::
+
+   ![The Create New Durable Workflow form with Name set to orderWorkflow and Workflow Input Data Type set to OrderInfo](/img/workflows/develop/create-workflow/create-workflow-form.png)
+
+4. Click **Create**.
+
+The workflow opens on its own diagram with a single **Start** node, and appears under **Workflows** in the sidebar.
+
+For a worked example that fills this in end to end, see [Build an order processing workflow](../getting-started/build-an-order-processing-workflow.md).
+
+## Design the steps
+
+The workflow diagram is the same flow diagram used everywhere else in WSO2 Integrator, with a group of durable steps added to the node panel:
+
+| Group | What it holds |
+|---|---|
+| **Workflow** > **Steps** | [Call Activity](activities.md), [Await Human Task](human-task-workflow.md), [Await Data Event](data-events.md), and [Sleep](durable-timers.md). |
+| **Workflow** > **Workflow Functions** | Replay-safe helpers: current time, whether the run is replaying, and the run's own ID and type. |
+| **Statement**, **Control**, **Error Handling** | The ordinary building blocks: variables, function calls, `if`, `while`, `foreach`, and error handling. |
+
+## Next steps
+
+- [Start a workflow](start-workflow.md) — launch a run from a service, an automation, or the console.
+- [Activities](activities.md) — the recorded units of work a workflow calls.
+- [Build an order processing workflow](../getting-started/build-an-order-processing-workflow.md) — the whole flow, step by step.

en/docs/workflows/develop/data-events.md

@@ -0,0 +1,71 @@
+---
+sidebar_position: 4
+title: "Await Data Events"
+description: Pause a WSO2 Integrator durable workflow until an external system or a person delivers data, then resume with that value as a typed, recorded result.
+keywords: [wso2 integrator, durable workflow, data event, send data, external data, wait, callback, long running]
+---
+
+import ThemedImage from '@theme/ThemedImage';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+# Await Data Events
+
+Sometimes a workflow needs *data*, not a decision — the employee submits the supporting bills, a partner system posts a shipping confirmation, a scanner returns a document. A **data event** is a named slot the workflow waits on. The instance suspends until something delivers a value into that slot, then resumes with the value as an ordinary typed result.
+
+<ThemedImage
+    alt="A workflow that reserves inventory and then halts on a Wait for payment step bound to paymentData, drawn with a dashed arrow arriving from outside the flow"
+    sources={{
+        light: useBaseUrl('/img/workflows/develop/data-events/await-data-event-light.png'),
+        dark: useBaseUrl('/img/workflows/develop/data-events/await-data-event-dark.png'),
+    }}
+/>
+
+Like every other durable wait, it costs nothing while it waits and it survives a restart.
+
+## Pause workflow for data event
+
+1. On the workflow diagram, click **+** where the workflow should wait.
+2. In the node panel, under **Workflow** > **Steps**, click **Await Data Event**. The **Await Data** form opens.
+3. Fill in the form:
+
+   | Field | Required | Description |
+   |---|---|---|
+   | **Data Receive Variable Name** | Yes | The variable that receives the value once it arrives. |
+   | **Data Type** | Yes | The type of the value the workflow expects. Pick an existing type, or create one from the list. |
+   | **Data Name** | Yes | The name used when sending the data into this workflow. |
+   | **Min Count** | No | Under **Advanced Configurations**. How many of the awaited events must arrive before the workflow continues. Defaults to all of them. |
+   | **Timeout** | No | Under **Advanced Configurations**. The longest the workflow waits, as a duration record. The wait returns an error when the timeout expires, which your workflow can handle. |
+
+   **Timeout** opens a **Record Configuration** editor: tick the units you want, such as **minutes**, and fill in their values. Switch the field to **Expression** to write the record yourself instead.
+
+4. Click **Add** to commit the **Data Waits** entry. It collapses to a row showing its type and variable. Use **+ Add Data Waits** to wait on more than one event.
+5. Click **Save**.
+
+![Adding an Await Data Event step and bounding the wait with a timeout](/img/workflows/develop/data-events/await-data-event.gif)
+
+The diagram gains a wait node, drawn with an arrow arriving from outside the flow, and the workflow now suspends there.
+
+:::tip Data event or human task?
+Use a **data event** when a system or a person is submitting *content* the workflow will process. Use a [human task](human-task-workflow.md) when a person is making a *decision* the Control Plane should render as a form in their inbox.
+:::
+
+## Watching a waiting workflow
+
+While the workflow waits, the execution graph in the [Integration Control Plane](../icp/managing-workflows.md) marks the halt point as a `DATA` node named after the event, with status `WAITING` — so anyone can see exactly what the process is blocked on rather than guessing that it is stuck.
+
+<ThemedImage
+    alt="Execution graph showing the workflow halted on a waiting billSubmitted data event"
+    sources={{
+        light: useBaseUrl('/img/workflows/develop/data-events/01-waiting-data-event.png'),
+        dark: useBaseUrl('/img/workflows/develop/data-events/01-waiting-data-event.png'),
+    }}
+/>
+
+The same graph is available over the [Management API](../reference/management-api.md).
+
+## Next steps
+
+- [Send a data event](send-data-event.md) — the delivery half: fill the event and resume the run.
+- [Await human task](human-task-workflow.md) — pause for a person's decision instead of their data.
+- [Durable timers](durable-timers.md) — waiting on the clock instead of an event.
+- [Activities](activities.md) — the recorded steps that process the data once it arrives.