Getting Started

Minimal Setup

Installation Add the bundle via Composer:

composer require digitalstate/platform-bpm-pm-bundle

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

Configuration Publish the default config:
```
php bin/console digitalstate:bpm-pm:install
```
Update config/packages/digitalstate_platform_bpm_pm.yaml with your ProcessMaker API credentials (URL, username, password, and workspace ID).
First Use Case: Sync a Process Trigger a process sync from ProcessMaker to your Laravel app:
```
php bin/console digitalstate:bpm-pm:sync-processes
```
Verify sync status via the Process model:
```
$processes = \DigitalState\Platform\BpmPmBundle\Entity\Process::all();
```
Key Classes to Explore
- \DigitalState\Platform\BpmPmBundle\Entity\Process: Represents a ProcessMaker process.
- \DigitalState\Platform\BpmPmBundle\Service\ProcessMakerClient: Core API client.
- digitalstate:bpm-pm:console commands: Listed in Resources/config/services.yaml.

Implementation Patterns

Workflow: Process Integration

Fetch and Cache Processes Use the ProcessMakerClient to fetch processes and cache them for performance:

$client = $this->container->get('digitalstate_platform_bpm_pm.process_maker_client');
$processes = $client->getProcesses(); // Returns array of Process entities

Event-Driven Syncs Subscribe to ProcessMakerEvents (e.g., ProcessUpdatedEvent) to react to changes:

use DigitalState\Platform\BpmPmBundle\Event\ProcessMakerEvents;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class ProcessSyncSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents()
    {
        return [
            ProcessMakerEvents::PROCESS_UPDATED => 'onProcessUpdated',
        ];
    }

    public function onProcessUpdated(ProcessUpdatedEvent $event)
    {
        // Trigger custom logic (e.g., update local DB, send notifications)
    }
}

Custom Process Fields Extend the Process entity to add custom fields:

namespace App\Entity;

use DigitalState\Platform\BpmPmBundle\Entity\Process as BaseProcess;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
class Process extends BaseProcess
{
    #[ORM\Column(type: 'string', nullable: true)]
    private ?string $customField = null;

    // Getters/setters...
}

Command Automation Schedule sync commands via Laravel’s task scheduler (app/Console/Kernel.php):

protected function schedule(Schedule $schedule)
{
    $schedule->command('digitalstate:bpm-pm:sync-processes')
             ->dailyAt('03:00');
}

API Proxy Pattern Use the bundle’s client to proxy ProcessMaker API calls in your controllers:

use DigitalState\Platform\BpmPmBundle\Service\ProcessMakerClient;

class ProcessController extends Controller
{
    public function __construct(private ProcessMakerClient $client) {}

    public function getProcesses()
    {
        return $this->client->getProcesses();
    }
}

Gotchas and Tips

Pitfalls

API Rate Limiting

ProcessMaker may throttle requests. Use exponential backoff in custom clients:

try {
    $response = $client->getProcesses();
} catch (RateLimitException $e) {
    sleep($e->getRetryAfter());
    retry();
}

Entity Mapping Quirks
- The Process entity maps to ProcessMaker’s "process" resource, but case sensitivity matters in field names (e.g., name vs Name).
- Override hydrate() in custom entities to handle unmapped fields:
```
public function hydrate(array $data, array $objects)
{
    parent::hydrate($data, $objects);
    $this->customField = $data['custom_field'] ?? null;
}
```
Workspace ID Misconfiguration
- The workspace_id in config must match the ProcessMaker workspace UUID, not the display name. Verify via:
```
php bin/console digitalstate:bpm-pm:list-workspaces
```

Command Output Parsing

Console commands return raw API responses. Parse JSON manually if needed:

$output = $this->getContainer()->get('command_bus')->handle(
    new SyncProcessesCommand()
);
$data = json_decode($output, true);

Doctrine Event Conflicts

If using custom Doctrine lifecycle callbacks, ensure they don’t conflict with the bundle’s Process entity listeners. Disable them temporarily:

# config/packages/doctrine.yaml
orm:
    entity_managers:
        default:
            listeners:
                DigitalState\Platform\BpmPmBundle\EventListener\ProcessListener: ~

Debugging Tips

Enable API Logging Add a custom logger to the ProcessMakerClient:

$client = $this->container->get('digitalstate_platform_bpm_pm.process_maker_client');
$client->setLogger($this->container->get('logger'));

Validate API Credentials Test credentials manually via:
```
php bin/console digitalstate:bpm-pm:test-connection
```
Check for Deprecated Methods The bundle may use undocumented methods. Inspect src/Service/ProcessMakerClient.php for @deprecated tags.

Extension Points

Custom Process Attributes Extend the Process entity and override the getAttributes() method to include additional fields:

public function getAttributes()
{
    $attributes = parent::getAttributes();
    $attributes['custom_field'] = $this->customField;
    return $attributes;
}

Webhook Integration Use the ProcessMakerWebhookEvent to handle real-time updates from ProcessMaker:

use DigitalState\Platform\BpmPmBundle\Event\ProcessMakerWebhookEvent;

$dispatcher->addListener(
    ProcessMakerWebhookEvent::class,
    function (ProcessMakerWebhookEvent $event) {
        // Process webhook payload (e.g., case creation)
    }
);

Custom Sync Strategies Implement ProcessSyncStrategyInterface to define custom sync logic:

use DigitalState\Platform\BpmPmBundle\Strategy\ProcessSyncStrategyInterface;

class CustomSyncStrategy implements ProcessSyncStrategyInterface
{
    public function shouldSync(\DigitalState\Platform\BpmPmBundle\Entity\Process $process)
    {
        return $process->isUpdatedAfter(\Carbon\Carbon::yesterday());
    }
}

# config/services.yaml
DigitalState\Platform\BpmPmBundle\Strategy\ProcessSyncStrategyInterface: '@custom_sync_strategy'

Override API Endpoints Extend ProcessMakerClient to use custom endpoints:

class CustomProcessMakerClient extends ProcessMakerClient
{
    protected function getBaseUri()
    {
        return 'https://custom-processmaker-instance.com/api';
    }
}

Bind it in services.yaml:

digitalstate_platform_bpm_pm.process_maker_client: '@custom_process_maker_client'

Add Custom Commands Create a new command extending AbstractProcessMakerCommand:

namespace App\Command;

use DigitalState\Platform\BpmPmBundle\Command\AbstractProcessMakerCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;

class CustomProcessCommand extends AbstractProcessMakerCommand
{
    protected static $defaultName = 'digitalstate:bpm-pm:custom-action';

    protected function execute(InputInterface $input, OutputInterface $output)
    {
        $this->client->customAction();
        $output->writeln('Custom action executed!');
    }
}

App\Command\CustomProcessCommand: ~

Platform Bpm Pm Bundle Laravel Package