Skip to content

Commit

Permalink
Update the Spring developer guide (#4301)
Browse files Browse the repository at this point in the history 
* Update the Spring developer guide

Improved the guide to align with the upcoming release of Camunda 8 Desktop Modeler and C8 Run. Includes revising the Prerequisites section, removing redundant steps now covered by the new Self-managed setup, and improving the clarity and structure of the getting started steps.

* Modified to a relative URL

* minor grammatical tweak

* remove non-prod note, adjust greenfield link

* fix FEEL link

* Update getting-started-java-spring.md

- Removed links to unused components
- Added note to ensure JAVA_Home is set properly
- Changed OpenJDK install url

* Removed download links temporarily

* backport

---------

Co-authored-by: Christina Ausley <christina.ausley@camunda.com>
Co-authored-by: Amara <amara.graham@camunda.com>
Co-authored-by: Amara Graham <akeller@users.noreply.github.com>
Co-authored-by: christinaausley <84338309+christinaausley@users.noreply.github.com>
  • Loading branch information
@camundom @christinaausley @akeller
5 people authored Oct 8, 2024
1 parent 5740992 commit 8840c28
Show file tree
Hide file tree
Showing 2 changed files with 83 additions and 65 deletions.
57 changes: 33 additions & 24 deletions docs/guides/getting-started-java-spring.md
View file
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 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
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

0 comments on commit 8840c28

Please sign in to comment.