Access to add and change pages is restricted. See: https://cwiki.apache.org/confluence/display/OFBIZ/Wiki+access

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 31 Next »

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

Important!

This tutorial is intended to be used with SVN revisions greater than 927271. It will not work with Release 4 or 9.04.
Currently the Ecommerce for Tenants is not supported.

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.

If you want to use OFBiz with only one database, there is nothing to change in what you were doing before.

The advantage with multi-tenant is that the tenant doesn't need access to load data using something like "ant run-install ..." or anything else on the command line. You could have hundreds of people active in other tenant instances so you don't want to stop and start the server to do anything like this, and hopefully you can avoid having an admin work with the tenant to get custom data loaded. You want things to be self-service, and that is the point of making it database driven (with a UI so the user can get stuff into the relevant portions of the database).

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-container.xml

yourTenantConfig.xml

Per Tenant add the following:
<Tenant tenantId="TENANT" tenantName="Tenant Name"/>

Note!

The TenantDataSource elements in the TenantDemoData.xml are only there to simplify the derby configuration for a quick demo. For any datasource based on non-derby, you will have to go the stony way described here.

ofbiz-container.xml

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

Make sure you understand at which load-level (with which reader) this file is going to be loaded. The data in the file needs to be loaded before OFBiz will be able to address any tenant data source!

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 each tenant database as follows:

Datasource reference on delegator

Add the datasource reference to your delegator element
<delegator name="default" entity-model-reader="main" entity-group-reader="main" entity-eca-reader="main" distributed-cache-clear-enabled="false">
(...)
<group-map group-name="org.ofbiz.tenant" datasource-name="localpostnew#TENANT"/>

Note!

Notice the naming convention for the datasource: The datasource-name value carries a "#" followed by the tenantId (from the yourTenantConfig.xml).

Datasource configuration

Add a datasource configuration element with the respective name. Just copy the existing entry for your database technology and change name, connection string etc accordingly.

Practical hint on 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.

Loading Tenant.

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

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

All of the following commands must be executed in sequence.

===========================================
$ svn co https://svn.apache.org/repos/asf/ofbiz/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
===========================================

Note that the long java lines instead of something like "ant run-install" are used in order to be able to specify a delegatorName.

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

Tenant Databases

The database are defined in the TenantDataSouces Entity not in the entityengine.xml
see the demo data in /framework/endity/data/TenantDemoData.xml

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) before running the tenant(s) data installation.

note!

It is suggested to use derby to test then look at the /runtime/data/derby/ for the dbnames that ofbiz will be looking for.

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:

...
<context-param>
    <param-name>entityDelegatorName</param-name>
    <param-value>default#tenantId</param-value>
    <description>The Name of the Entity Delegator to use, defined in entityengine.xml</description>
</context-param>
...

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

...
<context-param>
    <param-name>entityDelegatorName</param-name>
    <param-value>default#DEMO1</param-value>
    <description>The Name of the Entity Delegator to use, defined in entityengine.xml</description>
</context-param>
...

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

For more info you can check https://issues.apache.org/jira/browse/OFBIZ-3579 and the patch attached there.

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.

The incoming domain name sets the tenantId, so the changes in web.xml of the ecommerce is not required.

  • No labels