Summary
This page contains information on how to create a tenant in AppBase.
The tenant can be created in two ways:
- Automatic tenant creation
- Manual tenant creation
Automatic tenant creation requires a user with DBA privilege and is used when there aren't any specific requirements to the schema name or tenant directory names, because all tenant properties are configured by the AppBase and an arbitrary schema name is used.
Common use for automatic tenant creation is either AppBase Cloud installation or a developers AppBase installation when a DBA user is available for developer database.
Manual tenant creation is most commonly used on UAT or Production environments where it makes more sense to use limited security credentials for AppBase schema users or when particular schema names must be used. For manual tenant creation a DBA user creates empty tenant schema and assigns necessary privileges to it - after it the AppBase scripts are used to create database objects in the empty schema necessary for the AppBase tenant to function and finalize the tenant creation.
Manual Tenant Creation
1 Prepare Tenant Schema
Before creating the tenant you need to prepare the tenant's schema
The tenant schema can be prepared in two modes:
- using pre-created empty tenant schema available (existing empty schema mode)
- no the tenant schema created by AppBase (auto-generated schema mode)
For Existing Empty Schema Mode DBA user is not required - however it is required for someone with DBA level access to create an empty tenant schema and assign the necessary privileges to it. Please refer to this article for the information how to create an empty tenant schema and assign necessary privileges: Pre Installation Steps
Auto-Generated Schema Mode takes care about creating and configuring the schema, however this mode requires DBA user provided to AppBase and the mode generates arbitrary schema name.
Choose one of the two modes and continue to one of the two sections: Auto-Generated Schema Mode or Existing Empty Schema Mode
Auto-Generated Schema Mode
Make sure that you have specified valid DBAUser and password for DBAUser, DBAPassword placeholders.
AppBase will create the schema and assign all necessary privileges during tenant creation. Continue to the Create Tenant section
Existing Empty Schema Mode
User with DBA level access needs to create an empty tenant schema
1.1 Schema preparation by DBA user account
If the schema has been already prepared for you by your DBA (it was created and required privileges and quotas were assigned to the schema) then please skip to the section 1.2 Initializing Empty Tenant Schema with database objects
1.1.1 Assigning privileges
The DBA user must assign correct privileges to the new empty tenant schema.
On Oracle and Sql Server databases the ways the privileges are assigned are different. The next two paragraphs explains how to assign the privileges for each database
Oracle Database Tenant Schema privileges
For Oracle Database we require the tenant schema to have these privileges:
CREATE SESSION, CREATE VIEW, CREATE TRIGGER, CREATE TYPE, CREATE CLUSTER, CREATE INDEXTYPE, CREATE OPERATOR, CREATE PROCEDURE, CREATE SEQUENCE, CREATE TABLE
Sql Server Database Tenant Schema privileges
For Sql Server database we require the user created for the tenant schema to have db_owner role over its own database schema, for example:
ALTER ROLE [db_owner] ADD MEMBER [TENANT_USER]
Where TENANT_USER is the user created for the tenant schema
1.1.2 Assigning schema quotas
It is required to assign at least 1GB of table space quote for tenant schema
On Oracle and Sql Server space quotas are managed differently
Oracle Database Tenant Schema Quotas
You can use this helpful template:
alter user APPBASE_TENANT_01 quota 1000M on users;
The command above uses APPBASE_TENANT_01 as the tenant schema name and grants 1Gb of space quota on default table space "users". If you use different table space you need to replace "users" with you table space name in the command above
Sql Server Database Tenant Schema Quotas
It is required to configure the tenant schema space quotas to allow at least 1GB of table space
1.2 Initializing Empty Tenant Schema with database objects
After the previous steps are completed you need initialize the tenant schema with necessary database structure
1) Start Command Prompt as administrator by using "Run as administrator" option on cmd.exe and then change directory to where you put your substitution files during installation, for example: C:\AppBase\Install\Configuration\training.com
2) Execute command "Create-TenantSchema":
On Oracle and Sql Server create schema arguments are slightly different. The Sql Server version script command supports additional argument -TenantDbSchemaIn to specify the tenant schema name which can have different value from tenant login -TenantDbUserIn . The -TenantDbSchemaIn argument is required for Sql Server version
Create-Tenant Schema command for both Oracle and Sql Server use powershell scripts behind the scenes. This means that if your password has any of Powershell special characters (for example $ ) it must be escaped with a back quote character ` when replacing tenant_password argument. For example if your database password is pa$sword then you need to escape $ with ` as in pa`$sword so that the command argument will look like:
..\..\Scripts.2\InstallerMain.bat -ConfigFile Configuration.i01.srv01.appbase.xml -Command Create-TenantSchema -TenantDbUserIn tenant_login -TenantDbPasswordIn pa`$sword
Running "Create-TenantSchema" on Oracler
..\..\Scripts.2\InstallerMain.bat -ConfigFile Configuration.i01.srv01.appbase.xml -Command Create-TenantSchema -TenantDbUserIn tenant_login -TenantDbPasswordIn tenant_password
Please replace tenant_login, tenant_password actual values.
Running "Create-TenantSchema" on Sql Server
..\..\Scripts.2\InstallerMain.bat -ConfigFile Configuration.i01.srv01.appbase.xml -Command Create-TenantSchema -TenantDbUserIn tenant_login -TenantDbPasswordIn tenant_password -TenantDbSchemaIn tenant_schema
Please replace tenant_login, tenant_password, and tenant_schema with actual values.
2 Create Tenant
Now when the tenant schema is prepared you can proceed with creating tenant
Start from preparing tenant xml
Copy CreateTenant.xml.template from installation scripts directory (for example from C:\AppBase\Install\Scripts.2) to the substitution files directory (e.g. C:\AppBase\Install\Configuration\training.com)
Rename the file to CreateTenant.xml
Open the file and update it with correct values
Name | Description | Valid values |
|---|---|---|
| ServiceUrl | Optional. Allows to override tenant registry url - not used for most common installations - leave it empty | Empty value or tenant registry service url |
| FirstName | Required. Firstname for the admin user which will be created for this tenant | Valid Firstname |
| LastName | Required. Firstname for the admin user which will be created for this tenant | Valid Lastname |
| Required. Email for the admin user which will be created for this tenant. AppBase will send activation url to this email | Valid email | |
| Phone | Required. Phone for the admin user which will be created for this tenant | Valid phone |
| Company | Required. Company name for the tenant to be created | Valid company name |
| TenantCode | Optional. Leave empty to auto-generate tenant code | Empty or valid tenant code |
| MasterLogin | Required. Login name for the admin user to be created | Valid login |
| MasterPassword | Optional. Leave empty to assign the password later during account activation using the url sent to the email specified in "Email" after the tenant is created | Empty or valid password |
| TenantConfigurationConnectionString | Required for when creating tenant in "Existing Empty Schema Mode". Must be empty when creating tenant in "Auto-generated Schema Mode" | Valid connection string or empty depended on the chosen mode |
| SolutionConfigurationDirectory | Optional. Directory for solution files. Leave empty to allow AppBase to choose the directory | Empty or valid directory. If directory specified then all AppBase service accounts must have full control over the driectory |
| EnvironmentConfigurationDirectory | Optional. Directory for environment files. Leave empty to allow AppBase to choose the directory | Empty or valid directory. If directory specified then all AppBase service accounts must have full control over the driectory |
| TenantConfigurationDirectory | Optional. Directory for tenant files. Leave empty to allow AppBase to choose the directory | Empty or valid directory. If directory specified then all AppBase service accounts must have full control over the driectory |
| Solutions | Optional. Allows to specify solutions to import and deploy after the tenant is created | Ability to specify the solutions during tenant creation is an advanced feature and is out of scope of this document |
More information on the directory structure is available at url KB2018030700 AppBase Data folder default structure. Introduced in v 6.5.31
After you are done with modifying the CreateTenant.xml file run this command to create tenant:
..\..\Scripts.2\InstallerMain.bat -Command Server-CreateTenant -ServerFile server.appbase.xml -CreateTenantTemplateFileName CreateTenant.xml -Server srv01.appbase
Observe the command output and look for "Create-TenantInternal exited" message. If the previous line starts with "Create tenant succeeded" then the tenant was created successfully. Shortly you will receive the activation email on the email specified in "Email".
Automatic Tenant Creation
This section describes the process of automatic tenant creation.
DB user configured for the AppBase is a mandatory requirement for automatic tenant creation process.
As long as automatic tenant creation process control all DB operations, you can not use it for creating tenant in your particular DB schema.
Instruction
After the AppBase platform was installed and started you can create tenant.
Please open URL that can be constructed this way: <protocol>://<host>:<port>/TenantRegistry.Web/ to open Tenant Registration Form.
Please replace <protocol>, <host> and <port> with values used during AppBase installation.
If you do not see Google reCaptcha control on your screen as shown on the picture above, then you need to configure Google reCaptcha feature according to the page: KB2017101300 How to tune the Google reCaptcha
- If you fill in all needed fields and check "I want blank tenant" checkbox you'll see this screen:
Please, fill in all fields, accept "Master subscription agreement" and click the "Submit" button. Automatic tenant creation process will be started. If creation process is successful you will receive an email on address that you've specified earlier with correct login and password.
2. If you check "I want to select solution" checkbox you will see the next screen:
On that screen you can overview and select pattern solution for your own purposes.
Click "Get it" to confirm selected pattern solution.
Accept "Master subscription agreement" and click the "Submit" button. Automatic tenant creation process will be started.
3. You can create tenant with selected solution. For that you should know code of the solution. For creation open url: <protocol>://<host>:<port>/TenantRegistry.Web?code=<code>
There are two possible option of moderation that can be specified in <substitution.xml> during AppBase server installation process:
1- <ModerationMode> Post </ ModerationMode> - in this case, the the moderator are not required.
2- <ModerationMode> Pre </ ModerationMode> - this option requires confirmation by the server Administrator.
If condition <ModerationMode> Pre </ ModerationMode> have been chosen during AppBase installation you should follow instructions below.
If the platform was installed and configured properly and there aren't any issues with other third party components configuration used by the AppBase that you've configured during the platform installation (like SMTP server, database server etc), there will be few more actions that need to be taken/reviewed before the tenant creation is finalized.
- To receive an email in administrator mailbox to either accept or reject tenant creation request. The AppBase will send email to the address specified in <AdminEmail> substitution placeholder. If you reject the tenant creation request - the tenant will not be created. Nothing else will hapen regarding tenant creation request. However, if an amdinistrator chooses to approve the tenant creation request, then few more email will be sent.
- After the tenant is created (which happens only if administrator approved it) an email confirming successful tenant creation will be sent to the email address specified in <AdminEmail> substitution placeholder.
- AppBase sends email with url to activate created tenant and set tenant administrator password. The email is sent to the email address specified on the tenant registration form.