The Business Mappings and Conditions module permits implementers 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 implementers. In other words, it permits the programmers to create functionality in the application while giving to the implementer 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 programmer’s 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 or repetitive work over and over.
Fields of Business Mappings
-
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 mapping module
-
Map Number: auto numeric 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.
Types of Business Mappings
There are currently these different types of mappings:
-
Condition Query
-
Condition Expression
-
(Field) Mapping
-
Extended Field Information Mapping
-
Record Access Control
-
List Columns
-
RecordSet Mapping
-
Module Set Mapping
-
FieldSet Mapping
-
Master-Detail Mapping
-
IOMap
-
Field Dependency
-
Validations
-
Related Panes
-
Import
-
Duplicate Records
-
Global Search Autocomplete
-
Detail View Layout
-
Decision Table
Depending on the type of business mapping the contents of the record changes as explained next.
The two most typical business map errors are:
-
giving the record the wrong name: most business maps are launched depending on their name, so you must set it correctly
-
invalid XML: https://www.xmlvalidation.com
How an implementer can use a Business Mapping
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.
How a programmer can use a Business Mapping
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 variables 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.
How a programmer can add a Business Mapping Type
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
-
-
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();
In the next sections, we will study all the types of business mappings listed above.