Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update the Spring developer guide #4301

Merged
merged 11 commits into from
Oct 8, 2024
Merged

Update the Spring developer guide #4301

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
55fb0ee
Update the Spring developer guide
camundom Sep 13, 2024
cd006a9
Modified to a relative URL
camundom Sep 13, 2024
7462322
minor grammatical tweak
christinaausley Sep 16, 2024
9a3ea6a
remove non-prod note, adjust greenfield link
akeller Sep 24, 2024
f4fa19a
fix FEEL link
akeller Sep 24, 2024
cef3bd8
Merge branch 'main' into 4300-update-the-spring-developer-guide-to-in…
akeller Sep 25, 2024
1b3ea21
Update getting-started-java-spring.md
camundom Sep 27, 2024
e016e1c
Merge branch 'main' into 4300-update-the-spring-developer-guide-to-in…
akeller Oct 7, 2024
566ef17
Removed download links temporarily
camundom Oct 8, 2024
7b16b5c
Merge branch 'main' into 4300-update-the-spring-developer-guide-to-in…
christinaausley Oct 8, 2024
90c3e68
backport
christinaausley Oct 8, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 33 additions & 24 deletions docs/guides/getting-started-java-spring.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,6 @@ import Install from './react-components/install-c8run.md'
<span class="badge badge--beginner">Beginner</span>
<span class="badge badge--medium">1 hour</span><br /><br />

:::note
This tutorial is not intended for production purposes.
:::

In this guide, we'll step through using Spring Boot and the [Spring Zeebe SDK](/apis-tools/spring-zeebe-sdk/getting-started.md) with Desktop Modeler to interact with your local Self-Managed Camunda 8 installation. While this guide focuses on Self-Managed, you can do something similar with [SaaS](https://signup.camunda.com/accounts?utm_source=docs.camunda.io&utm_medium=referral).

