SugarCRM Cookbook: Adding Related Records

Lets jump right into this one and begin by looking at a code snippet:

$rel_name = 'contacts';

$record_id = 'some_id_value';

$bean->load_relationship($rel_name);

$bean->$rel_name->add($record_id);

So what does it do?

Assuming we execute the above code within the scope of a before_save logic hook for Opportunities, the above code would add a linked contact to the opportunity being saved. 

While that example may have limited applications, the snippet of code does not. It can be reused within any custom PHP code you are writing for SugarCRM to link records together, all via the SugarCRM framework.

The advantage of this approach is that it is applicable to any module. In addition, and perhaps more importantly, it is upgrade-safe and eliminates the need for us to know about relationship tables, linking fields or any of the finer details that SugarCRM relies upon to establish relationships between records.

In order to see the power of this little snippet, we need to dissect it line-by-line and expand scope of our example.

Here is our first line:

$rel_name = 'contacts'; 

This line simply contains a variable that has been assigned the string value of: contacts. This may seem rather simple, but it is the key to the process. 

As you might already know, every relationship in SugarCRM has a unique name, for example, opportunities_contacts. The key to making this code work is knowing the name of the relationship we wish to affect. 

In our example, we are linking a contact to an opportunity during the save process. It happens to be that the name of the Opportunity/Contact relationship SugarCRM utilizes for this process is simply: contacts (it does not use the opportunities_ prefix). That is our key to working with contacts that are related to a specific opportunity.

Our next step is to provide the ID value of the record we wish to link it to, in this case, the ID of the contact entry. Remember, our base is the opportunity record, so we need the ID of the other record, not that of the opportunity.  We are storing this value in variable defined in this line of code:

$record_id = 'some_id_value'; 

The manner in which you come about getting that value is irrelevant to the process. It could be the result of an SQL query that was executed earlier in the code, hard coded into the process or any other means. 

Next we find this line:

$bean->load_relationship($rel_name); 

There are couple of noteworthy points relating to this line. First, the usage of $bean. Because our code is being executed within the scope of a logic hook, it is possible for us to reference the current Opportunity record by simply using $bean. There is no need for us to actually load the Opportunity class or instantiate an instance of it. 

Lastly, we are calling the load_relationship() method for that Opportunity record. Notice we are passing the string value of contacts as the parameter (via the $rel_name variable). This essentially connects us to the area of the SugarCRM framework that allows us to manipulate which contacts are linked to the current opportunity.

Note: I have not confirmed the matter, but I suspect the relationship names used in this context are case-sensitive.

Alright, so we are connected to the appropriate area, but how do we actually link a contact? That question is answered by the last line in our code snippet:

$bean->$rel_name->add($record_id); 

There is a very important point to notice in this line of code. Although the earlier line of code connected us to the relationship, in order to add or delete corresponding records from it, we must reference the relationship name again and it must match the name used for the load_relationship() method. Thus, the syntax to be used is:

$bean->[relationship_name]->add([record_id]);

To finalize our analysis, it is not necessary to call $bean->save() because that is automatically taken care of for us by SugarCRM.

For those of you wondering about the manner in which you can adapt this code so you can use it outside the context of logic hooks, do not despair. That too is rather simple and does not require much modification to the above. The key to executing it outside the context of a logic hook is to instantiate an instance of the corresponding class first, in this case, an Opportunity. 

Suppose we wanted to link the contact to an opportunity, but using an external PHP script.

To do that, we would do something like this:

require_once('modules/Opportunities/Opportunity.php');

$rel_name = 'contacts';

$contact_id = 'id_of_contact_to_link';

$oppty_id = 'id_of_oppty_to_affect';

$oppty = new Opportunity();

$oppty->retrieve($oppty_id); //Load a specific opportunity

$oppty->load_relationship($rel_name);

$oppty->$rel_name->add($contact_id); //Note use of $rel_name

$oppty->save() //Call save because it is not within a logic hook!

Wondering how to delete a relationship entry instead of adding one?

Simple, change 

$oppty->$rel_name->add($contact_id); 

to

$oppty->$rel_name->delete($oppty_id, $contact_to_unlink_id)

That is it!