REST API: Conditional Start Events With POST /v2/conditions

by Admin 60 views
REST API: Conditional Start Events with POST /v2/conditions

Hey guys! Let's dive into the exciting world of Camunda and REST APIs, specifically focusing on how to kick off process instances using conditional start events. We're going to explore the ins and outs of the POST /v2/conditions endpoint, designed to evaluate root-level conditional start events. Buckle up; it's going to be a detailed ride!

Defining and Implementing the REST Endpoint

At the heart of our discussion is the POST /v2/conditions REST endpoint. This endpoint is your gateway to starting process instances based on predefined conditions. When a request hits this endpoint, the Camunda engine evaluates whether the specified conditions are met, and if they are, a new process instance is launched. Think of it as a smart trigger for your processes.

Request Payload

To make this endpoint truly versatile, we need a well-defined request payload. Here’s what it should support:

  • Optional tenantId: This is crucial for multi-tenancy environments, allowing you to specify which tenant the process instance should belong to. If you're not using multi-tenancy, you can leave this out.
  • Optional processDefinitionKey: This allows you to target a specific process definition key, ensuring that the conditions are evaluated only for the intended process. This is super handy when you have multiple processes with similar conditional start events.
  • variables JSON document: This is where the magic happens! The variables JSON document contains the variables used for condition evaluation. These variables are the fuel that drives the conditional logic, determining whether a process instance should start. Make sure these variables are correctly structured and contain the data needed for evaluation.

Multi-Tenancy Rules

Multi-tenancy adds a layer of complexity, but it’s essential for isolating processes and data between different tenants. Here are the rules we need to enforce:

  • MT enabled + missing tenantId → 400 Bad Request: If multi-tenancy is enabled, and the tenantId is missing from the request, we need to return a 400 Bad Request error. This ensures that every process instance is correctly associated with a tenant.
  • MT disabled + non-<default> tenantId → 400 Bad Request: If multi-tenancy is disabled, and the tenantId is not the default value, we also return a 400 Bad Request error. This prevents accidental assignment of process instances to non-existent tenants.

Response Payload

Once the conditions are evaluated and a process instance is started, we need to provide a meaningful response. The response payload should return a list of started process instances, including:

  • processDefinitionKey: This confirms which process definition was used to start the instance.
  • processInstanceKey: This is the unique identifier for the started process instance. You’ll need this to track and manage the instance.

Error Handling

Robust error handling is paramount for a reliable API. Here are the error scenarios we need to cover:

  • 400 Bad Request for invalid input: This should be returned when the request payload is malformed or missing required fields. Clear error messages will help users quickly identify and fix the issue.
  • 403 Forbidden if the caller is not allowed to start process instances: This ensures that only authorized users can start process instances. Implement proper authentication and authorization checks to enforce this.

Mapping to Broker-Side Commands and Events

Finally, we need to map the REST handler to the broker-side commands and events. This involves:

  • Mapping the POST /v2/conditions request to a ConditionIntent.EVALUATE command on the broker side.
  • Handling the ConditionIntent.EVALUATED event to construct the response payload with the started process instance details.

Diving Deeper into the Request Payload

Let’s break down the request payload components further. Understanding each part will empower you to use the POST /v2/conditions endpoint effectively.

tenantId

The tenantId is your key to a multi-tenant kingdom. In a multi-tenant environment, different tenants might have the same process definitions. The tenantId ensures that the process instance is created in the correct tenant. If multi-tenancy is enabled and you forget to include the tenantId, the system won't know where to put the new process instance, hence the 400 Bad Request.

In a single-tenant environment, you typically won't need to worry about this. However, if you do include a tenantId that isn't the default, you'll still get a 400 Bad Request because the system isn't set up to handle multiple tenants.

processDefinitionKey

The processDefinitionKey allows you to be specific about which process definition should be evaluated. Imagine you have several processes, each waiting for a specific condition to be met. By specifying the processDefinitionKey, you ensure that only the relevant process is triggered.

If you omit the processDefinitionKey, the system might evaluate conditions across multiple process definitions, which could lead to unexpected process starts. It's always a good practice to include this to avoid ambiguity.

variables JSON Document

This is where the real magic happens. The variables JSON document contains the data that the Camunda engine uses to evaluate the conditional start event. These variables must match the names and types expected by the condition expression.

For example, if your condition is orderTotal > 100, your variables JSON document should include orderTotal with a numeric value. If the variable is missing or of the wrong type, the evaluation might fail, or worse, lead to incorrect decisions.

Multi-Tenancy: A Closer Look

Multi-tenancy is a powerful feature that allows you to isolate processes and data between different groups or organizations using the same Camunda engine. Let's explore the multi-tenancy rules in more detail.

MT Enabled + Missing tenantId

When multi-tenancy is enabled, every process instance must belong to a tenant. If you try to start a process instance without specifying the tenantId, the system will reject the request with a 400 Bad Request error. This is to prevent accidental leakage of data between tenants.

The error message should be clear and informative, guiding the user to include the tenantId in the request. For example: `