rapidkit/laravel-camunda-client

High level model, something like Eloquent, to interact with Camunda resources via REST API.

v1.1.0 2024-05-03 23:31 UTC

Requires

• php: ^8.1
• guzzlehttp/guzzle: ^7.8
• illuminate/contracts: ^10.0
• spatie/laravel-data: ^3.8
• spatie/laravel-package-tools: ^1.14.0

Requires (Dev)

• laravel/pint: ^1.0
• nunomaduro/collision: ^7.9
• nunomaduro/larastan: ^2.0.1
• orchestra/testbench: ^8.0
• pestphp/pest: ^2.0
• pestphp/pest-plugin-arch: ^2.0
• pestphp/pest-plugin-laravel: ^2.0
• pestphp/pest-plugin-type-coverage: ^2.2
• phpstan/extension-installer: ^1.1
• phpstan/phpstan-deprecation-rules: ^1.0
• phpstan/phpstan-phpunit: ^1.0

MIT

• Bayu Hendra Winata
• rama

• laravel
• camunda
• laravolt
• camunda client

README

Introducing a convenient Laravel HTTP client wrapper designed to streamline your interactions with the Camunda REST API. This specialized tool simplifies the process of connecting your Laravel application to Camunda, allowing you to effortlessly send requests and retrieve data. With this wrapper, you can efficiently integrate Camunda's powerful workflow automation capabilities into your Laravel projects, making it easier than ever to orchestrate complex business processes and manage tasks seamlessly. Say goodbye to the hassles of manual API calls and hello to a smoother, more efficient workflow integration with Camunda.

Installation

You can install the package via composer:

composer require rapidkit/laravel-camunda-client

You can publish the config file with:

php artisan vendor:publish --tag='laravel-camunda-client-config'

This is the contents of the published config file:

return [
    'url' => env('CAMUNDA_URL', 'http://127.0.0.1:8080/engine-rest'),
    'user' => env('CAMUNDA_USER', 'demo'),
    'password' => env('CAMUNDA_PASSWORD', 'demo'),
    'tenant_id' => env('CAMUNDA_TENANT_ID', ''),
];

Usage

Process Definition

use RapidKit\LaravelCamundaClient\Http\ProcessDefinitionClient;

$variables = ['title' => ['value' => 'Sample Title', 'type' => 'string']];

// Start new process instance
$instance = ProcessDefinitionClient::start(key: 'process_1', variables: $variables);

// Start new process instance with some business key
$instance = ProcessDefinitionClient::start(key: 'process_1', variables: $variables, businessKey: 'somekey');

// Get BPMN definition in XML format
ProcessDefinitionClient::xml(key: 'process_1');
ProcessDefinitionClient::xml(id: 'process_1:xxxx');

// Get all definition
ProcessDefinitionClient::get();

// Get definitions based on some parameters
$params = ['latestVersion' => true];
ProcessDefinitionClient::get($params);

Reference:

• Camunda API: Process Definition

Process Instance

use RapidKit\LaravelCamundaClient\Http\ProcessInstanceClient;

// Find by ID
$processInstance = ProcessInstanceClient::find(id: 'some-id');

// Get all instances
ProcessInstanceClient::get();

// Get instances based on some parameters
$params = ['businessKeyLike' => 'somekey'];
ProcessInstanceClient::get($params);

ProcessInstanceClient::variables(id: 'some-id');
ProcessInstanceClient::delete(id: 'some-id');

Message Start Event

use RapidKit\LaravelCamundaClient\Http\MessageEventClient;

MessageEventClient::start(messageName: 'testing',  businessKey: 'businessKey');

$vars = ['title' => ['type' => 'String', 'value' => 'Sample Title']];
MessageEventClient::start(messageName: 'testing',  businessKey: 'businessKey', variables: $vars);

Task

use RapidKit\LaravelCamundaClient\Http\TaskClient;

