Lone Wolves

The module builder in SugarCRM allows you to create one-to-many relations between one of your custom built modules and a standard module. However, it does not allow you to create many-to-one relationships. This means that it is not possible to create an Invoices module for example, where one account relates to many invoices, but each invoice only relates to one account. While you can create such a relationship by using the “Relate” field, you will not get a subpanel on the Accounts module that shows all the invoices that relate to in.

In this article I will show you how you can create a many-to-one relation between your custom module and a standard module. This relationship works the same way as the one-to-many relationship with full support for searching and subpanels, only the other way around. My setup is based on my previous two SugarCRM articles: “Keeping SugarCRM under Subversion control” and “Build custom SugarCRM modules in Subversion”. That means that I will be working inside the installable zip package that is generated by the SugarCRM module builder.

You can download the full invoicing package that I created in this article. It has been tested on SugarCRM 5.1.0b.

0: Table of contents

1. 1: Create the package in the module builder
2. 2: Build the new relation
   1. 2.1: The language file
   2. 2.2: The layoutdefs
   3. 2.3: The relationship metadata
   4. 2.4: The vardefs
3. 3: Add the new relation to the layouts
4. 4: Update the manifest
5. 5: Deploy

1: Create the package in the module builder

Start off by creating your package in the module builder. In this case I created two simple modules: Invoices and InvoiceLines. I related them and then I published the package. Then I created a clean SugarCRM installation and installed the package on it, giving me two custom modules. Below you can see some screenshots of the setup.

And here is a screenshot of the module after installation.

2: Build the new relation

If you look at the source code of the package then you will find the relationship between the Invoices and InvoiceLines in the SugarModules/relationships/ directory.

We are simply going to copy and change those to implement the one-to-many relationship from the Accounts module to the Invoices module.

2.1: The language file

The files in the relationships/languages directory contain the name of the subpanel as it appears on the parent module. We need to add to the Accounts module here so I created Account.php and added a label for the Invoices subpanel title. I opted to use a sensible short name here instead of the overly long names like the module builder generates.

2.2: The layoutdefs

The layoutdefs contain the setup for the subpanel. Copy layoutdefs/inv_Invoices.php to layoutdefs/Accounts.php and take a look at its contents. It is easy to modify correctly for the relationship between accounts and invoices. As you can see, the relationship name will become accounts_inv_invoices and I have used the shortened title label from the language file above.

2.3: The relationship metadata

The actual definition of the relationship is in the relationships/relationships directory. It consists of two main parts: the definition of the relationship and the definition of the database table that will hold the relationship, both the fields and the indices. Copy the file inv_invoices_inv_invoicelinesMetaData.php to accounts_inv_invoicesMetaData.php and modify it. As before it is pretty straight forward.

Note that I chose better names for the fields that hols the account and invoice IDs and better names for the indices. The module builder creates pretty nonsensical names for these. By default the module builder creates names from the first part of the left hand module and the last part of the right hand module. This can be outright dangerous if you use long module names. You can get collisions&mdah;that is, the same name for different relationships. One of the many bugs that still haunt the module builder. So, be smart and change the names.

2.4: The vardefs

Now we can add the proper fields to the vardefs of the modules. Both the Accounts and Invoices module need a field that points to the relationship, and the Invoices module also needs fields to hold the account name and ID. In relationships/vardefs create Accounts.php as follows:

Then, open up relationships/vardefs/inv_Invoices.php and add three fields. One for the relationship, one for the account name and one for the account ID. These are similar to the fields you can find in the vardefs file for the invoice lines.

As you can see, I have given the account_name field a label of LBL_ACCOUNT. We need to add this to the language file of the Invoices module. So, open up modules/inv_Invoices/language/en_us.lang.php and add an entry for that label.

3: Add the new relation to the layouts

The next thing to do is adding the account_name field to the editviewdefs, detailviewdefs and listviewdefs on the Invoices module. The editviewdefs and detailviewdefs speak for themselves. The listviewdefs is a little more complicated as you can see below. See also my older article “Fixing one-to-many relationships in SugarCRM 5.1” about adding relationships to listviewdefs, search panels and more.

4: Update the manifest

The new relationship is finished now but we need to make sure that the module loader loads the files that we just added. Open up manifest.php and add the relevant entries as shown below.

5: Deploy

Now the package is finished. You can now run the buildpackage.sh script to generate the installable zip and install it on your SugarCRM installation. Below are some screenshots of the Invoices module with the newly added relationship.

And this is what the edit view looks like.

You can download the full invoicing package that I created in this article. It has been tested on SugarCRM 5.1.0b.