Create the initial tenant and database (DBUPGRADE)

To use Planning Space requires one initial tenant to be created. You need to create a new database in SQL Server, apply the DBUPGRADE program to it, and then create a new tenant in IPS Manager.

As an alternative to a new (empty) database, you may have been provided a starter database (as a BAK file).

Important: tenant names are not case-sensitive, hence a tenant named 'proto' could also be referred to by 'Proto' or 'PROTO', etc.

Create a new tenant database

In an SQL Server management tool, create a new database.

Alternatively, if have been provided a starter database (as a BAK file) then use the 'Restore Database' option in SQL Server.

The tenant database name is at your choice; you will need to enter the name into the tenant configuration in IPS Manager.

The two essential settings for the new database are:

  • Collation: Latin1_General_100_CI_AS_WS
  • Compatibility level: SQL Server 2016 (130)

The choice for Recovery Model will depend on the overall policy for backup and disaster recovery (DR) of the Planning Space deployment. The 'Simple' recovery model keeps the transaction log growth to a minimum and provides for best database performance. However this will entail a DR approach that is based on full and differential backups, in line with the required recovery point objective (RPO). If High Availability (always on, or mirroring) is a requirement, and/or point-in-time data restoration, then the 'Full' recovery model will be needed.

Apply DBUPGRADE to the tenant database

Next, run DBUPGRADE. This requires Microsoft Office (version 2010 or later) to be installed in the machine where the upgrade program is running (this can be any machine with network access to the SQL Server machine).

If you have used a starter database file, please check if this upgrade step is required. The upgrade program will grow the SQL Server logs due to creation of recovery log data; if the operational database Recovery Model setting is not 'Simple' then it is recommended to temporarily switch it to 'Simple' during the upgrade, in order to avoid the possibility of disk space overflow.

Use the 'DB Upgrade' program, downloadable from https://clients.aucerna.com/products/downloads. The version number must be the same as the version of IPS Server/Planning Space that you are installing. The downloaded file will be named 'dbupgrade_204XYYYY.zip', where 'X' is the update number and 'YYYY' is the build number (which is not normally significant for users).

If you are not installing the current latest version, check with Quorum Support for what is needed.

Note: It is recommended to disable realtime antivirus software if you experience slow performance of the DBUPGRADE program.

Unzip the ZIP file and run the executable 'Palantir.DBUpgrade.exe'. You should see a program window like this:

DBUPGRADE tool start screen

The SQL Server account that you use here needs to have the permission role 'db_owner' for the tenant database. If the SQL Server account is linked to your current Windows login, click the box Use Trusted Connection. Otherwise, type in the User name and Password of a SQL Server authenticated account.

In the Server field, click the down arrow to show a list of the SQL Server instances detected in the current Windows domain, and select the name of the SQL Server instance that you are using. You can also type the instance name into the input box.

In the Database field, you can type in the name of the tenant database, or click the down arrow to show the list of databases found in the SQL Server instance (note that you may not see any list, depending on the VIEW permissions of the SQL Server account that is being used).

If the SQL Server is configured with a self-signed or trusted certificate, you can enable SSL-based encryption by checking the box Use transport encryption. If you check Trust server certificate then the DBUPGRADE program will trust any certificate that is offered by the SQL Server machine; otherwise the Windows certification protocols must be satisfied.

Check box Check Excel dependencies: You should keep the default setting (checked).

Click the Connect button, and the program will check that the database is ready to be upgraded, then click the Next button to start the upgrade process.

A log file will be created at: 'C:\Users\{Username}\AppData\Local\Palantir\{DatabaseName}.txt'.

Note the DBUPGRADE process can take an hour or more to run for a new, empty database. For later new tenants, you can speed up the process by using an SQL Server backup file of the initial tenant as the source for a new database.

Set the database permissions for the SQL Server account

The SQL Server account used by IPS Server must have permissions on the new database as follows: 'db_datareader', 'db_datawriter', and 'pes_datawriter' (the last permission type is added by the DBUPGRADE program).

Create a new tenant in IPS Manager

Open IPS Manager, click Tenants on the left-hand menu, and click the New button to open a dialog:

Screenshot IPS new tenant creation

Type in a name for the new tenant. The name is at your choice; this name will appear in the URL for users to accesss Planning Space, so the name should be appropriate, not too long, and easy to type. Click the Create button.

This creates a new tab ('Atlantis' in the example screenshot) for the tenant configuration:

Screenshot IPS new tenant configuration

The new tenant's Data source (database), Cluster shared temp folder and Identity Provider (if ADFS-based authentication is used) need to be configured now.

Set the Identity Provider and Token Lifetime

These settings are only required when an Identity Provider server or service is used to authenticate SAML2 user accounts.

Token lifetime has a default value of 15 minutes.

For Identity Provider, click the Edit button and follow the instructions at Planning Space tenant IdP configuration.

Assign the tenant database

Important: Authentication of the connection to the tenant data source can use the IPS Service Account (with Windows authentication) or an SQL Server-authenticated account. SQL authentication is recommended, because it allows the cluster shared Temp folder to be located anywhere on the network. However, if the IPS Service Account is used then the Temp folder must be located on the same machine as the SQL Server; this is a security restriction imposed by SQL Server to restrict bulk insert operations.

Click the Assign button to open the Assign data source dialog:

Screenshot IPS new tenant assign data source

Server Name: Type the name of the SQL Server instance where the tenant database is stored.

Select IPS Service account if you have created a SQL Server account that is linked to the IPS Service Account in Windows; otherwise select Use SQL user name and password and type in the User name and Password of a SQL Server-authenticated account.

If the SQL Server is configured with a self-signed or trusted certificate then tick Use transport encryption to enable SSL-based encryption of traffic between the IPS Server machine(s) and the SQL Server machine. If you tick Trust server certificate then the IPS Server machines will automatically trust any certificate that is offered by the SQL Server machine; otherwise the Windows certification validation must be satisfied.

Database name: Type in the database name. Click the Test button to verify the database can be accessed and is ready to be used.

Click the Ok button to store the information, and close the dialog.

Set the Cluster shared temp folder

Enter the path for the Cluster shared temp folder in the input box. (See Cluster shared Temp folder.)

Authentication methods

The allowed authentication methods (Local, SAML2, Windows Active Directory) can be enabled or disabled for each tenant. See Tenant authentication methods.

Save the settings for the new tenant

Click the Save all changes button to save the settings for the new tenant.

Important: An initial administrator user is created for the tenant, with username 'Administrator' and password 'Administrator'.

All Planning Space users will require a tenant user account with password, or a tenant account that is linked to a Windows user account. See Tenant creation and management for how to manage the users of a tenant.

Before applications can be used, product licenses need to be available to users. See below.

Upload a product license for the tenant

Every user session in a tenant requires a license for the applications in use. You need to set the licensing mode for your deployment. In IPS Manager, click Product licensing in the left-hand menu. Select either Centralized pool or Per tenant (only one of the these can be active at any time).

For Centralized pool mode, all users in all tenants will take licenses from a single pool. The pool of licenses can be local or remote (provided by a license server). You need to set either:

  • Local pool: upload a license file in the Licenses box, or
  • Remote pool: check the ls proxy box and enter the address of a Forward Server, that is a remote license server that will provide licenses to this IPS Server.

In 'Per tenant' mode, each tenant is configured individually. You need to set either:

  • Local pool: upload a license file in the Licenses box; or
  • Remote pool: check the ls proxy box and enter the address of a Forward Server (it does not have to be the same license server as used by other tenants).

See Product licensing for more details.