Getting started - Installation, Configuration and Setup

Upgrade Note: When upgrading from QUBEdocs 3.x to QUBEdocs 4.x, we recommend that you uninstall your current version (through windows add/remove a program) before completing the rest of these steps.  This will remove a memory limitation that was present in older versions.  You will not lose any connections / models / snapshots as they are stored in the MS SQL Database and it is unaffected in the upgrade. 

QUBEdocs Installation

This section details the requirements, installation and configurations required for deploying QUBEdocs. It is expected that users of this section will have a good understanding of IBM Cognos TM1 / Planning Analytics, will be familiar with the TM1 data directory, and will have experience creating and editing TurboIntegrator processes.

Setup Considerations

The information below outlines some of the considerations to take into account when planning the installation of QUBEdocs.

Server Installation

QUBEdocs needs to be installed onto a Web server and it is recommended to have a single QUBEdocs installation for all TM1 environments so that the documentation for all models is stored in a single repository. By doing this, documentation can be accessed via a single portal and comparisons between different models and documentation versions can be made.  In addition, all IBM Cognos TM1 servers will need the QUBEdocs TM1 Model files deployed within their data directory for the documentation to be complete. The deployment and installation architecture is identified below.

QUBEdocs Installation and Deployment Architecture

Note:

• When QUBEdocs is utilizing a data store on a separate server it is recommended that the distance between the QUBEdocs application and the database is as close as possible.

Automation

Automating the generation of the QUBEdocs documentation can be achieved by adding the QUBEdocs Update process to a chore which points to the QUBEdocs Server and Connection or via a REST API call. This process is included with QUBEdocs, and further information about its deployment can be found in the section titled: QUBEdocs Local: Automating Regular Updates.

Permissions

The following permissions are required for the installation:

• Administrative permissions to the server QUBEdocs (and its pre-requisites) is being installed on.
• Administrative access is also required to the SQL Server database instance that is being used during the installation so that the QUBEdocs database can be created by the installer.

The following permissions are also required by QUBEdocs to generate and automate the documentation:

• The server which QUBEdocs is installed onto should have Network access to the required IBM Cognos TM1 Data and Configuration directories for all environments that are to be documented. By default, the built-in “NETWORK SERVICE” account is used to run the QUBEdocs server, however, this may need to be changed if TM1 models are on other servers.
• When automating QUBEdocs from TM1, the TM1 servers will need to be able to see the QUBEdocs web server so that a REST API call can be executed from within TM1 to refresh the documentation.

Software Environments

The QUBEdocs installation components have been designed to run on the following operating systems:

• Microsoft Windows 7;
• Microsoft Windows 8;
• Microsoft Windows 10
• Microsoft Windows Server 2008 R2
• Microsoft Windows Server 2012 R2
• Microsoft Windows Server 2016

Database

• An SQL Server Database is required for QUBEdocs. SQL Express is however bundled with the install files and can be used if a database server is not available. Note that:
  • Systems Administrator access to the database server is required during the install
  • If DB Creator access is not going to be available during the installation contact [e-mail] for a procedure for creating the QUBEdocs DB and user manually or manually create the database and user yourself, the user will require DB_Owner access. 
  • The SQL Server name, database name, port number and credentials are required during the installation (if not using the bundled SQL Server Express version).
  • We officially support all versions of SQL Server which have not reached their End of Life. Older versions may still work, but support options may be limited. As of now, the oldest version supported by Microsoft is SQL Server 2014 (SP3).

Domain Account

• A domain account is required to successfully configure QUBEdocs. This account needs read access to the TM1 / Planning Analytics database and configuration directories.
• (Optional) If you would like to use Windows Authentication with your SQL Server Instance, you will need to give this user a login and DB Owner access to the QUBEdocs Database or DB_Creator.
• If you want to access QUBEdocs from other computers on the same network/domain the service account given to QUBEdocs when running the installer will need to be on the same domain as the users accessing QUBEdocs. This service account can be seen by going to IIS and checking what identity the QUBEdocs Service Application Pool is using.
• Please ensure that the domain account has the ability log on as a service (You can verify if a user can log on as a service by using the "Local Security Policy" tool: Control Panel -> Administrative Tools -> Local Security Policy\Local Policies\User Rights Assignment\Log on as a service). This is required to install the necessary services for QUBEdocs to function.

Prerequisites

The following prerequisites are relevant to QUBEdocs:       

• IBM Cognos TM1 or Planning Analytics 

Note:

