Page tree
Skip to end of metadata
Go to start of metadata

Summary: describes how to deploy and configure CAST Dashboards embedded in the AIP Console package using a ZIP file (AIP Console ≥ 1.25). If you are using AIP Console ≥ 2.x as Docker containers, embedded Dashboards are automatically configured and you do not need to follow these steps.

Phase 1 - CAST RESTAPI deployment and configuration

Step 1 - Deploy the CAST RESTAPI

You must always use the cast-integrated-health-engineering-dashboard-<version>.zip file provided with the current release of AIP Console.

The cast-integrated-health-engineering-dashboard-<version>.zip is provided in the installation media .ZIP file (alongside the .JAR installer for the AIP Console) and is partly pre-configured for use with the CAST AIP Console. Locate the file and move it to a suitable location - it can be run from anywhere.

The CAST RESTAPI is started using the following files - however, CAST recommends not starting the application at this point (it will not start properly). You can also install the RESTAPI as a Microsoft Windows Service as an alternative to using the startup.bat (see below).

Microsoft Windows
<unpacked_zip>\startup.bat

Linux
<unpacked_zip>\startup.sh

Install as Microsoft Windows service

If you have deployed the ZIP file on Microsoft Windows and would like to control the application server via a Microsoft Windows Service, CAST provides an installation batch script to do this for you:

<unpacked_zip>\dashboard-service-install.bat

Double click this file to start the service installation. You may be prompted to accept a UAC warning:

On completion the service will be listed as CAST Dashboard Service with a startup type set to Automatic, log on as Local System and will not be running:

  • The installer requires:
    • Java JDK or JRE ≥ 8
    • a JAVA_HOME system environment variable pointing to the installation location of the Java JDK
  • The .bat installer will configure the service to use the <unpacked_zip>\amd64\dashboard-service.exe. You may want to ensure that the unpacked zip file is in an appropriate location.
  • You can change the log on as, after the install has completed by right clicking the service and changing the options in the Log On tab:

Memory tuning - optional

If you experience Low Memory/Recovered Memory/Out of Memory errors or exceptions then you may need to tune the RAM memory allocated to the web application.

Using startup batch scripts

If you are using the startup.bat or startup.sh scripts to start the web application, these scripts set the RAM memory allocated to the web application in the script itself using the Java -Xmx and -Xmss parameters:

  • Initial memory pool = 256MB
  • Maximum memory pool = 1024MB

If you would like to change these values, they are located on the following lines. Save the files after making the changes. Changes are only taken into account when the web application is started/restarted:

Microsoft Windows - startup.bat
java -jar -Xmx1024m -Xms256m cast-integrated-health-engineering-dashboard-<version>.jar

Linux - startup.sh
JAVA_OPTS="-Xmx1024m -Xms256m"

Using Microsoft Windows Service

The Microsoft Windows service installer batch script will set the service to use the following RAM memory - you may find that this is not sufficient if you experience out of memory Java errors and these values can be increased. After making changes, restart the Microsoft Windows service to ensure the changes are taken into account:

  • Initial memory pool = 256MB
  • Maximum memory pool = 1024MB

Step 2 - Ensure license.key is in place  - ≤ 1.25 only

When using AIP Console ≤ 1.25 access to data in the CAST Dashboard Service schema  (i.e. for use by the CAST Engineering Dashboard) is governed by a license key - see Dashboard Service license key configuration. You must have a valid UNRESTRICTED license key in your possession before you begin. When using AIP Console ≥ 1.26, a license key is not required and you can skip this section.

The license key should be deployed here:

<unpacked_zip>\configurations\license.key
Note that RESTRICTED license.key files are NOT supported.

Step 3 - Configure connection details

When the ZIP has been unpacked you now need to configure the application.properties file to tell the CAST RESTAPI on which CAST Storage Service/PostgreSQL instance the Dashboard schemas are stored. This file is located here:

<unpacked_zip>\configurations\application.properties

Locate the following section in the file:

## DATASOURCE (DataSourceAutoConfiguration & DataSourceProperties)
# properties which will be considered by spring-boot automatically to create the bean for datasource at run time
# Connection to PostgreSQL database
restapi.datasource[0].url=jdbc:postgresql://localhost:2282/postgres
restapi.datasource[0].username=operator
restapi.datasource[0].password=CastAIP
restapi.datasource[0].poolname=Resource1
restapi.datasource[0].minimumIdle=10
restapi.datasource[0].maximumPoolSize=20

One single CAST Storage Service / PostgreSQL instance

If all your Dashboard schemas are located on one single CAST Storage Service/PostgreSQL instance then you need to modify the url, username and password entries to match your target CAST Storage Service/PostgreSQL, for example:

  • You MUST change localhost in the restapi.datasource[0].url parameter to a host name or IP address
  • Save the file before proceeding.