$task = TaskClient::find(id: 'task-id');
$tasks = TaskClient::getByProcessInstanceId(id: 'process-instance-id');
$tasks = TaskClient::getByProcessInstanceIds(ids: 'arrayof-process-instance-ids');
TaskClient::submit(id: 'task-id', variables: ['name' => ['value' => 'Foo', 'type' => 'String']]); // will return true or false
$variables = TaskClient::submitAndReturnVariables(id: 'task-id', variables: ['name' => ['value' => 'Foo', 'type' => 'String']]) // will return array of variable

// Claim a Task
$tasks = TaskClient::claim($task_id,  $user_id);
// Unclaim a Task
$tasks = TaskClient::unclaim($task_id);
// Assign a Task
$tasks = TaskClient::assign($task_id,  $user_id);

External Task

use RapidKit\LaravelCamundaClient\Http\ExternalTaskClient;

$topics = [['topicName' => 'pdf', 'lockDuration' => 600_000]];
$externalTasks = ExternalTaskClient::fetchAndLock('worker1', $topics);
foreach ($externalTasks as $externalTask) {
    // do something with $externalTask
    // Mark as complete after finished
    ExternalTaskClient::complete($externalTask->id);
}

// Release some task
ExternalTaskClient::unlock($task->id)

Consume External Task

Create a new job to consume external task via php artisan make:job <JobName> and modify the skeleton:

use RapidKit\LaravelCamundaClient\Data\ExternalTaskData;
use RapidKit\LaravelCamundaClient\Http\ExternalTaskClient;

public function __construct(
    public string $workerId,
    public ExternalTaskData $task
) {
}

public function handle()
{
    // Do something with $this->task, e.g: get the variables and generate PDF
    $variables = \RapidKit\LaravelCamundaClient\Http\ProcessInstanceClient::variables($this->task->processDefinitionId);
    // PdfService::generate()

    // Complete the task
    $status = ExternalTaskClient::complete($this->task->id, $this->workerId);
}

Subscribe to some topic:

// AppServiceProvider.php
use RapidKit\LaravelCamundaClient\Http\ExternalTaskClient;

public function boot()
{
    ExternalTaskClient::subscribe('pdf', GeneratePdf::class);
}

Register the scheduler:

// app/Console/Kernel.php
protected function schedule(Schedule $schedule)
{
    $schedule->command('camunda:consume-external-task --workerId=worker1')->everyMinute();
}

If you need shorter pooling time (sub-minute frequency), please check Laravel Short Schedule.

References:

• https://laravel.com/docs/master/scheduling
• https://laravel.com/docs/master/queues
• https://github.com/spatie/laravel-short-schedule

Task History (Completed Task)

use RapidKit\LaravelCamundaClient\Http\TaskHistoryClient;

$completedTask = TaskHistoryClient::find(id: 'task-id');
$completedTasks = TaskHistoryClient::getByProcessInstanceId(id: 'process-instance-id');

Deployment

use RapidKit\LaravelCamundaClient\Http\DeploymentClient;

// Deploy bpmn file(s)
DeploymentClient::create('test-deploy', '/path/to/file.bpmn');
DeploymentClient::create('test-deploy', ['/path/to/file1.bpmn', '/path/to/file2.bpmn']);

// Get deployment list
DeploymentClient::get();

// Find detailed info about some deployment
DeploymentClient::find($id);

// Truncate (delete all) deployments
$cascade = true;
DeploymentClient::truncate($cascade);

// Delete single deployment
DeploymentClient::delete(id: 'test-deploy', cascade: $cascade);

Raw Endpoint

You can utilize RapidKit\LaravelCamundaClient\CamundaClient to call any Camunda REST endpoint.

use RapidKit\LaravelCamundaClient\CamundaClient;

$response = CamundaClient::make()->get('version');
echo $response->status(); // 200
echo $response->object(); // sdtClass
echo $response->json(); // array, something like ['version' => '7.14.0']

CamundaClient::make() is a wrapper for Laravel HTTP Client with base URL already set based on your Camunda services configuration. Take a look at the documentation for more information.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• rama
• All Contributors

License

The MIT License (MIT). Please see License File for more information.

References

• Deployment
• External Task
• Message
• Process Definition
• Task
• Task History