• Versions of TM1 / PA supported by IBM are currently supported by QUBEdocs.
• If running a UNIX® TM1 server, the TM1 data and configuration directories need to be connected to via FTP/FTPS.
• Planning Analytics or TM1 on the cloud is accessible by configuring an FTPS connection (Notice: The FTP connection option will be deprecated soon. Please see here for more information).
• Microsoft .NET Framework 4.8 (bundled with the installation)
• SQL Server 2008 R2+ (SQL Server Express 2014 bundled with Installation)
• Microsoft Internet Information Services (IIS) 7+

Recommended Hardware Environments

The following hardware recommendations are recommended for QUBEdocs.

Server

• RAM: 6GB free
• CPU: 4 Cores
• HDD: 10GB+ for Database & Installation files
• IIS is installed on the server and the IIS features (under Windows Features) as documented below are activated:
  

Client Requirements

• RAM: 2+ GB free
• CPU: 2GH+

Supported Browsers

The following web browsers are currently supported:

• Mozilla Firefox
• Google Chrome
• Microsoft Edge

Note: Older browsers may be compatible, but these have not been tested as extensively as the browsers mentioned above.

Backup and Recovery

It is recommended that the QUBEdocs database is backed up frequently to ensure that data is not lost. The server can be backed up and restored using normal SQL Server practices.

Installing QUBEdocs Server

The following sections refer to installing the QUBEdocs Server components.

Running the Installation Procedure

To install QUBEdocs, navigate to the installation files, right click on the “setup.exe” file and select “Run as an Administrator.”

Installing Prerequisites

If the installer identifies that any prerequisites are not met, the prerequisites wizard will run first and prompt to install required prerequisites before running the main QUBEdocs installation process.

Note: An SQL Server Express Instance is available to be installed for use with QUBEdocs in the absence of another instance of SQL Server being available.  By installing this component you are agreeing to SQL Server Express 2014 license terms. Uncheck this option if you wish to use another SQL Server instance.

Note: Although we have bundled .NET Framework 4.8 within the QUBEdocs installer, the installation of .NET Framework 4.8 can sometimes take very long and make the QUBEdocs installer appear to be unresponsive. We recommend that you download and install .NET Framework 4.8 prior to installing or upgrading QUBEdocs (if you do not already have .NET Framework 4.8) in your environment.

Note: The pre-requisite step within the installer sometimes incorrectly flags an item as required when it (or a later version) is installed.

Once the prerequisites are installed the main installation procedure will begin.

Installing QUBEdocs

Enter in the details of the service account you would like to use. This service account needs to have access to your TM1 data directories.

If you wish to use Windows Authentication with QUBEdocs you will also need to create a login for it in SQL Server.

The username is in the format <domain>\<username>

Click "Next".

Click "Setup" to begin the QUBEdocs setup wizard.

Troubleshooting

• If the application pool identity credentials are incorrect in the installation step to set up the application pool, you will see the following error when the QUBEdocs Keep Alive service is trying to be started:
  
  
  You will need to click on "Cancel" and restart the installation process.

QUBEdocs Setup

Configuring the Software

The following steps should be completed before launching QUBEdocs for the first the time.

1. Configure QUBEdocs

Open the URL http://localhost/QUBEdocs/#/setup

You should be brought to the following screen:

2. Configure Database

From here you are able to configure your database settings.

If you choose to install QUBEdocs with the bundled copy of SQL Express, you should select SQL Authentication from the dropdown and leave the defaults as they are.

Otherwise choose how you would like to connect (SQL or Windows Authentication) and the name of the server you are connecting to.

Note: You can find these details located in the web.config.back file of any previous installations

QUBEdocs is running the necessary migrations against your database.

3. Activating QUBEdocs

You will now be prompted to either enter your QUBEdocs Cloud account credentials or the license key provided to you, depending on the type of installation that will be required on the machine.

Online Activation

You will be prompted to login to your QUBEdocs Cloud account in order to activate the product in your environment. If you do not have a QUBEdocs Cloud account, please reach out to [e-mail]

Upon successful login, you will be able to activate your instance if your purchase has unused server licenses:

If your plan does not have any available server licenses, you will be prompted to deactivate one before you are able to activate QUBEdocs in the current environment. Please note: you will no longer be able to use QUBEdocs on that machine once the deactivation is done.

Offline Activation

If your machine does not have access to the internet, you will be prompted to enter a license key. This license key can be generated via your QUBEdocs Cloud account.

Navigate to the "Manage QUBEdocs Licenses" menu:

Click on "Create License Key" and enter the required information:

Note: if you are unsure of your machine name, open PowerShell and run the following command on the machine where you would like to install QUBEdocs:
$env:computername

