Relating Existing Records in Sugar BPM: Practical Example

Author: Yuri Gee

Date: 18 Jul 2025

5 minute read time

The current Sugar BPM Process Definition Designer includes a built-in action—Add a Related Record—which creates a new record and links it to the target module of the process. This article presents a prototype extension of that action, enabling the ability to relate existing records based on field value comparisons. The implementation is designed to be simple and straightforward, avoiding the need for custom logic hook development while still supporting common business scenarios that require linking existing records.

Scenario

Imagine you want to associate Call records that begin with “Bad time, will call back” to a specific Cases record. This can be accomplished using the extension demonstrated here by creating a service field called relate__condition_c in the Calls module.

You then can assign a value to this field within a Sugar BPM Process Definition, where Cases is the target module and Calls is a 1:M relationship. The related record can be matched using either a static value or a dynamic value pulled from the parent Case record, using standard Sugar BPM syntax. Additionally, Sugar Logic formulas can be used to populate the assignment field as needed.

In this example, a static value is applied—targeting the name field of a Call, using the format: field_name field_value, separated by a space.

Example of adding a related record condition in BPM designer

This BPM definition using the special field assignment will not create new records, instead it adds up to 10 existing related Call records that match the specified criteria (e.g., Call names starting with the given value). It also updates the parent-child relationship—which, in the case of Cases and Calls, is the primary link—by setting the parent_type and parent_id fields on the related Call records, ensuring they are properly associated with the Case.

Example of relating Calls to a Case

The service field in the related module (Calls) is used only to align with the existing layout of the Sugar BPM Add Related Record action.

Service field for BPM definition

Code Prototype

This file is based on the original stock ./modules/pmse_Inbox/engine/PMSEElements/PMSEAddRelatedRecord.php, incorporating some elements from ./modules/pmse_Inbox/engine/PMSERelatedModule.php.

Extensions are then applied within either the ./modules or ./custom/modules/pmse_Inbox/engine/PMSEElements/PMSEAddRelatedRecord.php directories.

Note that the original file is not included here, but it can be retrieved from your Sugar instance or a backup of its filesystem.

