v33.0.0 – Many-to-May+ and Random Salt

March 9, 2018


The release of Qobrix v33.0.0 expands the functionality of the many-to-many relationships and improves security with the random security salt.



Qobrix supported a variety of database relationships from day one.  One of these relationships is called many-to-many.  This one is useful when one module, for example a CRM Lead, can be linked to another module, for example a CRM Call, several times.  Each CRM Lead can have multiple calls associated with it, while any particular Call can be associated with multiple Leads.  Qobrix platform, being built on the CakePHP framework, had native support for such relationships, and it was very easy to define them in each module’s configuration.

As Qobrix platform matured, and was used for more and more complex applications, this simple setup become limiting and insufficient.  This is why Qobrix v33.0.0 introduces an expanded support for many-to-many relationships, which we internally call Many-to-Many+.  Plus stands for additional fields.  Let’s consider a different example of the Qobrix application.  The one that deals with Products and Orders.  Each Product can be a part of many different orders.  At the same time, each Order can, and usually does, contain several Products.  A simple many-to-many relationship is not enough in this case, as when the Product is linked to an Order, additional information, specific to the current Order, needs to be stored on the relationship.  Think of things like quantity, sub-total, discount, and comments.  In order to store these additional parameters, a joint table that holds the relationship between Products and Orders needs to have extra fields.  And not only this extra fields should exist in the database, the user interface needs to know how to render them, the permission system needs to know how to handle access, and the search and reporting system needs to know how to find and aggregate this information.

That is precisely what our Many-to-Many+ functionality aims to do.  As you can understand from the above description, adding support for many-to-many+ requires several significant changes to the Qobrix platform on a number of levels and in a number of different subsystems.  In order to assist with migrations and upgrades, and react faster to the feedback, we are splitting the implementation of this functionality into three milestones:

  1. Add support for many-to-many+ on the database and configuration level.
  2. Add support for many-to-many+ to the user interface.
  3. Add support for many-to-many+ to the search, reporting, security, API, and other subsystems.

Each one of these milestones will require a major release, changing how the Qobrix platform works.  Qobrix v33.0.0 introduces the first milestone – the support for the functionality on the database and configuration level.

At this state, the functionality is not yet visible or available to the end users.  However, system integrators and Qobrix application developers will need to do a few adjustments.  The changes are in several places, and below are the details of how it was implements.

First of all, we have removed the “manyToMany” section from all module’s configurations.  Instead, each join table is now implemented as a separate Qobrix module.  Yes, that’s right.  You’ll see a lot more modules in the configuration folder after the upgrade to this version.  Module naming convention follows the CakePHP naming convetion, with the relationship name consisting of the two tables in alphabetical order.  For example, the many-to-many relationship between Calls and Accounts now shows up as AccountsCalls module.

Implementing each many-to-many relationship as a separate module allows us to reuse all module functionality, such as configuration (icons, display fields, typeahead fields, etc), views, lists, and more.  It also will assist with easier plugging into the security and API subsystems later.   And we’ve also provided an upgrade script that will take care of this change for you.  Once you apply the upgrade scripts, all module configurations will be modified to remove the “manyToMany” section, and all currently configured relationships will be created as separate modules.  We’ll also create a separate database migration file for each one.  The database migration files will not modify the existing database in any way, but will provide a starting point for the later migrations.

Secondly, we have updated the module’s configuration schema to include the “type” property.  This property defines the type of the module.  All regular modules should set the type to “module”.  All new modules with the many-to-many relationship should use the type of “relation”.  Again, the upgrade script will take care of all existing configurations for you.

Thirdly, we have improved the API slightly to handle the related records better.  This is not yet the full support for the many-to-many+, but a starting point for easier handling of nested and complicated relationships.  And this change is also automatically handled once you upgrade to this version.

Random Security Salt

CakePHP framework is very security conscientious.  It provides a number of libraries, technologies and best practices out of the box to keep the security of the application in accordance to the best practices.  Qobrix platforms inherits and improves on this setup.  One particular aspect of the security setup is a random string for the security salt, which is used throughout the system for encryption and hashing purposes.  CakePHP provides a way to create a new random salt upon the system installation.  Qobrix improves this setup further by allowing a tight control over the security salt string over the environment files.

After building and deploying a number of Qobrix applications, we have realized that not many administrators pay attention to the security setup of their application, and often simply ignore the randomness and uniqueness of the security salt.  With Qobrix v33.0.0 we decided to make this setup easier to use, offloading the burden from the Qobrix application administrators.  From now on, the security salt is NOT defined in the environment files anymore.  Instead, it is stored in a separate file, which is ignored by version control.  During the installation or upgrade of the system, the build and deployment process will check if this file exists.  If it doesn’t a new random unique security salt will be generated and stored in the file.  If the file does exist, the security salt will remain as is.

This change, however, affects the existing and installed Qobrix applications.  Upon the upgrade to this version, a new security salt will be generated.  This will render all current sessions and tokens obsolete, so the users might need to logout, clear their cookies, and login again.  New application installations won’t need any special handling, as they will just start a new with the better security salt.

For those applications that had their own handling of the security salt, the adjustment needs to be made to store the custom salt in the “tmp/security.salt” file instead of the “.env” file.  Please don’t be alarmed by the temporary folder – it is project-based, rather than system-wide, and it is completely outside of the web server document root folder.  The two reasons we have placed this file in the temporary project folder are:

  • Security salt strings are not permanent and can be regenerated at any time, making them a temporary resource.
  • Project’s temporary folder is usually writeable by the Qobrix application, making it easier to generate the file when needed, during the application life cycle, rather than with a dedicated remote login by the administrator.

Component Updates