Configuration

Setting up Open ID with Canvas

Canvas v3.2.0 can now connect to IBM Planning Analytics instances configured with Open ID authentication.

Open ID authentication with Planning Analytics can be configured in two ways. It can either connect straight to your OpenID provider or by connecting to Cognos Analytics (the Cognos server will then authenticate you to your Open ID provider).

In the case where you are using Open ID with CAM Security, configuring Canvas is not different than setting up SSO with CAM and Canvas, as Canvas will only authenticate you with the Cognos server.

If you are using OpenID authentication without CAM security, the configuration on the Canvas side is quite straightforward.

But before going through these steps, you will need to make sure that you can connect to TM1 using OpenID.

Once the TM1 setup with OpenID is configured, open your instances.json file from the application WEB-INF folder (<canvasInstallationDirectory>\webapps\<applicationName>\WEB-INF), add the following property to the TM1 instance that was configured to connect with OpenID:

  • “useSSOWithOIDC”: true

Next, create a JSON file within WEB-INF/config/oidc folder. The name of the file should match the name of the instance (defined in instances.json) which will be configured for OpenID.

Path should be located in <Canvas Application>/WEB-INF/config/oidc/<instance-name>.json. For dev instance for example, it would be: <Canvas Application>/WEB-INF/config/oidc/dev.json

Sample content of the JSON file would be:

{
    “clientID”: “XXXX123456789ZZ”,
    “clientSecret”: “AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA”,
    “discoveryEndpoint”: “http://<OpenID Provider’s Well Known Configuration>”
}

That should be it!

Restart your Canvas Application Server. Go to your page’s Configuration page for example to trigger the OpenID Connect mechanism.

What to Expect

When you open up a page in Canvas that has TM1 data on it, Canvas will check first if the session is valid. If not, it will redirect the current page to the Open ID Provider’s Login page to ask the user to login. Once successful, the OpenID Provider will then redirect the user back to the Canvas page that triggers it.

Canvas will now try to login to TM1, given the new set of information present in the URL (the code parameter in particular). If valid, it will proceed as per normal with the page, and all TM1 operations should work based off the user that was retrieved from OpenID:

Canvas System Requirements

Server Requirements

  • Windows 2008 or later

  • Min 700Mb of disk space (1.2Gb if Samples Application with the Canvas Sample TM1 server is included)

  • CPU: < 1% during normal operations

  • RAM: Min 4 GB (Min 500 MB per application)

  • IBM TM1 10.2 Fix Pack 6 as minimum.

Web Browser

  • Internet Explorer 10+

  • Any other modern browser: Firefox, Chrome, Safari, etc.

Data Storage and Retention

  • Minimum 2GB free space on the disk.

  • No data stored. Only configurations in JSON files for TM1 Connectivity, Canvas Scheduler Tasks, etc.

Using SSL with Canvas

Create your own keystore and SSL certificate
 

  1. Open a Command Line Window using Run As Administrator
  2. Use the cd command to change the directory to the conf directory where Canvas is installed:

    cd C:\CWAS\conf
     
  3. Create your own keystore and generate a Certificate Signing Request:

    ..\jre\bin\keytool -genkey -alias tomcat -keyalg RSA -keystore canvas.keystore -keysize 2048
     
  4. Enter a password and write it down so you can use it later:

    Enter keystore password: 
     
  5. Enter the details for the certificate: 
     
    • First and last name (Common Name (CN)): Enter the domain of you are going to use for Canvas (i.e. canvas.mycompany.org) in the "first- and lastname" field.. It looks like "www.company.com" or "company.com". NOTE: The Common Name above must match the URL people are going to use to access Canvas
    • 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.
       
  6. 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
     
  7. Press <Enter> and use the same password as entered in Step 4

    Enter key password for <canvas>
    (RETURN if same as keystore password): [Enter]
     
  8. Generate a Certificate Signing Request (CSR) to be used by a certificate Authority (Symantec, Thawte, DigiCert, GeoTrust, Go Daddy, etc)

    ..\jre\bin\keytool -certreq -alias tomcat -file canvas.csr -keystore canvas.keystore
     
  9. Enter the password your created in step 4:

    Enter keystore password: 
     
  10. Follow the steps of your Certificate Authority to purchase a new certificate using the canvas.csr file that was created in the previous step.

    NOTE: The canvas.csr file will be in the conf directory where Canvas is installed
     
  11. At this point you should make a copy of the canvas.keystore file so you have a backup if you encounter problems when importing certificates


