Skip to content

docs: external service orchestration sample - #702

Merged
aludwiko merged 2 commits into
mainfrom
workflow-orchestration-sample
Jul 1, 2025
Merged

aludwiko merged 2 commits into
mainfrom
workflow-orchestration-sample

Conversation

@aludwiko

Copy link
Copy Markdown
Contributor

Once again, the goal of this sample:

  • show workflow orchestration without other Akka components, for people completely not familiar with Akka but looking for some workflow engine
  • should be minimalistic and comparable to other vendors
  • present human in the loop aspect for long-running workflow

I'm not planning to use it in the docs, but I think we should add a section "calling external service" in our docs, for that, I will use the existing samples.

@github-actions github-actions Bot added documentation documentation related java-sdk labels Jun 30, 2025

@octonato octonato left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

Good idea to add a line on the documentation saying that an workflow can call any external services and is not limit to Akka components.

import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;

public class WalletService {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe good to add a note here saying that this is a dummy wallet service and is just simulating a real one.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

and that the real service could be an external service that is called with HTTP

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

docs added

@patriknw patriknw left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

looking good

}
}

public Effect<Done> acceptationTimeout() {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think "acceptation" means something else.
"acceptance" or "confirmation" ?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed

import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;

public class WalletService {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

and that the real service could be an external service that is called with HTTP

.andThen(FraudDetectionResult.class, result ->
switch (result) {
case ACCEPTED -> effects().transitionTo("withdraw");
case MANUAL_ACCEPTATION_REQUIRED -> effects()

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably grammar should make this MANUAL_ACCEPTANCE_REQUIRED

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed

switch (result) {
case ACCEPTED -> effects().transitionTo("withdraw");
case MANUAL_ACCEPTATION_REQUIRED -> effects()
.updateState(currentState().withStatus(WAITING_FOR_ACCEPTATION))

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

WAITING_FOR_ACCEPTANCE is probably a little more accurate

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed

@patriknw

patriknw commented Jun 30, 2025 •

Copy link
Copy Markdown
Contributor

I have created repo https://github.com/akka-samples/transfer-workflow-orchestration so we can sync it there in same way as the other samples.

  • update samples.adoc
  • update llms.txt
  • update akka-code-init.json
  • mention in workflows.adoc
  • add to samples pr validation
  • add pr-akka-samples.yml

java docs

Update samples/transfer-workflow-orchestration/README.md

Co-authored-by: Renato Cavalcanti <renato@cavalcanti.be>

improving smaple

docs, improving compenstation sample

PR comments
@aludwiko
aludwiko force-pushed the workflow-orchestration-sample branch from f94864e to 881fb0d Compare July 1, 2025 13:35
@aludwiko

aludwiko commented Jul 1, 2025

Copy link
Copy Markdown
Contributor Author

All comments addressed.

@patriknw patriknw left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

== Calling external services

The Workflow can be used not only to orchestrate Akka components, but also to call external services. The step `call` method can invoke an HTTP endpoint, a gRPC service, or any other service that can be called from the Java code.
The Workflow can be used not only to orchestrate Akka components, but also to call external services. The step invoke an `call` method can xref:component-and-service-calls.adoc#_external_http_services[HTTP endpoint], a xref:component-and-service-calls.adoc#_external_grpc_services[gRPC service], or any other service that can be called from the Java code.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"a call", but the sentence is also strange: "call method can HTTP endpoint"

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah, makes no sense, fixed

@aludwiko
aludwiko merged commit f4d86ae into main Jul 1, 2025
@aludwiko
aludwiko deleted the workflow-orchestration-sample branch July 1, 2025 14:20
octonato added a commit that referenced this pull request Aug 7, 2025
* docs(concepts): clarify component interoperability (#689)

* docs(concepts): clarify component interoperability

Closes: lightbend/kalix#13639

* clarify component call behavior

* Update docs/src/modules/concepts/pages/concepts.adoc

* Refine explanation of handling of concurrency and blocking.

* docs: Feedback on the getting started part descriptions (#708)

* docs: Api key as secret environment variable (#710)

* docs: external service orchestration sample (#702)

java docs

Update samples/transfer-workflow-orchestration/README.md

Co-authored-by: Renato Cavalcanti <renato@cavalcanti.be>

improving smaple

docs, improving compenstation sample

PR comments

* chore: Fix some typos in akka-code-init (#713)

Fix some typos in akka-code-init

* docs: Document down-region (#711)

* docs: akka CLI docs (#715)

* docs: understanding index page (#714)

* Update LICENSE (#718)

* docs: correct CLI version (#719)

* chore: Agent single command handler in guidelines (#723)

* docs: Add IntelliJ IA assistant instructions (#724)

* chore: Update llms.txt (#722)

* chore: Add getting started guide as tutorial

* fix broken links

* update summary text

* docs: Akka 2.10.7 in release notes (#727)

* bump: SDK version 3.4.1 (#728)

* chore: bump SDK versions to 3.4.1 (#731)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* fix: TestModelProvider should match in opposite order (#730)

* to be able to change the responses, replacing a previous response

* feat: eventing testkit should accept component class instead of component id (#729)

* chore: Add missing .bundleignore (#733)

* build: Update to new runner and use whitelist URL (#721)

* docs: Include akka code init in getting started (#725)

* chore: Adding more tests to multi-agent sample (#732)

* chore: Add PreferencesEntityTest

* chore: Add ActivityViewTest

* chore: Add ActivityEndpointIntegrationTest with end-to-end interactions

* docs: glossary format (#736)

* docs(landing-page): use agentic system concepts (#738)

Replace component-centric labels with agentic capabilities.

Closes: lightbend/kalix#13760

* docs: update component composability diagram (#739)

Closes: lightbend/kalix#13687

* docs(operations): self-managed vs automated (#734)

Introduce feature comparison table for self-managed and automated
operations.

Move service packaging content to shared partial and update its
accompanying diagram.

Closes: lightbend/kalix#13759

* docs: Improve JavaDoc of EventSourcedEntity (#741)

* docs: Improve JavaDoc of EventSourcedEntity

* immutable state

* lowercase id

* move replication

* updated code snippet

* fmt

* review feedback

Co-authored-by: Andrzej Ludwikowski <aludwiko@users.noreply.github.com>

---------

Co-authored-by: Andrzej Ludwikowski <aludwiko@users.noreply.github.com>

* docs: Improve JavaDoc of Agent (#742)

* docs: Improve JavaDoc of Agent

* human edits, and removing some code snippets

* lowercase id

* AI model

* fmt

* chore: akka code init dir (#743)

* docs: Improve JavaDoc of KeyValueEntity (#735)

* docs: Improve JavaDoc of KeyValueEntity

* human edit

* immutable state

* lowercase id

* fmt

* move immutable

* move replication

* Apply suggestions from code review

Co-authored-by: Andrzej Ludwikowski <aludwiko@users.noreply.github.com>

---------

Co-authored-by: Andrzej Ludwikowski <aludwiko@users.noreply.github.com>

* docs: Improve JavaDoc of McpEndpoint (#744)

* docs: Improve JavaDoc of McpEndpoint

* only tool in code snippet

* fmt

* chore: Update shopping cart according to coding guidelines (#740)

* chore: release notes for 3.4.1 (#746)

* docs: Improve JavaDoc of HttpEndpoint (#745)

* docs: Improve JavaDoc of HttpEndpoint

* fmt

* chore: add missing javadoc to patch annotation (#747)

* chore: bump SDK versions to 3.4.2 (#751)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* chore: Format long lines (#750)

* Update LICENSE for 3.4.2 (#749)

* Update LICENSE for 3.4.2

* Update LICENSE

Co-authored-by: Johan Andrén <johan.andren@lightbend.com>

---------

Co-authored-by: Johan Andrén <johan.andren@lightbend.com>

* chore: Update markdown in ask-akka-agent (#752)

* chore: Wait for google pubsub topic to be created before testing it (#754)

* chore: remove github-actions from mvn pom (#756)

* Update LICENSE for 3.4.3 (#758)

* chore: bump SDK versions to 3.4.3 (#761)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* docs: rearrange agentic platform products diagram (#760)

Closes: lightbend/kalix#13686

* docs: clarify project structure and components (#759)

* docs: clarify project structure and components

Reorganize information to emphasize directory structure rather than abstract layers.

Move Akka component descriptions to conceptual introduction areas of docs.

Closes: lightbend/kalix#13763

* clarify location and purpose of tool directory

* Remove tool directory from guidance.

Align guidance with samples, simplify structure and avoid confusion.

* Update docs/src/modules/concepts/pages/architecture-model.adoc

* Clarify component placement and annotations

* put ESEs first, ahead of KVEs

* expand on view definition with new sources

* link to coding guidelines

* fix link

* fix: use fake key when running integration tests (#762)

* fix: define TestModelProvider as final (#763)

* fix: define TestModelProvider as final

* Apply suggestions from code review

Co-authored-by: Peter Vlugter <59895+pvlugter@users.noreply.github.com>

---------

Co-authored-by: Peter Vlugter <59895+pvlugter@users.noreply.github.com>

* update theme UI, code snippets, white text darkmode, bullet alignments, bold styles (#770)

* chore(docs): tidy up agentic AI anatomy diagram (#768)

Minor cleanup of Consistent fonts, stroke weights, whitespace, visual
balance.

Closes: lightbend/kalix#13688

* refining the additional samples page (#767)

* refining the additional samples page

* word duplication fix

* style

* moving akka chess up, modifying init JSON

* Update docs/src/modules/getting-started/pages/samples.adoc

Co-authored-by: Brent Eritou <brent.eritou@lightbend.com>

---------

Co-authored-by: Brent Eritou <brent.eritou@lightbend.com>

* Adding inter-agent comms doc (#773)

* Adding inter-agent comms doc

* vale fix

* missed a change

* adding link to understanding index page

* Update docs/src/modules/concepts/pages/inter-agent-comms.adoc

Co-authored-by: Brent Eritou <brent.eritou@lightbend.com>

* Update docs/src/modules/concepts/pages/inter-agent-comms.adoc

Co-authored-by: Brent Eritou <brent.eritou@lightbend.com>

* Update docs/src/modules/concepts/pages/inter-agent-comms.adoc

Co-authored-by: Brent Eritou <brent.eritou@lightbend.com>

* Update docs/src/modules/concepts/pages/inter-agent-comms.adoc

Co-authored-by: Brent Eritou <brent.eritou@lightbend.com>

* Update docs/src/modules/concepts/pages/inter-agent-comms.adoc

Co-authored-by: Brent Eritou <brent.eritou@lightbend.com>

* review changes

* Update docs/src/modules/concepts/pages/inter-agent-comms.adoc

Co-authored-by: Brent Eritou <brent.eritou@lightbend.com>

* Update docs/src/modules/concepts/pages/inter-agent-comms.adoc

Co-authored-by: Brent Eritou <brent.eritou@lightbend.com>

* Update docs/src/modules/concepts/pages/inter-agent-comms.adoc

Co-authored-by: Brent Eritou <brent.eritou@lightbend.com>

* Update docs/src/modules/concepts/pages/inter-agent-comms.adoc

Co-authored-by: Brent Eritou <brent.eritou@lightbend.com>

* Update docs/src/modules/concepts/pages/inter-agent-comms.adoc

---------

Co-authored-by: Brent Eritou <brent.eritou@lightbend.com>

* Auto PR - Akka Runtime version 1.5.3 (#766)

* bump: Akka Runtime to 1.5.3

* bump akka version

---------

Co-authored-by: Renato Cavalcanti <renato@cavalcanti.io>

* chore: java formatting plugin for samples (#775)

* chore: java formatting plugin

* use indent 0 everywhere

* check formatting in CI

* Document Java formatting in a README

* samples formatting with prettier-maven-plugin

* formatting tweaks

* fixed asciidocs tags

* fix formatting in ExampleEndpoint.java

* fixed ActivityViewTest

* fixed CustomersByCity

---------

Co-authored-by: Brent Eritou <brent.eritou@lightbend.com>

* chore: add akka resolver to settings.xml (#781)

* chore: add akka resolver to settings.xml

* passing settings when formatting

* move settings.xml to .github

* using Akka-Default

* chore(docs): tidy up deploy anywhere diagram (#771)

Closes: lightbend/kalix#13690

* chore: update labeller action (#782)

* chore(docs): tidy up data diagram (#774)

Closes: lightbend/kalix#13689

* docs: reorganize and rename getting started (#772)

Rename "Getting Started" to "Tutorials".

Position RAG agent and shopping cart tutorials under tutorial nav menu.

Closes: lightbend/kalix#13786

* docs(concepts): update deployment model section (#776)

Clarify service packaging and deployment models.

Introduce new diagrams for clustering and Akka Automated Operations.

Restructure content around development, self-managed, and AAO deployment
modes.

Closes: lightbend/kalix#13790

* docs(concepts): update Saga patterns guidance (#783)

* docs(concepts): update Saga patterns guidance

Closes: lightbend/kalix#13793

* Add guidance on how system complexity scales

* Revert "chore: update labeller action (#782)" (#787)

This reverts commit 8b81180.

* list-ids replaces list-entity-ids (#794)

* fix: some more snippets width reduction (#790)

* fix: some more snippets width reduction

* applied formatting

* fix: model provider config for samples (#764)

* fix: model proving config for samples

fixing message

fixing ask akka sample

improving the hello world

final improvements

removing fix for service setup

* java fmt

* fixing typo

* docs: update tutorial labels and nav structure (#792)

Closes: lightbend/kalix#13804

Co-authored-by: Renato Cavalcanti <renato@cavalcanti.be>

* docs: trim intro in author your first service (#793)

Closes: lightbend/kalix#13805

* chore: add prettier-ignore for format control (#795)

* chore: add prettier-ignore for format control

* remove prettier-ignore from generate site

* formatting

* fix(docs): incorrect GitHub casing (#796)

* cleaning up adopt and avoid table (#798)

* docs(concepts): reduce component icon size (#799)

Closes: lightbend/kalix#13809

* docs(concepts): clarify distributed systems page (#800)

Closes: lightbend/kalix#13816

* making the AI model provider config page more dev friendly (#803)

* making the AI model provider config page more dev friendly

* vale

* adding openai to vocab

* docs(ask-akka): add alternative to run mongodb locally (#806)

* docs(ask-akka): add alternative to run mongodb locally

* clarify intro

* fmt + minor fixes

---------

Co-authored-by: Andrzej Ludwikowski <andrzej.ludwikowski@lightbend.com>

* chore: langchain deps bump (#807)

* fix: wiring service class when it doesn't extend `ServiceSetup` (#785)

* fix: wiring service class when it doesn't extend `ServiceSetup`

* reverting labeler

* reverting labeler

* reverting labeler

* labels

* labels

* labels

* labels

* labels

* testing

* testing

* testing

* reverting

* validating ServiceSetup implementation

* chore(docs): standardize ACL page headings (#808)

* chore(docs): move component interoperability (#810)

Relocate component interoperability section to follow agentic runtime
explanation.

Closes: lightbend/kalix#13823

* docs(concepts): consolidate component overview (#811)

Closes: lightbend/kalix#13824

* chore: enable multi-agent IT in CI (#812)

* chore: license bump (#814)

* chore: bump SDK versions to 3.4.4 (#815)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* latest ui bundle, fixes alignment of elements in table cells (#819)

* fix: langchain version bump (#821)

* chore: license bump 3.4.5 (#823)

* fix: mvn publish with repo config (#824)

* chore: licence bump (#825)

* chore: bump SDK versions to 3.4.6 (#826)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* chore: debugging for bundle.sh (#817)

* chore: some debugging for bundle.s

* debugging with grep

* fixing script with sed

* fixing debugging

* Be explicit on timer uniqueness

* chore: running IT for helloworld-agent sample (#816)

* docs: add memory and event sourcing to state model (#818)

* docs: add memory and event sourcing to state model

Explain how Akka uses event sourcing for memory management.

Add diagrams, workflow examples, and agent memory behavior.

Closes: lightbend/kalix#13803

* capitalize Event Sourcing

* adding small page on async (#830)

* adding small page on async

* typo

* docs(concepts): sync vs async component invocation (#836)

Closes: lightbend/kalix#13867

* docs: remove Automated Operations features list (#832)

Remove Akka Automated Operations features list page and associated
references to it.

Closes: lightbend/kalix#13864

* docs(concepts): background execution overview (#834)

Closes: lightbend/kalix#13866

* docs: fix self-managed operations table row casing (#833)

* docs(concepts): format component table as bullets (#838)

* docs(concepts): format component table as bullets

Closes: lightbend/kalix#13879

* Update docs/src/modules/concepts/pages/concepts.adoc

* docs: clarify deployment model details (#839)

Closes: lightbend/kalix#13886

* feat: introducing serializable UserException (#765)

* feat: introducing serializable UserException

docs

improvements after review

missing docs for UserException

Update docs/src/modules/java/pages/errors-and-failures.adoc

Co-authored-by: Renato Cavalcanti <renato@cavalcanti.be>

removing errors as response

* fmt and test fix

* Update akka-javasdk/src/main/scala/akka/javasdk/impl/serialization/JsonSerializer.scala

Co-authored-by: Renato Cavalcanti <renato@cavalcanti.be>

* Update akka-javasdk/src/test/scala/akka/javasdk/impl/serialization/JsonSerializationSpec.scala

Co-authored-by: Renato Cavalcanti <renato@cavalcanti.be>

* improving code and docs

* rename to CommandException

* fmt

---------

Co-authored-by: Renato Cavalcanti <renato@cavalcanti.be>

* docs: improving service desc docs (#845)

* build: fix java formatting

* apply java formatting

* fix(docs): shopping-cart sample setup instructions (#835)

Replace outdated Akka CLI download steps with reusable project creation
partial.

Ensure consistency across samples and align with initial getting started
flow.

Closes: #837

* chore: Mandatory OpenAI key (#854)

* chore: namespace in service.yml (#855)

* build: automate organize imports with scalafix (#856)

* build: automate organize imports with scalafix

* apply scalafix organize imports

* fix: done deserialization (#858)

* Auto PR - Akka Runtime version 1.5.6 (#846)

* bump: Akka Runtime to 1.5.6

* bump: akka 2.10.8

* fix exception message in tests

* fix tests

* formatting

---------

Co-authored-by: Peter Vlugter <59895+pvlugter@users.noreply.github.com>
Co-authored-by: Renato Cavalcanti <renato@cavalcanti.io>

* bump: runtime 1.5.6-9d3afc8fa

* organize imports, formatting, and compilation

* adding missing headers

* formatting with prettier-formatter

* fix compensation transfer sample

---------

Co-authored-by: Brent Eritou <brent.eritou@lightbend.com>
Co-authored-by: Patrik Nordwall <patrik.nordwall@gmail.com>
Co-authored-by: Andrzej Ludwikowski <aludwiko@users.noreply.github.com>
Co-authored-by: olofwalker <23613882+olofwalker@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Enno Runne <458526+ennru@users.noreply.github.com>
Co-authored-by: Johan Andrén <johan.andren@lightbend.com>
Co-authored-by: Justin Pihony <justin.pihony@gmail.com>
Co-authored-by: Peter Vlugter <59895+pvlugter@users.noreply.github.com>
Co-authored-by: Richard Summerhayes <rasummer@users.noreply.github.com>
Co-authored-by: Kevin Hoffman <autodidaddict@users.noreply.github.com>
Co-authored-by: Kalix Bot <81730826+kalix-bot@users.noreply.github.com>
Co-authored-by: Eduardo Pinto <eduardo.pinto@lightbend.com>
Co-authored-by: Andrzej Ludwikowski <andrzej.ludwikowski@lightbend.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation documentation related java-sdk

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants