Tuesday, May 28, 2013

Understanding Company Setup Options

Hi Everyone,

Lets discuss companies setup using Configuration Setup application.

Company Setup in Acumatica designed to be using the same tables by multiple entities.
And when the record is shared, we are not replicating it but truly share.
To isolate one company from another within a table we have Masks as a column, they are processed automatically by Server application, to ensure we see a correct company data.

In order to understand the design, we need to put few considerations:

1. There is a single top level company and we use it as  a system storage for kernel data. This company is in Read Only mode for the end user. No data can be amended or inserted into that company and it stays at the top level node of the hierarchy tree.

What it means to us? Effectively, this top company is a break-point for any updates coming from below nodes. No data can be passed through this node to another nodes. Its a true dead end for any data coming from its children.

This company has fixed ID and it is always equal to 1 [One]. Consider it as Master Parent company.

2. We can create unlimited number of "normal" Parent Companies. But the trick is - if company is Parent, it can not be used for the users to log into it. It looks like a nonsense but you will soon understand what is the purpose of such Parent node. Parent company is the one that have child companies. Parent company can be a child of another, higher Parent company. Parent Companies data can be modified, updated or inserted. And because we can not directly log in into Parent Company, these updates/insertions can only be made either by it's child companies, it's parent companies or directly inserting data into it from a Template, using Configuration Tool.

3. We can create unlimited number of child companies, which can not be parent to any other companies. Forever young, in a sense :) It means we call a child a company that has parent but does not have its own children. Data in those companies are modifiable as well. And because we can log in into them we can modify data directly, or modification can be done by it's parent.

4. We have a data sharing mode or setup for all companies on a PER TABLE basis. Say, we define sharing data or data isolation (whatever you like) once only in a single place, for each table in the database. And it applied to all and any company immediately. There is no individual sharing/isolation mechanisms per company. But soon you will get that it is not necessary to setup isolation per company, it must be global setting :), per table. I will discuss how it works later, but let me mention: there could be Separate, Split or Share data isolation modes.

Lets start from a simple configuration with 2 child companies, 1 parent and of course 1 master parent.

In this example companies 3 and 4 will be used for log in, they are "true companies". The end user will think that there are only companies 3 and 4. Company 2 will be invisible. And company 1 is not only invisible, but it is Read Only :).

So you may ask a question, why do we need company 2?
The answer is - we need it to transfer data for the tables in SHARING DATA MODE from company 3 to company 4, because we can not transfer via company 1, remember, its Read Only one.
Secondly - we can use company 2 to propagate template data to child companies 3 and 4 for the tables in SPLIT DATA MODE.

So what if we need to share GL Accounts between companies 3 and 4, at the same time we would like to pre-populate the list of Customers for companies 3 and 4 with some list, but we would like to let end users to modify customers independently in companies 3 and 4.

Basically, for Account table we will use SHARE data isolation mode. While for Customer table (BAccount in fact) we will use SPLIT data isolation mode.

Exactly, when we use SHARE, data will be shared between companies 3 and 4, whatever update you made in co 3 will be propagated to co 4 and vice verse. But when we use SPLIT, data from Parent company are VISIBLE in child companies, and the end user will think that these data are actually company 3 or 4 data.
But at the moment you will update/delete/insert data in any of the child companies 3 or 4, data will become independent and for that particular data row from table Customer, system will SPLIT the row between company 3 and 4, creating 2 independent rows.

Well, all other tables we will keep in SEPARATE data isolation mode, which means they are absolutely isolated and independent in companies 3 and 4.

I predict some of you will say - we can use data import instead, why do we need this strange SPLIT mode at all! Well here are two reasons for it:
1. In split mode, before you made any modification to a data row, you save significant amount of database space, by not creating a row of data per company, instead, using a SINGLE row for ALL companies.
2. There are cases when we need to setup exactly the same list of entities for every new company. And running Data Import every time may not be a good option. As we might need to spent significant amount of time for it.

Anyway, if you do not like SPLIT mode, just use Data Import. And concentrate on SHARE and SEPARATE modes only :)

So, lets get to practice. Setup from above should look like this:

Take note, for Parent companies we must NOT check Visible option.
Then we have to setup companies first before going to data isolation configurations.

Now we have to add template data to company 2, I will use Demo company data.
Later it supposed to propagate Chart of Account to both companies 3 and 4, as well as pre-define customers and vendors in companies 3 and 4. Of course companies 3 and 4 will need to get setup for gl/ar/ap etc, which I will do manually but skip here.

Once setup is processed lets assign that Account we share and BAccount (Customer,Vendor,Employee) we split.

Then press Next and process the changes into a database.

Please take note, we should insert template data first then change isolation mode.

Now lets take a look at companies 3 and 4. COA is in place and shared and Customers are propagated as well.

And if I now change the customer in company 3, it will not affect company 4. Where the same list of customers if pre-created.

I only hope that concept of Companies and their data sharing modes became a bit clearer. Also, there is nothing wrong in setting companies structures like below:

Here we have Parent->Parent->Parent relationship between companies 1, 2 and 5.
And even if we switched on SHARE mode data from left company group (2,3,5,8,9) will never go to either company 4 or group of companies (6,7). Simply because company 1 is in Read Only mode and data can not pass through it.

So three blocks (2,3,5,8,9) ; (4) ; (6,7) are completely isolated from one another and can exchange data only within itself.

Have a great time configuring your companies :)

All the best,


  1. This is great blog for Acumatica users.
    I am wondering if you have some samples/explains on how to use web service generated by acumatica to query data?

    1. Thank you for the comment, I will definitely post about web service it in the future.

  2. Great! Thanks.

    We learned a lot from this blog and appreciate your works (seems like this blog is the only one I could find in internet which is very useful to us, I believe to any users of Acumatica also).

    I have recommended this blog to others colleague in our team. can't wait for your posts of web service.

  3. It can helps me a lot of reading your blog. Thank you so much.

  4. This comment has been removed by a blog administrator.

  5. Hi Sergey,

    I followed your steps, but when I update chart of account from company 3 it does not effect to company 4 :(

    1. You have probably mixed COA and Business Account. Please use the right table.

    2. Hi Sergey,

      I set COA (Account table) and Business Account (BAccount table) table SHARE mode, but it does not effect, could you help me to define the issue ?

    3. Please post a request to our support centre, if you are a partner. Or come to your partner for guidance, they could review your setup and find an issue.

  6. Hi Sergey,
    This module is apply for version 5.2?

  7. Company Masking applicable to any version.

  8. Great! Thanks for your information.

  9. Hi Sergey,
    I have some question about Sharing data between Tenancy.
    Can you help me solve my trouble?.
    I had set Table Account and BAccount to share --> It can see each other.
    But when I'm Insert new record it just insert for company 3 not insert to company 4, so it can't share data to company 4.

    1. Hi Hoang Long, there are ways to share record insrted for comapy 3, but make it visible from company 4. Record must not be duplicated. Here is the main trick actually. Record from company 3 will be visible in co's 3 and 4.

  10. Thanks for your reply. I had solve my problem.
    Your blog is great!