Import Your X.509 Certificate into the Key Store
 

  1. Open a Command Line Window using Run As Administrator
  2. Use the cd command to change the directory to the conf directory where Canvas is installed

    cd C:\CWAS\conf
     
  3. First import any root/intermediate certificate(s) as instructed by your Certificate Authority, these need to be imported BEFORE your certificate is imported:
     
    1. Save any root/intermediate certificates to the conf directory, i.e. root.cer
    2. Execute, replacing -alias and -file options for each certificate:

      ..\jre\bin\keytool -import -trustcacerts -alias root -keystore canvas.keystore -file root.cer
       
    3. Enter the password from above and press enter
       
  4. Import your actual certificate into the key store:
     
    1. Save the certificate to the conf directory, i.e. canvas.cer.
    2. Execute, the alias needs to be canvas: 

      ..\jre\bin\keytool -import -trustcacerts -alias tomcat -keystore canvas.keystore -file canvas.cer
       
    3. Enter the password from above and press enter
       
  5. If you get: Certificate reply was installed in keystore. The certificate has been successfully installed in the keystore

    If you receive this error, keytool error: java.lang.Exception: Failed to establish chain from reply, you need to install the appropriate intermediate certificates

Update the Connector Settings for the New Key Store

  1. Open conf/server.xml (in the Canvas install directory)

You will need to add the following code between <Service and <Engine section:

     <!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
    <Connector
           protocol="org.apache.coyote.http11.Http11NioProtocol"
           port="8443" maxThreads="200"
           scheme="https" secure="true" SSLEnabled="true"
           keystoreFile="C:/CWAS/conf/canvas.keystore" keystorePass="password"
           clientAuth="false" sslProtocol="TLS"
           
           URIEncoding="UTF-8"
           compressableMimeType="text/html,text/xml,text/plain,text/css,text/javascript,application/javascript,application/json"
           compression="on"
           compressionMinSize="2048"
    />

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

The server.xml file should look like this:

Finally restart the Cubewise Application Server service and you should now be able to access Canvas through the new port in this example 8443:

  • https://localhost:8443/samples

Set Printer Version to Use mode 2

Canvas v3 introduced a new printer version. By default, Canvas will now use this new printer version but if you prefer to go back to the first version of the printing you can change the printer version in your application Admin section:

Printer version mode 1 is the native printing version (Canvas v2 and previous versions) and Printer version 2 is the new printer.

This new printer is much faster and support better Canvas charts. It uses in the backend Headless Chromium. This printer version comes with a set of new parameters which you can find in the WEB-INF\config\settings.json file:

  • printerPath – location of the Chromium executables.

  • printerOnPageNavigationWaitForKeyword – keyword it waits from the printer engine to indicate completion of rendering of a web page. Default is ‘networkIdle‘.

  • printerPauseBeforePrint – timeout before issuing the request to generate the PDF.

  • printerPauseBeforeShutdown - On closing down the printer engine, sometimes it will need a longer wait time to wrap up and execute other clean up tasks. Default for this is 500ms.

  • printerPollerInterval – interval in millisecond to check for incoming messages from Chromium.

  • printerPollerIntervalMaxRetry – number of times the poller will try to check for incoming messages assuming a certain keyword has not been received yet.

  • printerScale – as per Chrome Print PDF settings, this is 50. But you can change it up to 200.

  • printerStartingPort – the starting port where Chromium can listen too. The number of instances that will be launch needs to have a unique port.

  • printerMaxInstance – the port that will be used will be incremented until this count has been reached. If you have port 9000 as set in printerStartingPort for example and you have in here a value of 10, then it means first instance will have 9000 as port, then 9001, and so on. What this is also means is that there can only be this printerMaxInstance value running at a time.

  • printerMaxPageSizeInMB – Maximum size, in MB, which helps the printer engine in allocating memory on the expected PDF output.

  • printerBaseUrl – if provided, this will be used to get the protocol and the host to use for accessing Chromium. Default is localhost.

