OOTB PDLC Happy Path documentation

docs/components/modeler/web-modeler/create-a-process-application.md

@@ -0,0 +1,63 @@
+---
+id: create-a-process-application
+title: Create a process application
+description: Create a process application and select a development cluster to deploy to.
+---
+
+import EmptyProjectImg from './img/process-applications/empty-project.png'
+import ReassignMainProcessImg from './img/process-applications/reassign-main-process.png'
+import FileListImg from './img/process-applications/file-list.png'
+
+Create a process application in your project to work on and deploy a set of related files.
+
+## Create a process application
+
+To create a process application, either:
+
+- Select **Create process application** in an empty project.
+- Select **New project > Create process application** if you have not yet created a project.
+  <p><img src={EmptyProjectImg} alt="Create a process application from an empty project" /></p>
+
+### Select a default cluster
+
+<span class="badge badge--cloud">Camunda 8 SaaS only</span>
+
+When you create a process application, you must select a development cluster to deploy to.
+
+- If you have already created a cluster, turn on the toggle next to the cluster name in **Select a development cluster**.
+- If you have not yet [created a cluster](/guides/create-cluster.md), or if **No Cluster has been created yet** is shown, select **Create new dev cluster**. The Console **Clusters** tab opens so you can create a new cluster.
+
+:::note
+
+- If your modeling plan does not allow you to create more clusters, a `Cluster creation is not available on this modeling plan` warning is shown. Contact the administrator or owner of your organization to upgrade your plan.
+
+- If you do not have the proper permissions to create a cluster, a `Missing permissions` warning is shown. Contact the administrator or owner of your organization to create a cluster.
+
+:::
+
+### Main process
+
+After you have created a process application, a new BPMN diagram is created and labeled as the main process.
+
+- The main process diagram is named using the process application name. You can rename the main process diagram any time.
+- A process application must have a main process. You cannot delete or move the main process diagram out of the process application.
+- You can assign another BPMN diagram as the main process using the **Reassign main process** option in the action menu.
+  <p>
+  <img src={ReassignMainProcessImg} alt="Reassign the main process" />
+  </p>
+
+### Add files to a process application
+
+To add more files to the process application, either:
+
+- Select the **Create new** dropdown on the process application page to create and add a new file.
+- Drag and drop files from your local computer.
+- Move an existing file into the process application from a different location in Web Modeler.
+
+The main process is always displayed at the top of the file list, regardless of the sort order.
+
+<p><img src={FileListImg} alt="Process application file list" /></p>
+
+:::note
+Process IDs, decision IDs, and form IDs must be unique across all files within a process application. This avoids ambiguity and conflicts when you link resources and deploy the process application.
+:::

docs/components/modeler/web-modeler/deploy-process-application.md

