Update "Get started with human task orchestration" guide to include Play #4401

mesellings · 2024-10-04T15:30:25Z

Description

Update the https://docs.camunda.io/docs/next/guides/orchestrate-human-tasks/ topic to include Play, milestone creation, and review as steps before running it on the cluster.

Relates to issue #4183.

When should this change go live?

This is a bug fix, security concern, or something that needs urgent release support.
This is already available but undocumented and should be released within a week.
This on a specific schedule and the assignee will coordinate a release with the DevEx team. (apply hold label or convert to draft PR)
This is part of a scheduled alpha or minor. (apply alpha or minor label)
There is no urgency with this change and can be released at any time.

PR Checklist

My changes are for an already released minor and are in /versioned_docs directory.
My changes are for the next minor and are in /docs directory (aka /next/).

My changes require an Engineering review, and I've assigned the Engineering DRI or delegate.
My changes require a technical writer review, and I've assigned @camunda/tech-writers as a reviewer.

mesellings · 2024-10-04T16:29:08Z

@conceptualshark Don't worry, I'm going to rebase this and start again on Monday - I saw your changes, so I'll need to adapt the new stuff for this - don't spend any more time on it 😄

…ecycle

github-actions · 2024-10-06T09:16:25Z

👋 🤖 🤔 Hello! Did you make your changes in all the right places?

These files were changed only in docs/. You might want to duplicate these changes in versioned_docs/version-8.6/.

docs/guides/getting-started-orchestrate-human-tasks.md
docs/guides/img/human-task-bpmn-diagram-gateway.png
docs/guides/img/human-task-bpmn-diagram-tasks.png
docs/guides/img/human-task-bpmn-diagram.png
docs/guides/img/operate-open-tasklist.png
docs/guides/img/play-chicken-complete.png
docs/guides/img/play-open-form.png
docs/guides/img/play-operate.png
docs/guides/img/play-play-button.png

You may have done this intentionally, but we wanted to point it out in case you didn't. You can read more about the versioning within our docs in our documentation guidelines.

Content has changed considerably after a merge conflict, it didn't need a review at this point

…ecycle

mesellings · 2024-10-07T16:15:45Z

This needs a review by Eric, so should not be merged - was waiting for the deploy workflow to be fixed - we can hopefully push this tomorrow

mesellings · 2024-10-07T16:41:22Z

@HanselIdes The preview environment is (finally) fixed and up for you to review:

https://preview.docs.camunda.cloud/pr-4401/docs/next/guides/orchestrate-human-tasks/

Depending on when you are able to review, we can try to get this into the release tomorrow, or push it afterwards?

…ecycle

HanselIdes

This is good progress, but fundamental updates to the user journey and differences between Desktop Modeler+C8 Run, Web Modeler SM, and Web Modeler SaaS make it difficult to follow the changes. It's probably best to group the tabs as
Desktop Modeler | Web Modeler
especially because we're uniting the UX between Web Modeler SaaS and SM

This complicates the flow and also the table of contents, where there are two step 4s

HanselIdes · 2024-10-08T07:19:11Z

docs/guides/getting-started-orchestrate-human-tasks.md


 import clsx from "clsx";
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import SaasPrereqs from './react-components/saas-prerequisites.md'
 import Install from './react-components/install-c8run.md'

-Camunda 8 allows you to orchestrate processes with human tasks of any complexity. Utilizing user tasks, you can create and assign tasks to users. Then, users can perform their work and enter the necessary data to drive the business process.
+You can use Camunda 8 to orchestrate processes with human tasks of any complexity. User tasks allow you to create and assign tasks to users, who can then perform their work and enter the required data to drive the business process.


Suggested change

You can use Camunda 8 to orchestrate processes with human tasks of any complexity. User tasks allow you to create and assign tasks to users, who can then perform their work and enter the required data to drive the business process.

You can use Camunda 8 to orchestrate processes with human tasks of any complexity. Use the user task BPMN element to create and assign tasks to users, who can then perform their work and enter the required data to drive the business process.

For the getting started with HTO guide, I'd also be interested in seeing @volodymyr-melnykc 's perspective as he's the HTO PM

HanselIdes · 2024-10-08T07:24:23Z

docs/guides/getting-started-orchestrate-human-tasks.md

