First two chapters of getting started added - #738
Open
thomasek wants to merge 1 commit into
Open
Conversation
📝 WalkthroughWalkthroughThe Getting Started documentation is reorganized into sequential engine, BPMN process, and human-task tutorials. Client library guidance is rewritten for current REST and gRPC APIs, while BPM concepts links are updated to the new tutorial route. ChangesGetting Started documentation
Estimated code review effort: 3 (Moderate) | ~25 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (1)
docs/static/client-libraries.md (1)
149-153: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick winKeep the gRPC example on the same version as
zenbpm-client-core. The docs example pinsgrpc-netty-shadedto1.80.0, whilezenbpm-client-coreuses1.78.0. Use a shared${grpc.version}property or import the gRPC BOM so copy-paste users don’t end up with mixed gRPC artifacts.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/static/client-libraries.md` around lines 149 - 153, Update the gRPC dependency example in the client library documentation to use the same version as zenbpm-client-core by referencing a shared ${grpc.version} property or importing the gRPC BOM instead of pinning grpc-netty-shaded to 1.80.0. Ensure copy-paste users receive consistent versions across all gRPC artifacts.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/static/client-libraries.md`:
- Around line 291-294: Update the DEBUG logging description in the
client-library documentation to accurately reflect each client’s behavior: REST
DEBUG uses BASIC logging, while gRPC DEBUG logs worker metadata rather than
request/response headers. Keep TRACE documented as exposing full request and
response bodies with its existing production warning.
- Around line 228-230: Update the Java examples in the
CreateProcessInstanceRequest snippets, including the example around
processDefinitionKey and the one near the other referenced section, to replace
Java 9-only Map.of usage with a Java 8-compatible Collections.singletonMap or
HashMap approach. Keep the examples’ existing variables and request construction
behavior unchanged.
In `@docs/tutorials/getting-started/orchestrate-human-tasks.mdx`:
- Around line 72-100: The Java and Go examples in
docs/tutorials/getting-started/orchestrate-human-tasks.mdx at lines 72-100,
123-135, and 159-172 must be self-contained: add shared client/context
initialization and job-key extraction once near the initial getJobs examples,
then reuse those symbols in the assign and complete examples instead of assuming
zenbpm, ctx, restClient, or jobKey already exist. Keep the existing generated
method and DTO names unchanged.
---
Nitpick comments:
In `@docs/static/client-libraries.md`:
- Around line 149-153: Update the gRPC dependency example in the client library
documentation to use the same version as zenbpm-client-core by referencing a
shared ${grpc.version} property or importing the gRPC BOM instead of pinning
grpc-netty-shaded to 1.80.0. Ensure copy-paste users receive consistent versions
across all gRPC artifacts.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: c1ae5ec8-00ba-46b2-8b59-84d7d7f04ede
⛔ Files ignored due to path filters (2)
docs/tutorials/assets/images/approval-process.svgis excluded by!**/*.svgdocs/tutorials/assets/images/first-bpmn-process.svgis excluded by!**/*.svg
📒 Files selected for processing (7)
docs/explanation/bpm-concepts.mddocs/static/client-libraries.mddocs/tutorials/getting-started.mdxdocs/tutorials/getting-started/_category_.jsondocs/tutorials/getting-started/first-bpmn-process.mdxdocs/tutorials/getting-started/orchestrate-human-tasks.mdxdocs/tutorials/getting-started/run-the-engine.mdx
💤 Files with no reviewable changes (1)
- docs/tutorials/getting-started.mdx
Comment on lines
228
to
+230
| CreateProcessInstanceRequest req = new CreateProcessInstanceRequest() | ||
| .processDefinitionKey(123456L) | ||
| .variables(vars); | ||
| .processDefinitionKey(definitionKey) | ||
| .variables(Map.of("orderId", 12345L)); |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
curl -fsSL https://raw.githubusercontent.com/pbinitiative/zenbpm-java-client/main/pom.xml \
| rg -n '<java.version>'
rg -n 'Map\.of|older Java versions' docs/static/client-libraries.mdRepository: pbinitiative/zenbpm
Length of output: 420
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
sed -n '216,270p' docs/static/client-libraries.md | cat -nRepository: pbinitiative/zenbpm
Length of output: 2558
Keep these examples Java 8-compatible (docs/static/client-libraries.md:228-230,259). Map.of requires Java 9, but the client still targets Java 8. Use Collections.singletonMap/HashMap, or scope the examples to Java 9+.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/static/client-libraries.md` around lines 228 - 230, Update the Java
examples in the CreateProcessInstanceRequest snippets, including the example
around processDefinitionKey and the one near the other referenced section, to
replace Java 9-only Map.of usage with a Java 8-compatible
Collections.singletonMap or HashMap approach. Keep the examples’ existing
variables and request construction behavior unchanged.
Comment on lines
+291
to
+294
| Logging verbosity is controlled through standard Spring logging levels, configured **per client** (`org.pbinitiative.zenbpm.rest`, `org.pbinitiative.zenbpm.grpc`): | ||
|
|
||
| - `DEBUG` — exposes request/response headers. | ||
| - `TRACE` — exposes full request and response **bodies**. **Never use `TRACE` in production**; it can leak sensitive data. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Correct the DEBUG logging description.
The REST client uses BASIC logging at DEBUG and BODY logging only at TRACE; the gRPC manager logs worker metadata rather than request/response headers. The current wording overstates what DEBUG exposes. (raw.githubusercontent.com)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/static/client-libraries.md` around lines 291 - 294, Update the DEBUG
logging description in the client-library documentation to accurately reflect
each client’s behavior: REST DEBUG uses BASIC logging, while gRPC DEBUG logs
worker metadata rather than request/response headers. Keep TRACE documented as
exposing full request and response bodies with its existing production warning.
Comment on lines
+72
to
+100
| ```java | ||
| // JobApi is generated from the OpenAPI spec; construct it with the ApiClient. | ||
| // verify: exact method/param names against the generated JobApi. | ||
| JobApi jobApi = new JobApi(zenbpm.getApiClient()); | ||
| JobPartitionPage jobs = jobApi.getJobs( | ||
| /* processInstanceKey */ null, | ||
| /* jobType */ "user-task", | ||
| /* assignee */ null, | ||
| /* state */ "active", | ||
| /* page */ 1, | ||
| /* size */ 10, | ||
| /* sortBy */ null, | ||
| /* sortOrder */ null | ||
| ); | ||
| ``` | ||
|
|
||
| </TabItem> | ||
| <TabItem value="go" label="Go"> | ||
|
|
||
| ```go | ||
| // verify: exact params/struct names against the generated zenclient. | ||
| restClient, _ := zenclient.NewClient("http://localhost:8080/v1") | ||
| jobType := "user-task" | ||
| state := zenclient.JobStateActive | ||
| resp, _ := restClient.GetJobs(ctx, &zenclient.GetJobsParams{ | ||
| JobType: &jobType, | ||
| State: &state, | ||
| }) | ||
| ``` |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Locate generated API contracts and client implementations.
fd -t f . | rg '(openapi|swagger|JobApi|zenclient|\.proto$)' || true
# Inspect the exact operations and request types documented by the tutorial.
rg -n -C 3 \
'getJobs|assignJob|completeJob|AssignJob|CompleteJob|GetJobsParams|func .*GetJobs|func .*AssignJob|func .*CompleteJob' \
. || trueRepository: pbinitiative/zenbpm
Length of output: 50376
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Inspect the tutorial around the affected snippets for surrounding setup/context.
sed -n '1,220p' docs/tutorials/getting-started/orchestrate-human-tasks.mdx
# Check the generated client signatures and request/response types directly.
rg -n -C 2 'type GetJobsParams|func .*GetJobsWithResponse|func .*GetJobs\(|type AssignJobJSONRequestBody|type CompleteJobJSONRequestBody|func .*AssignJob\(|func .*CompleteJob\(' internal test . || true
# Look for any earlier definitions of the allegedly missing tutorial variables.
rg -n -C 2 'zenbpm|restClient|ctx|jobKey' docs/tutorials/getting-started/orchestrate-human-tasks.mdx || trueRepository: pbinitiative/zenbpm
Length of output: 37609
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Check whether the tutorial page defines the allegedly missing identifiers elsewhere.
rg -n -C 2 '\bzenbpm\b|\brestClient\b|\bctx\b|\bjobKey\b' docs/tutorials/getting-started/orchestrate-human-tasks.mdx || true
# Inspect the generated Go client method signatures used by the tutorial.
sed -n '1538,1610p' pkg/zenclient/zz_generated.go
sed -n '906,930p' pkg/zenclient/zz_generated.go
sed -n '1218,1230p' pkg/zenclient/zz_generated.goRepository: pbinitiative/zenbpm
Length of output: 6454
Make the examples self-contained. These snippets still assume zenbpm, ctx, restClient, and jobKey exist; add the shared client/context setup and job-key extraction once, then reuse it in the assign/complete examples. The generated method and DTO names here already match the client.
📍 Affects 1 file
docs/tutorials/getting-started/orchestrate-human-tasks.mdx#L72-L100(this comment)docs/tutorials/getting-started/orchestrate-human-tasks.mdx#L123-L135docs/tutorials/getting-started/orchestrate-human-tasks.mdx#L159-L172
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/tutorials/getting-started/orchestrate-human-tasks.mdx` around lines 72 -
100, The Java and Go examples in
docs/tutorials/getting-started/orchestrate-human-tasks.mdx at lines 72-100,
123-135, and 159-172 must be self-contained: add shared client/context
initialization and job-key extraction once near the initial getJobs examples,
then reuse those symbols in the assign and complete examples instead of assuming
zenbpm, ctx, restClient, or jobKey already exist. Keep the existing generated
method and DTO names unchanged.
klajmajk
requested changes
Jul 27, 2026
klajmajk
left a comment
klajmajk
left a comment
Member
There was a problem hiding this comment.
In addition to my comments please check that all the links are relative.
if the links are not relative it will not hold selected version
Member
There was a problem hiding this comment.
Please use webmodeler created process.
Member
There was a problem hiding this comment.
I would drop the border for both the images
Member
There was a problem hiding this comment.
Well I would move this one level up and for now drop the tutorials.
|
|
||
| ## Next steps {#next-steps} | ||
|
|
||
| - **Understand the model.** [BPM Concepts](/explanation/bpm-concepts) — definitions, instances, tokens, and the job/worker mechanic in one short read. |
| - **A realistic process.** The [Commission Payout example](https://github.com/pbinitiative/zenbpm-examples/tree/main/examples/processes/02-commission-payout) adds user tasks and an exclusive gateway. | ||
| - **More workers.** [`examples/workers/`](https://github.com/pbinitiative/zenbpm-examples/tree/main/examples/workers) shows several workers in one Go project. | ||
| - **The APIs in full.** [REST (OpenAPI)](/static/openapi) and the [gRPC proto](/zenbpm.proto). | ||
| - **Engine internals.** [Architecture](/category/architecture). |
Member
There was a problem hiding this comment.
I would rather link to servicetask page reference/bpmn/supported-elements/activities/tasks/service-task
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary by CodeRabbit
New Features
Documentation