Configuring IIS in Cognos Analytics

Use this information to configure Microsoft Internet Information Services (IIS) for IBM® Cognos® Analytics with Watson.

When complete, IIS will be configured to serve static content (such as .js, .html, .css) directly from IIS while sending REST and other server requests to the back-end Cognos Analytics servers.

IIS automated script is available here.

Procedure

  1. Install the IIS Application Request Routing extension.
    1. Install the Application Request Routing extension for IIS by going to the following URL: https://www.iis.net/downloads/microsoft/url-rewrite
    2. When presented with the Microsoft Web Page, click on the green “Install this extension” button.
      Follow instructions to download and run the ARR extension.
    3. To ensure that the ARR extension was installed successfully, launch the IIS Manager from the Windows Start\Administrative Tools\ menu. Once the IIS Manager launches, click on the server name at the top left-hand side of the screen to display the available features. Within the middle IIS pane, the URL Rewrite feature should now be visible; it is installed when ARR is installed.
  2. Create a new, dedicated application pool. Name it, for example, CAPool.
    1. Right-click Application Pools. Click Add Application Pool.
  3. Optionally, create a server farm to provide load-balancing and failover for Cognos Analytics service requests. Include all Cognos Analytics servers that have the Application server components installed and configured.
    1. Right-click on Server Farms in the left-hand tree and select Create Server Farm.
    2. Name the new server farm. For example, ca_servers.
    3. For each Cognos Analytics server, perform the following steps:
      • Enter the server address. For example, ca-host1.
      • Click Advanced settings, and expand applicationRequestRouting. Set the httpPort or httpsPort (if you're using HTTPS). For example, 9300.
    4. Click Finish.
    5. Click No when prompted to allow IIS Manager to create a rewrite rule.
    6. Select your server farm in the left-hand tree and double-click Server Affinity.
    7. Select the Client Affinity check box.
    8. Click Apply.
    9. Select your server farm in the left-hand tree and double-click Caching.
    10. Change Query String Support to Include Query String.
    11. Click Apply.
    12. Select your server farm in the left-hand tree and double-click Health Test.
    13. In the URL Test section, enter the URL: http://ca_servers/bi/v1/ping
    14. Click Apply.
    15. Select your server farm in the left-hand tree and double-click Proxy.
    16. In the Time-out (seconds) field, change the value to 120.
    17. Click Apply.
  4. Right-click Default Web Site, and then click Add Application.
    • Alias is ibmcognos.
    • Application pool is the one created in step 1.
    • Physical path is install_location\webcontent
    1. Enable Web Content expiry.
      1. Select ibmcognos, and double-click HTTP Response Headers.
      2. Click Set Common Headers.
      3. Check Expire Web Content and set an expiry that works best for you.
    2. Select ibmcognos and double-click Mime Types.

      Add the following mime types to your IIS configuration if they are not already present.

      • .svg : image/svg+xml
      • .woff : application/x-font-woff
      • .json : application/json
      • .woff2 : font/woff2
      • .template : text/html
      • .txt : text/plain
      • .properties : text/plain
  5. If you are configuring single sign-on between IIS and Cognos Analytics, right-click ibmcognos, and click Add Application.
    • Alias to sso.
    • Application pool is the one you created in step 1.
    • Physical path is install_location\cgi-bin.
    1. Select sso and double-click Handler Mappings.
    2. Click Add Module Mapping in the right Actions pane.
      • Request path is cisapi.
      • Module is IsapiModule.
      • Executable is install_location\cgi-bin\cognosisapi.dll.
      • Name is Cognos SSO.
      • Click Request Restrictions, and ensure that Invoke Handler is unchecked.
      • Click OK twice.
      • On the Edit Script Map dialog, click Yes.
      • Select sso and double-click Modules. If the WebDAVModule appears in the list, remove it.
  6. Create URL-rewrite rules to map requests to the correct handlers.
    1. Click on the bi directory under ibmcognos.
    2. Double-click URL Rewrite.
    3. Add a server variable to identify the Cognos Analytics location by clicking View Server Variables.
      • Click Add.
      • Name the variable HTTP_X_BI_PATH.
      • Click Back to Rules.
      • Click View Server Variables.
      • Click Add.
      • Name the variable HTTP_X_WEBCONTENTROOT
      • Click Back to Rules.
      • Click View Server Variables.
      • Click Add.
      • Name the variable HTTP_X_FORWARDED_HOST.
      • Click Back to Rules.
    4. If you want to integrate Cognos Analytics for Jupyter Notebook Server, you must add a rule to map WebSocket requests from IBM Cognos Analytics with Watson notebooks to the back-end Jupyter Notebook Server.

      For more information, see Installing IBM Cognos Analytics for Jupyter Notebook Server.

      Important: These steps use WebSocket Protocol, which is available only in IIS versions 8.0 and later.
      1. Ensure that you have installed IIS version 8.0 or later.
      2. Install WebSocket Protocol support in IIS.

        For more information, see WebSocket <webSocket> (https://docs.microsoft.com/en-us/iis/configuration/system.webserver/web socket).

      3. Click bi, which is under the ibmcognos alias created in step 4.
      4. Click Add Rules > Inbound Rules > Blank Rule .
        • If proxies are not already enabled, you are prompted to enable them. Click OK.
        • The server name and port are defined in the config.conf file when you configure Jupyter Notebook Server.

        Select the newly created rule and click Edit.

        • Pattern is v1/jupyter/(user/[^/]*)/(api/kernels/[^/]+/channels)
        • Action type is Rewrite.
        • Rewrite URL (for SSL configurations) is https://jupyter_host_name:jupyter_host_port/bi/v1/jupyter/{R:1}/{R:2}

          For non-SSL configurations use the following rewrite URL: http://jupyter_host_name:jupyter_host_port/bi/v1/jupyter/{R:1}/{R:2}

        • Check Append query string.
        • Check Stop processing of subsequent rules.
        • Click Apply and Back to Rules.
    5. Re-select bi directory under ibmcognos.
    6. Add a rule to pass the Cognos Analytics location to the ca-host machines by clicking Add Rules > Inbound Rules > Blank Rule.
      • Name is Headers.
      • Pattern is (.*)
      • Action type is none.
      • Expand Server variables and
        • Click Add. Select HTTP_X_BI_PATH and set the value to /ibmcognos/bi/v1.
        • Click Add. Select HTTP_X_FORWARDED_HOST and set the value to {HTTP_HOST}.
        • Click Add. Select HTTP_X_WEBCONTENTROOT and set the value to /ibmcognos.
      • Clear Stop processing of subsequent rules.
      • Click Apply and Back to Rules.
    7. If you configured the SSO application in a previous step, add rules to map login and legacy UI service requests to the SSO handler.
      1. Click Add Rules > Inbound Rules > Blank Rule.
        • Name is SSO Login.
        • Pattern is v1/login$
        • Action type is Rewrite.
        • Rewrite URL is /ibmcognos/sso/cisapi/bi/v1/login
        • Check Stop processing of subsequent rules.
        • Click Apply and Back to Rules.
      2. Click Add Rules > Inbound Rules > Blank Rule.
        • Name is Legacy SSO.
        • Pattern is (v1/disp(/.*)?)
        • Action type is Rewrite
        • Rewrite URL is /ibmcognos/sso/cisapi/bi/{R:1}
        • Check Stop processing of subsequent rules.
        • Click Apply and Back to Rules.
    8. Add a rule to map Cognos Analytics REST service requests to the backend Cognos Analytics servers.
      1. Click Add Rules > Inbound and Outbound Rules > Reverse Proxy .
        • If proxies are not already enabled, you are prompted to enable. Click OK.
        • Server name is ca-host:9300/bi

          or if you have configured a server farm, http://ca_servers/bi

        Select the newly created rule and click Edit.

        • Pattern is (^$)|(^v1(/.*)?)|(^[^/]+\.jsp)|(^login$)
        • Action type is Rewrite.
        • Rewrite URL is http://ca-host:9300/bi/{R:0}

          or if you have configured a server farm, http://ca_servers/bi/{R:0}

        • Check Stop processing of subsequent rules.
        • Click Apply and Back to Rules.
      2. Click Add Rules > Inbound Rules > Blank Rule.
        • Name is Event Studio.
        • Pattern is ^(ags|cr1|prompting|ccl|common|skins|ps|cps4)/(.*)
        • Open the Conditions section.
        • Change the Logical Grouping to Match Any
        • Click Add.
          • Condition input is {HTTP_REFERER}
          • Check if input string is Matches the Pattern
          • Pattern is v1/disp
          • Check Ignore case.
        • Click Add
          • Condition input is {HTTP_REFERER}
          • Check if input string is Matches the Pattern
          • Pattern is (ags|cr1|prompting|ccl|common|skins|ps|cps4)/(.*)\.css
          • Check Ignore case.
        • Action type is Rewrite
        • Rewrite URL is /ibmcognos/{R:0}
        • Check Stop processing of subsequent rules.
        • Click Apply and Back to Rules.
      3. Click Add Rules > Inbound Rules > Blank Rule
        • Name is Report Viewer
        • Pattern is ^rv/(.*)
        • Action type is Rewrite
        • Rewrite URL is /ibmcognos/{R:0}
        • Check Stop processing of subsequent rules.
        • Click Apply and Back to Rules.
    9. Add a rule to allow Cognos Analytics pages to load without a trailing slash in URL.
      1. Click the ibmcognos alias.
      2. Double-click URL Rewrite
      3. Click Add Rules > Inbound Rules > Blank Rule
        • Name is Add Trailing Slash
        • Pattern is ^bi$
        • Action type is Redirect
        • Redirect URL is {R:0}/
        • Check Append query string.
        • Redirect type is Permanent (301)
        • Click Apply and Back to Rules.
  7. Adjust request size limits.
    1. Select the bi directory under the ibmcognos application created earlier.
    2. Double-click Request Filtering.
    3. Click Edit Feature Settings... from the right-hand panel.
      • Set Maximum URL length (bytes) to 8192.
      • Set Maximum query string (bytes) to 8192.
      • Click OK.
    4. Double-click Request Filtering.
    5. Select Headers tab and click Add Header.
    6. In Header Box, type the header field name as Referer.
    7. In the Size Limit box, type 8192.
    8. Click OK.
    9. Repeat process for a header field name entitled Cookie with the Size Limit of 4096.
    10. Click OK.
    11. Click the ibmcognos virtual directory.
    12. In the Home view, Management section, double-click Configuration Editor.
    13. In the Section drop-down list, expand system.web, and select httpRuntime.
    14. Set the property maxQueryStringLength to 8192.
    15. Apply the configuration change.
  8. Configure IIS to allow to pass through the custom 441 errors that are used for recoverable exceptions from CAM. Otherwise, IIS can block these errors, and the customer sees the "Invalid Logon Response" error when trying to log on.
    1. Click the ibmcognos virtual directory.
    2. In the Home view, Management section, double-click Configuration Editor.
    3. In the Section drop-down list, expand system.webServer, and select httpErrors.
    4. Set the existingResponse property to PassThrough.
    5. Apply the configuration change.
  9. If you configured the SSO application in previous steps, enable Windows Authentication.
    1. Select the SSO application. For Microsoft Edge browser, select the ibmcognos application.
    2. Double-click Authentication. Disable Anonymous Authentication, and enable Windows Authentication.
    Cognos Analytics should now be available at: http://iis-host/ibmcognos/.
    Troubleshooting: If you are prompted repeatedly to enter your user id and password, follow these steps:
    • Clear the cache of your web browser.
    • Enter the Cognos Analytics URL from a different computer.
    • Ensure that you type a slash (/) at the end of the Cognos Analytics URL.
    Note: If you configured a multi level virtual directory folder above the ibmcognos application, such as Default Web Site > MyVirtualDirectoryFolder > ibmcognos , use /MyVirtualDirectoryFolder/ibmcognos instead of /ibmcognos in the URL-rewrite rules you created in Step 6.