:::note
Expand All @@ -35,16 +31,26 @@ For example, in this guide we will outline a BPMN model to receive a payment req
While stepping through this guide, you can visit our [sample repository](https://github.com/camunda/camunda-8-get-started-spring/blob/main/src/main/java/io/camunda/demo/process_payments/ChargeCreditCardWorker.java) with the completed code to check your work.
:::

## Step 1: Install Camunda 8 Self-Managed
## Prerequisites

Before getting started, ensure you have the following in your local environment:

<Install/>
- Access to your preferred code editor or IDE
- [OpenJDK 21+](https://openjdk.org/install/)
- Camunda 8 Desktop Modeler and Camunda 8 Run
Copy link
Contributor

Choose a reason for hiding this comment

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

Can we link to the docs for both here?

Copy link
Contributor

Choose a reason for hiding this comment

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

I will incorporate this in a separate PR @conceptualshark 👍


:::note
After installing OpenJDK, ensure `JAVA_HOME` is set by running `java -version` in a **new** terminal.

If no version of Java is found, follow your chosen installation's instructions for setting `JAVA_HOME` before continuing.
:::

## Step 2: Create a new Spring Boot project
## Step 1: Create a new Spring Boot project

Next, create a new Spring Boot project:

1. Go to [https://start.spring.io/](https://start.spring.io/) to get started.
2. Under **Project**, select **Maven**. Under **Language**, select **Java**. Under **Spring Boot**, select the latest non-SNAPSHOT version (currently 3.3.0).
2. Under **Project**, select **Maven**. Under **Language**, select **Java**. Under **Spring Boot**, select the latest non-SNAPSHOT version (currently 3.3.3).
3. Under **Project Metadata**, configure the following:
1. **Group**: `io.camunda.demo`
2. **Artifact**: `process_payments`
Expand All @@ -57,27 +63,30 @@ Next, create a new Spring Boot project:
4. Click **Generate**.
5. Download the project, extract the `.zip` file, and add the contents to your desired location.
6. Open this project in your preferred code editor.
7. Run `mvn spring-boot:run` in your terminal to confirm your Spring project builds.
7. From within the extracted directory, run `mvn spring-boot:run` in your terminal to confirm your Spring project builds.
8. (Optional) Run `git init` if you'd like to commit milestones along the way, and add a `.gitignore` file containing `target/` to ignore build artifacts.

## Step 3: Create a new BPMN diagram
## Step 2: Create a new BPMN diagram

Next, we'll create a BPMN diagram to represent the transaction model shown at the beginning of this guide:

1. Open Desktop Modeler.
2. Click **Create a new diagram** in Camunda 8, and name your diagram `Process payments` with an id of `process-payments`.
3. Add a start event, and name it `Payment request received`.
4. Append a task named `Prepare transaction`.
5. Click the wrench-shaped change type context menu icon to change the type of task to a script task, and configure the following properties:
1. **Implementation**: `FEEL expression`
2. Click **Create a new diagram** in Camunda 8.
3. In the Properties panel, under the General section:
- Name your diagram `Process payments`
- Set the ID to `process-payments`
4. Add a start event, and name it `Payment request received`.
5. Append a task named `Prepare transaction`.
6. Click the wrench-shaped change type context menu icon to change the type of task to a script task, and configure the following properties:
1. **Implementation**: `FEEL expression` [What is FEEL?](/components/modeler/feel/what-is-feel.md)
2. **Script/Result variable**: `totalWithTax`
3. **Script/FEEL expression**: `total * 1.1` (this represents the tax applied to the transaction.)
6. Append a task named `Charge credit card`.
7. Click on the task and click the wrench-shaped icon to change the type of task to a service task. In the properties panel, change the **Task definition/Type** to `charge-credit-card`.
8. Append an end event named `Payment executed`.
9. Save this BPMN file to your Spring project in `src/main/resources`, and name it `process-payments.bpmn`.
7. Append a task named `Charge credit card`.
8. Click on the task and click the wrench-shaped icon to change the type of task to a service task. In the properties panel, change the **Task definition/Type** to `charge-credit-card`.
9. Append an end event named `Payment executed`.
10. Save this BPMN file to your Spring project in `src/main/resources`, and name it `process-payments.bpmn`.

## Step 4: Deploy your process
## Step 3: Deploy your process

To deploy your process, take the following steps:

Expand All @@ -88,7 +97,7 @@ To deploy your process, take the following steps:

When you open Operate at http://localhost:8080/operate/, you should now note the process deployed to your local Self-Managed setup.

## Step 5: Run your process from Modeler
## Step 4: Run your process from Modeler

To run your process, take the following steps:

Expand All @@ -98,7 +107,7 @@ To run your process, take the following steps:

From Operate, you should now notice a process instance running. You'll notice the process instance is waiting at **Charge credit card**, because we'll need to configure a job worker.

## Step 6: Implement a service task
## Step 5: Implement a service task

To implement a service task, take the following steps:

Expand Down Expand Up @@ -182,7 +191,7 @@ To check your work, visit our [sample repository](https://github.com/camunda/cam

In your terminal, run `mvn spring-boot:run`, where you should see the `charging credit card` output. In Operate, refresh if needed, and note the payment has executed.

## Step 7: Start a process instance
## Step 6: Start a process instance

To start a process instance programmatically, take the following steps:

Expand Down Expand Up @@ -242,7 +251,7 @@ To check your work, visit our [sample repository](https://github.com/camunda/cam

Re-run the application in your terminal with `mvn spring-boot:run` to see the process run, and note the instance history in Operate.

## Step 8: Deploy the process
## Step 7: Deploy the process

To deploy your process, take the following steps:

Expand Down
91 changes: 50 additions & 41 deletions versioned_docs/version-8.6/guides/getting-started-java-spring.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,6 @@ import Install from './react-components/install-c8run.md'
<span class="badge badge--beginner">Beginner</span>
<span class="badge badge--medium">1 hour</span><br /><br />

:::note
This tutorial is not intended for production purposes.
:::

In this guide, we'll step through using Spring Boot and the [Spring Zeebe SDK](/apis-tools/spring-zeebe-sdk/getting-started.md) with Desktop Modeler to interact with your local Self-Managed Camunda 8 installation. While this guide focuses on Self-Managed, you can do something similar with [SaaS](https://signup.camunda.com/accounts?utm_source=docs.camunda.io&utm_medium=referral).

:::note
Expand All @@ -35,16 +31,26 @@ For example, in this guide we will outline a BPMN model to receive a payment req
While stepping through this guide, you can visit our [sample repository](https://github.com/camunda/camunda-8-get-started-spring/blob/main/src/main/java/io/camunda/demo/process_payments/ChargeCreditCardWorker.java) with the completed code to check your work.
:::

## Step 1: Install Camunda 8 Self-Managed
## Prerequisites

Before getting started, ensure you have the following in your local environment:

<Install/>
- Access to your preferred code editor or IDE
- [OpenJDK 21+](https://openjdk.org/install/)
- Camunda 8 Desktop Modeler and Camunda 8 Run

:::note
After installing OpenJDK, ensure `JAVA_HOME` is set by running `java -version` in a **new** terminal.

If no version of Java is found, follow your chosen installation's instructions for setting `JAVA_HOME` before continuing.
:::

## Step 2: Create a new Spring Boot project
## Step 1: Create a new Spring Boot project

Next, create a new Spring Boot project:

1. Go to [https://start.spring.io/](https://start.spring.io/) to get started.
2. Under **Project**, select **Maven**. Under **Language**, select **Java**. Under **Spring Boot**, select the latest non-SNAPSHOT version (currently 3.3.0).
2. Under **Project**, select **Maven**. Under **Language**, select **Java**. Under **Spring Boot**, select the latest non-SNAPSHOT version (currently 3.3.3).
3. Under **Project Metadata**, configure the following:
1. **Group**: `io.camunda.demo`
2. **Artifact**: `process_payments`
Expand All @@ -57,27 +63,30 @@ Next, create a new Spring Boot project:
4. Click **Generate**.
5. Download the project, extract the `.zip` file, and add the contents to your desired location.
6. Open this project in your preferred code editor.
7. Run `mvn spring-boot:run` in your terminal to confirm your Spring project builds.
7. From within the extracted directory, run `mvn spring-boot:run` in your terminal to confirm your Spring project builds.
8. (Optional) Run `git init` if you'd like to commit milestones along the way, and add a `.gitignore` file containing `target/` to ignore build artifacts.

## Step 3: Create a new BPMN diagram
## Step 2: Create a new BPMN diagram

Next, we'll create a BPMN diagram to represent the transaction model shown at the beginning of this guide:

1. Open Desktop Modeler.
2. Click **Create a new diagram** in Camunda 8, and name your diagram `Process payments` with an id of `process-payments`.
3. Add a start event, and name it `Payment request received`.
4. Append a task named `Prepare transaction`.
5. Click the wrench-shaped change type context menu icon to change the type of task to a script task, and configure the following properties:
1. **Implementation**: `FEEL expression`
2. Click **Create a new diagram** in Camunda 8.
3. In the Properties panel, under the General section:
- Name your diagram `Process payments`
- Set the ID to `process-payments`
4. Add a start event, and name it `Payment request received`.
5. Append a task named `Prepare transaction`.
6. Click the wrench-shaped change type context menu icon to change the type of task to a script task, and configure the following properties:
1. **Implementation**: `FEEL expression` [What is FEEL?](/components/modeler/feel/what-is-feel.md)
2. **Script/Result variable**: `totalWithTax`
3. **Script/FEEL expression**: `total * 1.1` (this represents the tax applied to the transaction.)
6. Append a task named `Charge credit card`.
7. Click on the task and click the wrench-shaped icon to change the type of task to a service task. In the properties panel, change the **Task definition/Type** to `charge-credit-card`.
8. Append an end event named `Payment executed`.
9. Save this BPMN file to your Spring project in `src/main/resources`, and name it `process-payments.bpmn`.
7. Append a task named `Charge credit card`.
8. Click on the task and click the wrench-shaped icon to change the type of task to a service task. In the properties panel, change the **Task definition/Type** to `charge-credit-card`.
9. Append an end event named `Payment executed`.
10. Save this BPMN file to your Spring project in `src/main/resources`, and name it `process-payments.bpmn`.

## Step 4: Deploy your process
## Step 3: Deploy your process

To deploy your process, take the following steps:

Expand All @@ -88,7 +97,7 @@ To deploy your process, take the following steps:

When you open Operate at http://localhost:8080/operate/, you should now note the process deployed to your local Self-Managed setup.

## Step 5: Run your process from Modeler
## Step 4: Run your process from Modeler

To run your process, take the following steps:

Expand All @@ -98,7 +107,7 @@ To run your process, take the following steps:

From Operate, you should now notice a process instance running. You'll notice the process instance is waiting at **Charge credit card**, because we'll need to configure a job worker.

## Step 6: Implement a service task
## Step 5: Implement a service task

To implement a service task, take the following steps:

Expand Down Expand Up @@ -182,7 +191,7 @@ To check your work, visit our [sample repository](https://github.com/camunda/cam

In your terminal, run `mvn spring-boot:run`, where you should see the `charging credit card` output. In Operate, refresh if needed, and note the payment has executed.

## Step 7: Start a process instance
## Step 6: Start a process instance

To start a process instance programmatically, take the following steps:

Expand All @@ -209,31 +218,31 @@ import io.camunda.zeebe.spring.client.annotation.Deployment;
@SpringBootApplication
public class ProcessPaymentsApplication implements CommandLineRunner {

private static final Logger LOG = LoggerFactory.getLogger(ProcessPaymentsApplication.class);
private static final Logger LOG = LoggerFactory.getLogger(ProcessPaymentsApplication.class);

@Autowired
private ZeebeClient zeebeClient;
@Autowired
private ZeebeClient zeebeClient;

public static void main(String[] args) {
SpringApplication.run(ProcessPaymentsApplication.class, args);
}
public static void main(String[] args) {
SpringApplication.run(ProcessPaymentsApplication.class, args);
}
}
```

3. Implement an overriding `run` method in `ProcessPaymentsApplication`. When the application runs, it will create a new `process-payments` process instance, of the latest version, with specified variables, and send it to our local Self-Managed instance:

```java
@Override
public void run(final String... args) {
var bpmnProcessId = "process-payments";
var event = zeebeClient.newCreateInstanceCommand()
.bpmnProcessId(bpmnProcessId)
.latestVersion()
.variables(Map.of("total", 100))
.send()
.join();
LOG.info("started a process instance: {}", event.getProcessInstanceKey());
}
@Override
public void run(final String... args) {
var bpmnProcessId = "process-payments";
var event = zeebeClient.newCreateInstanceCommand()
.bpmnProcessId(bpmnProcessId)
.latestVersion()
.variables(Map.of("total", 100))
.send()
.join();
LOG.info("started a process instance: {}", event.getProcessInstanceKey());
}
```

:::note
Expand All @@ -242,7 +251,7 @@ To check your work, visit our [sample repository](https://github.com/camunda/cam

Re-run the application in your terminal with `mvn spring-boot:run` to see the process run, and note the instance history in Operate.

## Step 8: Deploy the process
## Step 7: Deploy the process

To deploy your process, take the following steps:

Expand Down
Loading