Bpm Camunda Sdk Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require digitalstate/bpm-camunda-sdk
   

   Ensure your Laravel project has guzzlehttp/guzzle (dependency for HTTP requests).

2. Basic Client Initialization

   use DigitalState\Bpm\Camunda\Client;
   
   $client = new Client('http://your-camunda-server:8080/engine-rest');
   $client->setAuth('username', 'password'); // Basic Auth
   

3. First Use Case: Start a Process

   $processDefinitionKey = 'your-process-key';
   $variables = ['key' => 'value'];
   
   $processInstance = $client->processInstance()->start($processDefinitionKey, $variables);
   echo "Started process with ID: " . $processInstance->getId();
   

4. Key Documentation

   • Camunda REST API Docs (for endpoint reference).
   • SDK methods mirror Camunda’s REST API (e.g., processInstance(), task(), history()).

Implementation Patterns

Workflow: Process Lifecycle Management

1. Process Startup

   $client->processInstance()->start('order-process', ['customerId' => 123]);
   

   • Use start() with a ProcessDefinitionKey and optional variables (serialized as JSON).

2. Task Handling

   $task = $client->task()->listTasks('user123');
   $task->complete(['customVar' => 'value']);
   

   • Fetch tasks with listTasks($assignee) and complete them with complete($variables).

3. Variable Management

   $client->processInstance()->setVariables('procInstId', ['status' => 'approved']);
   $variables = $client->processInstance()->getVariables('procInstId');
   

4. Event Listeners (Webhooks)

   $client->eventSubscription()->subscribe(
       'process-started',
       'http://your-app.com/camunda/webhook',
       ['processDefinitionKey' => 'order-process']
   );
   

   • Use Laravel’s Http facade to handle incoming webhook payloads.

Integration with Laravel

1. Service Provider Binding

   // app/Providers/AppServiceProvider.php
   public function register()
   {
       $this->app->singleton(Client::class, function () {
           return new Client(config('camunda.url'))
                   ->setAuth(config('camunda.username'), config('camunda.password'));
       });
   }
   

2. Queue Jobs for Async Operations

   // app/Jobs/StartCamundaProcess.php
   public function handle()
   {
       $client = app(Client::class);
       $client->processInstance()->start('async-process', ['data' => $this->payload]);
   }
   

3. Middleware for Auth/Validation

   // app/Http/Middleware/ValidateCamundaRequest.php
   public function handle($request, Closure $next)
   {
       if ($request->is('camunda/webhook')) {
           $this->validateWebhook($request);
       }
       return $next($request);
   }
   

Gotchas and Tips

Pitfalls

1. Authentication

   • Basic Auth is default, but Camunda supports OAuth2. Extend the Client class to add OAuth:

     $client->setAuth(new \GuzzleHttp\Auth\OAuth2\OAuth2Client());
     

   • Store credentials in Laravel’s .env (never hardcode).

2. Variable Serialization

   • Variables are JSON-encoded by default. Nested arrays/objects must be serializable:

     $variables = ['metadata' => ['nested' => ['key' => 'value']]];
     

   • Use json_encode() for complex data or ensure Client uses json_encode($data, JSON_THROW_ON_ERROR).

3. Rate Limiting

   • Camunda’s default REST API has no strict rate limits, but high-frequency calls may trigger server-side throttling.
   • Implement exponential backoff in Laravel:

     use Symfony\Component\RateLimiter\RateLimiter;
     
     $limiter = new RateLimiter(10, 'minute');
     if (!$limiter->isAllowed()) {
         sleep($limiter->waitTime());
     }
     

4. Idempotency

   • Starting a process with the same businessKey may create duplicates. Use processDefinitionId + variables for uniqueness:

     $client->processInstance()->start(
         'order-process',
         ['businessKey' => 'order_123', 'customerId' => 123]
     );
     

Debugging

1. Enable Guzzle Middleware Add a logging middleware to inspect requests/responses:

   $client->getHttpClient()->getEmitter()->attach(
       new \GuzzleHttp\Middleware::tap(function ($request) {
           \Log::debug('Camunda Request', ['url' => (string) $request->getUri()]);
       })
   );
   

2. Error Handling

   • Wrap SDK calls in try-catch for DigitalState\Bpm\Camunda\Exception\CamundaException:

     try {
         $client->task()->complete('taskId');
     } catch (\Exception $e) {
         \Log::error("Camunda task completion failed: " . $e->getMessage());
         throw new \RuntimeException("Process failed", 0, $e);
     }
     

3. Version Mismatches

   • Ensure the SDK version aligns with your Camunda server version (e.g., 7.17.x). Check the Camunda API docs for breaking changes.

Extension Points

1. Custom Endpoints Extend the Client class to add non-standard endpoints:

   class CustomCamundaClient extends Client
   {
       public function customEndpoint($path, $method = 'GET', $data = [])
       {
           return $this->request($method, $path, $data);
       }
   }
   

2. Laravel Events Trigger Laravel events on Camunda callbacks:

   // In your webhook handler
   event(new \App\Events\CamundaProcessStarted($payload));
   

3. Mocking for Tests Use Laravel’s MockHttp to test SDK interactions:

   $this->mock(Http::class)->shouldReceive('post')
       ->once()
       ->andReturn(Http::response(['id' => 'test'], 200));