Installation guide

Owned by Ada atrajer
Last updated: May 16, 2024 by Joana MFC Corte-Real (Unlicensed)
14 min read

Install on the same server as TM1 1. Run the installer to install apliqo server and demo app

» Run the installer to install apliqo server and demo app

  • Double click on Apliqo.2.2 executable file.

  • If you get the following “Windows Defender SmartScreen” window, click on “More info”: • Then, click on “Run Anyway”

  • In the “Welcome to Apliqo UX Setup” window, click Next, then accept the license agreement by clicking on “I Agree”:

  • Select the options you need: “Install Apliqo Server” option will install the core components only. “Apliqo Demo” will install a TM1 instance having demonstration examples. “Create Backup” is available if the product is already installed (e.g. in case of an upgrade):

Note: as of version 2.2 an additional TM1 instance will be created and named

“ux_content_store”. This instance will be used to store the view definitions for the UX, considering that multi-instance capabilities have been introduced in this version. This will be the default instance to store the view definitions, while the data referenced in these views can be retrieved from several TM1 instances at the same time.

  • Choose the Install location. By default, it is set to “C:\ApliqoServer\”

  • Set the port number for the application server and the maximum memory. The port number set here will be used to reach the UX applications in the address bar of the browser. The default value is set to 8880. Should this port be already in use, make sure to change it to a different one. The maximum memory for the application server is by default set to 1024 MB, anyway if you have enough memory it is a good practice to increase this value to 4096 MB:

  • Define the Start Menu folder in which to create shortcuts and click “Install”

  • The installation procedure starts:

  • When completed, click “Next”:

  • Then “Finish”

» Test the installation

  • Now the installation is complete, in the Windows services snap-in a new service named “Apliqo Application Server” is existing and running:

  • The installation folder has the following structure:

  • In particular, under “db” subfolder two TM1 instances have been placed, “UX_CotentStore” and “UX_Samples”

  • This subfolder is used to store the TM1 instances which were installed during the installation. Two corresponding TM1 server services should have also been created:

  • The “webapps” subfolder is used to store all the UX applications running on the server. A sub-folder named “Appliqo_Demo” has been created by the installer:

It is possible to copy and rename this Demo application to create new UX apps. In general, the web browser address to open one of the applications will have the following structure:

http://<hostname>:<portnumber>/<AppName>/

where <AppName> is the name of the new sub-folder in the web apps directory.

NB: Application names are case sensitive!

For example, it is possible to open the “Apliqo_Demo” application in the browser using an address like http://<hostname>:<portnumber>/Apliqo_Demo/

A pre-defined user in this demo instance is “demo1”, no password.

NOTE: By default, the user will get 30 days trial license to use the application. After 30 days without a valid license, a login error will be returned, even when using the valid credentials.

» Create new UX Application

  • Double click on Apliqo.2_5_2 executable file.

  • If you get the following “Windows Defender SmartScreen” window, click on “More info”:

  • Then, click on “Run Anyway”

  • In the “Welcome to Apliqo UX Setup” window, click Next, then accept the license agreement by clicking on “I Agree”:

  • Select the “Create New Application” option which will create the new application under the Aplqio Server

  • Enter the following details:

    • Enter the application name in the New application name field.

    • If the content store does not exist, enable the Create a new content store and enter the following details

    • Enter the new service name in the Content Store Service Name

    • Enter the new content store HTTP port number

    • Enter the folder path where the content store data has to be saved in your local

    • Click on the Next button

Note: This is the web app name. In browser, application will be running under this name

  • Enter the TM1 model name in the Target TM1 model and specify the Target TM1 model API link with the port number. If the application has two data models then second target TM1 model details can be filed in this view.

  • Click next to start the installation procedure:

  • When completed, click “Next”:

  • Then “Finish”

  • Newly created app will be available under the ApliqoServer/webapps folder.

Install on a different server from where TM1 installed

