Integrating NestJS with Camunda-Zeebe SaaS: A Step-by-Step Guide
Tags: nestjs, camunda, zeebe, orchestration
Published: 2024-01-02 14:49:00

### Introduction

In today's dynamic software development landscape, orchestrating workflows efficiently is crucial. [Camunda-Zeebe](https://camunda.com/platform/zeebe/), a cloud-native workflow automation platform, seamlessly integrates with NestJS, a powerful Node.js framework. In this tutorial, we'll explore how to set up and connect NestJS with Camunda-Zeebe SaaS, allowing you to manage workflows with ease.

### Prerequisites

Before diving into the integration, make sure you have the following prerequisites in place:

- Node.js and npm installed
- NestJS application set up
- Camunda-Zeebe SaaS account

### Setting Up Zeebe Microservice

In your `main.ts` file, register the Zeebe microservice. This establishes the connection between your NestJS application and the Zeebe server.

```ts
// main.ts

import { AppModule } from './app.module';
import { NestFactory } from '@nestjs/core';
import { ZeebeServer } from 'nestjs-zeebe';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const microservice = app.connectMicroservice({
    strategy: app.get(ZeebeServer),
  });

  await app.startAllMicroservices();
  await app.listen(3002);
}
bootstrap();
```

### Configuring ZeebeModule in AppModule

In your `app.module.ts` file, register the ZeebeModule and configure the connection options. Ensure you replace placeholders with your actual credentials and gateway address.

```ts
// app.module.ts

import { ZeebeModule, ZeebeServer } from 'nestjs-zeebe';
import { Module } from '@nestjs/common';

@Module({
  imports: [
    ZeebeModule.forRoot({
      gatewayAddress: '<yourGatewayAddress>',
      options: {
        oAuth: {
          url: 'https://login.cloud.camunda.io/oauth/token',
          audience: 'zeebe.camunda.io',
          clientId: '<yourClientId>',
          clientSecret: '<yourClientSecret>',
        },
      },
    }),
  ],
  // ... other module configurations
})
export class AppModule {}
```

Remember to replace `<yourGatewayAddress>`, `<yourClientId>`, and `<yourClientSecret>` with your actual Camunda-Zeebe SaaS credentials.

### Starting Workflow Instances

In your `app.controller.ts` file, use the Zeebe client to start a workflow instance.

```ts
// app.controller.ts

import { ZEEBE_CONNECTION_PROVIDER } from 'nestjs-zeebe';

@Controller()
export class AppController {
  constructor(@Inject(ZEEBE_CONNECTION_PROVIDER) private readonly zbClient: ZBClient) {}

  @Get()
  async startWorkflow(): Promise<CreateProcessInstanceResponse> {
    return this.zbClient.createProcessInstance({
      bpmnProcessId: 'Process_16ssnwv',  // Replace with your actual BPMN process ID
      variables: {
        // Workflow variables
      },
    });
  }
  // ... other controller methods
}
```

Replace `Process_16ssnwv` with your actual BPMN process ID.

### Subscribing to Zeebe Events

In your `app.controller.ts` file, implement a Zeebe worker to subscribe to specific events in the workflow.

```ts
// app.controller.ts

@Controller()
export class AppController {
  // ... other controller methods

  @ZeebeWorker('mail')
  mail(@Payload() job: ZeebeJob, @Ctx() context: { worker: ZBWorker<IInputVariables, ICustomHeaders, IOutputVariables> }) {
    console.log('Mail, Task variables', job.variables);

    // Task worker business logic goes here
    console.log('Send mail, success');

    job.complete(updatedVariables);
  }
}
```

Adjust the worker method (`mail` in this case) to match your workflow's task name and implement the necessary business logic.

### Conclusion

Congratulations! You've successfully integrated NestJS with Camunda-Zeebe SaaS, allowing you to manage workflows effortlessly. This powerful combination opens up a world of possibilities for orchestrating complex business processes in a scalable and efficient manner.

Feel free to explore further and adapt these steps to your specific use case. Happy coding!