SuiteCRM Developer Insights - Field Definition Mappers

This week Clemente Raposo, Lead Developer of SuiteCRM, explains how to use Field Definition Mappers in SuiteCRM 8.

Field Definition Mappers are designed as a favourable way to manipulate field behaviour or to change how fields display. They allow you to transform the original values before they are processed just after the field definitions (vardefs) are fetched. Additionally, Mappers work independently, so it is possible to add as many as you need and can be defined to apply across all modules or just for a specific module. Overall, Field Definition Mappers are a great way for you to extend SuiteCRM 8 to work just the way you want it to.

In today’s example, we are going to demo an alternative way to define updating field value based on a backend calculation, using an example that changes the priority field in Cases based on the subject value. Watch this week’s video to learn all about Field Definition Mappers, and be sure to check below to get the code example to help you get started.

Below you will find the code sample from the video:

Copy to Clipboard

<?php

namespace App\Extension\defaultExt\modules\Cases\FieldDefinitions\Mappers;

use App\Engine\LegacyHandler\LegacyHandler;
use App\FieldDefinitions\Entity\FieldDefinition;
use App\FieldDefinitions\LegacyHandler\FieldDefinitionMapperInterface;

class PriorityCalculationLogicDefinition  implements FieldDefinitionMapperInterface
{
    /**
     * @inheritDoc
     */
    public function getModule(): string
    {
        return 'cases';
    }

/**
     * @inheritDoc
     */

public function getKey(): string
    {
        return 'cases-priority-calculation-logic-definition';
    }

/**
     * @inheritDoc
     * @param FieldDefinition $definition
     */
    public function map(FieldDefinition $definition): void
    {
        // 1. Get logic entry
        $vardefs = $definition->getVardef();
        $priority = $vardefs['priority'] ?? [];
        $logic = $priority['logic'] ?? [];

// 2. Add new logic rule
        $logic['case-calculate-priority'] = [
            'key' => 'updateValueBackend',
            'modes' => ['edit', 'create'],
            'params' => [
                'fieldDependencies' => [
                    'type',
                    'name',
                ],
                'process' => 'case-calculate-priority',
                'activeOnFields' => [
                    'type' => ['User'],
                    'name' => [
                        ['operator' => 'not-empty' ]
                    ]
                ]
            ]
        ];

// 3. Re-set the priority definition into the field definitions
        $priority['logic'] = $logic;
        $vardefs['priority'] = $priority;
        $definition->setVardef($vardefs);
    }
}

extensions/defaultExt/modules/Cases/FieldDefinitions/Mappers/PriorityCalculationLogicDefinition.php

Copy to Clipboard

<?php

namespace App\Extension\defaultExt\modules\Cases\Service\Fields;

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

class CaseCalculatePriority implements ProcessHandlerInterface
{
    protected const MSG_OPTIONS_NOT_FOUND = 'Process options are not defined';
    protected const MSG_INVALID_TYPE = 'Invalid type';
    public const PROCESS_TYPE = 'case-calculate-priority';

/**
     * CaseCalculatePriority constructor.
     */
    public function __construct()
    {
    }

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

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

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

$editACLCheck = [
            'action' => 'edit',
        ];

if ($id !== '') {
            $editACLCheck['record'] = $id;
        }

return [
            $module => [
                $editACLCheck
            ],
        ];
    }

/**
     * @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
    {

$options = $process->getOptions();
        $type = $options['record']['attributes']['type'] ?? '';
        if (empty($type)) {
            throw new InvalidArgumentException(self::MSG_OPTIONS_NOT_FOUND);
        }

if ($type !== 'User') {
            throw new InvalidArgumentException(self::MSG_INVALID_TYPE);
        }
    }

/**
     * @inheritDoc
     */
    public function run(Process $process)
    {
        $options = $process->getOptions();

$type = $options['record']['attributes']['type'] ?? '';
        $name = $options['record']['attributes']['name'] ?? '';

$value = 'P3';
        if (strpos(strtolower($name), 'warning') !== false) {
            $value = 'P2';
        }

if (strpos(strtolower($name), 'error') !== false) {
            $value = 'P1';
        }

$responseData = [
            'value' => $value
        ];

$process->setStatus('success');
        $process->setMessages([]);
        $process->setData($responseData);
    }
}

extensions/defaultExt/modules/Cases/Service/Fields/CaseCalculatePriority.php

This sample can be used as an example to add your own Field Definition Mappers based extension in SuiteCRM.

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 – Field Definition Mappers

About SuiteCRM

Share This Story, Choose Your Platform!