Back to S100: System Installation and Maintenance

Lesson 4: Maintaining Tenants

In this lesson, you will learn how to add more tenants to an Acumatica ERP instance and remove unneeded ones. Additionally, you will explore various modifications that can be made to tenants to meet your company's requirements.

Tenant Maintenance: General Information

Acumatica ERP provides you with the ability to create additional tenants, maintain them, and delete them by using the Acumatica ERP Configuration wizard. This topic describes the ways of adding tenants by using the Acumatica ERP Configuration wizard, provides an overview of the System and custom parent tenants, and explains various changes that can be made to tenants.

Learning Objectives

In this lesson, you will do the following:

Become familiar with the process of adding more tenants
Become familiar with the System tenant, a custom parent tenant, and the tenant hierarchy
Create an additional tenant
Deploy a multitenant Acumatica ERP instance
Explore the visibility of tenants
Learn about restrictions on tenant access
Delete a tenant

Applicable Scenarios

You may need to learn how to maintain tenants of the Acumatica ERP instance in scenarios that include the following:

You are an implementation consultant who needs to add an additional tenant to the existing Acumatica ERP instance.
You are an implementation consultant who needs to know what the System tenant is and how to create a custom parent tenant.
You are a system administrator who needs to restrict access to some tenants within the Acumatica ERP instance for employees of the company.

The System Tenant and Tenant Hierarchy

When you deploy an Acumatica ERP application instance, the hidden System tenant is always created automatically. The System tenant has an ID of 1 in the Parent Tenant ID column on the Tenant Setup page of the Acumatica ERP Configuration wizard. The System tenant contains predefined system data, such as preconfigured roles and numbering sequences, as well as wiki-based documentation. The system data is used by all tenants of the same application instance. By default, the System tenant is hidden and all user-created tenants inherit the initial configuration and system (predefined) data from the System tenant. That is, in the tenant hierarchy, the System tenant serves as the root tenant and is the parent of all other tenants. All the data available in the System tenant is visible to other tenants in the same database. Lesson 4: Maintaining Tenants | 55

When you create a new tenant, its parent tenant must be selected; the System tenant is inserted as a parent by default. If you create a new tenant by using the Acumatica ERP Configuration wizard, you can select any parent tenant for each of the child tenants by specifying its ID in the Parent Tenant ID column. If you create a tenant on the Tenants (SM203520) form, the System tenant is assigned as its parent automatically and you cannot change it. For details, see Managing Tenants by Using the Web Interface.

          Users can sign in to only child tenants. If you select an existing tenant to be a parent, users will not be
          able to sign in to the parent tenant anymore.

You cannot delete the System tenant.

Creation of Additional Tenants

For an Acumatica ERP instance, you can create additional tenants on the Tenant Setup page of the Acumatica ERP Configuration wizard during or aer the initial deployment of an instance. You can add an additional tenant to the instance by clicking Create on the Application Maintenance page of the wizard. For details, see Tenant Maintenance: To Create an Additional Tenant. Also, you can create tenants and view information about their settings on the Tenants (SM203520) form. For details, see Managing Tenants by Using the Web Interface.

A Custom Parent Tenant

An application update or upgrade replaces all the data available in the System tenant, while the data created by users in user-created tenants remains unchanged. If you would like to replace preconfigured data, such as roles and numbering sequences, similarly for multiple new tenants, you can create a custom parent tenant: a parent tenant that will be used instead of the System tenant for your new tenants. To configure a custom parent tenant, you create a new tenant on the Tenant Setup page of the Acumatica ERP Configuration wizard and provide a name that clearly indicates how this tenant will be used (for example, NewParent or MyParent). This tenant is a child of the System tenant and inherits all its data. In the custom parent tenant, you can override the preconfigured settings as needed and specify other configuration settings to be used in all the new tenants. Then when you create a new tenant by using the Acumatica ERP Configuration wizard, you specify the custom parent tenant as the parent tenant of the new tenant. The new tenant will inherit all the data from the custom parent tenant rather than from the System tenant. You can create a custom parent tenant that is a child of another parent tenant. Note that users cannot sign in to a parent tenant.

          You can create new tenants based on the custom parent tenant only by using the Acumatica ERP
          Configuration wizard. If you create new tenants on the Tenants (SM203520) form, the System tenant
          is assigned as its parent automatically. Due to technical limitations, you can have a maximum of
          127 tenants on an Acumatica ERP instance. This includes all types of tenants, irrespective of their
          statuses.