@@ -100,13 +139,14 @@ To run this guide, make sure to be in **Implement** mode to specify the technica

 1. A **start event** is automatically added to the canvas. Click it to display configuration and append options.


The start event should be automatically selected- you can check this behavior on SaaS

HanselIdes · 2024-10-08T07:26:04Z

docs/guides/getting-started-orchestrate-human-tasks.md

@@ -100,13 +139,14 @@ To run this guide, make sure to be in **Implement** mode to specify the technica

 1. A **start event** is automatically added to the canvas. Click it to display configuration and append options.
 2. Click the rectangular **Append Task** icon to append a task.


These instructions should be updated to account for the new context pad. The user has to hover over the blue circle to the right, then click the rectangular append task icon. This applies for all instructions- they should be double-checked

HanselIdes · 2024-10-08T07:28:02Z

docs/guides/getting-started-orchestrate-human-tasks.md

-2. Click the blue **link icon** in the lower right corner. A menu expands that allows you to create a new form.
- <img src={ModelerFormMenuImg} style={{width: 400}} alt="Annotation to open the form menu" />
-3. Click **Create new form**. A form will be created and opened in the form editor. The form is automatically named.
+1. Click the blue **link icon** in the lower right corner. A menu expands that allows you to create a new form.


I saw this instead of the empty state

HanselIdes · 2024-10-08T07:30:28Z

docs/guides/getting-started-orchestrate-human-tasks.md

@@ -174,7 +213,7 @@ If the properties panel for your form doesn't open automatically, navigate to **

 ## Step 3: Link the form to your process


If you create a form according to these instructions, then this step is automatically completed.

HanselIdes · 2024-10-08T07:39:23Z

docs/guides/getting-started-orchestrate-human-tasks.md

+First, you must create the BPMN diagram file and project.
+
+1. Open Web Modeler, and click **New project**. Every file in Web Modeler requires a project.
+2. Select **Create new > BPMN diagram**.


For automation, users should always use process applications. They have the most features, including a smoother Play deployment experience

HanselIdes · 2024-10-08T07:39:52Z

docs/guides/getting-started-orchestrate-human-tasks.md


-### Deploy and test run
+1. Click the **Play** tab to enter Play mode.
+1. Once the Play environment is ready, click **Start a process instance** to start testing your process.


With 8.6, the user will need a cluster rather than just waiting for the Play environment.

HanselIdes · 2024-10-08T07:42:24Z

docs/guides/getting-started-orchestrate-human-tasks.md

+As well as using Play mode to quickly validate and run your process in development, you can also:
+
+- Deploy the process to a [cluster](/components/concepts/clusters.md) in other environments such as testing, staging, and production. After you deploy your process, it can be run on the cluster.
+- Run and complete the user task in [Tasklist](/components/tasklist/introduction-to-tasklist.md). Applications such as Tasklist can be used by humans to complete tasks. As well as using Play mode and Tasklist to run a process, you can call the process via the API or an inbound trigger. Read more about [run options](/components/modeler/web-modeler/run-or-publish-your-process.md).


You can follow a link to Operate...

and then a link to Tasklist if you have an open user task...

Or you can open Tasklist and it should show the open task directly

mesellings · 2024-10-08T10:54:32Z

This is good progress, but fundamental updates to the user journey and differences between Desktop Modeler+C8 Run, Web Modeler SM, and Web Modeler SaaS make it difficult to follow the changes. It's probably best to group the tabs as Desktop Modeler | Web Modeler especially because we're uniting the UX between Web Modeler SaaS and SM

This complicates the flow and also the table of contents, where there are two step 4s

Thanks @HanselIdes I'll take another look at this - I really appreciate the comprehensive feedback 👍

mesellings · 2024-10-11T15:35:01Z

@HanselIdes I've gone through the SaaS section and incorporated all your feedback - please check you are happy with the new structure, and I will move onto the SM section.

https://preview.docs.camunda.cloud/pr-4401/docs/next/guides/orchestrate-human-tasks/

I've condensed it into 3 stages: Step 1: Create and design a process, Step 2: Design and link a form, and Step 3: Run and validate your process.
I think it might be good to keep the SaaS & Web Modeler / SM Camunda 8 Run & Desktop Modeler split as it covers multiple bases for users - what do you think?

p.s. Ignore the right-hand menu for now, as it is still affected by the unchanged SM content.

