Skip to content

Commit

Permalink
Merge pull request #134 from mmiikkkkaa/fix-doc-typos
Browse files Browse the repository at this point in the history
zambrovski authored Nov 22, 2024
2 parents 4a3a154 + e98aeea commit 2439a00
Showing 7 changed files with 37 additions and 38 deletions.
18 changes: 9 additions & 9 deletions docs/getting-started/index.md
Original file line number Diff line number Diff line change
@@ -40,18 +40,18 @@ public class CompleteUserTaskUseCase implements CompleteUserTaskInPort {
```

As you can see, the code above doesn't contain any engine-specific code, but rather uses only code from `process-engine-api`.
This means that the resulting code is portable and the decision about used engine doesn't influence the implementation
of you application logic.
This means, that the resulting code is portable and the decision about the used engine doesn't influence the implementation
of your application logic.

The second step depends on your target architecture and used process engine. Please refer to the one of the following
The second step depends on your target architecture and used process engine. Please refer to one of the following
configurations:

## Camunda Platform 7 running as embedded engine

If you start with a Camunda Platform 7 operated in an embedded engine mode, by for example using the Camunda Spring Boot Starter,
If you start with a Camunda Platform 7, operated in an embedded engine mode, by for example using the Camunda Spring Boot Starter,
the following configuration is applicable for you.

First of all add the corresponding adapter to your project's classpath:
First of all, add the corresponding adapter to your project's classpath:

```xml
<dependency>
@@ -61,7 +61,7 @@ First of all add the corresponding adapter to your project's classpath:
</dependency>
```

and finally add the following configuration to your configuration properties. Here is a version for `application.yaml`:
and finally, add the following configuration to your configuration properties. Here is a version for `application.yaml`:

```yaml
dev:
@@ -85,7 +85,7 @@ dev:

## Camunda Platform 7 running as remote engine

If you start with a Camunda Platform 7 operated remotely, the following configuration is applicable for you.
If you start with a Camunda Platform 7, operated remotely, the following configuration is applicable for you.

First of all add the corresponding adapter to your project's classpath. In order to connect to remote engine,
you will need to use some client. Assuming you are using Camunda Hub extension [camunda-platform-7-rest-client-spring-boot](https://github.com/camunda-community-hub/camunda-platform-7-rest-client-spring-boot),
@@ -119,7 +119,7 @@ you will also need to add some additional libraries. Here is the result:

```

and finally add the following configuration to your configuration properties. Here is a version for `application.yaml`:
And finally, add the following configuration to your configuration properties. Here is a version for `application.yaml`:

```yaml
dev:
@@ -148,7 +148,7 @@ feign:

## Camunda Platform 8 as SaaS

If you start with a Camunda Platform 8 operated as SaaS, the following configuration is applicable for you.
If you start with a Camunda Platform 8, operated as SaaS, the following configuration is applicable for you.

First add the corresponding adapter to your project's classpath:

16 changes: 8 additions & 8 deletions docs/introduction/clean-architecture.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
Clean Architecture is a set of principles defined by [Uncle Bob's post back in 2012](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)
Clean Architecture is a set of principles defined by [Uncle Bob's post back in 2012](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html),
and focuses on several rules applied during system design. This principles are originally published in different architectural approaches
and are used combined to achieve some software quality values like:

@@ -11,16 +11,16 @@ Considering application of Clean Architecture principle, the architectural bluep

![Clean Architecture](../assets/img/clean-architecture.png)

There are in general multiple inbound adapters for the application, responsible for initialization of the control flow. A common one is a REST adapter offering
some endpoint for HTTP access of some frontend. There might be many other, like message consumers, but the interesting one in the context of process
applications is the WorkflowAdapter. Every time, the process orchestration needs to invoke some business functionality of our application, it would
There are, in general, multiple inbound adapters for the application, responsible for initialization of the control flow. A common one is a REST adapter offering
some endpoint for HTTP access of some frontend. There might be many other, like message consumers, but the interesting one, in the context of process
applications, is the Workflow Adapter. Every time, the process orchestration needs to invoke some business functionality of our application, it would
use this to access its implementation of a particular use case. Usually, process engines have some measures and API to register callbacks for this.

On the outbound adapter side, the application relies on different third-party technologies integrated via outbound ports. Following the dependency rule,
the application code is not allowed to reference any adapters directly. A common practice is to use Dependency Inversion to wirte the adapter implementing
the outbound port, so the use case implementation only has a reference to the outbound port and the IoC container provides the adapter implementation
at runtime. Again, the part specific to process applications is the integration of the Workflow Adapter, responsible to forwarding of all calls to the
process engine. Usually, this adapter translates the process-related operations like starting of new process instances or completion of user or service
the application code is not allowed to reference any adapters directly. A common practice is to use Dependency Inversion, to write the adapter implementing
the outbound port, so the use case implementation only has a reference to the outbound port, and the IoC container provides the adapter implementation
at runtime. Again, the part specific to process applications is the integration of the Workflow Adapter, responsible for forwarding all calls to the
process engine. Usually, this adapter translates the process-related operations, like starting of new process instances or completion of user or service
tasks to a vendor-specific process engine API.

The `Process Engine API` provides vendor-agnostic abstract API for the `Workflow Adapter` and uses a set of adapter modules, translating its invocation
15 changes: 7 additions & 8 deletions docs/introduction/index.md
Original file line number Diff line number Diff line change
@@ -1,20 +1,19 @@
Instead of learning and using of vendor-specific APIs to build your process applications, you should focus on delivering business value. Construction
of scalable, robust and future-proof applications is easy, if system components are designed to fulfill clear goals and have clear responsibilities.
This kind of architecture is called [Clean architecture](clean-architecture.md), and we recommend to follow it in general situations. In doing so, technology is hidden inside
adapters and the business and domain logic stays technology-agnostic and independent.
This kind of architecture is called [Clean architecture](clean-architecture.md), and we recommend to follow it in general situations. In doing so, technology is hidden inside adapters and the business and domain logic stays technology-agnostic and independent.

Our experience with different process engines led us to an idea to create a vendor-independent API abstracting main capabilities of a process engine.
Our experience with different process engines led us to an idea to create a vendor-independent API, abstracting main capabilities of a process engine.
In doing so, we followed several ideas:

* The API must be asynchronous
* The user should not make assumptions about the implementations of the API to stay portable if those are exchanged.
* The API offers the minimal set of capabilities instead of support all possible vendor specific product features, which have nothing to do with process orchestration.
* The API must be asynchronous.
* The user should not make assumptions about the implementations of the API, to stay portable if those are exchanged.
* The API offers the minimal set of capabilities instead of support all possible vendor-specific product features, which have nothing to do with process orchestration.
* Different aspects of process engine integration are solved using different independent APIs.
* The API is command based (you pass immutable commands indicating your intent).
* For interaction with your software, the API uses subscriptions.
* The vendor-adapters implementing APIs are drop-ins to your application classpath and your application should not depend on it (rather you can configure those independently)
* The vendor adapters implementing APIs are drop-ins to your application classpath and your application should not depend on it (rather you can configure those independently).

Having all this in mind, we provide a Process Engine API with several adapters which are ready to use in your next process application. In particular,
Having all this in mind, we provide a Process Engine API with several adapters, which are ready to use in your next process application. In particular,
you can use Process Engine API in your application and configure the adapter to use it with the following process engines / operation modes:

* Camunda Platform 7 Embedded (Spring Boot)
8 changes: 4 additions & 4 deletions docs/reference-guide/correlation-api.md
Original file line number Diff line number Diff line change
@@ -3,15 +3,15 @@ title: Correlation API
---

The Correlation API provides functionality to correlate messages with running process instances.
It is intended to be used in outbound adapters of the port/adapter architecture in order to control
It is intended to be used in outbound adapters of the port/adapter architecture, in order to control
the process engine from your application.

Message correlation denotes the ability of a process engine to continue the process execution of a process instance waiting in a catch message event
Message correlation denotes the ability of a process engine to continue the process execution of a process instance, waiting in a catch message event,
if a message with a given name is delivered to the process engine. In doing so, it requires a way to target a single process execution (otherwise the
correlation fails regarding BPMN specification).

Different engines provide different notions for targeting a single process execution. We believe that the best way to do so is not to rely on individual
engine features, but rather should be based on an approach which can be applied in any BPMN engine either message correlation based on a correlation value,
Different engines provide different notions for targeting a single process execution. We believe that the best way to do so, is not to rely on individual
engine features, but rather should be based on an approach which can be applied in any BPMN engine, either message correlation based on a correlation value,
or supporting scoped variable mapping. In both cases, it is useful to use a value of a process variable as a correlation value.

In case the engine supports correlation value, you just need to define it in your BPMN. Here is an example of doing it in Camunda 8:
8 changes: 4 additions & 4 deletions docs/reference-guide/index.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
The `process-engine-api` provides an API to abstract from concrete process engine implementation, with the ability
The `process-engine-api` provides an API to abstract from a concrete process engine implementation, with the ability
to write your application code engine-agnostic and later (re-)configure for the usage of a particular process engine.

The API consists of different parts independent of each other:
@@ -10,19 +10,19 @@ The [Deployment API](deployment-api.md) allows to deploy process-related resourc
### Process API

The [Process API](process-api.md) provides functionality, required to control the lifecycle of the processes. It allows to start new process instances.
It is intended to be used in outbound adapters of the port/adapter architecture in order to control the process engine
It is intended to be used in outbound adapters of the port/adapter architecture, in order to control the process engine
from your application.

### Correlation API

The [Correlation API](correlation-api.md) provides functionality to correlate messages with running process instances.
It is intended to be used in outbound adapters of the port/adapter architecture in order to control
It is intended to be used in outbound adapters of the port/adapter architecture, in order to control
the process engine from your application.

### Signal API

The [Signal API](signal-api.md) provides functionality to send signals to running process instances.
It is intended to be used in outbound adapters of the port/adapter architecture in order
It is intended to be used in outbound adapters of the port/adapter architecture, in order
to control the process engine from your application.

### Task Subscription API
8 changes: 4 additions & 4 deletions docs/reference-guide/process-api.md
Original file line number Diff line number Diff line change
@@ -3,12 +3,12 @@ title: Process API
---

The Process API provides functionality, required to control the lifecycle of the processes. It allows to start new process instances.
It is intended to be used in outbound adapters of the port/adapter architecture in order to control the process engine
It is intended to be used in outbound adapters of the port/adapter architecture, in order to control the process engine
from your application.

There are two ways to start processes:
- by providing a process definition key
- by providing a start message
There are two ways to start processes:
* by providing a process definition key
* by providing a start message

In both cases, you might provide a process payload passed to the started process instance.

2 changes: 1 addition & 1 deletion docs/reference-guide/signal-api.md
Original file line number Diff line number Diff line change
@@ -3,7 +3,7 @@ title: Signal API
---

The Signal API provides functionality to send signals to running process instances.
It is intended to be used in outbound adapters of the port/adapter architecture in order
It is intended to be used in outbound adapters of the port/adapter architecture, in order
to control the process engine from your application.


0 comments on commit 2439a00

Please sign in to comment.