The result will be the machine name you need to provide here.

Copy the key to use in the QUBEdocs setup wizard.

4. Configuring Security

Important step for anyone upgrading from a previous version of QUBEdocs: Please copy the Salt and Password from your web.config.back. If you do not, you will need to re-enter the password attached to all of your connections.

We recommend that you turn Authentication on - you will automatically be added to the qubedocsManager profile and can then configure other user accounts at a later date.

5. Other Settings

These settings configure some of the folders that QUBEdocs needs to operate, for most people the defaults will not need to change.

6. Setup Complete

...And you're done. You should now be able to continue on to the connections page to setup your first connection. You can always come back to this setup wizard if you need to change anything by going to the setup URL in the first step.

Deploying and Configuring the QUBEdocs TM1 Model

Note: you only need to follow these steps if this is your first time installing QUBEdocs or you wish to update the QUBEdocs Files.

Once installed, the following steps will ensure that QUBEdocs is configured for your TM1 / ICAS environment:

1. Stop the TM1 / ICAS service(s) and create a backup of the data directories that you are going to deploy the QUBEdocs model onto.

2. Navigate to the installation directory to retrieve the QUBEdocs files. Note that the default directory where these files are stored is:

     C:\Program Files (x86)\QUBEdocs Ltd\QUBEdocs\ApplicationFiles

• QUBEdocs TM1 Model_FULLINSTALL.zip (Install files)
• QUBEdocs TM1 Model_UPGRADE.zip (Upgrade files)

3. Confirm that you have successfully backed up the model and then unpack either the Upgrade Files to your TM1 data directory (if you are upgrading from a previous version of QUBEdocs) or the Install Files if you are setting up QUBEdocs for the first time.

Note:

• These files will overwrite previously installed QUBEdocs files. If you are deploying these into multiple environments or would like to QA the files first, you can unpack them into a temporary directory first and then copy them into the data directories manually.
• These files need to be deployed onto all Cognos TM1 Servers that are going to be documented with QUBEdocs
• If deploying to a UNIX® TM1 Server, the files will first need to be saved onto a windows server and the tm1xfer command line utility will need to be used to transfer the files between environments. For details on how to use tm1xfer consult the IBM documentation here.
• It is recommended that the following configuration settings are set in the tm1s.cfg file when using QUBEdocs:
  • AllowSeparateNandCRules=T
  • PerformanceMonitorOn=T (if capturing performance statistics with QUBEdocs is desired)

4. Restart the TM1 / ICAS server.

5. Once the server has restarted, for new installations, there should now be two new cubes (“QUBEdocs Definitions” and “QUBEdocs Applications”) and a number of views for each cube. There should also be a new TurboIntegrator process called “QUBEdocs Update” in Server Explorer. In addition, there will be application folders which help to organise the QUBEdocs content. If the upgrade option as used, changed files will simply be refreshed.

6. Run the process, “QUBEdocs Update” and ensure that “Y” is set for the first parameter and the second parameter is set to “N.” Leave all others blank.

• The first parameter updates the definitions (in the cube and on disk) in preparation for the generation of the documentation – this should be set to “Y”.
• The second parameter determines whether or not the QUBEdocs documentation will be generated automatically from this interface – this should be set to “N” as it recommended to generate the documentation manually the first time.

7. Repeat these steps for all Cognos TM1 environments that are to be documented with QUBEdocs.

     

Note: It is recommended practice to generate the documentation manually the first time to ensure that the solution is configured correctly. Please see the next section “Administering QUBEdocs” for details on how to do this. Once this has been run manually, the process can be run with the Generate QUBEdocs option set to “Y” and with the server / connection name specified.

Configuring IIS to document remote servers

Note: you only need to follow these steps if you choose 'Local System' when installing QUBEdocs

When QUBEdocs is installed, the application pool that it uses (QUBEdocs Service AppPool) is set to use the default NETWORK SERVICE application pool identity.  When documenting remote TM1 services this may need to be changed to a domain account that has access to the appropriate server directories.  To do this:

1. Select the QUBEdocs application pool

2. Select Advanced Settings from the right hand pane. 

3. In the advanced settings, change the application pool identity from NETWORK SERVICE to a custom account that has access to the appropriate data directories.

      

Once configured with appropriate access, you should be able to generate documentation for remote TM1 servers.

Once all of these steps have been completed, QUBEdocs has been configured for the TM1 environment.  Next, a connection between the TM1 server and QUBEdocs needs to be established.  Please see the next chapter – Administering QUBEdocs for details on how establish this connection and generate the documentation through the “QUBEdocs Manager” interface.