Skip to main content

InterSystems Reports Server with InterSystems IRIS

InterSystems Reports became available with InterSystems IRIS and IRIS for Health 2020.1. However, beginning with Release 2020.4, InterSystems has added several new capabilities to improve the InterSystems Reports Server. These changes are:

  • Addition of a Docker container with InterSystems Reports Server to make implementation and distribution easier. This container is available in the InterSystems Docker repository. https://containers.intersystems.com. This container does not include InterSystems IRIS or IRIS for Health software. The docker-compose file is available from the WRC download site. For more details see Docker Container Installation

  • Addition of InterSystems Reports server scripting for installation of the software. This automates installation and setup of InterSystems IRIS as the database for InterSystems Reports configuration. All configuration and management data for InterSystems Reports is stored in InterSystems IRIS. This script is available from the WRC Download site. For more details see Server Installation.

  • Enable configuration of InterSystems Reports Server from the System Management Portal via Linked User Accounts. This enables the InterSystems administrator to configure and view any configured Reports Servers from the Management Portal. For more details see Using the Management Portal and Enabling Linked User Accounts.

There are three entities involved in the InterSystems Reports server:

  • The InterSystems IRIS instance where report configuration information is stored.

  • The InterSystems IRIS instance that supplies data for reports.

  • The InterSystems Reports server, supplied by Logi Analytics.

All three can be running on the same machine, or any combination of different machines. If you use more than one machine, they all must be able to communicate with each other. The reports configuration and reports data functions can be performed by the same InterSystems IRIS instance, or two different instances. The installation script provided by InterSystems sets up the instance where configuration information is stored, and the Reports server.

InterSystems recommends one InterSystems Reports Server per source InterSystems IRIS instance. The Designer can be shared.

Server Installation