HanselIdes

The one thing that must be addressed is the inaccuracy between SaaS and SM. In this guide as it's written, SM represents local development (Desktop Modeler + C8 Run), not self-managed.

docs/guides/getting-started-orchestrate-human-tasks.md

HanselIdes · 2024-10-14T09:37:37Z

docs/guides/getting-started-orchestrate-human-tasks.md

-1. A **start event** is automatically added to the canvas. Click it to display configuration and append options.
-2. Click the rectangular **Append Task** icon to append a task.
+1. A **start event** is automatically added to the canvas and selected.
+2. Append a task. For example, hover over the blue plus icon and select the **Append Task** icon from the [context pad](/components/modeler/web-modeler/context-pad.md).


Arguably, the append element option offers better discovery for automation options and fewer steps, combining step 2 and 4. @lmbateman / @nikku, do you think we should drive new users to use the append anything option?

docs/guides/getting-started-orchestrate-human-tasks.md

mesellings · 2024-10-16T09:57:51Z

@HanselIdes I've made those changes now, and other than the Append element comments, this is probably good to go for a final review?

In summary, I changed language to Desktop/Web as suggested, added a context pad link, and removed some heading elements from the Desktop validate section to avoid them appearing in the right-hand TOC (until we can fix this so it takes tabbed content into context).

HanselIdes

LGTM!

HanselIdes · 2024-10-17T12:25:13Z

docs/guides/getting-started-orchestrate-human-tasks.md

- Select **Self-Managed** to see an example using Camunda 8 Run and Desktop Modeler.
- Select **SaaS** to see an example using Camunda 8 SaaS and Web Modeler.
+- Select **Desktop** to see an example using Camunda 8 Run and Desktop Modeler in a local development environment.
+- Select **Web** to see an example using Camunda 8 SaaS and Web Modeler.


Web Modeler Self-Managed is excluded, but that's appropriate for this stage of the journey

conceptualshark

My lingering question here is why the addition of Play changes the Web Modeler section of this guide into "validate with Play" as the end result, and not completing and checking on the task in Tasklist and Operate.

I don't think this guide should solely walk a user through building a model and using Play for initial validation. Presenting options for understanding how that process moves through/works with Operate and Tasklist is an equally important end result.

conceptualshark · 2024-10-18T15:42:23Z