» Run the installer to install apliqo server and demo app

  • Double click on Apliqo.2_5_2 executable file.

  • If you get the following “Windows Defender SmartScreen” window, click on “More info”:

  • Then, click on “Run Anyway”

  • In the “Welcome to Apliqo UX Setup” window, click Next, then accept the license agreement by clicking on “I Agree”:

  • Select the options you need: “Install Apliqo Server” option will install the core components only. “Demo Application” option will create a demo app under the ApliqoServer folder

  • Choose the Install location. By default it is set to “C:\ApliqoServer\”

  • Set the port number for the application server and the maximum memory. The port number set here will be used to reach the UX applications in the address bar of the browser. Default value is set to 8880. Should this port be already in use, make sure to change it to a different one. The maximum memory for the application server is by default set to 1024 MB, anyway if you have enough memory it is a good practice to increase this value to 4096 MB:

  • Define the Start Menu folder in which to create shortcuts and click “Install”

  • The installation procedure starts:

  • When completed, click “Next”:

  • Then “Finish”

  • Newly created app will be available under the ApliqoServer/webapps folder.

» Copy the UX Sample and UX Content store to the TM1 server

If the TM1 is not installed in the same machine, the TM1 services seen won’t be created. Manual steps are necessary to create at least the “UX_Content_Store” instance in the target machine, where TM1 servers are running.

  • In the installation folder, open the “db” subfolder and copy both “UX_CotentStore” and “UX_Samples” to the target server, let’s say inside “C:\TM1\Instances” directory:

  • In both instances, open tm1s.cfg file and check the port numbers. Be sure that these ports are free, otherwise, change them to custom ports that work for you:

As visible, the “UX_ContentStore” TM1 Instance comes by default using ports 32888 and 8878.

  • In the target machine, register two new TM1 services to execute these two instances, using the Cognos Configuration tool. Right-click on “TM1 Server”, select “New Resource” and “TM1 Server instances”:

  • Assign one name like “UX_ContentStore” to the instance, then click OK and point to the directory in which the tm1s.cfg file of that instance is:

  • Right-click on the new TM1 server and start it:

  • Once the TM1 instances are up and running, configure the instances.json of the Apliqo_Demo app by point the TM1 instances rest API and restart the Apliqo Application Server services.

» Create new UX Application

  • Double click on Apliqo.2_5_2 executable file.

  • If you get the following “Windows Defender SmartScreen” window, click on “More info”:

  • Then, click on “Run Anyway”

  • In the “Welcome to Apliqo UX Setup” window, click Next, then accept the license agreement by clicking on “I Agree”:

  • Select the “Create New Application” option which will create the new application under the AplqioServer

  • Enter the following details:

    • Enter the application name in the New application name field.

    • If content store is already exist, then disable the check box and click next.

  • Enter the TM1 model name in the Target TM1 model and specify the Target TM1 model API link with the port number. If the application has two data models then second target TM1 model details can be filed in this view.

  • Click next to start the installation procedure:

  • When completed, click “Next”:

  • Then “Finish”

Newly created app will be available under the ApliqoServer/webapps folder.

Install a license key

To license the product, copy your “Canvas.xml” file into the “Conf” subfolder you find in the installation path:

Configure instances.json file

» Location

Instances.json will located in the ApliqoServer/webapps/APPLICATION_NAME/webinf/ instances.json

» Configuration params

To link a UX application to a TM1 instance, you will have to update the instances.json file. Each UX application has its own WEB-INF\instances.json file.

