API documentation for process management apis by Christine-Jose · Pull Request #173 · IBM/bamoe-docs

Christine-Jose · 2025-03-26T14:08:15Z

API documentation of process management REST API endpoints of workflow application in process-compact-architecture.

martinweiler · 2025-03-27T16:01:46Z

workflow/process-management.adoc

+= Management API
+include::../partials/attributes.adoc[]
+
+Process management in Kogito applications refers to the orchestration and execution of business processes and workflows, enabling the automation of complex tasks and decision-making in a cloud-native environment.


I think this sentence is too generic. To me, it does not provide much value in reference to the rest of the doc. I'd suggest to delete it.

Changes are done.

martinweiler · 2025-03-27T16:14:41Z

workflow/process-management.adoc

+
+Process management in Kogito applications refers to the orchestration and execution of business processes and workflows, enabling the automation of complex tasks and decision-making in a cloud-native environment.
+
+In Kogito, Process Management APIs are crucial for interacting with business processes, including starting, querying, and managing the lifecycle of processes. Kogito provides RESTful APIs to manage processes and tasks in workflows, leveraging its integration with jBPM for business process management (BPM) and Drools for business rule management.


please replace Kogito with {PRODUCT_SHORT}

including starting, querying, and managing the lifecycle of processes.

I don't think that all of this is possible through the Management APIs. I also wouldn't bring tasks and Drools into the picture here.

What about this?

In {PRODUCT_SHORT}, Process Management APIs are provided to interact with business process definitions and active process instances. These APIs allow to obtain metadata information about process definitions, as well as provide management endpoints for active process instances.

Changes are done.

martinweiler · 2025-03-27T16:37:38Z

workflow/process-management.adoc

+In Kogito, Process Management APIs are crucial for interacting with business processes, including starting, querying, and managing the lifecycle of processes. Kogito provides RESTful APIs to manage processes and tasks in workflows, leveraging its integration with jBPM for business process management (BPM) and Drools for business rule management.
+
+== Process Management APIs
+The kie-addons-quarkus-process-management is an extension for Kogito that integrates Quarkus with Kie (Drools and jBPM), enabling process management features for business workflows in a Quarkus-based microservice architecture. It provides the necessary infrastructure for running and managing business processes (from jBPM) and rules (from Drools) within a Kogito service on Quarkus.


Suggestion:

The kie-addons-quarkus-process-management is an extension for {PRODUCT_SHORT} that enables process management features for business workflows in a Quarkus-based microservice architecture. (remove the second sentence)

Changes updated.

martinweiler · 2025-03-27T16:56:41Z

workflow/process-management.adoc

+|===
+|*Type* |GET
+
+|*Description* | It returns the list of process names that are currently executing.


suggestion:

It returns the list of process definition names that are deployed in the runtime.

Changes are done.

martinweiler · 2025-03-27T16:57:07Z

workflow/process-management.adoc

+
+|*Inputs* |
+
+|*Output* a| A JSON List of _Process names_ that are currently executing.


same as above

Changes are done.

martinweiler · 2025-03-27T17:06:13Z

workflow/process-management.adoc

+
+|*Example* |curl -X 'GET' \
+'http://localhost:8080/management/processes' \
+-H 'accept: */*'


These examples are not rendered correctly. I'd suggest to:

surround them with +curl example+ to mark them as code

remove the \ line demarcations

Note this applies to all curl commands here, as well as in the user tasks api doc.

Added the changes for all curl commands in process-management & user task doc.

surround them with +curl example+ to mark them as code

I am sorry - this got formatted badly and sent you in the wrong direction.
What I meant to suggest were changes similar to the ones in https://github.com/IBM/bamoe-docs/pull/179/files

martinweiler · 2025-03-27T17:19:10Z

workflow/process-management.adoc

+|*Description* |It returns the complete process information of the specified processId.
+
+|*Inputs* |
+* processId: String (PathParameter)


Please make sure all the Inputs lists are properly formatted. This requires the second column to be marked as AsciiDoc (a), either in

|*Inputs* a|

or right when the table is defined:

[cols="1,1a"]

Changes are done.

martinweiler · 2025-03-27T17:35:05Z

workflow/process-management.adoc