Restriction of Access to Tenants

In a multitenant Acumatica ERP instance, the tenant selection box appears on the Sign-In page by default, allowing users to select the tenant to sign in from the list of all available tenants. If you want to restrict the list of tenants a user can see to only those the user has access to, select the Secure Tenant on the Sign-In Page check box on the Tenant Setup page of the Acumatica ERP Configuration wizard. In this case, the tenant selection box does not appear on the Sign-In page by default, and all users must first authenticate themselves by entering their username and password. Depending on the user, one of the following occurs: Lesson 4: Maintaining Tenants | 56

A user who has access to only one tenant will be automatically signed in to that tenant aer entering their username and password.
A user who has access to multiple tenants and has the same credentials for these tenants must select a tenant in the tenant selection box, which appears aer the user has been authenticated and contains the list of tenants available to the user.
A user who has access to multiple tenants and has diﬀerent credentials for diﬀerent tenants is signed in to the tenant whose credentials the user entered on the Sign-In page.

If a user who has access to multiple tenants and signs in to an Acumatica ERP instance by using single sign- on (SSO) with an external identity provider, the user is signed in to the first tenant that is listed on the Tenant List (SM203530) form with SSO enabled.

                 If you are using multiple tenants and SSO authentication and the Secure Tenant on the Sign-
                 In Page check box is selected, ensure that all users can sign in to the first tenant listed on the
                 Tenant List (SM203530) form. If a user cannot sign in to the first listed tenant, they will not be
                 able to select a diﬀerent tenant to sign in to.

Visibility of Tenants

You can define the visibility of tenants for users on the Sign-In page of the Acumatica ERP instance. You do this by
clearing or selecting the check box in the Visible column in the row of the tenant on the Tenant Setup page of the
Acumatica ERP Configuration wizard. For details, see Tenant Maintenance: To Change Tenant Visibility

Deletion of Tenants

You may need to delete an existing tenant. You can do this by using the Acumatica ERP Configuration wizard. On
the Tenant Setup page of the wizard, you can select the tenant you want to remove and click Delete. For details,
see Tenant Maintenance: To Delete a Tenant.

           Because any tenant you see on the Tenant Setup page may be in production, you should create
           backups before making any changes.

Tenant Maintenance: To Deploy an Instance with Multiple Tenants

The following activity will walk you through the process of creating an Acumatica ERP application instance with
three tenants. You will also make some changes to the tenants of the instance.

Story

Suppose that you are the system administrator for a group of companies, and you need to deploy the Acumatica
ERP application instance with three tenants, one for each of the companies included in the group. You also need to
make some changes to the tenants and then delete one of the existing tenants.

Process Overview

In this activity, you will do the following:

Deploy the Acumatica ERP application instance with three tenants.
Set up the visibility of a tenant.
Delete an existing tenant. Lesson 4: Maintaining Tenants | 57

System Preparation

Before you begin deploying an Acumatica ERP application instance, make sure that you have performed the following prerequisite activity: Acumatica ERP Installation On-Premises: To Install the Acumatica ERP Configuration Wizard.

Step 1: Creating an Instance with Multiple Tenants and Changing Tenants’ Visibility Settings To create a multitenant Acumatica ERP instance, do the following:

On the Start menu, click Acumatica ERP Configuration to open the Acumatica ERP Configuration wizard.
On the Welcome page, click Deploy a New Acumatica ERP Instance.
On the Database Server Connection page, specify the following settings, and then click Next to go to the next page:

Server Type: Microso SQL Server
Server Name: (local)
Windows Authentication: Selected

On the Database Configuration page, specify the following settings, and then click Next to go to the next page:

Create a New Database: Selected
New Database's Name: AcumaticaMultitenant

On the Tenant Setup page, do the following to configure the tenants of the instance: a. Click the Create button twice to add two more new tenants in addition to the default new tenant, so that there are three new tenants in the list. The system automatically assigns the following names to the tenants in the Tenant Name column:

