Multitenancy support and how to use it

This tutorial document is meant for explaining the OFBiz multitenancy functionnality. It will help to configure and use it

Introduction

Multi-tenancy has been introduced in OFBiz at rev 927271. Multi-tenancy is the ability to run separate data instances (tenants) from a single copy of OFBiz. Each data instance is kept in a separate database. A user logs into a data instance (or tenant) by specifying the tenant ID in the login form. Note that a default database is still used.

If you want to use OFBiz with only one database (ie you don't want to use multi-tenants), there is nothing to change in what you were doing before.

Tenant Databases

The datasources (= database references) are defined in the TenantDataSouces Entity not in the entityengine.xml (cf. description below).

Of course, if you are using a DBMS which does not support the ";create=true" syntax used OOTB with Derby (eg Postgres, MySql, etc.) you need to create the tenant(s) DB(s) and credentials before running the tenant(s) data installation.

Configuring for MultiTenant

The configuration files that need to be touched are the following:

• OFBIZ-HOME/framework/entity/data/<yourTenantConfig>.xml
• OFBIZ-HOME/framework/entity/config/entityengine.xml
• OFBIZ-HOME/framework/entity/ofbiz-component.xml

yourTenantConfig.xml

Per Tenant add the following:

This information will be stored on the database that you specify underneath the org.apache.ofbiz.tenant entity group on entityengine.xml.

ofbiz-component.xml

Add a row to load your own config file above OR alter the row pointing to the DemoTenantData.xml

This means: If you decide to assign this file load to the reader="ext", you need to execute the following data read sequence before you can access the tenant databases:

$ java -Xmx512m -XX:MaxPermSize=128m -jar ofbiz.jar -install -readers=seed -delegator=default
$ java -Xmx512m -XX:MaxPermSize=128m -jar ofbiz.jar -install -readers=seed-initial -delegator=default
$ java -Xmx512m -XX:MaxPermSize=128m -jar ofbiz.jar -install -readers=ext -delegator=default

Of course you can group this all into a single data loader run:

$ java -Xmx512m -XX:MaxPermSize=128m -jar ofbiz.jar -install -readers=seed,seed-initial,ext -delegator=default

It is not a good idea to assign this file-load to readers="seed", because seed and seed-initial level data will be loaded to every tenant database as well.

entityengine.xml

Add a dedicated datasource entry for persistence of the tenant data sources as follows:

Datasource reference on delegator

Add the datasource reference to your delegator element

Datasource configuration

Add a datasource configuration element with the respective name ('localpostnewtenant' in this example). Just copy the existing entry for your database technology and change name, connection string etc accordingly.

Loading Tenant.

To load the multi-tenant demo, run ant run-install-multitenant OR ant load-demo-multitenant.

To set up the databases for multi-tenancy and load the seed data only, do the following:

$ svn co [https://svn.apache.org/repos/asf/ofbiz/ofbiz-framework/trunk] ofbiz
$ ant
$ java \-Xmx512m \-XX:MaxPermSize=128m \-jar ofbiz.jar \-install \-readers=seed \-delegator=default
$ java \-Xmx512m \-XX:MaxPermSize=128m \-jar ofbiz.jar \-install \-readers=seed \-delegator=default#DEMO1
$ java \-Xmx512m \-XX:MaxPermSize=128m \-jar ofbiz.jar \-install \-readers=seed \-delegator=default#DEMO2
$ ant run

Starting with revision New Revision: 1172989 two new ant command are added which will load all seed/demo data of components which are not connected to a tenant or connected with this specific tenant, or load all tenants this way.

In order to know which component are connected to which tenant, 2 entities were added:
1. Component (is automatically loaded by ant run-install)
2. TenantComponent

With the following xml file lines these entities can be connected with a tenant
<TenantComponent tenantId="tn1" componentName="cpn1"/>

Available command detail:
1. By using: "ant run-install-tenant" (load specify component data filter with tenantId)
1.1 "ant run-install-tenant" will install all tenant data (reader=tenant)
1.2 "ant run-install-tenant -DtenantId=<tenantId>" will install all tenant data and then run install all default OFBiz components and only components related to tenant (all readers).
1.3 "ant run-install-tenant -DtenantId=<tenantId> -Ddata-readers=seed,seed-initial,..." will install all tenant data and then run install all default OFBiz components and only components related to tenant (specify readers).
1.4 "ant run-install-tenant -DtenantId=<tenantId> -Dcomponent=<componentName>" will install all tenant data and then run install all default OFBiz components and and only one component.

2. By using: "ant run-install-all-tenants" (load all tenant and all data)
2.1 "ant run-install-all-tenants" will install all tenant data and then install all data (separate data by each tenant).
2.2 "ant run-install-all-tenants -Ddata-readers=seed,seed-initial,..." will install all tenant data and then load specify reader (seperate data by each tenant).

Practical hint on entity readers

It may make sense to define new readers per tenant in order to avoid tenant-specific data to be loadad on each tenant database. This is of special interest if you are planning to segragate tenants later on, i.e. using the tenant database with a dedicated tenant OFBiz instance.
In order to do this: Define more readers in entityengine.xml and use them in the ofbiz-component.xml to mark exclusive files for a certain tenant.

Delegator naming convention

In order to address data for be loaded only for a specific tenant, the tenant's delegator needs to be specified. the naming convention is as follows:

• delegatorname (from entityengine.xml; in most cases this equals 'default', but you may have renamed your delegator ....)
• #
• tenantId (is has become a practice to use UPPPERCASE for this Id; it is the same Id that you use to authenticate for a certain tenant as per the next section)

Displaying the tenant Id field for connection

in framework/common/config/general.properties, change the multitenant option to Y
This will show the TenantID for login.
For Demo purposes use the DEMO1 and DEMO2

Setting the ecommerce app. to use a specific Tenant Database

You can determine the tenant used in the ecommerce app. setting the paramenter entityDelegatorName in the web.xml file of the web application, as follows:

where tenantId is the Tenant ID of your ecommerce app. For example, for the Tenant DEMO1 the code will be:

Then, ensure that exists a "ProductStore" related with the "WebSite" settled in the parameter webSiteId of the previous web.xml file. You can load a demo product store (related with the websiteId "WebStore") doing this:

$OFBIZ_HOME> java -Xmx512m -XX:MaxPermSize=128m -jar ofbiz.jar -install -readers=seed,demo -delegator=default#tenantId

Setting the initial path according to domain name

You can determine a initial path used in the tenant

<Tenant tenantId="TENANT" tenantName="Tenant Name" domainName="domain.name" initialPath="/initial"/>

If a user enter any domain names (without mount point) which be specified in the Tenant entity then the system would redirect to the initial path.
If the system doesn't has any web application with root mount but a user would like to use the tenant feature with redirecting to the initial path, the user have to create a new web application for the root mount.
If the system already has a web application with root mount and don't want it redirect to the other path, just don't put the domain that was using in the Tenant entity.