The Business Mappings and Conditions module permits implementors to define high level configuration options for the execution of the application.

Using different types of structured XML, JSON or direct SQL, this module will define conditions, field mappings and other advanced logic to modify the functionality of the application without the need to get into programming details.

This module also serves another purpose: separating the programmers from the implementors. In other words, it permits the programmers to create functionality in the application while giving to the implementor total control on how that functionality should act in different cases for different installations.

With this module we achieve a much more configurable application without the need to depend on specific programming knowledge.

Note that in the end, many of these mappings or conditions are actually a washed down configuration screen. Many times, from a programmers point of view, creating certain functionality is easy, the problem is creating a GUI for the user to be able to configure the different options that are present in the code. Usually we spend more time programming the interface than the actual solution. With Business Mappings and Conditions we create a spartan, manual but generic interface to many features without getting to complicated nor repeating work over and over.

We have a relation of different Business Mappings we use where you can find a whole set of different Business Mappings which can be used in your application directly or with easy modifications to adapt them to your needs.

Have a look here and please share your settings with us!

• Map Name: this is a textual identifier of the mapping. It is very important to use the exact name that each feature requires as that is what the code looks for. These names are constantly evolving as we add new features that use the mappings module
• Map Number: autonumeric reference field
• Map Type: the type of mapping that is required, Depending on the type, the structure of the contents field is different
• Map Contents: the actual definition of the mappings, normally this will be an XML structure

There are currently these different types of mappings:

• Condition Query
• Condition Expression
• (Field) Mapping
• Record Access Control
• List Columns
• Block Access TBD
• Import TBD
• Map fields TBD
• IOMap TBD
• Search and Update TBD
• Field Dependency TBD

Depending on the type of the business mapping the contents of the record changes as explained next.

Once a programmer has established the code changes to use a Business Mapping, the implementor has to create, one or more, records in the module with that type of Business Mapping.

Usually, the programmer will have created some examples and documentation on the exact formatting and options supported by the business mapping type.

Once created and configured the code will use the mapping.

Optionally, the implementor can create more than one mapping of this type with different configurations and then associate each one to different users, with the help of the Global Variable module.

The idea is to get the mapping to apply and then pass in the parameters so the mapping can be processed.

The correct way to do this is using the global variable module so that the mappings are dependent on the users and pass in the default mapping which you should have created.

  $cbMapid = GlobalVariable::getVariable('BusinessMapping_SalesOrder2Invoice', cbMap::getMapIdByName('SalesOrder2Invoice'));
  if ($cbMapid) {
	$cbMap = cbMap::getMapByID($cbMapid);
	$focus->column_fields = $cbMap->Mapping($so_focus->column_fields,$focus->column_fields);
  } else {
...

All global variable whose name starts with 'BusinessMapping_' will return the associated mapping.

In the code above, the Mapping called 'SalesOrder2Invoice' is the default mapping.

If the mapping is found we apply it by calling the type of mapping and passing the required parameters for each type.

You should consider implementing the 'else' part in case no mapping is found.

Adding a new process is rather simple:

• Add your mapping type to the changeset file so it gets added in the business mapping picklist
  • build/changeSets/cbMapAddMapTypes.php
  • see the code
• Add the translation of the mapping type to the modules/cbMap/language files
• Copy the file modules/cbMap/processmap/processMap.php to a file named as your mapping inside this same directory
• Now modify this file to process your mapping. Basically you will need a convert method that will convert the XML into a PHP array and then add methods that read the array and return answers, values or parts of that array

Once you have done that you will be able to launch your mapping by loading the CRMID and calling the mapping name.

Let's look at a real example: List Columns Mappings

As you can see in the commit, we add the ListColumns type to the picklist and translation files. Then we add a new script that, first documents the required XML structure, then converts the XML to an array for easier processing and then defines a set of helper methods to extract information from the mapping.

Finally you can see how this is used here. Once we have a Mapping ID, we load it:

$cbMap = cbMap::getMapByID($cbMapid);

and then call the ListColumns mapping type to initialize the internals (call processMap) and from there we call the helper methods to get the information we need:

$focus->search_fields = $cbMap->ListColumns()->getSearchFields();