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 that the software is being installed on is required to install this application and its included pre-requisites.
• 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 support@qubedocs.com 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.

Prerequisites

The following prequisites 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.5.2 (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 as documented here 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.

 

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

 

Installing QUBEdocs

During the installation procedure, you will be prompted to enter the serial number (received after your purchase) to activate the installer. Internet access will be required to verify the serial number during installation.

 

Note:

• The information and serial number should be entered exactly as they are on the QUBEdocs licensing email.
• If internet access is not available on the server where QUBEdocs is to be installed, please contact QUBEdocs for details on how to install the software based on a manual activation process.

 

 

Note: Make sure to keep the serial number in a safe place, you will need it to install any new versions of QUBEdocs Local.

 

Next, 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.

QUBEdocs Setup

Configuring the Software

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

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

You should be brought to the following screen:

Click Next

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

Click Next

QUBEdocs is running the necessary migrations against your database.

 

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.

Click Next

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

Click Next

...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 URL above.

 

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 are given below:

 

     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.