Two of the entities mentioned previously are involved in installation of the InterSystems Reports Server, `the InterSystems IRIS instance where report configuration information is stored, and the InterSystems Reports server, supplied by Logi Analytics.

Use the following steps to install the InterSystems Reports Server.

  1. Make sure the machine where you are installing the Server meets the Logi Analytics minimum System Requirements.

  2. Select (or install) an InterSystems IRIS instance to store Logi configuration tables. You need to note the following information for future use:

    1. The machine hostname or IP address

    2. The InterSystems IRIS superserver port number

    3. The InterSystems IRIS system user and password. This user should have %All access. It is used only during installation. Due to a current limitation, passwords cannot contain exclamation marks (!).

  3. Logi stores internal system tables in a designated namespace in the InterSystems IRIS instance. You provide a name for this namespace, and the install script creates the namespace for you.

  4. For InterSystems IRIS 2020.4 and above, you need to supply a name for this Logi Server Configuration. This is the name that identifies this report server instance in the Management Portal.

  5. Make sure a supported JDK is somewhere on Logi Server machine. See Supported Java Technologies for information on JDK supported by InterSystems IRIS. Make note of path and filename where JDK is installed for future use.

  6. Download install folder from the, WRC Distributions page. Click Components, then search for “InterSystems Reports Server”, version 17.1. Unzip the downloaded file somewhere on your Logi Server machine. Due to a current limitation, make sure there are no spaces in the file path.

  7. If the InterSystems IRIS instance you are using to store configuration information is not version 2020.4 or above, modify bin/PrepareReportInstall.java in the install folder you downloaded from the WRC. The required change is described in Version Dependencies.

You are now ready to run the installation script. The Installation script for the InterSystems Reports Server is part of the InterSystems Reports installation kit you received from InterSystems, available on the WRC Download site. The script is named InterSystemsReportSetup.bat or InterSystemsReportSetup.sh, depending on your platform. The install script prompts you to input the following values:

Prompt
Default Value
Help Text
InterSystems IRIS Hostname or IP address
127.0.0.1
The computer hosting InterSystems IRIS configuration instance, from step 2 in the preceding list. If you are using your local computer, please use the IP address 127.0.0.1, or the hostname rather than localhost.
InterSystems IRIS Superserver Port
1972
The superserver port of the InterSystems IRIS configuration instance, from step 2 in the preceding list.
Namespace
 
The InterSystems IRIS namespace to be used by this report server. Note each report server requires a separate namespace. If the given namespace does not exist it is created.
Logi Report Server Name
 
For InterSystems IRIS 2020.4 and above, the name InterSystems IRIS uses to refer to this report server. This is the name you decided on in step 4 of the preceding list. The name you enter here appears in the InterSystems Reports page in the Management Portal. Note that each report server requires a unique name.
Logi Report Server Host
127.0.0.1
The computer hosting the Logi Report Server. Note that InterSystems IRIS uses this address to access this report server, so ensure the machine hosting InterSystems IRIS can reach it. If InterSystems IRIS Reports is being hosted on your local computer, please use 127.0.0.1, the IP address, or the hostname rather than localhost.
Logi Report Server Port
8888
The port the Logi Report Server uses. Must be available and between 1 and 65535. Unless you are installing multiple Logi Servers on one machine, keep the default of 8888.
Single Sign-On Enabled (true/false)
true
Controls whether InterSystems IRIS is able to use single sign-on to access this Logi Report Server from the Management Portal.Correct if/when UI is changed
System User
_system
Required during set up to create or modify the report namespace, server, and user. Is not used after install time. Any user with the %All role is sufficient.
System Password
 
The password for the system user provided in the previous step.
Report User
REPORT
The InterSystems IRIS user this report server connects as. If the given user does not exist it is created.
Report User's Password
 
The password for the report user provided in the previous step. If the user is created in the previous step, the password supplied here is applied to that user.
Logi Report Server License User
  The license user from the user/key pair you received when you purchased InterSystems Reports.
Logi Report Server License Key
  The license key from the user/key pair you received when you purchased InterSystems Reports.
Logi Report Location
C:\\LogiReport\\Server or /LogiReport/Server
The absolute path where this script should install the Logi Report Server on this computer.
JDK Location
 
The absolute path where you installed the local JDK in step 6 in the preceding list. This location varies depending on your operating system and how java was installed. You may also have several versions installed. If you did not install JDK in step 6 in the preceding list, you can usually locate it by running which java on mac or Unix or running where java on windows.

The installation script performs the following actions:

  • Does the necessary InterSystems IRIS setup:

    • creates the report namespace and user if necessary

    • sets up the InterSystems IRIS instance to store report configuration information

    • gives privileges on the report namespace to the report user

  • Installs the Logi Report Server

  • Sets up Linked User Accounts on the Logi Report Server

  • Sets up a connection between the Logi report server and the InterSystems IRIS database

Docker Container Installation

Docker Container Connecting to Existing IRIS instance

Note that config.properties is mounted as a docker secret and should be removed after you have started the server(s). See: https://docs.docker.com/engine/swarm/secrets/.

  1. Edit //main/logireports/docker-installation/bin/config_template.properties and rename it to config.properties. This config.env is similar to the non-docker version, but does not require the following information:

    1. IRIS.JdbcDriverFile

    2. LOGI.LicenseUser

    3. LOGI.LicenseKey

    4. LOGI.InstallPath

  2. Open a terminal, change to the reports directory, and run docker-compose up report-server.

Docker Compose

The docker-compose.yml file in //main/logireports/ provides a way for users to quickly start a report server and IRIS instance in a docker container. To run it:

  1. Place an InterSystems IRIS license key file, renamed to iris.key in reports/docker-installation/bin

  2. Create a file called password.txt and place in reports/docker-installation/bin with the password to set for IRIS system accounts. This should not be SYS. Note that there are multiple options for how to reset the password on IRIS docker containers, see https://docs.intersystems.com/irislatest/csp/docbook/Doc.View.cls?KEY=ADOCK#ADOCK_iris_images_password_auth.

  3. Edit //main/logireports/docker-installation/bin/config_template.properties and rename to config.properties. This config.properties is identical to the one for standalone installation, except:

    1. IRIS.SuperserverPort must be 9091, if you want to change this, you also need to change it in docker-compose.yml.

    2. IRIS.SystemPassword must be identical to the password in password.txt.

  4. Run docker-compose up to start.

  5. After shutting down, you need to recreate password.txt to rerun. You may also need to run docker-compose down before restarting.

Version Dependencies

If you are connecting to an instance of InterSystems IRIS at a version less than 2020.4, remove the following from PrepareReportInstall.java as %Report.ServerDefinition does not exist in earlier versions.

// create report server
IRISObject reportServer = (IRISObject)
iris.classMethodObject("%Report.ServerDefinition", "%New");
reportServer.set("Name", usrProp.getProperty("LOGI.ServerName")); 
reportServer.set("Host", usrProp.getProperty("LOGI.Host")); 
reportServer.set("Port", usrProp.getProperty("LOGI.Port")); 
if (usrProp.getProperty("LOGI.SSOEnabled").equalsIgnoreCase("true")){
 reportServer.set("SSOEnabled", true); 
}else{ 
 reportServer.set("SSOEnabled", false);
} 
reportServer.invoke("%Save"); 
System.out.printf("Created report server %s.\n", usrProp.getProperty("LOGI.ServerName"));

Using the Management Portal

You can use the Management Portal to create, view, and edit InterSystems IRIS Reports server configurations. The installation process creates a report server, which is listed on the InterSystems Reports page on the Management Portal. To find this page, select System Administration > Configuration > InterSystems Reports. The following screen shot shows the page with the initial report server. The server name listed here is the one you supplied to the install script as Logi Report Server Name.

Report server definition called ReportServer

Form that is used to create a new Report Server definition

Selecting a server in the list and using the Edit button opens the same form initialized with values from the selected server. You can modify the server configuration, or use the Delete button to remove it entirely. Selecting the SSO Enabled check box enables the Linked User Accounts feature, see Enabling Linked User Accounts.

Form that is used to edit a Report Server definition

If Linked User Accounts has been enabled, you can access the Logi report server from the Management Portal. Select System Administration > Configuration > InterSystems Reports to navigate to the InterSystems Reports page, which lists existing reports servers. Select Configure.

Form used to open InterSystems Report Configuration page

This action opens the InterSystems Report Configuration page:

Form used to open Logi Report

Clicking on Select opens Logi Report, logged in as TestUser.

Enabling Linked User Accounts

Linked user accounts is a feature that enables you to access Logi Report directly from the InterSystems IRIS Management Portal without entering an additional Logi user name and password. This functionality is achieved by linking a user account on the InterSystems IRIS server with a Logi user account. This linkage is made by assigning a role to the InterSystems IRIS user. The name of this role must follow a specific naming convention.

  • The first part of the name is the name you supplied as the Logi Report Server Name during server installation.

  • The second half of the name is the name of a Logi user.

  • The two halves of the name are separated by an underscore character (_).

For example, if the Logi Report Server Name is IRISP284 and there is a Logi user named TestUser, a role having the following name can link an InterSystems IRIS user to TestUser on Logi Report:

IRISP284_TestUser

Logi users named admin and guest exist on Logi Report systems by default. When you enable linked user accounts on an InterSystems IRIS report server, that action creates roles to link InterSystems IRIS users to these Logi accounts. These roles are:

  • LogiServerConfigName_admin

  • LogiServerConfigName_guest

When the linked user accounts feature is disabled, these roles are not edited or deleted, but do not appear in the configure page. You can create additional roles for linking user accounts as you would create any other InterSystems IRIS roles, being careful to follow the naming convention.

Given a Logi server configuration name IRISP284, the following screen shot shows the default roles create by the installation script, and an additional role for Logi user TestUser created through the Management Portal.

List of roles that provide single sign-on to the Report Server

The ability of users to configure report servers is influenced by the privileges assigned to them. Users with %Admin_Secure have access to report server operations that indirectly manipulate roles, while users without that privilege do not. When creating a new report server, users without %Admin_Secure are unable to toggle linked user accounts. The form is presented to such users with the SSO Enabled check box disabled. If a new report server is created with SSO Enabled selected, the default roles are created automatically.

If these roles already exist, they are not overwritten or updated upon creation of the report server. The admin and guest roles, whether generated manually or automatically, and other roles of the form "<ReportServer.Name>_role" are updated automatically when you change the name of the report server. These roles are also deleted upon deletion of the report server.

Feedback