Platform Bpm Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle Add to composer.json:

   composer require digitalstate/platform-bpm-bundle
   

   Enable in config/bundles.php:

   return [
       // ...
       DigitalState\Platform\BPMBundle\DigitalStatePlatformBPMBundle::class => ['all' => true],
   ];
   

2. Configure the BPM Engine Publish the default config:

   php artisan vendor:publish --tag=platform-bpm-config
   

   Edit config/platform_bpm.php to define your engine (e.g., Camunda):

   engines:
       camunda:
           type: camunda
           url: "http://camunda:8080/engine-rest"
           auth:
               username: "demo"
               password: "demo"
   

3. First Use Case: Starting a Process Inject the BpmClient service and trigger a process:

   use DigitalState\Platform\BPMBundle\Client\BpmClientInterface;
   
   class MyService {
       public function __construct(private BpmClientInterface $bpmClient) {}
   
       public function startProcess() {
           $processDefinitionKey = 'my_process';
           $variables = ['input' => 'data'];
   
           $result = $this->bpmClient->startProcess(
               'camunda', // engine name
               $processDefinitionKey,
               $variables
           );
   
           return $result->getProcessInstanceId();
       }
   }
   

Implementation Patterns

Workflow: Process Lifecycle Management

1. Process Deployment Use the BpmClient to deploy a BPMN file:

   $this->bpmClient->deployProcessDefinition(
       'camunda',
       'path/to/process.bpmn',
       '1.0'
   );
   

2. Process Execution Start a process with variables:

   $this->bpmClient->startProcess(
       'camunda',
       'order_process',
       ['customerId' => 123]
   );
   

3. Task Handling Fetch and complete tasks:

   $task = $this->bpmClient->getTask('camunda', 'taskId');
   $this->bpmClient->completeTask('camunda', 'taskId', ['output' => 'data']);
   

4. Event Listeners Subscribe to process events (e.g., ProcessStartedEvent):

   use DigitalState\Platform\BPMBundle\Event\ProcessStartedEvent;
   
   public function onProcessStarted(ProcessStartedEvent $event) {
       // Handle event (e.g., log, notify)
   }
   

   Register in EventSubscriber:

   services:
       App\EventListener\MyBPMListener:
           tags:
               - { name: kernel.event_subscriber }
   

Integration Tips

• OroPlatform Integration Extend Oro’s workflow system by hooking into BPM events:

  use Oro\Workflow\Event\WorkflowEvent;
  
  public function onWorkflowTransition(WorkflowEvent $event) {
      $this->bpmClient->triggerExternalTask($event->getTransition()->getName());
  }
  

• API Controllers Expose BPM actions via API:

  use Symfony\Component\HttpFoundation\JsonResponse;
  
  public function startProcessAction(BpmClientInterface $bpmClient) {
      $result = $bpmClient->startProcess('camunda', 'api_process', []);
      return new JsonResponse(['processId' => $result->getProcessInstanceId()]);
  }
  

• Command-Line Tools Create Artisan commands for admin tasks:

  php artisan bpm:deploy --engine=camunda --file=process.bpmn
  

Gotchas and Tips

Pitfalls

1. Engine-Specific Quirks

   • Camunda uses processDefinitionKey, while other engines may require processDefinitionId.
   • Validate engine-specific configs (e.g., Camunda’s historyLevel).

2. Authentication Issues

   • Ensure auth config matches the BPM engine’s credentials.
   • For OAuth2, extend BpmClient to support custom auth handlers.

3. Error Handling

   • Wrap BPM calls in try-catch:

     try {
         $this->bpmClient->startProcess(...);
     } catch (\DigitalState\Platform\BPMBundle\Exception\BpmException $e) {
         // Log or retry
     }
     

4. Process Variables

   • Serialization: Complex objects may need custom serializers (e.g., JsonSerializable).

Debugging

• Enable API Logging Add to config/platform_bpm.php:

  debug: true
  

  Logs will appear in var/log/dev.log.

• Check Engine Health Use the BpmClient::ping() method to verify connectivity:

  if (!$this->bpmClient->ping('camunda')) {
      throw new \RuntimeException('BPM engine unavailable');
  }
  

Extension Points

1. Custom Engines Implement DigitalState\Platform\BPMBundle\Client\EngineInterface for new BPM systems.

2. Event Customization Extend event classes (e.g., ProcessStartedEvent) to add custom data:

   class CustomProcessStartedEvent extends ProcessStartedEvent {
       public function __construct(array $customData) {
           $this->customData = $customData;
       }
   }
   

3. Middleware Add middleware to BpmClient for pre/post-processing:

   $client->addMiddleware(new \App\Middleware\LogBPMRequests());
   

4. Testing Use the BpmClientMock for unit tests:

   $mock = new BpmClientMock('camunda');
   $mock->shouldReceive('startProcess')->andReturn(new ProcessInstance());