For a tenant with an ID of 2: Company
For a tenant with an ID of 3: Company2
For a tenant with an ID of 4: Company3 b. In the first tenant in the list (the Company tenant), double-click in the Parent Tenant ID column. Notice that you can select only the default parent tenant (the System tenant, which has an ID of 1). c. Select the Advanced Settings check box below the table. Now the wizard also displays the System tenant in the table. Notice that the Visible check box for this tenant is cleared, meaning that users do not see it. d. In the row with the Company tenant, clear the Visible check box. e. In the row with the Company3 tenant, double-click in the Parent Tenant ID column and select 2, as shown in the screenshot below. This makes Company3 the child of Company. In this configuration, users will be able to sign in to only Company2 and Company3, because these tenants do not have children. Lesson 4: Maintaining Tenants | 58
```
Figure: The tenants to be created for the instance
```
f. Click Next to go to the next page.

On the Database Connection page, select Windows Authentication; click Next.
On the Instance Configuration page, specify the following settings, and then click Next to go to the next page:

Instance Name: AcumaticaMultitenant
Create Acumatica ERP Site: Selected
Local Path to the Instance: The path on the local computer to the application instance

On the Website Configuration page, specify the following settings, and then click Next to go to the next page:

Website Settings: Default Web Site
Create Virtual Directory: Selected
Virtual Directory Name: AcumaticaMultitenant
Use Existing Application Pool: Selected
List of existing application pools: DefaultAppPool Leave the other settings without changes.

On the Confirmation of Configuration page, click Finish, and wait while the new application instance is created. 10.Aer the installation is completed, click OK in the dialog box to return to the Acumatica ERP Configuration wizard. 11.Click Perform Application Maintenance. On the Application Maintenance page, which opens, the list of existing application instances now contains three sites: AcumaticaT100, AcumaticaS100, and AcumaticaMultitenant, as shown in the following screenshot. Lesson 4: Maintaining Tenants | 59
```
    Figure: The list of the application instances

 12.Click the row with the AcumaticaMultitenant instance, and then click Launch.
    The instance opens in a new tab of your default browser. Notice that the instance’s Sign-In page has the
    tenant selection box above the Sign In button with the Company2 and Company3 tenants you have created
    in this step, as shown in the following screenshot.


    Figure: The Sign-In page with the tenant selection box
```

Step 2: Setting Up Tenant Visibility To make changes to tenants of the created instance, do the following:

Go back to the Acumatica ERP Configuration wizard.
On the Application Maintenance page, click the row with the AcumaticaMultitenant instance, and click Maintain Tenants.
In the SQL Server Authentication dialog box, leave Windows Authentication selected, and click OK. The Tenant Setup page is displayed for the selected instance.
Click Create to add one more tenant to the instance. Lesson 4: Maintaining Tenants | 60
The system adds a new row with the Company4 tenant to the list.
Select the Secure Tenant on the Sign-In Page check box. This hides the tenant selection box on the Sign-In page until a user enters a username and password. Aer the user is authorized, the system displays the tenant selection box with the list of tenants to which the user can sign in.
In the row with Company3 tenant, clear the check box in the Visible column. This makes the tenant invisible to all users. Only the Company2 and Company4 tenants have the Visible check box selected, as shown in the following screenshot.
Figure: The restriction of tenant visibility on the Sign-In page
Click Next.
On the Confirmation of Configuration page, click Finish.
Aer the application instance is updated, click OK in the dialog box to return to the Acumatica ERP Configuration wizard. 10.Click Perform Application Maintenance. 11.On the Application Maintenance page, click the row with the AcumaticaMultitenant instance, and click Launch. The instance opens in a new tab of your default browser. Notice that the instance Sign-In page does not have the tenant selection box. 12.Enter the default username and password for the application instance (admin and setup, respectively). Because the admin user has access to all the tenants you have created, the tenant selection box is displayed for the user. Notice that only Company2 and Company4 are available for signing in, as shown in the following screenshot. Lesson 4: Maintaining Tenants | 61
Figure: The tenant selection box on the Sign-In page

13.Select the Company2 tenant in the tenant selection box and click Sign In. The Sign-In page refreshes and shows the read-only tenant selection box with the selected Company2 tenant. The system prompts you to enter a new password and confirm it, as shown in the following screenshot.

Figure: Creation of a new password for a tenant in a multitenant instance

