Setting up your first Development Project
- C# / ASP.NET Core 3
- Go
- Java + Spring
- Kotlin + Spring
- NodeJS
Approximate time to complete: 1 hour
The Zeebe C# Client is available for .NET Zeebe applications.
Watch a video tutorial on YouTube walking through this Getting Started Guide.
Estimated time to complete: 60 minutes
The Zeebe Go Client is available for Go applications.
Watch a video tutorial on YouTube walking through this Getting Started Guide.
The Spring Zeebe Client is available for Spring and Spring Boot applications.
Watch a video tutorial on YouTube walking through this Getting Started Guide.
The Spring Zeebe Client is available for Spring and Spring Boot applications.
Watch a video tutorial on YouTube walking through this Getting Started Guide.
The Zeebe Node Client exists for Node.js applications.
Watch a video tutorial on YouTube walking through this Getting Started Guide.
#
Prerequisites- C# / ASP.NET Core 3
- Go
- Java + Spring
- Kotlin + Spring
- NodeJS
#
Scaffolding the project- C# / ASP.NET Core 3
- Go
- Java + Spring
- Kotlin + Spring
- NodeJS
- Create a new .NET Core Web API application:
- Add the Zeebe C# Client from Nuget:
Configure NLog for logging
- Install NLog packages (we'll use NLog):
- Create a file
NLog.config
, with the following content:
- Edit the file
Program.cs
to configure NLog:
Download a maven Spring starter from here.
Unzip it into a new directory.
- Add the Spring Zeebe Client dependency to the
pom.xml
file:
Download a maven Spring starter from here.
Unzip it into a new directory.
- Add the Spring Zeebe Client dependency to the
pom.xml
file:
- Install tools:
- Create project:
- Edit
tsconfig.json
with the following config:
- Install
zeebe-node
anddotenv
:
#
Create Camunda Cloud cluster- C# / ASP.NET Core 3
- Go
- Java + Spring
- Kotlin + Spring
- NodeJS
- Log in to https://camunda.io.
- Create a new Zeebe Cluster.
- When the new cluster appears in the console, create a new set of client credentials.
- Copy the client Connection Info environment variables block.
#
Configure connection- C# / ASP.NET Core 3
- Go
- Java + Spring
- Kotlin + Spring
- NodeJS
- Add the
dotenv.net
package to the project:
- Edit
Startup.cs
and add the service in theConfigureServices
method:
- Create a file in the root of the project
CamundaCloud.env
, and paste the client connection details into it, removing theexport
from each line:
Note: if you change cluster configuration at a later date, you may need to delete the file ~/zeebe/cloud.token
. See this bug report.
- Add an
ItemGroup
inCloudStarter.csproj
to copy the.env
file into the build:
- Create a file in
Services/ZeebeService.cs
, with the following content:
- Save the file.
We will use GoDotEnv to environmentalize the client connection credentials.
- Add GoDotEnv to the project:
- Add the client connection credentials for your cluster to the file
.env
:
Note: make sure to remove the export
keyword from each line.
- Save the file.
- Add the client connection credentials for your cluster to the file
src/main/resources/application.properties
:
- Save the file.
- Add the client connection credentials for your cluster to the file
src/main/resources/application.properties
:
- Save the file.
- Create a file
.env
in the root of the project - Paste the client connection environment variable block
- Delete the
export
from in front of each line in the file
You will end up something that looks like this:
- Save the file.
#
Test Connection with Camunda Cloud- C# / ASP.NET Core 3
- Go
- Java + Spring
- Kotlin + Spring
- NodeJS
We will create a controller route at /status
that retrieves the status and topology of the cluster.
- Create a file
Controllers/ZeebeController.cs
, with the following content:
- Edit the file
Startup.cs
, and inject theZeebeService
class into the service container in theConfigureServices
method, like this:
- Run the application with the command
dotnet run
(remember to set the client connection variables in the environment first).
Note: you can use dotnet watch run
to automatically restart your application when you change your code.
- Open http://localhost:5000/status in your web browser.
You will see the topology response from the cluster.
- Paste the following code into the file
main.go
:
Run the program with the command
go run main.go
.You will see output similar to the following:
This is the topology response from the cluster.
- Annotate the
CloudStarterApplication
class in the filesrc/main/java/io.camunda/CloudStarterApplication.java
with the@EnableZeebeClient
annotation, and add the@Autowired
ZeebeClientLifecycle
property:
- Add the
@RestController
annotation to the class, and create a REST mapping that returns the cluster topology:
Run the application with the command
mvn spring-boot:run
.Open http://localhost:8080/status in your web browser.
You will see the topology response from the cluster.
- Annotate the
CloudStarterApplication
class in the filesrc/main/java/io.camunda/CloudStarterApplication.kt
with the@EnableZeebeClient
annotation, and add the@Autowired
ZeebeClientLifecycle
property:
- Add the
@RestController
annotation to the class, and create a REST mapping that returns the cluster topology:
Run the application with the command
mvn spring-boot:run
.Open http://localhost:8080/status in your web browser.
You will see the topology response from the cluster.
We will connect to the Zeebe cluster in Camunda Cloud, and request its topology.
- In the
src
folder, create a file calledapp.ts
. - Edit the file, and put in the following code:
- Run the program with the command:
ts-node src/app.ts
You will see output like this:
#
Create a BPMN model- C# / ASP.NET Core 3
- Go
- Java + Spring
- Kotling + Spring
- NodeJS
- Download and install the Zeebe Modeler.
- Open Zeebe Modeler and create a new BPMN Diagram.
- Create a new BPMN diagram.
- Add a StartEvent, an EndEvent, and a Task.
- Click on the Task, click on the little spanner/wrench icon, and select "Service Task".
- Set the Name of the Service Task to
Get Time
, and the Type toget-time
.
It should look like this:
- Click on the blank canvas of the diagram, and set the Id to
test-process
, and the Name to "Test Process".
- C# / ASP.NET Core 3
- Go
- Java + Spring
- Kotling + Spring
- NodeJS
- Save the diagram to
Resources/test-process.bpmn
in your project.
- Save the diagram to
test-process.bpmn
in your project.
- Save the diagram to
src/main/resources/test-process.bpmn
in your project.
- Save the diagram to
src/main/resources/test-process.bpmn
in your project.
- Save the diagram to
bpmn/test-process.bpmn
in your project.
#
Deploy the BPMN model to Camunda Cloud- C# / ASP.NET Core 3
- Go
- Java + Spring
- Kotlin + Spring
- NodeJS
We need to copy the bpmn file into the build, so that it is available to our program at runtime.
- Edit the
Cloudstarter.csproj
file, and add the following to theItemGroup
:
Now we create a method in our service to deploy a bpmn model to the cluster.
- Edit
ZeebeService.cs
, and add aDeploy
method:
- In the
ZeebeService.cs
file, update the interface definition:
Now, we call the Deploy
method during the initialization of the service at startup. We need to do it here, because the service is not instantiated
- Edit
Startup.cs
, and add the following lines to theConfigure
method:
- Edit the
main.go
file, and add a new functiondeploy
:
- Now update the
main()
function to look like this:
- Run the program with
go run main.go
.
You will see the deployment response:
- Edit the
src/main/java/io.camunda/CloudStarterApplication.java
file, and add the@ZeebeDeployment
annotation to theCloudStarterApplication
class:
- Edit the
src/main/kotlin/io.camunda/CloudStarterApplication.kt
file, and add the@ZeebeDeployment
annotation to theCloudStarterApplication
class:
- Edit the
src/app.ts
file, to be this:
- Run the program with the command:
ts-node src/app.ts
You will see output similar to this:
The workflow is now deployed to the cluster.
#
Start a Workflow Instance- C# / ASP.NET Core 3
- Go
- Java + Spring
- Kotlin + Spring
- NodeJS
We will create a controller route at /start
that will start a new instance of the workflow.
- Add fastJSON to the project:
- Edit
Services/ZeebeService.cs
and add aStartWorkflowInstance
method:
- Update the service interface definition:
- Edit
Controllers/ZeebeController.cs
, and add a REST method to start an instance of the workflow:
Run the program with the command:
dotnet run
.Visit http://localhost:5000/start in your browser.
You will see output similar to the following:
A workflow instance has been started. Let's view it in Operate.
We will add a webserver, and use it to provide a REST interface for our program.
Add
"net/http"
to the imports inmain.go
.Edit the
main.go
file, and add a REST handler to start an instance:
- Now update the
main()
function to add an HTTP server and the/start
route:
Run the program with the command:
go run main.go
.Visit http://localhost:3000/start in your browser.
You will see output similar to the following:
A workflow instance has been started. Let's view it in Operate.
- Edit the
src/main/java/io.camunda/CloudStarterApplication.java
file, and add a REST method to start an instance of the workflow:
Run the program with the command:
mvn spring-boot:run
.Visit http://localhost:8080/start in your browser.
You will see output similar to the following:
A workflow instance has been started. Let's view it in Operate.
- Edit the
src/main/kotlin/io.camunda/CloudStarterApplication.kt
file, and add a REST method to start an instance of the workflow:
Run the program with the command:
mvn spring-boot:run
.Visit http://localhost:8080/start in your browser.
You will see output similar to the following:
A workflow instance has been started. Let's view it in Operate.
- Edit the
src/app.ts
file, and make it look like this:
- Run the program with the command:
ts-node src/app.ts
You will see output similar to:
A workflow instance has been started. Let's view it in Operate.
#
View a Workflow Instance in Operate- C# / ASP.NET Core 3
- Go
- Java + Spring
- Kotling + Spring
- NodeJS
- Go to your cluster in the Camunda Cloud Console.
- In the cluster detail view, click on "View Workflow Instances in Camunda Operate".
- In the "Instances by Workflow" column, click on "Test Process - 1 Instance in 1 Version".
- Click the Instance Id to open the instance.
- You will see the token is stopped at the "Get Time" task.
Let's create a task worker to serve the job represented by this task.
#
Create a Job Worker- C# / ASP.NET Core 3
- Go
- Java + Spring
- Kotlin + Spring
- NodeJS
We will create a worker program that logs out the job metadata, and completes the job with success.
- Edit the
Services/ZeebeService.cs
file, and add a_createWorker
method to theZeebeService
class:
- Now add a
CreateGetTimeWorker
method, where we supply the task-type for the worker, and a job handler function:
The worker handler function is async
so that it runs on its own thread.
- Now create a method
StartWorkers
:
- And add it to the
IZeebeService
interface:
- Now call this method in the
Configure
method inStartup.cs
:
- Run the program with the command:
dotnet run
.
You will see output similar to:
- Go back to Operate. You will see that the workflow instance is gone.
- Click on "Running Instances".
- In the filter on the left, select "Finished Instances".
You will see the completed workflow instance.
We will create a worker that logs out the job metadata, and completes the job with success.
- Edit the
main.go
file, and add a handler function for the worker:
- Update the
main
function to create a worker in a go routine, which allows it to run in a background thread:
- Run the worker program with the command:
go run main.go
.
You will see output similar to:
- Go back to Operate. You will see that the workflow instance is gone.
- Click on "Running Instances".
- In the filter on the left, select "Finished Instances".
You will see the completed workflow instance.
We will create a worker program that logs out the job metadata, and completes the job with success.
- Edit the
src/main/java/io.camunda/CloudStarterApplication.java
file, and add a REST method to start an instance of the workflow:
- Run the worker program with the command:
mvn spring-boot:run
.
You will see output similar to:
- Go back to Operate. You will see that the workflow instance is gone.
- Click on "Running Instances".
- In the filter on the left, select "Finished Instances".
You will see the completed workflow instance.
We will create a worker program that logs out the job metadata, and completes the job with success.
- Edit the
src/main/kotlin/io.camunda/CloudStarterApplication.kt
file, and add a REST method to start an instance of the workflow:
- Run the worker program with the command:
mvn spring-boot:run
.
You will see output similar to:
- Go back to Operate. You will see that the workflow instance is gone.
- Click on "Running Instances".
- In the filter on the left, select "Finished Instances".
You will see the completed workflow instance.
We will create a worker program that logs out the job metadata, and completes the job with success.
- Create a new file
src/worker.ts
. - Edit the file to look like this:
- Run the worker program with the command:
ts-node src/worker.ts
.
You will see output similar to:
- Go back to Operate. You will see that the workflow instance is gone.
- Click on "Running Instances".
- In the filter on the left, select "Finished Instances".
You will see the completed workflow instance.
#
Create and Await the Outcome of a Workflow Instance- C# / ASP.NET Core 3
- Go
- Java + Spring
- Kotlin + Spring
- NodeJS
We will now create the workflow instance, and get the final outcome in the calling code.
- Edit the
ZeebeService.cs
file, and edit theStartWorkflowInstance
method, to make it look like this:
Run the program with the command:
dotnet run
.Visit http://localhost:5000/start in your browser.
You will see output similar to the following:
We will now create the workflow instance, and get the final outcome in the calling code.
- Edit the
createStartHandler
function in themain.go
file, and make the following change:
Run the program with the command:
go run main.go
.Visit http://localhost:3000/start in your browser.
You will see output similar to the following:
We will now create the workflow instance, and get the final outcome in the calling code.
- Edit the
src/main/java/io.camunda/CloudStarterApplication.java
file, and edit thestartWorkflowInstance
method, to make it look like this:
Run the program with the command:
mvn spring-boot:run
.Visit http://localhost:8080/start in your browser.
You will see output similar to the following:
We will now create the workflow instance, and get the final outcome in the calling code.
- Edit the
src/main/kotlin/io.camunda/CloudStarterApplication.kt
file, and edit thestartWorkflowInstance
method, to make it look like this:
Run the program with the command:
mvn spring-boot:run
.Visit http://localhost:8080/start in your browser.
You will see output similar to the following:
We will now create the workflow instance, and get the final outcome in the calling code.
- Keep the worker program running in one terminal.
- Edit the
src/app.ts
file, and make it look like this:
- Run the program with the command:
ts-node src/app.ts
.
You will see your worker log out the job as it serves it, and your program will produce output similar to the following:
#
Call a REST Service from the Worker- C# / ASP.NET Core 3
- Go
- Java + Spring
- Kotlin + Spring
- NodeJS
We are going to make a REST call in the worker handler, to query a remote API for the current GMT time.
- Edit the
ZeebeService.cs
file, and edit theCreateGetTimeWorker
method, to make it look like this:
- Run the program with the command:
dotnet run
. - Visit http://localhost:5000/start in your browser.
You will see output similar to the following:
- Edit the file
main.go
and add these structs for the REST response payload and the worker variable payload:
- Replace the
handleGetTime
function inmain.go
with the following code:
- Run the program with the command:
go run main.go
. - Visit http://localhost:3000/start in your browser.
You will see output similar to the following:
- Edit the
src/main/java/io.camunda/CloudStarterApplication.java
file, and edit thehandleGetTime
method, to make it look like this:
- Run the program with the command:
mvn spring-boot:run
. - Visit http://localhost:8080/start in your browser.
You will see output similar to the following:
- Edit the
src/main/kotlin/io.camunda/CloudStarterApplication.kt
file, and edit thehandleGetTime
method, to make it look like this:
- Run the program with the command:
mvn spring-boot:run
. - Visit http://localhost:8080/start in your browser.
You will see output similar to the following:
- Stop the worker program.
- Install the
got
package to your project:
- Edit the file
src/worker.ts
, and make it look like this:
- Run the worker program with the command:
ts-node src/worker.ts
- In another terminal, run the program with the command:
ts-node src/app.ts
You will see output similar to the following:
#
Make a Decision- C# / ASP.NET Core 3
- Go
- Java + Spring
- Kotlin + Spring
- NodeJS
We will edit the model to add a Conditional Gateway.
- Open the BPMN model file
bpmn/test-process.bpmn
in the Zeebe Modeler. - Drop a Gateway between the Service Task and the End event.
- Add two Service Tasks after the Gateway.
- In one, set the Name to
Before noon
and the Type tomake-greeting
. - Switch to the Headers tab on that Task, and create a new Key
greeting
with the ValueGood morning
. - In the second, set the Name to
After noon
and the Type tomake-greeting
. - Switch to the Headers tab on that Task, and create a new Key
greeting
with the ValueGood afternoon
. - Click on the arrow connecting the Gateway to the Before noon task.
- Under Details enter the following in Condition expression:
- Click on the arrow connecting the Gateway to the After noon task.
- Click the spanner/wrench icon and select "Default Flow".
- Connect both Service Tasks to the End Event.
It should look like this:
#
Create a Worker that acts based on Custom Headers- C# / ASP.NET Core 3
- Go
- Java + Spring
- Kotlin + Spring
- NodeJS
We will create a second worker that combines the value of a custom header with the value of a variable in the workflow.
- Edit the
ZeebeService.cs
file and create a couple of DTO classes to aid with deserialization of the job:
- In the same file, create a
CreateMakeGreetingWorker
method:
- Now call this method in the
StartWorkers
method of theZeebeService
:
- Edit the
startWorkflowInstance
method, and pass in a variablename
when you create the workflow:
You can change the variable name
value to your own name (or derive it from the url path or a parameter).
- Run the program with the command:
dotnet run
. - Visit http://localhost:5000/start in your browser.
You will see output similar to the following:
We will create a second worker that takes the custom header and applies it to the variables in the workflow.
- Edit the
main.go
file, and add structs for the new worker's request and response payloads:
- Create the
handleMakeGreeting
method inmain.go
:
- Edit the
main
function and create a worker:
- Edit the
startWorkflowInstance
method, and make it look like this:
You can change the variable value to your own name (or derive it from the url path or a parameter).
- Run the program with the command:
go run main
. - Visit http://localhost:3000/start in your browser.
You will see output similar to the following:
We will create a second worker that takes the custom header and applies it to the variables in the workflow.
- Edit the
src/main/java/io.camunda/CloudStarterApplication.java
file, and add thehandleMakeGreeting
method, to make it look like this:
- Edit the
startWorkflowInstance
method, and make it look like this:
You can change the variable name
value to your own name (or derive it from the url path or a parameter).
- Run the program with the command:
mvn spring-boot:run
. - Visit http://localhost:8080/start in your browser.
You will see output similar to the following:
We will create a second worker that takes the custom header and applies it to the variables in the workflow.
- Edit the
src/main/kotlin/io.camunda/CloudStarterApplication.kt
file, and add thehandleMakeGreeting
method, to make it look like this:
- Edit the
startWorkflowInstance
method, and make it look like this:
You can change the variable name
value to your own name (or derive it from the url path or a parameter).
- Run the program with the command:
mvn spring-boot:run
. - Visit http://localhost:8080/start in your browser.
You will see output similar to the following:
We will create a second worker that takes the custom header and applies it to the variables in the workflow.
- Stop the worker running.
- Edit the file
src/worker.ts
, and make it look like this:
- Edit the file
src/app.ts
, and make it look like this:
- Start the workers with the command:
ts-node src/worker.ts
- Start the app with the command:
ts-node src/app.ts
You will see output similar to the following:
#
Profit!Congratulations. You've completed the Getting Started Guide for Camunda Cloud.