Fullscreen

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
//Added at line 159 of the original file////////////////////////////////////////////////////////////////////////////////////////
// This is a service field-relate__condition_c-that should be included in the Process Definition of the main module to define the condition for adding an existing related record.
if (isset($fields['relate__condition_c'])) 
{ 
    $parentBean = $bean;
    $relationship_name = $arr_module;
        if (!empty($parentBean)) {
        if (empty($parentBean->field_defs[$relationship_name])) {
            throw ProcessManager\Factory::getException('InvalidData', "Unable to find field {$fieldName}", 1);
        }
        
        $chainModulePresent = false;
        $additional_params = (isset($definitionBean) && !empty($definitionBean->act_params)) ? json_decode($definitionBean->act_params) : null;
        if (isset($additional_params->chainedRelationship->module) && !empty($additional_params->chainedRelationship->module))  $chainModulePresent = true;
    
        $relate_condition = !empty($fields['relate__condition_c']) && is_scalar($fields['relate__condition_c']) ? (string)$fields['relate__condition_c'] : '';
        list($field_name, $field_value) = strpos($relate_condition, ' ') !== false ? explode(' ', $relate_condition, 2): ['', ''];
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

//Added at line 159 of the original file////////////////////////////////////////////////////////////////////////////////////////

// This is a service field-relate__condition_c-that should be included in the Process Definition of the main module to define the condition for adding an existing related record.
if (isset($fields['relate__condition_c'])) 
{ 
    $parentBean = $bean;
    $relationship_name = $arr_module;

        if (!empty($parentBean)) {
        if (empty($parentBean->field_defs[$relationship_name])) {
            throw ProcessManager\Factory::getException('InvalidData', "Unable to find field {$fieldName}", 1);
        }
        
        $chainModulePresent = false;

        $additional_params = (isset($definitionBean) && !empty($definitionBean->act_params)) ? json_decode($definitionBean->act_params) : null;
        if (isset($additional_params->chainedRelationship->module) && !empty($additional_params->chainedRelationship->module))  $chainModulePresent = true;
    
        $relate_condition = !empty($fields['relate__condition_c']) && is_scalar($fields['relate__condition_c']) ? (string)$fields['relate__condition_c'] : '';
        list($field_name, $field_value) = strpos($relate_condition, ' ') !== false ? explode(' ', $relate_condition, 2): ['', ''];

        $related_beans = [];
        $target_module = "";
        if ($parentBean->load_relationship($relationship_name) && !empty($field_name) && !$chainModulePresent) {
        
            $target_module = $parentBean->$relationship_name->getRelatedModuleName();

            $rel_type = 'many';
            if (
                method_exists($parentBean->$relationship_name, 'getRelationshipObject') &&
                ($relObj = $parentBean->$relationship_name->getRelationshipObject()) &&
                isset($relObj->def['lhs_module'], $relObj->def['rhs_module'], $relObj->def['relationship_type'])
            ) {
                
                $def = $relObj->def;
                $parentModule = $parentBean->module_name;
                // TO_NOTE: module can be the same in circular relationship, e.g. Cases to Cases
                // TO_NOTE: The 'true_relationship_type' may differ from 'relationship_type', 
                // which can cause one-to-one relationships to be interpreted as one-to-many.
                // In such cases, the related query should be limited to a single result if necessary.

                    $side = ($def['lhs_module'] === $parentModule) ? 'rhs' :
                        (($def['rhs_module'] === $parentModule) ? 'lhs' : 'undefined');

                if ($side !== 'undefined') {
                    $rel_type = match ($def['relationship_type']) {
                        'one-to-many' => ($side === 'lhs') ? 'one' : 'many',
                        'many-to-one' => ($side === 'lhs') ? 'many' : 'one',
                        'many-to-many' => 'many',
                        'one-to-one' => 'one',
                        default => 'many',
                    };
                }
            }

            $bean = BeanFactory::getBean($target_module);
            if (isset($bean->field_defs[$field_name])) {
                $query = new SugarQuery();
                $query->select(['id']);
                $query->from($bean, ['team_security' => true]); 
                //TO_NOTE: may need to further sanitize $field_value for sql use
                $query->where()->equals($field_name, $field_value);
                //TO_NOTE: *:1 relationships may need to use queries returning or limiting to 1
                $limit = ($rel_type === 'many') ? 10 : 1;
                $query->limit($limit);

                $results = $query->execute();

                foreach ($results as $row) {
                    $related_beans[] = BeanFactory::getBean($target_module, $row['id']);
                }
            } 
        } 

        foreach ($related_beans as $relatedModuleBean) {
        
            $shouldSave = false;
            // TO_NOTE: this will link related records as children to parent (main record) if both parent_type and parent_id are available
            if (isset($relatedModuleBean->field_defs['parent_type'], $relatedModuleBean->field_defs['parent_id'])) {
                $relatedModuleBean->parent_type = $parentBean->module_dir;
                $relatedModuleBean->parent_id = $parentBean->id;

                $shouldSave = true;
            }
    
            if ($parentBean->module_name == $target_module) {
                $relatedModuleBean->pa_related_module_save = true;

                $shouldSave = true;
            }

            // TO_NOTE: saving related bean may not be necessary at all times esp. when Parent - Child relationship is not updated
            if ($shouldSave) PMSEEngineUtils::saveAssociatedBean($relatedModuleBean);
                
            // TO_NOTE: this will link main relationship, several times for many-to-many types or query returning multiple records
            if (!$relatedModuleBean->in_save) {
                $rel_id = $relatedModuleBean->id;
                $bean_id = $parentBean->id; 
                $parentBean->load_relationship($relationship_name);  
                $parentBean->$relationship_name->add($rel_id);
                
                $this->logger->debug("Add record $rel_id of relationship $relationship_name to $bean_id");
            }
        }
        // TO_NOTE: testing showed it may be required when admin changes record's assigned user, but may not be necessary in all cases and make it easier to avoid loops
        PMSEEngineUtils::saveAssociatedBean($parentBean);
    }

    $this->logger->debug('Script executed');
    return $this->prepareResponse($flowData, 'ROUTE', $flowAction);
}
//Resuming logic from the original file///////////////////////////////////////////////////////////////////////////////////////////////

Implementation Highlights and Constraints

Supports only one related module; second-level (chained) relationships are not included.

Field names used for matching are sanitized using standard SugarQuery logic; further sanitization may be needed. Matching respects Teams and Role-based permissions of the user executing the BPM.

Data types tested include strings or possibly fields convertible to strings.

To prevent slow queries, consider adding an index to the matching column; default query limit is 10 records.

Both stock and custom fields can be used for matching, including BPM expressions and Sugar Logic formulas.

Saving related and parent beans may occur but is not always required; careful design and testing is needed to avoid loops.

SugarCRM supports various relationship types: one-to-one, one-to-many, many-to-many, parent-child, circular, and relationships via module or linking tables.

Relationship types may use true_relationship_type and relationship_type; some may default to many even if they are many-to-one. In many-to-one relationships, the logic may still add a parent record if a valid parent-child link exists and the query returns multiple results; this behavior can be disabled.

Some tested scenarios included: adding Contacts to Accounts, linking Calls to Cases, relating Parent Accounts, assigning Users to Cases, and relating Accounts to Cases.

Final Thoughts

This prototype illustrates how existing records can be linked using simple Sugar BPM extensions, leveraging various relationship types and dynamically populated fields from the main record—including Sugar Logic formulas. A similar approach can be applied to removing existing relationships as needed.

Before considering production use, please ensure thorough testing across different scenarios, data types, and relationship structures. Also consider potential interactions with other BPM processes, as this example is provided as-is and may require further refinement for stable deployment.

I’d love to hear how you’re exploring SugarCRM BPM in this and similar use cases!