QUBEdocs Local: Managing Connections & Profiles

The QUBEdocs Manager interface is used to administer the QUBEdocs solution and to generate new documentation versions.  Within the QUBEdocs Manager interface the following capabilities are available:

• Manage Connections – Add, modify and delete connections, generate documentation and remove old versions.
• Manage Profiles – Add, modify and delete different documentation profiles for different user groups.
• Browse Profiles and Documentation – Browse generated QUBEdocs versions and see what profile settings have been applied (i.e. what areas of the documentation have been turned on and off)

These are described in more detail in the following sections.

Accessing QUBEdocs Manager

QUBEdocs Manager can be accessed via the following URL:          

    http://localhost/QUBEdocs/#/qubedocsManager

Note:

• The default port number is 80, therefore the port number does not normally need to be given.
• QUBEdocs URLs are case sensitive and as such, “qubedocsManager” must be spelt with a capital “M”.

Managing Connections

The managing connections area is used for adding, removing and editing connections.  It can be navigated to by selecting the “Manage Connections” item in the left-hand pane.

Once selected, this will bring up the following screen which is used for managing both connections and the generated versions of the QUBEdocs documentation.

Select the “Add Connection” button to establish a new connection between QUBEdocs and a TM1 model.

Creating a new connection

To create a new connection, a name for the connection must be defined along with the approriate configuration and database directories. These fields are explained below:

Name

This is a unique name used to identify the connection. This normally reflects the Cognos TM1 server instance name and environment (e.g. QUBEdocs_Dev).

Environment

The environment field is used to group connections on the main page.  For example, you may want to put all of your non-production models in a “Development” environment grouping and all of your production servers under a “Production” heading. Altertatively, you may want to group models based on their purpose, audience or some other logical grouping.

Configuration Directory

This directory sould be mapped to the location of the “tm1s.cfg” file for the Cognos TM1 model being documented. In some cases this will be the same as the database directory.  Local, UNC & FTP/FTPS paths are all supported.

Notice: The FTP connection option will be deprecated soon. Please see here for more information.

Note: UNC paths will require access from the application pool running QUBEdocs to the the servers being documented by QUBEdocs.  You can validate that connections have been established correctly by selecting the “Validate” button.

Database Directory

This directory should be mapped to the location of the data directory for the Cognos TM1 model being documented, i.e. the directory where the TM1 model files are stored.

Directory Credentials

The user name and password fields should only be supplied when connecting to a data source over FTPS such as TM1 on the Cloud or IBM Planning Analytics.  Access to local and UNC paths are controlled through the application pool identity configured in IIS. 

Use Transfer Package option

The “Use Transfer Package” option can be used to significantly improve performance times when connecting over FTPS.  This option does however require that the “QUBEdocs Create Package” process is run prior.  If using the FTPS connector it is a good practice to schedule this process to run within TM1.

Note:

• UNC paths should be specified for directories when documenting models on another server. E.g.

         \\devcx\c$\Program Files\IBM\Cognos Express\Xcelerator\Custom\TM1Data\CXMD

• FTPS based paths should be specified when documenting a cloud instance of TM1.

E.g.

ftps://nameofcloudserver.com/prod/data/tm1

• The directory credential fields are optional as they are dependent on your connection type.
• Connections can be added and deleted and file paths can be browsed to by selecting the appropriate menu to the right of the Generate

Advanced Settings Tab

The advanced settings tab provides control over what TM1 objects are processed during the generation process.  Only objects which have a tick against them will be available in QUBEdocs.

Generating a documentation version

To generate documentation for a TM1 model, select the appropriate connection name from the list. 

This will expand the connection group to reveal all of the previously saved version snapshots. Once the connection has been selected, click Generate and the documentation will be generated.

Note: The “Documentation Generating” notification will display in the right-hand corner of the screen to advise that the documentation is generating and once completed another notification, “Generation Complete” will be displayed.

Monitoring generation progress

You can monitor progress while the documentation is being generated by selecting the “Current Activity” tab. This will display a list of activities that QUBEdocs goes through while generating the documentation.  Generation errors will also be displayed here.

Selecting the newly generated version

Once the documentation is has been generated the latest version will be available by selecting the appropriate connection name in the home page.  

It will also be available for selection in the Model and Versions Selection screen which is accessed by clicking on the following selector.

Managing Profiles

The profiles area allows administrative users to save specific settings to one or more profiles. By using profiles, the documentation can be segmented for different user groups. Different areas of the documentation can be turned on and off and access to specific models can be controlled. 

To add, remove and update profiles, select the Manage Profiles option from the left-hand pane.

Adding and setting-up Profiles

QUBEdocs comes with one default profile named “qubedocs” in addition to the admin “qubedocsManager” profile. This can profile modified if required and other profiles can be added.

To modify a profile simply select the profile name.  To test that a profile is setup correclty click on the profile based URL next to the name.

Additional profiles can be added by selecting the Add button and edited by selecting the profile name.  Once selected, the following screen will be displayed. 

In this screen:

• An appropriate name can be given for the profile.
• Default settings can be set which determine whether or not control objects are displayed in the documentation, changes are marked up in change reports and which connections are available to users who are using that profile.

Also, if QUBEdocs is running in secured mode, specific users will need to be associated with the profile before they are able to see the information in QUBEdocs.  QUBEdocs comes with a default profile called qubedocs that users can be associated with. To assign users to this profile (or any other profiles that have been created) navigate to the Manage Profiles tab.

In the Profile Users screen:

• Users can be added simply by entering their Domain\Username into the dialog box and selecting Add. Note that it is good practice to use the Validate button to ensure that users have been added correctly first.
• Users can be assigned the Manage Connections permission which will mean that they have the ability to re-generate the documentation and remove documentation versions for any connections associated with the profile.
• User access to a given profile can be removed.

Filtering out pages and connections

By default, all areas of the documentation are available. The areas (such as tabs or pages) can however be toggled on and off using the buttons on the right hand-side of the contents pane.  In the example below, all areas have been made available apart from the “Processes” tab. 

If the actual documentation is browsed via the QUBEdocs Manager interface, areas that have been filtered out will also be hidden. This is depicted below.

When viewing QUBEdocs based on the “qubedocs” profile, the areas will be hidden from view.

QUBEdocs can be viewed based on a specific profile by navigating to the following link:

http://localhost/QUBEdocs/#/<profileNameHere>