Please find below all instances.json parameters:

  • name: (Required) name of the TM1 instance in Canvas that you will you on your Canvas Directives and Services. It does not have to be the same as the ServerName in tm1s.cfg

  • restURI: (Required) [http/https]://[YourTM1ServerHost]:[HTTPPortNumber]

  • tm1webUri: (Optional) TM1 Web URL ([http/https]://[YourTM1WebServer]:9510/tm1web)

  • camNamespaces: (Required) CAM Namespace as it is defined in Cognos Configuration

  • loginInstances: In which you can specify which of the following instances share the same users/logins with the content store one. When one user logs into the content store instance at the first login screen, she/he will be also automatically logged into the instances specified here (since they share the same credential) without being asked for a new login. Multiple instance names can be separated using commas.

  • useSSOWithCAM: To enable Single Sign-On (Default is false) useSSOWithRedirect: (Optional) Sets the behavior (Default is true)(v3.0.1+)

  • useSSORedirecWithBaseURL: (Optional) To set the URL being passed to the authentication provider. If set to true, this will only pass the base URL of the application in the form of: [http/https]://[CanvasServer]:[CanvasServerPort]/[CanvasApplication]/ (Default is false)(v3.0.1+)

  • clientCAMURI: (Optional from v3.0.1+) clientCAMURI as it is defined in Cognos Configuration

  • useSSOviaJS: (Optional) To authenticate with CAM via JavaScript (Default is false)(v3.0.1+)

Setting the session timeout

» Step1: For each application

Change of session timeout should be done separately for each application in the web.xml file available under: ApliqoServer\webapps\App_Name\WEB-INF folder.

By default session timeout is set to 30 (minutes).

<session-config> <session-timeout>30</session-timeout> <cookie-config> <name>APPBASESESSIONID</name> </cookie-config> </session-config>

  • After making the changes: 

    • Save the file 

    • Clear the cookies in the browser

    • Reload the app

» Step 2: HTTPSessionTimeoutMinutes parameter update in tm1s.cfg files

In the case of setting the session timeout for the application higher than 30 minutes, it is recommended to update / add HTTPSessionTimeoutMinutes parameter in the tm1s.cfg file, both for the data model and the contentstore.

If HTTPSessionTimeoutMinutes parameter is not specified in tm1s.cfg file then it will default to 20 minutes, which can cause users to be logged off earlier than based on the time set in web.xml file.

Using SSL with UX Create your own Keystore and SSL certificate

» Create your own Keystore and SSL certificate

  • Open a Command Line Window using Run As Administrator

  • Use the "cd" command to change the directory to the conf directory where ApliqoServer is installed:

cd C:\ApliqoServer\conf

  • Create your own key-store and generate a Certificate Signing Request:

..\jre\bin\keytool -genkey -alias tomcat -keyalg RSA -keystore apliqoux.keystore -keysize 2048

  • Enter a password and write it down so you can use it later:

Enter the details for the certificate

- First and last name (Common Name (CN)): Enter the domain of you are going to use for ApliqoUX (i.e. apliqoux.mycompany.org) in the "first and last name" field. It looks like "http://www.company.com " or "http://company.com ".

- Organizational Unit (OU): This field is optional; but can be used to help identify certificates registered to an organization, i.e. the name of the department making the request.

- Organization (O): If your company or department, exclude any special characters such as & or @ from the name.

- Locality or City (L): The locality field is the city or town name, for example, New York.

- State or Province (S): Spell out the state completely; do not abbreviate the state or province name, for example, Florida

- Country Name (C): Use the two-letter code for the country, for example, US, AU, UK, etc.

  • Confirm that the details are correct, type 'y' and press <Enter>:

Is CN=demo.cubewise.com, OU=Unknown, O=Cubewise, L=North Sydney, ST=New South Wales, C=AU correct?

[no]: y

  • Press <Enter> and use the same password as entered in Step 4

Enter key password for <apliqoux>

(RETURN if same as keystore password): [Enter]

  • Generate a Certificate Signing Request (CSR) to be used by a certificate Authority (Symantec, Thawte, DigiCert, GeoTrust, Go Daddy, etc)

  • Enter the password your created in step 4:

Enter keystore password:

  • Follow the steps of your Certificate Authority to purchase a new certificate using the apliqoux.csr file that was created in the previous step.

  • At this point, you should make a copy of the apliqoux.keystore file so you have a backup if you encounter problems when importing certificates

» Import Your X.509 Certificate into the Key Store

  • Open a Command Line Window using Run As Administrator

  • Use the cd command to change the directory to the conf directory where ApliqoUX is installed

  • First import any root/intermediate certificate(s) as instructed by your Certificate Authority, these need to be imported BEFORE your certificate is imported:

    • Save any root/intermediate certificates to the conf directory, i.e. root.cer

    • Execute, replacing -alias and -file options for each certificate:

    • Enter the password from above and press enter

  • Import your actual certificate into the key store:

    • Save the certificate to the conf directory, i.e. apliqoux.cer.

    • Execute, the alias needs to be apliqoux:

    • Enter the password from above and press enter

» Update the Connector Settings for the New Key Store

You can choose a different port number, in this example we are using 8880.

Finally restart the Apliqo Application Server service and you should now be able to access Apliqo UX through the new port in this example 8880:

https://localhost:8880/UX_Demo

Additional Settings when working with Load Balancer

» Production environments with load balancing set

Modify following settings in the WEB-INF/wro.properties file:

resourceWatcherUpdatePeriod=0

cacheUpdatePeriod=0

debug=false

Setup the backup process on the newly created content stores

The following link will give the brief instruction about how to setup the backup of the content store instance. This also covers the scheduled backup configuration.

• Configure Backup