Create the initial tenant and database (DBUPGRADE)

To use Planning Space or CX Suite 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) by Quorum Software.

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) by Quorum Software 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 provided by Quorum Software, 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 'DBUpgrade' program (downloadable from https://clients.aucerna.com/products/downloads). Unzip 'DBUpgrade_16.5.x.xxxx', where 'x' is the update number and 'xxxx' is the build number (which can be ignored; the zip filename may have the version number without full stops 'dbupgrade_165xxxxx').

Note that the DBUPGRADE version and update numbers must be what are required for the version of IPS Server/Planning Space that you are installing. If you are not installing the current latest version, check with Quorum Software Support for what is needed.

Note: It is recommended to disable realtime antivirus software if you experience slow performance of the DBUPGRADE program. Version 16.5 Update 7 and later contain code improvements which should make this problem very unlikely.

Run the executable 'Palantir.DBUpgrade.exe'.

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 Username 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 ticking the box 'Use transport encryption'. If you tick '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 'Add tenant' button to open a dialog:

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

This creates a new entry in the list of tenants. The tenant name 'tenant1' has been used.

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 'Configure' 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. This security restriction can be avoided, and the shared Temp folder placed anywhere on the network, by means of more complex system configuration: Kerberos delegation must be configured, and required SETSPN commands must be performed by a Domain Administrator. Please contact Quorum Support for instructions for running IPS Server and SQL Server in this configuration.

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

Select or enter a server name: either type the name of the SQL Server instance where the tenant database is stored, or click the down arrow which will show a list of the SQL Server instances detected in the current Windows domain.

Enter information to login to server: Select 'Use 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 username and password of a SQL Server authenticated account.

Connection properties: 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 protocols must be satisfied.

Select the database on the server: You can type in the database name, or click the down arrow to show the list of databases found in the SQL Server instance (note: the list function may not work, depending on the 'VIEW' permissions of the SQL Server account that you are using, in this case you must type in the name). Click the 'Test' button to verify the database can be accessed and it is ready to be used.

Click the 'Ok' button to save 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

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.

The initial tenant settings under 'Available applications' are that client access to all applications is disabled.

Before applications can be used, product licenses need to be available to users. Then, to enable access to applications, tick the box for 'PlanningSpace' and/or 'cx SUITE', and click the 'Save all changes' button.

Upload a product license for the tenant

Every user session in a tenant requires a license for the applications in use; these licenses are temporarily taken from a shared license 'pool'.

You need to set the licensing mode for your deployment. In PalantirIPS 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: 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: use the 'Edit licenses' button to upload a product license file that you have obtained from Quorum Support (which will be keyed to a specific IPS Server machine and tenant name); or
• remote pool: enter the name of a remote license server in the 'License server proxy' field (it does not have to be the same license server as used by other tenants).

See Product licensing for more details.