SuiteCRM Developer Insights - Module Record Actions

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

Record action configuration provides a way to add actions to the record view of a module. Besides the ability to define a label and the action process handler, this configuration has built-in support coping with several other scenarios: opening a record selection modal before running the action, opening a confirmation modal before running the action, redirecting to a different view after executing the action and reloading the current record after running the action.

In today’s example, we are going to demo an alternative way to define actions to your module, using an example that adds a “Link Account” button to the Opportunities module record view. Watch this week’s video to learn how to add custom record actions, and be sure to check below to get the code example to help get you started.

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

Copy to Clipboard

public/legacy/custom/Extension/modules/Opportunities/Ext/Language/en_us.link_account.php

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.recordview.actions') ?? [];
    $modules = $actions['modules'] ?? [];
    $opportunities = $modules['opportunities'] ?? [];
    $recordActions = $opportunities['actions'] ?? [];

// 2. Add the link account Action definition
    $recordActions['link-account'] = [
        'key' => 'opportunity-link-account',
        'labelKey' => 'LBL_LINK_ACCOUNT', // New label, defined in public/legacy/custom/Extension/modules/Opportunities/Ext/Language
        'asyncProcess' => 'true',
        'modes' => ['detail', 'edit'],
        'acl' => ['view'],
        'aclModule' => 'Accounts',
        'params' => [
            // Allow selecting a record from a modal before running action
            'selectModal' => [
                'module' => 'Accounts'
            ]
            
            //MORE: Other available params

// 'displayConfirmation' => true, // Enable to show a confirmation modal before running action
            // 'confirmationLabel' => 'NTC_DELETE_CONFIRMATION' // set the message to show on the confirmation modal

]
    ];

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

defaultExt/config/modules/Opportunities/recordview/actions/link-account.php

Copy to Clipboard

<?php

namespace App\Extension\defaultExt\modules\Opportunities\Process\Service\RecordActions;

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

class LinkAccountAction extends LegacyHandler implements ProcessHandlerInterface
{
    protected const MSG_OPTIONS_NOT_FOUND = 'Process options is not defined';
    protected const PROCESS_TYPE = 'record-opportunity-link-account';

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

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'] ?? '';

$acls = [
            $module => [
                [
                    'action' => 'view',
                    'record' => $options['id'] ?? ''
                ]
            ]
        ];

$modalRecord = $options['params']['modalRecord'] ?? [];
        $modalRecordModule = $modalRecord['module'] ?? '';
        $modalRecordId = $modalRecord['id'] ?? '';

if ($modalRecordModule !== '') {
            $acls[$modalRecordModule] = [
                [
                    'action' => 'view',
                    'record' => $modalRecordId
                ]
            ];
        }

return $acls;
    }

/**
     * @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();
        ['module' => $baseModule, 'id' => $id] = $options;

if (empty($id) || $baseModule !== 'opportunities') {
            throw new InvalidArgumentException(self::MSG_OPTIONS_NOT_FOUND);
        }

['modalRecord' => $modalRecord] = $options['params'];
        ['module' => $modalModule, 'id' => $modalId] = $modalRecord;

if (empty($modalId) || $modalModule !== 'accounts') {
            throw new InvalidArgumentException(self::MSG_OPTIONS_NOT_FOUND);
        }
    }

/**
     * @inheritDoc
     */
    public function run(Process $process)
    {
        $options = $process->getOptions();
        ['id' => $opportunityId] = $options;
        ['modalRecord' => $modalRecord] = $options['params'];
        ['id' => $accountId] = $modalRecord;

$result = $this->linkAccount($opportunityId, $accountId);

$process->setStatus($result['status']);
        $process->setMessages($result['messages']);
        $process->setData($result['data']);
    }

protected function linkAccount(string $opportunityId, string $accountId): array
    {
        // 1. initialize legacy handler
        $this->init();

// 2. Retrieve the Account and the Opportunity
        /** @var \Opportunity $opportunity */
        $opportunity = \BeanFactory::getBean('Opportunities', $opportunityId);

/** @var \Account $account */
        $account = \BeanFactory::getBean('Accounts', $accountId);

if (empty($account)) {
            $this->close();

return [
                'status' => 'error',
                'data' => [],
                'messages' => [
                    'LBL_RECORD_NOT_FOUND'
                ]
            ];
        }

// 3. Link the account to opportunity and save
        $opportunity->account_id = $accountId;

$opportunity->save();

// 3. Prepare response and request frontend to reload
        $responseData = [

'reload' => true,

// OTHER AVAILABLE OPTIONS
            // 'reloadRecentlyViewed' => true,
            // 'reloadFavorites' => true,

// 'handler' => 'export', // options: export, redirect, audit

// Params vary according to the handler that is used
            // 'params' => [
            //     'route' => $options['module'],
            //     'queryParams' => []
            // ]
        ];

$result = [
            'status' => 'success',
            'data' => $responseData,
            'messages' => [
                'LBL_LINK_RELATIONSHIP_SUCCESS'
            ]
        ];

// Close legacy handler
        $this->close();

return $result;
    }
}

defaultExt/modules/Opportunities/Process/Service/RecordActions/LinkAccountAction.php

The above can be used as an example to add your own custom actions and custom buttons to the Record View 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 – Module Record Actions

About SuiteCRM

Share This Story, Choose Your Platform!