AspenTech IP.21 Agent

The AspenTech InfoPlus 21 Agent uses SqlPlus ODBC Driver to execute SqlPlus queries to read data from an InfoPlus server. The agent is a .NET application and is delivered separately from the core HighByte Intelligence Hub installation. The requirements for the agent are as follows.

1. Windows Operating System
2. Microsoft .NET 4.8 or greater
3. SqlPlus ODBC Driver. This is installed as part of the InfoPlus 21 installation or manually following instructions documented in the Aspen Support Knowledge Base.

The Intelligence Hub communicates with the agent over a secure websocket (wss) connection that requires a TLS certificate. To use a self-signed certificate and private key run the following command to install it into the LocalMachine\Personal certificate store. Certificate installation must be performed with an account that has Administrator permissions. The installation process grants the Current User, Local System account, and Administrators read access to the certificate and private key. Non-admin users that need to run the agent interactively will need to be granted read permission to the certificate’s private key. This can be managed using the Windows Certificate Store by right-clicking the certificate, choosing All Tasks > Manage Private Keys.

intelligencehub-ip21.exe -installcert

By default the agent will use the self-signed certificate and private key. The self-signed certificate will expire after 5 years. The tool outputs information about the certificate as well as the user that was granted access to the certificate private key. Access to the private key is required in interactive and service mode.

The agent runs as a standalone application, by running the intelligencehub-ip21.exe OR as a Windows service. When running standalone, it’s recommended to run the executable with admin level permissions. To install as a service, run the following command. InstallUtil is found in the .NET installation directory: %windir%\Microsoft.NET\Framework64\v4.0.30319\InstallUtil.exe

installutil intelligencehub-ip21.exe

NOTE: Whether the agent is run in a console or a service the application should be run with a user that has read-only access to InfoPlus.21 database.

To optionally control the service name, using the following syntax.

installutil /serviceName="myServiceName" /displayName="myDisplayName" intelligencehub-ip21.exe

The agent opens a port to receive requests from the HighByte Intelligence Hub instance. By default, this communication occurs using secure websockets. On the first run the agent creates a settings.json file. The file contains the following.

{
	"port": 45390,
	"token": "randomtoken",
	"subjectName": "HighByte IP.21 Agent"
}

Any changes to these settings require restarting the agent.

In the Intelligence Hub IP.21 connection settings, enter the IP/port of the agent, as well as the token. The agent also has a local intelligencehub.log file for debug information. See below on how to enable detailed diagnostics logging.

To use a custom certificate/private key, import the key pair into LocalMachine\Personal certificate store and grant read permission to the imported private key. Permissions for the private key can be managed through the certificate store by right-clicking the certificate, choosing All Tasks > Manage Private Keys.

Next, set subjectName in settings.json to match the certificate Subject Common Name. This information can be reviewed by opening the Certificate, choosing the Details tab, and scrolling to the Subject entry.

For example, a certificate with Subject of CN = MyOrgAgentCertificate, update the settings.json to:

{
	"port": 45390,
	"token": "randomtoken",
	"subjectName": "MyOrgAgentCertificate"
}

Diagnostics Logging

The IP.21 Agent includes detailed diagnostics to analyze read and write performance. The agent uses NLog for to control log retention policy and verbosity. To control diagnostics change the intelligencehub-ip21.exe.config file in the same directory as the intelligencehub-ip21.exe file.

Add the following configuration to the file, save the file, and restart the agent. Diagnostics logs will be included in the console output and in the log file.

If the agent is running as a Windows Service under a Windows account with access to IP.21, it must also have local file system access to write the diagnostics file locally. Otherwise, the local log file will not be written.

The default logging configuration is shown below.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
	<configSections>
		<!-- Register NLog as a configuration section -->
		<section name="nlog" type="NLog.Config.ConfigSectionHandler, NLog" requirePermission="false" />
	</configSections>
	<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
		  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
		<!-- Define targets (where logs are written) -->
		<targets>
			<!-- File target 3 files up to 100MB each -->
			<target xsi:type="File"
					name="logfile"
					fileName="intelligencehub.log"
					archiveFileName="intelligencehub.{#}.log"
					archiveNumbering="Rolling"
					archiveAboveSize="104857600"
				maxArchiveFiles="3"
				layout="${date:format=dd-MM-yyyy hh\:mm\:ss} | ${level} | Agent | ${message}" />
			<target xsi:type="Console" name="console" layout="${date:format=dd-MM-yyyy hh\:mm\:ss} | ${level} | Agent | ${message}" />
		</targets>

		<!-- Define rules (what gets logged and where) -->
		<rules>
			<!-- Log all levels to the file -->
			<logger name="*" minlevel="Trace" writeTo="logfile" />
			<logger name="*" minlevel="Trace" writeTo="console" />
		</rules>
	</nlog>
	<startup>
		<supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.8"/>
	</startup>
</configuration>