SuiteCRM Developer Insights - Adding Bulk Actions

This week Clemente Raposo, Lead Developer of SuiteCRM, takes you through how to add custom bulk actions to your modules in SuiteCRM 8.

The bulk action configuration allows you to add actions to the list view’s bulk actions dropdown menu. In addition to specifying a label and action handler, this configuration has built-in support coping with several other scenarios: setting a minimum and/or maximum record selection limit, opening a record panel for extra inputs, displaying a record selection modal before running the action, showing a confirmation modal prior to execution, redirecting to a new view after the action, and refreshing the current list view upon completion.

In today’s example, we’ll demonstrate how to add a bulk action that opens a record panel for additional input. We’ll use an example that introduces a “Dynamic Rename” action to the bulk action menu in the Opportunities module list view.

Check out this month’s video to learn how to create custom bulk actions and see below for code samples to help you get started.

For those of you who are keen to get started, you can find the code sample from the video below:

Copy to Clipboard

<?php

namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use Symfony\Component\DependencyInjection\ContainerBuilder;

return static function (ContainerBuilder $container): void {

// 1. Retrieve the actions for opportunities from the symfony container parameters
    $actions = $container->getParameter('module.listview.bulk_action') ?? [];
    $modules = $actions['modules'] ?? [];
    $opportunities = $modules['opportunities'] ?? [];
    $bulkActions = $opportunities['actions'] ?? [];

// 2. Add the dynamic rename action definition
    $bulkActions['opportunity-dynamic-rename'] = [
        'key' => 'opportunity-dynamic-rename',
        'labelKey' => 'LBL_DYNAMIC_RENAME', // New label, defined in public/legacy/custom/Extension/application/Ext/Language
        'asyncProcess' => 'true',
        'modes' => ['list', 'detail', 'edit'],
        'acl' => ['view', 'edit'],
        'params' => [
            'allowAll' => false,
            'min' => 2,
            'max' => 10,
            'recordPanel' => [
                'title' => 'LBL_DYNAMIC_RENAME',
                'fields' => [
                    [
                        "name" => "prefix",
                        "label" => "LBL_PREFIX",
                        "fieldDefinition" => [
                            "name" => "prefix",
                            "vname" => "LBL_PREFIX",
                            "type" => "varchar",
                            "len" => "255",
                        ],
                        "type" => "varchar",
                    ]
                ],
                'mode' => 'massupdate',
                'actions' => [
                    [
                        'key' => 'cancel',
                        'labelKey' => 'LBL_CANCEL',
                        'modes' => ['massupdate']
                    ],
                    [
                        'key' => 'bulk-action',
                        'labelKey' => 'LBL_SUBMIT_BUTTON_LABEL',
                        'modes' => ['massupdate'],
                        'klass' => ['btn', 'btn-danger', 'btn-sm'],
                        'params' => [
                            'allowAll' => false,
                            'min' => 2,
                            'max' => 10,
                            'bulkAction' => 'opportunity-dynamic-rename',
                            'displayConfirmation' => true,
                            'confirmationLabel' => 'LBL_BULK_ACTION_MASS_UPDATE_CONFIRMATION'
                        ]

]
                ]

]

]
    ];

// 3. Add back to the symfony container parameters
    $opportunities['actions'] = $bulkActions;
    $modules['opportunities'] = $opportunities;
    $actions['modules'] = $modules;
    $container->setParameter('module.listview.bulk_action', $actions);
};

extensions/defaultExt/config/modules/Opportunities/listview/actions/dynamic-rename.php

Copy to Clipboard

<?php
    
namespace App\Extension\defaultExt\modules\Opportunities\Process\Service\BulkActions;

use ApiPlatform\Core\Exception\InvalidArgumentException;
use App\Engine\LegacyHandler\LegacyHandler;
use App\Process\Entity\Process;
use App\Process\Service\ProcessHandlerInterface;
use Exception;