14.Enter a new password and confirm it. 15.Click the link of the Acumatica User Agreement above the Sign In button, read the agreement, and then select the check box to indicate that you have read the terms of the agreement and agree to them. 16.Click Sign In. You have signed in to the AcumaticaMultitenant instance. Now you can work within the Company2 tenant. 17.Sign out. 18.On the Sign-In page, enter the default username and password for the application instance (admin and setup, respectively) to access the Company4 tenant. Since the admin user has access to all the tenants you have created, the system prompts you to change the default password for the Company4 tenant, as shown in the following screenshot. Notice that because you have entered the default password, the tenant selection box for the remaining Company4 tenant does not appear. Lesson 4: Maintaining Tenants | 62

      Figure: Creation of a new password for another tenant in a multitenant instance

   19.Change the password and click Next.
      You have signed in to the AcumaticaMultitenant instance. Now you can work within the Company4 tenant.
      You can also switch to the Company2 tenant in the user menu, as shown in the following screenshot.


      Figure: Access to multiple tenants

Step 3: Deleting an Existing Tenant In this step, you will delete the unnecessary tenant by doing the following:

Return to the Acumatica ERP Configuration wizard.
While you are viewing the Application Maintenance page, do the following: a. In the Installed Sites list, click the row with the AcumaticaMultitenant instance. b. Click Maintain Tenants.
In the SQL Server Authentication dialog box, leave Windows Authentication selected, and click OK.
On the Tenant Setup page, select the row with the Company4 tenant in the Installed Tenants list.
Click Delete.
Click OK in the confirmation dialog box to delete the tenant.
Click Next.
On the Confirmation of Configuration page, do the following: a. Check the configuration settings you have specified. b. Click Finish to delete the tenant. Lesson 4: Maintaining Tenants | 63

Tenant Maintenance: To Explore Tenant Visibility

The following activity will walk you through the process of exploring how tenant visibility aﬀects the existing
Acumatica ERP application instance.

Story

Suppose that you are the system administrator of your company, and you have been asked to add a new tenant to
the existing Acumatica ERP application instance. You will explore how to use the visible tenant as a parent tenant.
Additionally, you will verify the capability of having an instance where all tenants are invisible.

Process Overview

In this activity, you will explore the visible capabilities of tenants.

System Preparation

Before you begin performing the step of this activity, make sure that you have performed the following prerequisite
activity: Instance Deployment: To Deploy an Instance with Demo Data.

Step: Exploring the Capabilities of Tenant Visibility To explore the capabilities of tenant visibility, do the following:

On the Start menu, click Acumatica ERP Configuration to open the Acumatica ERP Configuration wizard.
On the Welcome page, click Perform Application Maintenance.
In the list of existing application instances, select the row with the AcumaticaT100 instance, and click the Maintain Tenants button.
In the SQL Server Authentication dialog box, leave the default settings, and click OK. This opens the Tenant Setup page, which shows the full list of tenants for the selected application instance.

Select the Advanced Settings check box below the list of tenants. The system displays the default System tenant with an ID of 1 in the list of tenants.

                With the Advanced Settings check box selected, you can also select a new data template in
                the Insert Data column for an existing tenant. If you finish updating the tenant, the Acumatica
                ERP Configuration wizard replaces the tenant data with the data of the selected template.

Clear the Visible check box in the row with the Company tenant, and click Next. The system displays a warning informing you that you cannot continue with all the instance's tenants being invisible.
In the warning dialog box, click OK.
On the Tenant Setup page, to which you return, do the following: a. Click Create below the list of tenants to add one more tenant. b. For the new tenant, select 2 in the Parent Tenant ID column. c. Select the Visible check box in the row with the Company tenant. d. Click Next. Lesson 4: Maintaining Tenants | 64
The system displays an error message informing you that you cannot continue because only an invisible tenant can be specified as a parent of another tenant, as shown in the following screenshot.
Figure: The error message
In the dialog box, click OK. The system automatically clears the Visible check box in the row with the Company tenant. 10.On the Tenant Setup page, to which you return, do the following: a. Make sure that the Visible check box is selected only in the row with the new tenant, and that 2 is selected as the Parent Tenant ID in this row. b. Click Next. 11.On the Confirmation of Configuration page, review your changes, and click Finish. 12.Wait while the application instance settings are updated, and click OK. Lesson 5: Maintaining Instances | 65