Skip to main content

InterSystems Reports Server with InterSystems IRIS

InterSystems Reports became available with InterSystems IRIS and InterSystems 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.comOpens in a new tab. This container does not include InterSystems IRIS or InterSystems 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

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

InterSystems Reports Server Version 19.0

Use the following steps to install the InterSystems Reports Server version 19.0:

  1. Make sure the machine where you are installing the InterSystems Reports Server meets the Logi Analytics minimum System RequirementsOpens in a new tab. Make sure a version of JDK supported by both Logi and InterSystems is installed somewhere on machine running the designer. See Supported Java TechnologiesOpens in a new tab for information on JDK supported by InterSystems IRIS, and System RequirementsOpens in a new tab for JDK supported by Logi. Make a note of the path to the JDK. You need this information when you select a JDK later in the installation.

  2. Make sure the same machine also has an instance of InterSystems IRIS® or InterSystems IRIS for Health™.

  3. Download the InterSystems Reports Server installation kit from WRC Distributions page, using the information you received when you purchased InterSystems Reports.

    The kit should include the following files:

    • intersystems-jdbc-3.2.1.jar

    • intersystems-reports-18.3.0.jar

    • readme.txt

    • server.exe

    • version.txt

  4. Open a command window and change directory to the location of the kit.

  5. Enter the following command:

    • Windows:

      java -cp .;./* com.intersystems.reports.Installer
    • Unix:

      java -cp .:./* com.intersystems.reports.Installer

      This command uses a colon (:) instead of a semicolon (;), because the classpath delimiter is different on Unix and Windows.

  6. The installer script prompts you for the following information:

    1. InterSystems IRIS hostname or IP address.

    2. The superserver port of InterSystems IRIS.

    3. 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, the script will create it.

    4. The unique name to assign to this report server (Logi Report Server Name).

    5. The computer hosting this report server (Logi Report Server Host).

      Note that InterSystems IRIS will use this address to access this report server, so ensure it is reachable from the machine hosting InterSystems IRIS. If InterSystems IRIS and Logi Report are being hosted on the same computer, please use 127.0.0.1, the IP address, or the hostname rather than localhost.

    6. The port Logi Report will use. Must be available and between 1 and 65535.

    7. Enable Single Sign-On — controls whether InterSystems IRIS will be able to use single sign-on to access this Report Server from the Management Portal.

    8. InterSystems IRIS user this Report Server will connect as (Report User). If this user does not exist, the script will create it.

    9. Password for the report user.

    10. The license user from the user/key pair you received when you purchased InterSystems Reports.

    11. The license key from the user/key pair you received when you purchased InterSystems Reports.

    12. The absolute path on this computer where to install Logi Report Server.

    13. JDK path.

    After you enter this information, the installer sets up the Report server and then uses a JDBC connection to connect to IRIS and set up the report namespace and report user.

You should then see messages like the following:

================================================================================
 
                      InterSystems Reports Installation
 
================================================================================
Loaded configuration from C:\iscreports-sample\config.properties
Performing IRIS setup...
Waiting for JDBC connection to setup users and namespaces (as necessary)...
Successfully connected to jdbc:IRIS://127.0.0.1:1972/%SYS.
Successfully saved Report Server definition "report-server"
Using pre-existing report namespace "REPORTS".
Created report user "REPORT".
Successfully connected to jdbc:IRIS://127.0.0.1:1972/REPORTS.
Granted %DB_OBJECT_DEFINITION to REPORT
Installing Logi Report Server (this may take a few minutes)...
Configuring single sign on from IRIS to Logi Report server...
================================================================================
 
              InterSystems Reports Installation was successful.
 
================================================================================

Alternative: Performing Manual Configuration and Installation

Instead of installing as described above, you can edit a configuration file and use that in the installation. The steps are as follows:

  1. Follow steps 1–3 of the basic installation procedure, making sure of prerequisites and obtaining the kit.

  2. Update the config.properties file in the ISCReports kit with the relevant information. The following sample demonstrates the fields that need to be populated:

    IRIS.Host=127.0.0.1
    IRIS.SSPort=1972
    IRIS.ReportNamespace=REPORTS
    LOGI.ServerName=report-server
    LOGI.Host=127.0.0.1
    LOGI.Port=8888
    LOGI.EnableSSO=true
    IRIS.SystemUser=_system
    IRIS.SystemPassword=SYS
    IRIS.ReportUser=REPORT
    IRIS.ReportPassword=SYS
    LOGI.LicenseUser=Intersystems
    LOGI.LicenseKey=999999999999999999999999999999999999999999999999
    LOGI.InstallPath=C:\LogiReport\Server
    LOGI.JdkPath=C:\Program Files\Java\jdk-16.0.2

    Note:

    • IRIS.Host is the name of the server where IRIS is installed.

    • IRIS.SSPort is the superserver port (you can find this in the About section of IRIS Management Portal).

    • LOGI.InstallPath is the path where ISCReport software will be installed in your machine

    • LOGI.JdkPath is the path to JDK in your machine (To find this for Windows, type echo %JAVA_HOME% at a command prompt. To find this for Unix, type which java or whereis java.)

  3. Open a command window and change directory to the location where your ISCReports kit is present.

  4. Enter the following command:

    • Windows:

      java -cp .;./* com.intersystems.reports.Installer --load config.properties
    • Unix:

      java -cp .:./* com.intersystems.reports.Installer --load config.properties

InterSystems Reports Server Version 18.2.2

Due to temporary restrictions, no installation script is available for InterSystems Reports Server, version 18.2.2, To use this updated server from Logi Analytics, follow the installation instructionsOpens in a new tab provided by Logi Analytics. Make sure a JDK supported by both InterSystems and Logi is installed somewhere on the Logi Server machine. See Supported Java TechnologiesOpens in a new tab for information on JDK supported by InterSystems IRIS and System RequirementsOpens in a new tab for JDK supported by Logi. You need the JDBC driver class name and the JDBC driver class path when you install the report server.

Docker Container Installation

Docker Container Connecting to Existing InterSystems 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/Opens in a new tab.

  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 InterSystems 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 InterSystems IRIS system accounts. This should not be SYS. Note that there are multiple options for how to reset the password on InterSystems IRIS docker containers, see https://docs.intersystems.com/irislatest/csp/docbook/Doc.View.cls?KEY=ADOCK#ADOCK_iris_images_password_authOpens in a new tab.

  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

Selecting the New Report Server button opens the form shown below, which you can use to configure a new report server by entering the Name, Host, and Port, and using the SSO Enabled check box to determine whether single sign-on is enabled.

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 used to edit an existing 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.

FeedbackOpens in a new tab