## DATASOURCE (DataSourceAutoConfiguration & DataSourceProperties)
# properties which will be considered by spring-boot automatically to create the bean for datasource at run time
# Connection to PostgreSQL database
restapi.datasource[0].url=jdbc:postgresql://192.168.200.104:2282/postgres
restapi.datasource[0].username=operator
restapi.datasource[0].password=CastAIP
restapi.datasource[0].poolname=Resource1
restapi.datasource[0].minimumIdle=10
restapi.datasource[0].maximumPoolSize=20

Multiple CAST Storage Services  / PostgreSQL instances

If your Dashboard schemas are located on multiple CAST Storage Services/PostgreSQL instances, you need to add in the additional servers as shown in the example below:

  • Ensure that you modify the url, usernamepassword and resource entries to match your target CAST Storage Service/PostgreSQL. In particular, the resource entry must be unique within the application.properties file.
  • The [0] must also be incremented for additional CAST Storage Service/PostgreSQL instances, for example, use restapi.datasource[1]restapi.datasource[2] etc.
  • You MUST change localhost in the restapi.datasource[0].url parameter to a host name or IP address
  • Save the file before proceeding.
## DATASOURCE
# Resource1 is the datasource name used in domains.properties
# Adapt server name (localhost) and port (2282) if required
# You can add multiple datasources if you want to connect to multiple CSS Servers. Datasource name must be unique
# You have to configure your domains names and relative schema names in domains.properties
restapi.datasource[0].url=jdbc:postgresql://192.168.200.104:2282/postgres
restapi.datasource[0].username=operator
restapi.datasource[0].password=CastAIP
restapi.datasource[0].poolname=Resource1
restapi.datasource[0].minimumIdle=10
restapi.datasource[0].maximumPoolSize=20

restapi.datasource[1].url=jdbc:postgresql://192.168.200.105:2282/postgres
restapi.datasource[1].username=operator
restapi.datasource[1].password=CastAIP
restapi.datasource[1].poolname=Resource2
restapi.datasource[1].minimumIdle=10
restapi.datasource[1].maximumPoolSize=20

minimumIdle and maximumPoolSize

The following options are used to govern the connections from the web application to the target CAST Storage Service/PostgreSQL instance:

restapi.datasource[0].minimumIdle=10
restapi.datasource[0].maximumPoolSize=20

CAST recommends using the default options unless you are experiencing performance issues. The options are used as follows:

minimumIdle

The minimum number of connections that should be kept in the pool at all times (even if there is no traffic). Default value is 10.  Idle connections are checked periodically.

maximumPoolSizeThe maximum number of active connections that can be allocated from this pool at the same time. The default value is 20.

Step 4 - Configure domains.properties for the Measurement Service schema

Open the following file with a text editor - this file defines the connection between the RESTAPI and the CAST Storage Service/PostgreSQL on which the Measurement Service schema is stored:

<unpacked_zip>\configurations\domains.properties

One uncommented line will exist as follows - if you have defined one single CAST Storage Service/PostgreSQL instance in the previous step and you are using the default settings for the Measurement Service schema (see Administration Center - Settings - Measurement), then you do not need to make any changes here:

AAD=Resource1,general_measure

Otherwise make changes as follows:

  • AAD refers to the Measurement Service schema. This entry must always start with AAD. Do not change this.
  • Resource1 refers to the name attribute used in the <resource> tag in the context.xml file - see Step 3 above. This identifies the CAST Storage Service/PostgreSQL connection parameters (as defined in the context.xml file) specifically for the Measurement Service schema.
  • general_measure is the name of the Measurement Service schema you are using with AIP Console (this is the default name for this schema as defined in Administration Center - Settings - Measurement). If you are using a different name, then please update it here.

Step 5 - Start the CAST RESTAPI

Start up (if it is not already running) the web application to ensure that the changes are taken into account. The bootable ZIP is set to run on port 8087 by default. You may need to update inbound firewalls to allow access from AIP Console to this port. You can also change the port number in the following file:

<unpacked_zip>\configurations\application.properties

in the following line:

# Configure server port. This is necessary only for the .jar mode/version
server.port=8087

Phase 2 - AIP Console configuration

Login to the AIP Console with a user account that already has the Admin role and switch to the Admin Center:

Now move to the System Settings panel:

Open the Dashboard Integration settings panel and fill in as explained in Administration Center - Settings - Dashboard Integration:

Save the file and then restart the AIP Console to ensure that the changes are taken into account.

Test the configuration

In the CAST AIP Console, click either of the dashboard icons to check that you can access the dashboards:

Notes

Declaring a new AIP Node in AIP Console when the embedded Dashboards have already been configured requires that you save the Dashboard Integration settings to ensure any snapshots generated with the AIP Node before it was declared are made available in the dashboards.

  • No labels