Cognos Analytics

Cognos Analytics on Cloud Configure Database Access			Firewall Rules: Port 443 outgoing to IBM cloud. For specific endpoints see: SCA Network Requirements

Although Cognos Analytics on Cloud can consume, visualise and report on data from a variety of sources such as flat file uploads,  one of the most useful and dynamic ways is to query source databases directly. 

Querying a live, transactional database leads to a realtime view of information with data warehouses often providing near real time insights (depending on their update frequency. 

For cloud or internet open databases this is simply a matter of configuring the database connection to go direct to the source (with appropriate security and firewall rules) however,  often the desired database resides on a private cloud or on premise network with no direct accessibility from the internet.

In cases where there is no direct, open path to the database IBM Satellite Connector offers a secure and managed means for IBM Cognos Analytics on Cloud to access a query the data.

This blog looks at creating a Satellite Connector to enable encrypted communications between IBM Cognos Analytics on Cloud.

Please note:  for IBM Cognos Analytics on Cloud (Hosted) a VPN is configured and Satellite Connector does not apply.

Satellite Connector is a full, standalone, IBM Technology that clients can use in their own IBM Cloud Accounts.  To simplify its use  IBM Cognos Analytics on Cloud has embedded the technology into the offering as part of the subscription.  As a part of the Cognos Analytics on Cloud solution the only documentation relevant to Satellite Connector is the Agent itself,  all server components are managed by IBM as part of the service.  This can cause some confusion when clients read the Satellite Connector documentation so please ignore any that discusses the server/cloud side of Satellite Connector.

Satellite Connector

The installation of the Satellite Connector Agent is relatively simple however it does require infrastructure and possible firewall changes.

To prepare your infrastructure for the implementation of the Satellite Connector Agent with Cognos Analytics on Cloud.

A Satellite Connector agent can runs natively on windows as a service or as a docker agent.  Many clients use Windows OR do not have container skills so I have focused on information pertaining to a native Windows agent install.

If docker, for the benefits it provides, is an option, you can find more information on how to run the image on Windows Subsystem for Linux (WSL2) here: https://docs.docker.com/desktop/wsl/

Windows agent hardware requirements:

You will need one (or more) machines (usually virtual) for the Windows Satellite Connector Agent to be installed on.

A single connector will support up to 35 endpoints (Databases).

Two Windows agents cannot coexist on the same machine as they run as a service.

For High Availability (HA), two or more machines with agents installed are required per Connector. A recommendation for HA is three agents per Satellite Connector meaning three windows machines.

An alternative is to use Docker containers which would reduce the number of machines required as more than one container can run on the same machine.

Installation requirements for the machines:

The installation requirement for the Windows agent at the time of writing is:

• Connector agent for Windows supports Windows 10 and later or Windows Server 2016 and later.
• The Windows server where you run your Connector agent must have at least 4 cores and 4GB memory.
• For high availability, plan to deploy 1 agent per windows host and 3 to 6 agents in total per Planning Analytics environment.
• The Windows machine must have a network route to the required databases and port 443 outgoing to the internet.

Note on High Availability (HA): HA may be required depending on how mission critical Cognos Analytics on Cloud is however, this is a decision made based on risk levels of a particular CA application and the data connectivity required from the source databases.

Networking (Firewall rules):

All Satellite Connector Agent machines need a network route that is open to your internal/cloud databases and their respective ports (target data sources)

All Satellite Connector Agent machines need an outgoing internet connection on port 443.

Note on Firewall configuration:

IF your firewall team only open outgoing ports (443) to specific destinations

An FQDN (Fully Qualified Domain Name) should be used if possible as IP addresses can change.

Network requirements and endpoints can be found here: https://ibm.biz/CS_PAoC_SCA_NetReq

When looking at the network requirements link above for the target Satellite Connector data centre it is important to note where your current Cognos Analytics on Cloud system operates and select the correct Satellite Connector data center for your 443 outgoing rules. ie, for EMEA use the Frankfurt details.

Planning Analytics to Satellite Connector mappings:

Windows Agent Installation and Configuration:

Once the machines that will host the Satellite Connector Agent are provisioned in your network and the firewall is open you can start the agent installation and configuration process.

Step 1, Define the Satellite Connector in Cognos Analytics on Cloud

In Cognos Analytics select the menu bars in the top left corner and then select "Manage".
Select the the Satellite Connector option.
In the Satellite Connector window select "Create Satellite connector"
Give the connector a name such as London or Head office (for the location where the Agent will be installed) and hit Create.
You can now download the image or, in this case, the windows agent files. Download the Windows installer files and copy the Connector ID and Api key. Both the ID and key will be used when you configure your installed agent so make a note of these now.  Note: If you configure multiple agents for high availability (HA) then all of them should use the same ID and keys.
The next step is to define your first endpoint (database). The endpoint name is your choice and usually is something that identifies the target database. The host and port are the host ip and port upon which your database accepts queries, for example, port 50000 for DB2.  In my case the database is mySQL and runs locally on the same machine as the agent. Note:  additional endpoints can be created once the wizard is completed.
The next step is a summary of the actions needed to point your Cognos Analytics data server connection at the Satellite connector endpoint.

You will now see your Connector details such as location the connector is managed from and current status:

Note:  the Properties context menu on the connector shows the ID and Key while you can also download the agent from the "Download client" menu as well.

Drilling down on a connector shows the endpoints.  this is where you can add more endpoints if required.

Step 2,  Download the client (if not already done while configuring the connector):

Note: this is also how you can download new versions of the agent.

Select the newly created Satellite Connector and on the right hand side of the screen select the context menu and "Download client".
From here you can select the agent type (in my case, Windows) and use the download client button for the Windows agent installation. Ensure you also copy agent Connector ID and the API key. Select "Download connector agent".
Your download folder should now contain the zip file for the agent. This can now be moved to the server that you wish to run the agent on.

Step 3, Run the Satellite connector agent installation and configure using the Connector ID and access token

Before running the install for the Satellite connector agent you will need to extract the files to an appropriate location.  Often,  files downloaded are blocked by Windows so it is advised to "right click" on the installer zip file, select properties and check the "Unblock" option then apply.
You can now "Extract All" the contents of the installer zip file to a directory where you would like the installer to run.  The directory choice is up to you, in this case I have used "C:\satellite-agent-windows".
Once extracted,  find the config file in the extracted directory (C:\satellite-agent-windows).  Edit the file.
The file will contain settings for areas such as log level. The two items that need changing are: <connector_id> and <api_key> Update these with your connector ID and the API key.  These can be copied and  found under the connector context menu: Properties
Once edited your file should have the ID and Key between the two double quote marks. Save the config file and close it.
To install the Satellite connector agent,  Open a powershell window.
Change directories to the root of the installer extracted files and run ".\install" to execute the installer.  You will be asked to confirm the install: type y and hit return. Please also note that for updates there is also an update script and an uninstall script to remove the agent.
When the installer is running,  you will see several popups asking to make changes to the Windows machine (such as registering the service).  Answer "Yes" to these.
Once the install is complete,  you should see a new Satellite Connector service in the Windows services and it should be running.
In Cognos analytics, under the Satellite Connector menu you can now that the connection states "Connected".  If it does not, first refresh the page.   Other areas to check if the connection is not Online are the logs under the installation directory (in my case: C:\satellite-agent-windows\logs).  The log file for connections is "connector-agent-<todays date and log number>.log". Please also ensure that the firewall has been correctly opened as detailed above.

Step 4, Update your datasource connection to use the Satellite Connector and test connectivity

To update any existing (or new) connections to your databases so they go via the Satellite Connector secure network. select the Manage menu..
Then select the Data server connections option.
You can now test the connection to the database via the Satellite Connector secure network by selecting the new endpoint and, from the three dot context menu, select "Details"
Drill down on the data server connection you wish to update to use Satellite Connector so you are on the connections screen and, from the context menu, select "Properties".
Select the connection tab.
Scroll down the page and find the section "On-Premise destination". Expand the section and select the Connector you wish to use from the Satellite Connector dialog.
This will now list endpoints for the Satellite Connector. Expand this and select the correct endpoint.
Ensure the Authentication method is correct and then select the dispatches you wish to test connectivity from.
Once you hit "Test connection" you should see a success message.  If the connection is unsuccessful then you can view the results to see what the issue may be.  Usually it is related to incorrect credentials or connection information such as the database in the JDBC url.