+
+== Source File Management APIs
+Source file management in Kogito, a cloud-native business automation platform, typically involves managing files related to business process management (BPM), decision management (DMN), and other related artifacts.
+The kie-addons-quarkus-source-files extension is part of Kogito's integration with Quarkus and is primarily used for loading source files (such as BPMN, DMN, and DRL files) in a Quarkus-based Kogito project. This extension allows Kogito applications to dynamically load these source files, which are essential for executing business processes, decision tables, and rules within a Quarkus runtime.


Suggestion for an intro sentence:

The Source File Management APIs in {PRODUCT_SHORT} provides endpoints that allow users to dynamically retrieve BPMN source files at runtime. This API is provided by the kie-addons-quarkus-source-files extension.

Note:
Just FYI - the list of files that are returned by this API is defined here:
kie-addons-quarkus-source-files
and it is used here as a filter:
https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/quarkus/addons/source-files/deployment/src/main/java/org/kie/kogito/addon/source/files/deployment/KogitoAddOnSourceFilesProcessor.java#L104

That's why it doesn't make sense to add anything but BPMN here (as BAMOE doesn't support serverless workflow).

Changes are done.

martinweiler · 2025-03-27T18:04:32Z

workflow/process-management.adoc

+== Callback Jobs Service Management APIs
+
+In Kogito, Callback Jobs Service Management APIs are used to manage callback jobs, which are jobs or tasks that are triggered at a specific point in a process or workflow. These callbacks allow external systems to be notified about events occurring within the Kogito process engine or business workflows. Kogito allows users to schedule and handle jobs, including callback jobs that can invoke external systems or APIs.
+


suggestion:

In {PRODUCT_SHORT}, the Callback Jobs Service Management APIs are used to manage callbacks into the runtime engine from an external job service. These callbacks allow external systems, such as the job service, to trigger the execution of a TriggerJobCommand. If successful, the process instance linked to this command gets signalled and resumes its execution. This API is provided by the kogito-addons-quarkus-jobs-management extension.

<dependency> <groupId>org.kie</groupId> <artifactId>kogito-addons-quarkus-jobs-management</artifactId> </dependency>

NOTE: This API endpoint is not primarily intended for manual invocation.

Changes are done.

martinweiler · 2025-03-27T18:06:08Z

workflow/process-management.adoc

+-H 'Content-Type: application/json' \
+-d '"string"'
+
+|===


Please comment this whole section. As per the statement above, this is more for internal usage than for anyone invoking this endpoint manually. We might want to document it at some point, so you don't have to remove these details completely, but at this point I'd not have it in the generated docs. Thanks!

Commented the code.

martinweiler · 2025-03-27T18:30:20Z

workflow/process-management.adoc

+
+|===
+
+== Job Service Management APIs


I think we can remove the whole section. I don't see this endpoint useful in the compact architecture setup. I have created a JIRA to investigate about it's potential removal:
https://jsw.ibm.com/browse/DBACLD-172132

I think so, IMO sticking to process instance management and sources would be the best.

Removed the section.

martinweiler · 2025-03-27T18:31:14Z

Thanks for your hard work on this one @Christine-Jose - I think this is a tricky chapter, apologies for the many remarks and suggestions.

pefernan · 2025-03-27T16:59:49Z

workflow/process-management.adoc

+    <dependency>
+      <groupId>org.kie</groupId>
+      <artifactId>kie-addons-quarkus-process-management</artifactId>
+    </dependency>


Suggested change

<dependency>

<groupId>org.kie</groupId>

<artifactId>kie-addons-quarkus-process-management</artifactId>

</dependency>

[source,xml]

<dependency>

<groupId>org.kie</groupId>

<artifactId>kie-addons-quarkus-process-management</artifactId>

</dependency>

----

pefernan · 2025-03-27T17:00:59Z

workflow/process-management.adoc

+ <dependency>
+      <groupId>org.kie</groupId>
+      <artifactId>kogito-addons-quarkus-jobs-management</artifactId>
+</dependency>


Suggested change

<dependency>

<groupId>org.kie</groupId>

<artifactId>kogito-addons-quarkus-jobs-management</artifactId>

</dependency>

[source,xml]

<dependency>

<groupId>org.kie</groupId>

<artifactId>kogito-addons-quarkus-jobs-management</artifactId>

</dependency>

----

pefernan · 2025-03-27T17:01:26Z

workflow/process-management.adoc

+ <dependency>
+      <groupId>org.kie</groupId>
+      <artifactId>kie-addons-quarkus-source-files</artifactId>
+</dependency>


Suggested change

<dependency>

<groupId>org.kie</groupId>

<artifactId>kie-addons-quarkus-source-files</artifactId>

</dependency>

[source,xml]

<dependency>

<groupId>org.kie</groupId>

<artifactId>kie-addons-quarkus-source-files</artifactId>

</dependency>

----

pefernan · 2025-03-27T17:04:46Z

workflow/process-management.adoc

+|===
+|*Type* |DELETE
+
+|*Description* |It cancels the specific processInstanceId for the given processId


I think it should say something like:
It aborts a specific process instance of a given process

I see that in the endpoints descriptions you sometimes refer to processInstanceId/processId and in other process instance and process.

I'd try to use same wording, IMO process instance and process will make it more clear

Changes are done.

pefernan · 2025-03-27T20:08:32Z

workflow/process-management.adoc

+
+|===
+
+== Job Service Management APIs


I think so, IMO sticking to process instance management and sources would be the best.

Signed-off-by: christinejose <christine.jose@ibm.com>

pefernan · 2025-03-28T13:04:29Z

I'm ok with the content, not sure if the nav.adoc is right

martinweiler · 2025-03-28T21:17:45Z

Closing - this has been superseded by PR #180

josedee requested review from elguardian, martinweiler and pefernan March 26, 2025 14:32

Christine-Jose force-pushed the DBACLD-171361-process-compact-architecture branch from 7a9c385 to ce9553f Compare March 26, 2025 14:44

martinweiler reviewed Mar 27, 2025

View reviewed changes

pefernan requested changes Mar 27, 2025

View reviewed changes

Christine-Jose force-pushed the DBACLD-171361-process-compact-architecture branch from 2aa6f0f to 525933c Compare March 28, 2025 09:36

Christine-Jose added 3 commits March 28, 2025 15:11

Process Management APIs documentation

82fbf2f

Signed-off-by: christinejose <christine.jose@ibm.com>

Changes for the management api documentation

f8172d0

Signed-off-by: christinejose <christine.jose@ibm.com>

Review comments updated

3e3236b

Signed-off-by: christinejose <christine.jose@ibm.com>

Christine-Jose force-pushed the DBACLD-171361-process-compact-architecture branch from 525933c to 3e3236b Compare March 28, 2025 09:41

Christine-Jose added 4 commits March 28, 2025 16:37

updating the nav.adoc and resolving conflicts

0efb103

Merge branch '9.2.0' into DBACLD-171361-process-compact-architecture

8fbebdd

Correcting the changes after conflict resolving

a994365

updating nav.adoc

1fab8ea

pefernan approved these changes Mar 28, 2025

View reviewed changes

pefernan self-requested a review March 28, 2025 13:25

Christine-Jose mentioned this pull request Mar 28, 2025

Process Management API documentation #180

Merged

martinweiler closed this Mar 28, 2025


		Process management in Kogito applications refers to the orchestration and execution of business processes and workflows, enabling the automation of complex tasks and decision-making in a cloud-native environment.

		In Kogito, Process Management APIs are crucial for interacting with business processes, including starting, querying, and managing the lifecycle of processes. Kogito provides RESTful APIs to manage processes and tasks in workflows, leveraging its integration with jBPM for business process management (BPM) and Drools for business rule management.


		\|Inputs \|

		\|Output a\| A JSON List of _Process names_ that are currently executing.

		== Callback Jobs Service Management APIs

		In Kogito, Callback Jobs Service Management APIs are used to manage callback jobs, which are jobs or tasks that are triggered at a specific point in a process or workflow. These callbacks allow external systems to be notified about events occurring within the Kogito process engine or business workflows. Kogito allows users to schedule and handle jobs, including callback jobs that can invoke external systems or APIs.

Comments

Conversation

Christine-Jose commented Mar 26, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

martinweiler Mar 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

martinweiler commented Mar 27, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pefernan commented Mar 28, 2025

Uh oh!

martinweiler commented Mar 28, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

martinweiler Mar 27, 2025 •

edited

Loading