Which files are overwritten during a Canvas upgrade

During a Canvas upgrade, the installer can upgrade either the Cubewise Application Server or the application folders (webapps) or both. That is why you have to be careful about which files you can and can't be changed to allow upgrades to work smoothly.

In this article we use the following color coding:

  • red: all files should not be manually modified.
  • yellow: some files can be manually modified.
  • blue: all files can be manually modified.

CWAS

  • backups: contains all application folders backups created during an upgrade.
  • conf: you can update the server.xml file to update the Canvas port number.
  • webapps: contains all Canvas applications.

    CONF

    In the Conf folder the only file you should update is the server.xml file where you can update the Cubewise Application Server's port number. But do note that this will be overwritten if the option "Install Canvas Application Server" is selected. So migrate your settings after upgrade.

    In the Conf folder you will find the license file (Canvas.xml).

     

    webapps

    In the webapps folder, the files inside samples folder are overwritten during an upgrade when the "samples" application is checked.

     

     

    An application folder

    • css: global format settings of the application.
    • html: all HTML pages.
    • images: all images.
    • js: all controllers.
    • menu: left pane menu structure.
    • WEB-INF: configuration.

     

     

     

     

    HTML

    You can create as many HTML pages as you want. We recommend to use the Page Creator to create a new page.

    JS

    In the JS folder you will find all controllers, you can add as many controllers but just do not touch the admin and system folders.

    Menu

    You can update manually the menu.json and the states.json file but you need to be aware that these files can be updated from the user menu management page in the admin section.

    WEB-INF

    • config: security settings such as updating admin password.
    • pages: index.ftl file, check the following article.
    • resources: Define all MDX queries.
    • instances.json: TM1 connection settings

    License file

    The Canvas application server will not work without a license file. To get a license file, you need to send the server name to your Cubewise local office. You need one license file per server.

    1. Once you have received the license file (Canvas.xml), put it in the CWAS\Conf:

    2. Then restart the Cubewise Application Server.

    3. Clear the cache (SHIFT + F5) and then refresh your browser, the "invalid license" message should have disappeared.

    If the message is still there, you can first check if the server name is correct in the license file. To see if the license has not expired, you can check the expiration date:

    Index.ftl structure

    Canvas is a single page application SPA. Each Canvas application has a single web page which swaps and loads its different contents, depending on what the user click. All HTML pages are loaded in the container (blue). A single page (red) is loaded, that is why you see a “#” between the URL and the HTML path:

    The red area is defined by the index.ftl file and the blue area is your HTML page. The index.ftl file is used to update everything that you find in the red area such as logo, headers, menu and homepage.

    Prior v1.2, to update the logo or add a custom library you had to update the index.ftl in the following folder:

    • C:\CWAS\webapps\<application name>\WEB-INF\pages

    We moved the index.ftl to the following new folder:

    • C:\CWAS\webapps\< application name>\WEB-INF\pages\system

    So updating you logo is now done through the navigation.logo.ftl file.

    Important: If you upgrade your existing Canvas application to Canvas v1.2. You will have to migrate all changes you made from your index.ftl (WEB-INF\pages\) into the different new ftl files (WEB-INF\pages\). The index.ftl file which is used by the Canvas application is in \WEB-INF\pages\system.

    We did this in order to split the index.ftl file between the area you can update and the area you should not update. Starting with v1.2, the WEB-INF\pages\system\index.ftl file should not be updated anymore. The area you can update is now separated into different files that you can find in \WEB-INF\pages. The new index.ftl will include these new customizable ftl file during application load.

    There are now 9 ftl files:

    • header.library.ftl: To add links to your custom libraries.
    •  header.script.init.ftl: For configuring your SSO and adding your angular modules.
    • header.script.others.ftl: Configure your accounting.js settings and other initializations.
    •  navigation.body.custom.ftl: Make your own navigation body.
    • navigation.logo.ftl: Update the logo.
    • navigation.top.left.ftl: For adding items into the top left navigation bar.
    •  navigation.top.right.ftl: For adding items into the top right navigation bar.
    • page.footer.ftl: Add your custom page footer.
    • page.header.ftl: Add your custom page header.

    The contents of these files get inserted into the index.ftl file when your Canvas application loads. Should you want to know more about the expected content of each FTL file, you can check out the index.ftl file to see where these files will be inserted and what HTML elements are near it.

    FAQ

    General

    + What is Canvas ?

    The Canvas platform is a combination of client side components and an application server that simplifies requests to TM1. Canvas has numerous components / controls that have been based on existing TM1 functionalities, such as: DBR, DBRW, DBRA, SUBNM and Active Forms. The goal is to leverage the knowledge of TM1 and add to that mix, technologies that are broadly supported in the web development world.

    + What do you need to know before using Canvas ?

    All Canvas applications are authored in HTML. Canvas comes with a complete set of HTML planning and reporting samples which will help you to quickly build out your new TM1 web applications.

    The expectation is that if you know how to write a rule or a Turbo Integrator process, you will quickly learn how to use HTML with TM1. Learning HTML will provide you with a skill that will always be in fashion.

    + Can Canvas replaces Cognos BI?

    Yes&No, If you uses Cognos BI just for Dashboarding then Yes Canvas can replaces it but if you use the bursting and offline mode features of Cognos BI, these features are currently not available with Canvas. What is more, Canvas has Read/Write capabilities! It is more than just a BI tool, with Canvas you can also do Planning and dashboarding.

    Configuration

    + Canvas prerequisites

    Canvas system requirements can be found here.

    Canvas comes with an application server "Cubewise Application Server" and a TM1 instance "CXMD" (required for the samples). In order to set up Canvas, you will need to have a minimum of 3 port number available:

    • Canvas server
    • CXMD portnumber
    • CXMD HTTPportnumber
    • Then one port number per TM1 instance in order to enable TM1 REST API.

    + Can we update the Canvas port number later on

    Yes, that can be changed anytime, just restart the "Cubewise Application Server" once the port number has been updated.

    + What TM1 Security does Canvas support?

    Canvas supports TM1 Security mode 1,2,4 and 5. Canvas supports CAM authentication which allows any LDAP directory to be used including the Active Directory (see how to set up CAM security).

    + Can we avoid the CWAS folder being placed at the root of the C: drive?

    Yes, you can put the CWAS folder anywhere you like. Be aware that if you put it inside C:\Program Files for example, you might have to deal with Windows security everytime you update your Canvas files.

    + What does the CWAS folder do?

    The CWAS contains the Tomcat server and the webapps folder. Just by copying the files you have "installed" tomcat. It does not have to be installed as a service to run it, you can just double-click on the bin/startup.bat file to start it up. It is preferable though that you install it as a Windows service, especially if it is going to be used in production.

    Technical

    + Which type of server is behind the Cubewise Application server?

    Canvas uses a Apache Tomcat server, which is different to an Apache HTTP Server. Tomcat is a Java application server that can be used for lots of purposes including serving HTML pages, CSS, etc..

    + In which language the Canvas server has been written?

    Canvas' server component is written in Java.

    + Does Canvas uses its own REST API or does it uses the TM1 REST API ?

    Canvas uses TM1's REST API, while at the same time exposing its own REST APIs that simplifies the calls to often used functions with TM1.

    Canvas is the middle layer illustrated below:

    Canvas client (browser) > Canvas' REST API > Canvas Server > TM1's REST API > TM1 (and back the other way)

    + Can we have multiple Tomcat running at the same time with different versions?

    You can have multiple versions of Tomcat running as long as they each have their own ports. For example, TM1 Web uses version 6 and we are using version 7.
    If you want to use Canvas with an existing Tomcat server it has to be version 7 at least.

    + Will there be compatibility issues with other web servers (for example IIS)

    Canvas does not work with IIS but can work side by side, with the only issue being port conflicts. This is as each port can only be used by one program.

    SMTP (Email) Settings

    Canvas allows you to send email alerts, to do this it needs to access an SMTP server. For most corporate networks the SMTP server will accept any email send requests from servers in the same network.

    You need to provide Canvas the following information as a minimum:

    • SMTP Server: This can be the name of the SMTP server or an IP address
    • SMTP Port Number: The default port number is 25, other common ports include: 587 or 465.
    • SMTP From Address: This is the email address that will be in the From field in the email. In most cases this doesn't have to be a valid email address and could be something like: noreply@yourcompany.com.

    You update the SMTP settings in Canvas in the settings

    • http://localhost:8080/<application name>/admin#/setting

    Things to Check

    SMTP Relay

    In some environments access to the SMTP server is restricted by computer, if you are unable to send emails from Canvas you should check with your System Administrator if this is the case. What needs to be enabled is SMTP relay for your TM1/Canvas server and provide either the server name or IP address.

    Firewall Restictions

    Another reason email sending may be blocked is due to a firewall on the TM1/Canvas server. This could be either the built in Windows Firewall or a third-party application such as SymantecNorton, etc. Check to see if any of these are installed and activated.

    Server Memory Management

    The Java application server (cwas.exe) which runs in the background has a default memory allocation of 1024 MB.

    This is also known as Heap memory.

    Recommendations

    A general recommendation is to have 500MB per application. Each folder that is created in the webapps directory has its own context which means resources aren't shared, i.e. the ROOT and samples directories. 
    The amount of memory required will also be increased depending on the number of users and size of requests. 

    Once the JVM (Java Virtual Machine) of the Cubewise Application Server has reached this value, it will slow down because it has to make some spaces for the new objects by deleting unused objects in order to keep the memory below 1024 MB, this is called garbage collector.

    Update JVM maximum memory

    The current default value is 1,024 MB and can be changed by updating the registry value:

    • Open a command prompt as an administrator:
    •  Go to the CWAS bin folder:
      • cd C:\CWAS\bin
    • Open the Cubewise Application Server properties using the command:
      • tomcat7w.exe //ES//CWAppServer

    You should now see the properties window, go to the Java tab :

    • Update the value and click OK.

    Restart the Cubewise Application Server.

    Update PermGen Allocation

    There is another type of memory that the JVM uses, and this is referred to as PermGen. in a brief description, the Heap memory configured above, stores the actual objects generated, whereas the PermGen memory stores the metadata about the generation of these objects.

    The default allocation is 64Mb. There will be cases however that you will have encountered an OutOfMemory error, where PermGen will be indicated on the log file. On situations similar to these, you can add another parameter to increase this PermGen by appending the following into the Java Options:

    -XX:PermSize=256m
    -XX:MaxPermSize=2560m
    

    The max value here should generally be around 25-40% of your allocated Heap memory.

    Your Java Options now look similar to this:

    Restart the Cubewise Application Server service on update.

    Update admin console password

    Each Canvas application has its own admin console. You can access the admin console via the following URL:

    • http://<server name>:<Canvas port number>/<application name>/admin

    For example to access the admin section of the samples application, the URL is:

    • http://localhost:8080/samples/admin

    You will be prompted with the following login window:

    The default login is:

    • Username: Admin
    • Password: canvas

    Update the password:

    You can update the admin console password in the settings page:

    • http://<server name>:<Canvas port number>/<Application name>/admin#/setting
    • For the samples application: http://localhost:8080/samples/admin#/setting 

    Reset the password:

    The password is encrypted and can be found in CWAS/webapps/<application name>/WEB-INF/config/security.json:

    If you are unable to login:

    To reset the password, set the password value to blank in the security.json file:

    After updating the security.json file, you do not need to restart the Cubewise Application Server.

    Parameters in the instances.json file

    To link a Canvas application to a TM1 instance, you will have to update the instances.json file. Each Canvas application has its own WEB-INF\instances.json file. For the samples application, the instances.json file is located in the following folder C:\CWAS\webapps\samples\WEB-INF

    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)

    • tm1WebLoginAtServer: (Optional) To initiate TM1 Web Login from Server (Default is false)

    • dispatcherURI: (Optional) Used in conjunction with tm1WebLoginAtServer property.

    • ChartColorScheme: Default chart colors of the application

    The following parameters are only needed if you want to configure CAM Security:

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

    • 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+)

    Other SSO related configuration:

    • 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+)

    After updating the instances.json file, you have to restart the Cubewise Application Server for Canvas to pick up the changes.

    How to add Canvas extensions to Visual Studio Code

    You can use any text editors to update a HTML page but we recommend to use Visual Studio Code. We have created two Visual Studio extensions which will help you to use Canvas:

    • Canvas: List Canvas directives and pre-populate the code.
    • Canvas Best Practice: List all best practices that you should follow.

    You can find these two extension on the Visual Studio Marketplace:

    It is very quick to install these extensions:

    1. Open Visual Studio Code, go to extensions menu and filter with Canvas, you should now see the two Canvas extensions:

    2. Click Install on both Canvas and Canvas Best Practice, once they are installed, you will need to click the Reload button, it will close and then reopen Visual Studio Code:

    This is it. To use the Canvas extension, you will need to open an html file and start typing tm1-ui and you should see a list with all Canvas directives:

    If you start by typing tm1-template, you'll see a list of template that you can use:

    To read the best practice, go to the extension menu and click on the Canvas Best Practice extension:

    Setting up SSO with CAM and Canvas

    This document will guide you to configure Single Sign On with CAM Security. Before proceeding, ensure that the user is able to go to http://<host>:<port>/ibmcognos using his/her PC, without being prompt for a username and password. Note also this only works with Internet Explorer and Chrome due to security configuration.

    To setup SSO with CAM and Canvas, you will first need to make some changes to Cognos BI/Analytics and then make some changes into Canvas.

    1. Cognos BI

    Update variables_TM1.xml to add the url of your Canvas application. For example, if you have a Canvas application (folder name in CWAS/webapps folder) named "finance-canvas", and you are still using the default port of "8080" for Canvas, then the URL entry will look like:

    <url>http://localhost:8080/finance-canvas/</url>

    Copy the js and the html file inside ../webapps/<canvas app>/assets/sso and place them into the WebContent folder of your Cognos BI installation.

    Open up xdomain.canvas.html file and add your Canvas origin and port. By default, you will see below:

    <!DOCTYPE HTML>
    <script src="xdomain.canvas.js"></script>
    <script>
        xdomain.masters({
          "http://localhost:8080": "/*"
        });
    </script>

    If you will access your Canvas application through an FQDN named SERVER-PROD for example, and on port 9555, add the following entry:

    <!DOCTYPE HTML>
    <script src="xdomain.canvas.js"></script>
    <script>
        xdomain.masters({
          "http://localhost:8080": "/*",
          "http://SERVER-PROD:9555": "/*"
        });
    </script>

    Should you have Cognos Application Firewall enabled, you may need to update the "Valid domains and hosts" property to add your Canvas server. This property is usually found when you click on the following:

    Cognos CAF.png

    Click on the Edit icon on the Value box:

    Edit Icon.PNG

    To add your Canvas server (still using the SERVER-PROD:9555) on the window that will pop-up. The entry looks like this:

    Cognos CAF.png

    For further details on this Valid domains and hosts, check out this article by IBM.

    2. Setup Canvas v3 and later versions

    If you are using Canvas v2.0.7 or previous versions, jump this section, this section is only for Canvas v3.0 and later versions.

    In Canvas v3, setting up SSO has been simplified. With v3, you just need to add to the instances.json, canNamespaces and useSSOWithCAM parameter as below:

    [
        {
            "name":"dev",
            "restUri":"https://localhost:8881",
            "tm1WebUri":"http://localhost:9510/tm1web",
            "chartColorScheme":["#FB6900", "#F63700", "#004853", "#007E80", "#00B9BD"]      
          
            "camNamespaces":["AD_SERVER_LOCAL"],
            "useSSOWithCAM":true
        }
    ]

    Save and Restart your Canvas application via Cubewise Application Server.

    2. Setup with Canvas v2.0.7 and previous versions

    Update instances.json file and add the following last 3 properties:

    [
        {
            "name":"dev",
            "restUri":"https://localhost:8881",
            "tm1WebUri":"http://localhost:9510/tm1web",
            "chartColorScheme":["#FB6900", "#F63700", "#004853", "#007E80", "#00B9BD"]      
          
            "clientCAMURI":"http://localhost/ibmcognos/cgi-bin/cognos.cgi",
            "camNamespaces":["AD_SERVER_LOCAL"],
            "useSSOWithCAM":true
        }
    ]

    Lastly, open up the WEB-INF/pages/header.script.init.ftl file and update the following section accordingly:

    // For SSO Configuration
    ssoSlaves = {
      "http://localhost": "/ibmcognos/xdomain.canvas.html"
    };

    The format of the above is <origin>:<path to the xdomain.canvas.html> file. Note that the <origin> should be the same as the origin you have configured on your clientCAMURI property. This will be: http://localhost/ibmcognos/cgi-bin/cognos.cgi.

    Save and Restart your Canvas application via Cubewise Application Server.

    Enabling TM1 Web Integration with Canvas

    This article list down the configurations that you need to do first, before you can view your TM1 Web sheets and/or Cube Views within Canvas:

    1) Update tm1web_config.xml

    Search and update for CrossDomainAccessList and set the value to '*' or to the appropriate domain. For further details, please check IBM's documentation on this.

    Search and update for LegacyUrlApiSessionDiscoveryEnabled and set the value to 'False' as Canvas is using URL API to render your Websheets and Cubeviews. 

    2) Restart TM1 Web Service

    In Services, restart IBM Cognos TM1 Application Server.

    3) Check TM1 Web connection

    Verify that you are able to login into your instance via tm1web. Use the TM1 web url http://<servername>:9510/tm1web/ and test the connection.

    4) Update instances.json file

    Go into your <canvas>/WEB-INF directory and open up instances.json file. Check that the tm1webUri property in there matches the server name and the port where you access your TM1 Web (this is typically http://localhost:9510/tm1web).

    If you are on a non-PA version of TM1 and you are not using SSO, you will need to add/update the following properties (post Canvas v3.0.1): 

    • dispatcherURI
    • tm1WebLoginAtServer

    For example,

    {
      
      "dispatcherURI":"http://YOURCOGNOSHOST:9300/p2pd/servlet/dispatch",
      "tm1WebLoginAtServer": true
    }

     

    5) Check TM1 web in Canvas

    Once these are done, verify by using Canvas tm1web component in ine of your Canvas page (Components/tm1web):

    Define Cubewise Application Server port number

    Canvas uses a Tomcat server called Cubewise Software Application Server, the port number is defined in the C:\CWAS\conf\server.xml file:

    By default it is set up to 8080, but you can change it and then restart the Cubewise Software Application Server. The port number has to be different to the HTTPportnumber of your TM1 instance defined in the tm1s.cfg.

    If your application folder is called Canvas (C:\CWAS\webapps\Canvas), the URL to launch will be:

    http://<servername>:<port number>/canvas/

    Define multiple TM1 instances

    In Canvas, TM1 instance settings are defined in the C:\CWAS\webapps\<application name>\WEB-INF\instances.json. You can define as many TM1 instance you want per Canvas application. 

    Here is an example on how to set up 2 instances dev and prod in one Canvas application, in the instances.json file:

     [ {   "name":"dev",

            "restUri":"https://localhost:8881",

            "tm1WebUri":"http://localhost:9510/tm1web",

            "applyParenthesisFormatting":true,

            "chartColorScheme":["#FB6900", "#F63700", "#004853", "#007E80", "#00B9BD"]

        }  ,

       {    "name":"prod",

            "restUri":"https://localhost:8882",

            "tm1WebUri":"http://localhost:9510/tm1web",

            "applyParenthesisFormatting":true,

            "chartColorScheme":["#FB6900", "#F63700", "#004853", "#007E80", "#00B9BD"]

        }   ] 

    Or, if you have created 2 separate webapps, you can configure individually as:

     For /canvas1,

    [   {  "name":"dev",

            "restUri":"https://localhost:8881",

            "tm1WebUri":"http://localhost:9510/tm1web",

            "applyParenthesisFormatting":true,

            "chartColorScheme":["#FB6900", "#F63700", "#004853", "#007E80", "#00B9BD"]

        }  ] 

    For /canvas2,

    [  {   "name":"dev",

            "restUri":"https://localhost:8882",

            "tm1WebUri":"http://localhost:9510/tm1web",

            "applyParenthesisFormatting":true,

            "chartColorScheme":["#FB6900", "#F63700", "#004853", "#007E80", "#00B9BD"]

        }  ]

    Note: You should restart the "Cubewise Application Server" after updating the instances.json file.

    Define a TM1 instance in Canvas

    With the REST API, a TM1 instance is not defined by its servername but it is defined by its HTTPPortNumber in tm1s.cfg, you can check the blog on how to enable REST API.

    TM1 instances in a Canvas application are defined in the instances.json file. You can find this file in the following folder: C:\CWAS\webapps\<application name>\WEB-INF\ file. For example, if you want to define a new TM1 instance for the ROOT application, you will find the instances.json in C:\CWAS\webapps\ROOT\WEB-INF\ :

    • name: name of the TM1 instance in Canvas, it does not have to be the same as servername
    • restURI: http://<TM1 computer name>:<httpportnumber>
    • tm1webUri: http://<TM1 Web computer name>:9510/tm1web
    • applyParenthsesisFormatting: format number
    • ChartColorScheme: color coding

    Create a new Canvas application

    A Canvas application is defined in the C:\CWAS\webapps folder. By default there are two applications called ROOT and samples:

    A Canvas application folder is structured as below:

    The main folders that you need to be aware off:

    • WEB-INF: it's the configuration folder
      • instances.json : TM1 instance settings
    •  html: where you'll find all your html pages
    • images: to store images that you're going to use in your application
    • js: to store the controllers
    • menu:
      • menu.json: left pane menu structure configuration
      • states.json: states for all canvas pages

    The URL to test your application is http://<servername>:<port number>/<folder name>/

    To access the default application ROOT, you do not need to put the folder name in the URL: http://localhost:8080/

    Create a new application

    You can add as many application folder as you want, just copy the canvas folder and change the name. If you name the new folder canvas the new URL will be:

    • http://localhost:8080/canvas/

    After adding a new Canvas application folder, you have to restart the Cubewise Application Server.