docs/guides/getting-started-orchestrate-human-tasks.md

 <Tabs groupId="install" defaultValue="saas" queryString values={
 [
-{label: 'Self-Managed', value: 'sm' },
-{label: 'SaaS', value: 'saas' },
+{label: 'Desktop', value: 'sm' },


Would it be beneficial for these to read more descriptively/match the description above? "SaaS and Web Modeler" | "Self-Managed and Desktop Modeler". As labels, they're short enough to scroll by right now, and if SaaS vs SM didn't entirely capture the paths here, I don't think Desktop vs Web does either.

Per Eric's point, I don't want the implication to be that these are exclusive methods for either version, but I do think we should align with the current Getting Started experience defining SaaS and SM as the modes of moving through the guides.

conceptualshark · 2024-10-18T15:51:44Z

docs/guides/getting-started-orchestrate-human-tasks.md

+
+In this example, you will learn how to:
+
+- Create and run your first process with a human in the loop.


I like the later wording of "route (a) process flow based on a user decision." "A human in the loop" still feels ambiguous; not blocking, but I'm not sure if a more descriptive task here would be helpful, though we describe the action enough otherwise so it may just be me.

docs/guides/getting-started-orchestrate-human-tasks.md

conceptualshark · 2024-10-18T16:10:36Z

docs/guides/getting-started-orchestrate-human-tasks.md


-### Create a new file
+Start by creating and designing a process to demonstrate how to route the process flow based on a user decision. In this example, you will create a process to decide what to eat for dinner.


Suggested change

Start by creating and designing a process to demonstrate how to route the process flow based on a user decision. In this example, you will create a process to decide what to eat for dinner.

To learn how to route a process flow based on a user decision, you will create and design a process to decide what to eat for dinner.

conceptualshark · 2024-10-18T16:27:46Z

docs/guides/getting-started-orchestrate-human-tasks.md

-5. Select the user task and click on the diamond-shaped icon to append an exclusive gateway. The gateway allows to route the process flow differently, depending on conditions.
-6. Select the gateway and append a task by clicking the task icon. Repeat it to create a second process flow. Name the tasks based on what the user decides to eat: in this case, we've named ours `Prepare chicken` and `Prepare salad`.
+1. A **start event** is automatically added to the canvas and selected.
+2. Append a task. For example, hover over the blue plus icon and select the **Append Task** icon from the [context pad](/components/modeler/web-modeler/context-pad.md).


Context pad is more useful for the SaaS/web modeler side of things and not the same experience in desktop. If this section is swapped to Append element instead (and the context pad reference removed), it brings it back in line with the Desktop experience and would remove the need for another set of split/tabbed content.

docs/guides/getting-started-orchestrate-human-tasks.md

HanselIdes · 2024-10-20T20:57:52Z

My lingering question here is why the addition of Play changes the Web Modeler section of this guide into "validate with Play" as the end result, and not completing and checking on the task in Tasklist and Operate.

I don't think this guide should solely walk a user through building a model and using Play for initial validation. Presenting options for understanding how that process moves through/works with Operate and Tasklist is an equally important end result.

@conceptualshark The goal mentioned in the guide says:
"This guide introduces you to the basics of human task orchestration. You will create a simple process to decide on what to eat for dinner, and drive the process flow according to that decision."

The best way to "drive the process flow" is through Play. It requires no navigation, and the additional features that Tasklist has (assignee, priority, process visualization) are unnecessary and perhaps distracting. I think it makes sense to mention that you can also go through Operate and Tasklist, but it is not necessary to achieve the stated goal.

If you believe the "get started" guides should feature Operate and Tasklist, then we can talk about changing their goal. Within the PM team, the focus has been around getting to 'hello world'. When I learned Python scripting (which is my background- I'm not a pro dev here), "hello world" happens in the console within a second of writing or editing the code with as little context change as possible.

Co-authored-by: Cole Isaac <82131455+conceptualshark@users.noreply.github.com>

github-actions · 2024-10-21T13:43:35Z

The preview environment relating to the commit 86b4640 has successfully been deployed. You can access it at https://preview.docs.camunda.cloud/pr-4401/index.html

mesellings added 3 commits October 2, 2024 14:21

Initial edits

6d4c5ce

Draft changes

081fc4a

Initial draft

f7d7026

mesellings self-assigned this Oct 4, 2024

mesellings changed the title ~~Update get started with human task orchestration to include Play~~ Update "Get started with human task orchestration" guide to include Play Oct 4, 2024

This comment was marked as outdated.

Sign in to view

Merge branch 'main' into mes-4183-update-getting-started-with-dev-lif…

9af30e5

…ecycle

TW edits for SaaS and SM

2d56593

Merge branch 'main' into mes-4183-update-getting-started-with-dev-lif…

aaf40f4

…ecycle

mesellings added the hold This issue is parked, do not merge. label Oct 7, 2024

akeller requested a review from HanselIdes October 7, 2024 16:19

github-actions bot temporarily deployed to camunda-docs October 7, 2024 16:31 Destroyed

Merge branch 'main' into mes-4183-update-getting-started-with-dev-lif…

f40fb63

…ecycle

github-actions bot temporarily deployed to camunda-docs October 7, 2024 18:31 Destroyed

HanselIdes requested changes Oct 8, 2024

View reviewed changes

mesellings added 2 commits October 11, 2024 16:00

TW review edits for SaaS

262751a

Fix admonition formatting

b37f8ee

github-actions bot temporarily deployed to camunda-docs October 11, 2024 15:22 Destroyed

HanselIdes requested changes Oct 14, 2024

View reviewed changes

Change to Desktop/Web, add context pad link, remove Desktop headings

80499b9

github-actions bot temporarily deployed to camunda-docs October 16, 2024 10:11 Destroyed

HanselIdes previously approved these changes Oct 17, 2024

View reviewed changes

conceptualshark mentioned this pull request Oct 17, 2024

Add Self-Managed install steps to API Orchestration GSG #4000

Open

mesellings requested a review from conceptualshark October 18, 2024 13:29

conceptualshark requested changes Oct 18, 2024

View reviewed changes

Update docs/guides/getting-started-orchestrate-human-tasks.md

8878ef7

Co-authored-by: Cole Isaac <82131455+conceptualshark@users.noreply.github.com>

mesellings dismissed HanselIdes’s stale review via 8878ef7 October 21, 2024 13:10

mesellings and others added 3 commits October 21, 2024 08:15

Update docs/guides/getting-started-orchestrate-human-tasks.md

493d43c

Co-authored-by: Cole Isaac <82131455+conceptualshark@users.noreply.github.com>

Update docs/guides/getting-started-orchestrate-human-tasks.md

5805441

Co-authored-by: Cole Isaac <82131455+conceptualshark@users.noreply.github.com>

Update docs/guides/getting-started-orchestrate-human-tasks.md

3298504

Co-authored-by: Cole Isaac <82131455+conceptualshark@users.noreply.github.com>

github-actions bot temporarily deployed to camunda-docs October 21, 2024 13:36 Destroyed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update "Get started with human task orchestration" guide to include Play #4401

Update "Get started with human task orchestration" guide to include Play #4401

mesellings commented Oct 4, 2024

This comment was marked as outdated.

mesellings commented Oct 4, 2024

github-actions bot commented Oct 6, 2024 •

edited

Loading

mesellings commented Oct 7, 2024

mesellings commented Oct 7, 2024

HanselIdes left a comment

HanselIdes Oct 8, 2024

HanselIdes Oct 8, 2024

HanselIdes Oct 8, 2024

HanselIdes Oct 8, 2024

HanselIdes Oct 8, 2024

HanselIdes Oct 8, 2024

HanselIdes Oct 8, 2024

HanselIdes Oct 8, 2024

mesellings commented Oct 8, 2024

mesellings commented Oct 11, 2024

HanselIdes left a comment

HanselIdes Oct 14, 2024

mesellings commented Oct 16, 2024

HanselIdes left a comment

HanselIdes Oct 17, 2024

conceptualshark left a comment

conceptualshark Oct 18, 2024

conceptualshark Oct 18, 2024

conceptualshark Oct 18, 2024

conceptualshark Oct 18, 2024

HanselIdes commented Oct 20, 2024

github-actions bot commented Oct 21, 2024

	You can use Camunda 8 to orchestrate processes with human tasks of any complexity. User tasks allow you to create and assign tasks to users, who can then perform their work and enter the required data to drive the business process.
	You can use Camunda 8 to orchestrate processes with human tasks of any complexity. Use the user task BPMN element to create and assign tasks to users, who can then perform their work and enter the required data to drive the business process.

		@@ -100,13 +139,14 @@ To run this guide, make sure to be in Implement mode to specify the technica

		1. A start event is automatically added to the canvas. Click it to display configuration and append options.

		@@ -100,13 +139,14 @@ To run this guide, make sure to be in Implement mode to specify the technica

		1. A start event is automatically added to the canvas. Click it to display configuration and append options.
		2. Click the rectangular Append Task icon to append a task.

		@@ -174,7 +213,7 @@ If the properties panel for your form doesn't open automatically, navigate to **

		## Step 3: Link the form to your process


		In this example, you will learn how to:

		- Create and run your first process with a human in the loop.


		### Create a new file
		Start by creating and designing a process to demonstrate how to route the process flow based on a user decision. In this example, you will create a process to decide what to eat for dinner.

	Start by creating and designing a process to demonstrate how to route the process flow based on a user decision. In this example, you will create a process to decide what to eat for dinner.
	To learn how to route a process flow based on a user decision, you will create and design a process to decide what to eat for dinner.

Update "Get started with human task orchestration" guide to include Play #4401

Are you sure you want to change the base?

Update "Get started with human task orchestration" guide to include Play #4401

Conversation

mesellings commented Oct 4, 2024

Description

When should this change go live?

PR Checklist

This comment was marked as outdated.

mesellings commented Oct 4, 2024

github-actions bot commented Oct 6, 2024 • edited Loading

mesellings commented Oct 7, 2024

mesellings commented Oct 7, 2024

HanselIdes left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mesellings commented Oct 8, 2024

mesellings commented Oct 11, 2024

HanselIdes left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mesellings commented Oct 16, 2024

HanselIdes left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

conceptualshark left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

HanselIdes commented Oct 20, 2024

github-actions bot commented Oct 21, 2024

github-actions bot commented Oct 6, 2024 •

edited

Loading