@@ -0,0 +1,66 @@
+---
+id: deploy-process-application
+title: Deploy and run your process application
+description: You can deploy your process application to a cluster, and run your process application to test, debug, and observe how it performs in a live environment.
+---
+
+import DeployImg from './img/process-applications/define-stages-deploy.png'
+import RunProcessApplicationImg from './img/process-applications/run-process-application.png'
+import DeployErrorImg from './img/process-applications/deploy-error.png'
+
+You can deploy your process application to a cluster, and run your process application to test, debug, and observe how it performs in a live environment.
+
+## Deploy your process application
+
+To deploy your process application:
+
+1. Open the [main process](create-a-process-application.md#main-process).
+1. Select **Deploy** to open the **Deploy process application** modal.
+   <p><img src={DeployImg} alt="Deploy a process application" /></p>
+1. Turn on the toggle for the cluster stage you want to deploy to.
+1. Perform any other actions as required, such as:
+   - Unpausing the chosen cluster if it has been auto-paused. Select **Resume**.
+   - Managing the cluster. Select **Manage**.
+   - [Defining the stages](process-application-pipeline.md#deployment-pipeline-stages) of your deployment pipeline. Select **Define stages**.
+1. Select **Deploy** to deploy the process application to the selected cluster.
+
+All BPMN, DMN, and form files contained in the process application folder are deployed as a single bundle.
+
+:::note
+If any resource fails to deploy, the whole deployment [fails](#deployment-errors) and the cluster state remains unchanged. This safely ensures that a process application cannot be deployed incompletely or in an inconsistent state.
+:::
+
+## Run a process application
+
+You can run your process application to test, debug, and observe how it performs in a live environment.
+
+To run your process application:
+
+1. Open the [main process](create-a-process-application.md#main-process).
+1. Select **Run** to open the **Start instance** modal.
+   <p><img src={RunProcessApplicationImg} alt="Run a process application" /></p>
+1. Select **Run** to start a new instance.<p><ul><li>Before the actual process instance is started, all resources are redeployed if required so the new instance
+   always uses their latest state.</li><li>After the process instance is started, you will receive a notification with a link to the process instance view in
+   [Operate](../../operate/operate-introduction.md). Open this link to monitor the process instance.</li></ul></p>
+
+:::info
+Single-file deployment is not supported in a process application. If you select **Deploy** or **Run** in any diagram other than the main process, you are prompted to open the main process for deployment.
+:::
+
+## Deployment errors
+
+If the deployment of a process application fails (for example, because one or more of the contained resources has invalid implementation properties), a modal is shown containing the error message thrown by the Zeebe engine.
+
+The message typically provides the name of the affected resource, the ID of the invalid diagram element, and the error details.
+
+<p><img src={DeployErrorImg} style={{width: 680}} alt="Process application deployment error" /></p>
+
+### Deployment of external resources
+
+You can link BPMN processes, DMN decisions, or forms that are not part of the process application itself (external
+resources) from any process inside a process application.
+
+Note that when you deploy the process application:
+
+- Linked external forms are deployed together with the process application.
+- Linked external BPMN and DMN diagrams are _not_ deployed together. You must deploy these separately.

docs/components/modeler/web-modeler/process-application-pipeline.md

@@ -0,0 +1,90 @@
+---
+id: process-application-pipeline
+title: Process application development lifecycle
+description: You can use Web Modeler to quickly develop and progress low-risk process application releases through the stages of a typical development lifecycle.
+---
+
+import DeployProcessApplicationDiagramImg from './img/process-applications/diagram-process-application-pipeline.png'
+import DeployStagesImg from './img/process-applications/define-stages.png'
+
+You can use Web Modeler to quickly develop and progress low-risk process application releases through the stages of a typical development lifecycle.
+
+<p><img src={DeployProcessApplicationDiagramImg} alt="Process application file list" /></p>
+
+:::caution
+For business-critical and higher-risk processes that require strict governance and/or quality requirements, you can [integrate Web Modeler into your CI/CD pipelines](/docs/guides/devops-lifecycle/integrate-web-modeler-in-ci-cd.md).
+:::
+
+## Model
+
+During the modeling stage, you will typically:
+
+- [Create a process application](create-a-process-application.md) and select a default development cluster to deploy to.
+- Invite other users to collaborate on the process application.
+- Define and set up the clusters and deployment stages you will use in your development pipeline.
+- Model your diagrams and associated resources, and fix errors shown in the modeler.
+- Use [token simulation](token-simulation.md) to correct and optimize your process flow.
+
+### Deployment pipeline stages
+
+You can use the provided Web Modeler deployment pipeline to manage your application process deployment. The deployment pipeline has four stages named **Development**, **Testing**, **Staging**, and **Production**.
+
+| Stage       | Description                                                                                                     |
+| :---------- | :-------------------------------------------------------------------------------------------------------------- |
+| Development | Use to create and test new software features and changes.                                                       |
+| Testing     | Use for quality checks, ensuring software meets defined standards before release.                               |
+| Staging     | Use for controlled testing where changes are validated before deployment to production.                         |
+| Production  | The live system with the latest software. Only administrators and organization owners can deploy to this stage. |
+
+To define your deployment pipeline stages:
+
+1. Open the [main process](create-a-process-application.md#main-process).
+1. Select **Deploy** to open the **Deploy process application** modal.
+1. Select **Define stages** to open the **Define stages** modal.
+   <p><img src={DeployStagesImg} alt="Define stage for deployment modal" /></p>
+1. Select and assign a cluster to each deployment stage that you want to use in your deployment pipeline.
+1. Select **Save** to save your changes and close the modal.
+
+:::note
+
+- An administrator must define the cluster to deploy to for each stage.
+- During deployment, the next stage is not automatically selected. You must select the stage you want to promote to.
+- You must select a cluster for at least one stage to be able to deploy. An **Undefined stages** warning is shown if no cluster is selected for at least one stage.
+
+:::
+
+## Validate
+
+When your process application is ready for validation you can deploy it to your development cluster.
+
+- Use [Play mode](play-your-process.md) to quickly validate the process behavior and play different scenarios.
+- Validate that all files and resources are correctly deployed.
+
+:::note
+Play is being rebuilt and progressively rolled out to more users. See [Play limitations and availability](/docs/components/modeler/web-modeler/play-your-process.md#limitations-and-availability) for Play limitations and why you might not see the **Play** tab.
+:::
+
+## Review
+
+After validation is complete, you can release a version of your process application for review and approval.
+
+- Use [process application versioning](process-application-versioning.md) to track and review changes across the files and assets in the process application. You can [compare milestones](/docs/components/modeler/web-modeler/milestones.md#compare-milestones) to visually review changes between two versions of a BPMN file, or view code changes for other files.
+- Use comments to make review collaboration easier.
+- Approvers can add a comment to the main process diagram to indicate that a review is complete and that the process application is ready to be promoted to the next stage.
+
+## Promote
+
+After the review is complete, you can promote the versioned process application to the next stage(s) of the deployment pipeline. For example, promote to your testing cluster/stage, then to staging, and finally to production.
+
+:::info
+If you want to use your own deployment pipeline after the review is complete, you can use [Git Sync](git-sync.md) at this point to deploy and promote the process application through your own pipeline.
+:::
+
+## Process governance
+
+The Web Modeler development lifecycle provides the following process governance:
+
+| Governance         | Description                                                                                                                                                                                                                                                                                                                                     |
+| :----------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Change control     | Users can announce a review is complete by adding a comment to the main process diagram. Governance is not enforceable, and comments can be deleted.                                                                                                                                                                                            |
+| Deployment control | <p><ul><li><p>Deployments can only be made to the pre-defined set of approved clusters.</p></li><li>Only users with correct privileges can deploy, and only organization administrators can deploy to `prod` tagged clusters.</li><li>Each deployment action is logged with information on the user and stage it was deployed to.</li></ul></p> |

docs/components/modeler/web-modeler/process-application-versioning.md

@@ -0,0 +1,41 @@
+---
+id: process-application-versioning
+title: Process application versioning
+description: Process applications allow you to deploy multiple related files together in a single bundle.
+---
+
+Although you cannot version a process application itself, you can use [bulk milestone creation](milestones.md#bulk-milestone-creation) and version tags to save a single 'versioned' snapshot of all the process application files in one action, instead of having to create separate milestones for every file.
+
+- When you create a milestone in any process application file, a milestone is also created with the same name (version tag) for all files currently available in the process application.
+
+- This allows you to track a process application through the development lifecycle and ensure the correct version is called.
+
+## A worked example
+
+In this example, you have a process application that contains multiple files as well as the main process.
+
+- You create a new milestone for the main process and enter "1.2" as the version tag.
+- When you create this new milestone, a milestone is also created for every other file and named with the same "1.2" version tag.
+- All files in the process application now have a "version 1.2" milestone.
+
+![Diagram showing an example process application bulk milestone creation](img/process-applications/process-application-milestone-diagram.png)
+
+## Create a bulk milestone
+
+To create a bulk milestone for a process application:
+
+1. Open any file in a process application and [create a milestone](milestones.md#create-a-milestone).
+1. Enter a **Version tag**.
+1. Select **Create** to create the milestone and matching version milestones for every file in the process application.
+
+![Create a milestone screen](img/milestones/web-modeler-milestone-create-versioned-milestone-highlight.png)
+
+Now when you open the milestone history for any file in the process application, you can use the file navigation header buttons to switch between files, and view their individual milestone history. See [compare milestones](/docs/components/modeler/web-modeler/milestones.md#compare-milestones).
+
+![Milestone history with file navigation header buttons highlighted](img/milestones/web-modeler-milestone-compare-process-application-files-highlight.png)
+
+:::note
+
+When naming your milestone with a version tag, you cannot edit or delete the created versions.
+
+:::