class DynamicRenameBulkAction extends LegacyHandler implements ProcessHandlerInterface
{
    protected const MSG_OPTIONS_NOT_FOUND = 'Process options is not defined';

protected const PROCESS_TYPE = 'bulk-opportunity-dynamic-rename';

/**
     * @inheritDoc
     */
    public function getProcessType(): string
    {
        return self::PROCESS_TYPE;
    }

/**
     * @inheritDoc
     */
    public function getHandlerKey(): string
    {
        return $this->getProcessType();
    }

/**
     * @inheritDoc
     */
    public function requiredAuthRole(): string
    {
        return 'ROLE_USER';
    }

/**
     * @inheritDoc
     */
    public function getRequiredACLs(Process $process): array
    {
        $options = $process->getOptions();
        $module = $options['module'] ?? '';
        $ids = $options['ids'] ?? [];

return [
            $module => [
                [
                    'action' => 'edit',
                    'ids' => $ids
                ],
            ],
        ];
    }

/**
     * @inheritDoc
     */
    public function configure(Process $process): void
    {
        //This process is synchronous
        //We aren't going to store a record on db
        //thus we will use process type as the id
        $process->setId(self::PROCESS_TYPE);
        $process->setAsync(false);
    }

/**
     * @inheritDoc
     */
    public function validate(Process $process): void
    {
        if (empty($process->getOptions())) {
            throw new InvalidArgumentException(self::MSG_OPTIONS_NOT_FOUND);
        }

$options = $process->getOptions();

if (empty($options['module']) || empty($options['action'])) {
            throw new InvalidArgumentException(self::MSG_OPTIONS_NOT_FOUND);
        }
    }

/**
     * @inheritDoc
     */
    public function run(Process $process)
    {
        $options = $process->getOptions();
        $attributes = $options['payload']['panelRecord']['attributes'] ?? [];

if (empty($attributes)) {
            $process->setStatus('error');
            $process->setMessages(['LBL_BULK_ACTION_MASS_UPDATE_NO_FIELDS']);

return;
        }

$result = $this->renameRecords($process);

$responseData = [
            'reload' => true,
            'dataUpdated' => true,
            'reloadGlobalRecentlyViewed' => true,
            'reloadRecentlyViewed' => true,
            'reloadFavorites' => true
        ];

$process->setData($responseData);

$process->setStatus('success');
        $process->setMessages($result['messages'] ?? ['LBL_BULK_ACTION_MASS_UPDATE_SUCCESS']);
        if (!$result) {
            $process->setStatus('error');
            $process->setMessages(['LBL_ACTION_ERROR']);
        }

$process->setData($responseData);
    }

/**
     * @param Process $process
     * @return array
     */
    protected function renameRecords(Process $process): array
    {
        $this->init();
        $options = $process->getOptions();

$attributes = $options['payload']['panelRecord']['attributes'] ?? [];

/* MORE OPTIONS - Handle when criteria is sent
            if (is_array($options['criteria'])) {
                $criteria = $options['criteria'];
                $sort = $options['sort'] ?? [];
            }
        */

$notFound = [];
        $failed = [];

$prefix = $attributes['prefix'];
        $count = count($options['ids']);

if (is_array($options['ids']) && $count) {

foreach ($options['ids'] as $id) {
                /** @var \Opportunity $opportunity */
                $opportunity = \BeanFactory::getBean('Opportunities', $id);

if (empty($opportunity)) {
                    $notFound[] = $id;
                    continue;
                }

try {
                    $opportunity->name = $prefix . $opportunity->name;
                    $opportunity->save();
                } catch (Exception $e) {
                    $failed[] = $id;
                }
            }
        }

$totalFailed = count($failed) + count($notFound);

$this->close();

if ($count === $totalFailed) {
            return [
                'success' => false,
                'messages' => ['LBL_BULK_ACTION_MASS_UPDATE_NO_RECORDS']
            ];
        }

if ($totalFailed > 0) {

return [
                'success' => true,
                'messages' => ['LBL_BULK_ACTION_MASS_UPDATE_NO_RECORDS']
            ];
        }

return [
            'success' => true,
            'messages' => ['LBL_BULK_ACTION_MASS_UPDATE_SUCCESS']
        ];
    }
}

extensions/defaultExt/modules/Opportunities/Process/Service/BulkActions/DynamicRenameBulkAction.php

Copy to Clipboard

public/legacy/custom/Extension/application/Ext/Language/en_us.dynamic_rename.php

The above can be used as an example on how to add Bulk Actions to your modules in SuiteCRM 8.

If you are looking for more development insights, the Development Team here at SalesAgility have created instructor-led Masterclasses. Designed for developers, covering both SuiteCRM 8.x and SuiteCRM 7.x, head over to the MasterClasses to find out more.

About SuiteCRM

SuiteCRM is one of the world’s most popular CRM applications. Our feature-rich enterprise-ready alternative to Salesforce enables your sales teams to sell, market & service smarter. Providing all the benefits of CRM at substantially lower costs, with the freedoms and flexibility of Open Source.

You can download and host SuiteCRM on your own servers, in the public cloud / private cloud or try our SAAS offering SuiteCRM Hosted. It is the ultimate freedom, allowing you to stay in full control over your business data. Try SuiteCRM for free here.

Help support the SuiteCRM project by becoming a sponsor today!

SuiteCRM Developer Insights – Adding Bulk Actions

About SuiteCRM

Share This Story, Choose Your Platform!