Ignition Module
JVM AGENT
Overview
The Seeq Ignition Module integrates Seeq's trending, visualizations, calculations, analytics, cleansing, modeling, advanced monitoring and reporting into Inductive Automation's Ignition platform.
Prerequisites
Download the appropriate Seeq Ignition Module module file from the Seeq Product Download page.
You must choose the v7 module if you are using Ignition 7.x, and the v8 module if you are using Ignition 8.x.
Some browsers like Internet Explorer 11 may rename the module file such that it has a .zip extension. You will have to use Windows Explorer to change the extension to .modl.
In a web browser, open the Ignition Gateway configuration site and log in with administrator credentials.
Browse to the SYSTEM → Modules section.
Scroll to the bottom of the page and click the Install or Upgrade a module link.
Click Choose File and browse to the .modl file you downloaded in Step 1.
Click Install and allow the module to load.
After installing the module, you may need to log out and log back in to the Ignition configuration site so that the SEEQ settings area appears in the bottom left of the page.
Browse to the SEEQ → Settings section.
In the Seeq Server Hostname textbox, enter the hostname or IP address of the Seeq SaaS service or your Seeq Server machine.
Ensure that the port number specified in Seeq Server Port is not blocked by a firewall on the Seeq Server machine. (Instructions for Windows Firewall configuration here.)
If you're connecting to a Seeq Server which is running with a self-signed certificate, you need to copy the Seeq Server's certificate to the Ignition Gateway machine by hand.
The certificate is stored on the Seeq Server in the Seeq data folder under the keys subfolder. Copy the seeq-cert.pem file in that folder to the appropriate location on the Ignition Gateway machine (the <ignition_data>/certificates/supplemental folder).
If you are using Ignition 8.0 and earlier, contact Seeq Support for assistance installing the self-signed certificate.
In Seeq Workbench, go to the API Reference page (from the upper-right "hamburger" menu), find the GET /systems/agentKey endpoint, and click its Execute button. Copy the value of the “agentKey” property from the JSON response and then paste it into the Agent Key section of the SEEQ → Settings section on the Ignition Gateway.
Click Save Changes.
Refresh your Seeq Workbench screen and you should see your Ignition tags in the Data tab. Indexing all the tags may take some time. Check out the Browsing Ignition Tags from Seeq Workbench while you wait.
Configuration
Filtering Tag Providers
By default, Seeq will index all tag providers that are defined on the gateway. If more than one tag provider is indexed, then the asset tree in Seeq Workbench will include the tag providers near the top.
You may wish to filter down to a particular set of providers, perhaps because you don't need to see all the providers in Seeq or because some of the providers are unavailable.
To filter the set of providers, take the following steps:
In the Ignition Gateway configuration site, browse to the SEEQ section at the bottom of the configuration section list on the left hand side.
Select the SEEQ → Settings section.
In the Tag Providers section, add a comma-delimited list of all tag providers you want Seeq to index. For example:
CODEdefault,Orlando,DallasClick Save Changes.
Seeq will begin re-indexing and the tag providers listed will be the only ones showing in Seeq.
Remote Tag Providers and Tag History Splitters
If you are utilizing the Gateway Network features of the Ignition system and have the Seeq Ignition Module installed on a "central" gateway that accesses tags on a remote gateway via the Remote Tag Provider feature, Seeq can access data from such tags if the central gateway has a database connection to the historical data. If the name of the database connection on the central gateway is identical to the history provider that is defined for the remote tags, Seeq will automatically find the correct connection to use for historical data queries. Otherwise, errors will appear in Seeq Workbench when you attempt to access that tag data. You can rectify these errors by specifying a Database Mapping. For example, let's say you have a relatively complex topology involving Tag History Splitter providers. If you receive an error in Seeq like Datasource 'Splitter01' is not defined on this gateway, and you want Seeq to use a database connection called "Central_Historian" for any tags that are historized to the Splitter01 history provider, you can navigate to the SEEQ → Settings section of the Ignition Gateway and add a Database Mapping entry like so:
Splitter01 => Central_HistorianThis will inform Seeq to use the "Central_Historian" connection whenever it encounters a tag whose history provider is "Splitter01". You can add as many mappings as necessary, with each one on its own line.
Secondary (Read-Only) Databases
In some cases, you may have decided to replicate an Ignition SQL Tag Historian database to a secondary SQL database server so that you can isolate ad-hoc analytics activity to the secondary server. In many cases, SQL replication schemes require that the secondary database is read-only. During indexing, Seeq requires a writable connection to the historian so that it can manage Tag Fingerprints (below). You can make a Database Mapping entry like so:
Primary_Historian =>> Secondary_HistorianNotice the double arrows in the mapping syntax (in contrast to prior examples of database mappings). In this case, all historical queries (which are read-only in nature) that would normally be levied against Primary_Historian will now instead be issued against Secondary_Historian.
Tag Fingerprinting
Tag Fingerprinting is a feature that overcomes a limitation of Ignition whereby tag history is lost when a tag is renamed or moved in the hierarchy. The “OPC Item Path” for a tag (if present) is used as a unique identifier for tag history. Seeq creates a fingerprint column in the sqlth_te table of the SQL Tag Historian database and maintains cross-references between OPC Item Paths and Ignition Tag Paths. Wherever possible, this cross-reference is used to retrieve all history for an OPC Tag, regardless of where it lived in the Ignition tag hierarchy.
Tag Fingerprinting thus requires write access to the SQL Tag Historian database. If you cannot provide write access to the database, or you otherwise want to turn off the Tag Fingerprinting feature, uncheck the Tag Fingerprinting checkbox in the SEEQ → Settings section of the Ignition Gateway and click Save Changes. When the feature is turned off, tag history will be lost when tags are renamed or moved.
Property Transforms
You can use Property Transforms to make changes to tag properties as they are indexed by the Seeq Ignition Module. Follow the instructions in the Property Transforms article and put the transforms JSON in the Transforms field of the SEEQ → Settings section of the Ignition Gateway, but with an important difference from the article's examples: Exclude the Transforms: label. For example:
[
{
"Inputs": [
{
"Property": "Interpolation Method",
"Value": "linear"
}
],
"Outputs": [
{
"Property": "Interpolation Method",
"Value": "step"
}
]
}
]Property Transforms will not be applied until an indexing operation has completed.
Upgrading the Ignition Module
To ensure a smooth upgrade of Seeq and the Seeq Ignition module follow the below steps in order:
Disable all Seeq-Ignition gateway module(s); you do this by going to the Seeq - Settings menu and deselecting the 'Enabled' checkbox.
Upgrade the Seeq Server (install the upgrade AND let it start fully, i.e. to where you have the Seeq Login page available or the Launch Seeq UI shows "Server is running")
Upgrade the Seeq-Ignition Module
Enable the Module
Known Issues
There are no known issues for the Ignition Module connector. Please report any issues you find to our support portal.
Troubleshooting
Log Files
Troubleshooting information for the Seeq Ignition Module uses the Ignition logging system. It is accessed from the STATUS → DIAGNOSTICS → Logs section of the Ignition Gateway configuration interface.
In the Filter text box, enter com.seeq to limit output to only the Seeq Ignition Module and filter out Ignition Gateway logs and logs from other modules.
By default, the logs will include INFO level information. You can adjust the logging level by clicking on the Settings button (pictured above) in the Logs interface. In the resulting Log Configuration modal dialog, enter com.seeq in the Filter text box and set the com.seeq entry to the desired logging level. Setting the level this way will set all child packages to the same level and will save any changes made so they can be restored if the Seeq Ignition Module is restarted. This setting will also affect the logs that are available to be seen in the Seeq Logs viewer facility in Seeq. Close the dialog when all updates are complete.
You can download the logs to an .idb file and send them to Seeq personnel for further examination by clicking the Download Logs button (pictured to the left).
Unable to Connect to Server because of Corporate Firewall SSL Certificate Replacement
If you're connecting to a Cloud Server, such as Seeq SaaS, and you are seeing connection errors in the Ignition logs because the corporate firewall is doing SSL certificate replacement, you will need to add the certificate to the Java trust store for Ignition.
Open command prompt on the Ignition Server
Issue this command: cd "C:\Program Files\Inductive Automation\Ignition\lib\runtime\jre-win\bin"
For next command, replace "mycertificate.cer" with the path to your locally saved certificate. When prompted the default password is: changeit
Do: keytool -import -trustcacerts -file "mycertificate.cer" -alias sgServerCA -keystore "C:\Program Files\Inductive Automation\Ignition\lib\runtime\jre-win\lib\security\cacerts"
Restart the Seeq Module to establish the connection
Unable to Connect to Server When Seeq Is Using a Self-Signed Certificate
If you are seeing connection errors in the Ignition logs when using a self-signed certificate on the Seeq server, you will need to add the Seeq server certificate to the Java trust store on the Ignition server.
Open command prompt on the Ignition Server
Issue this command: cd "c:\Program Files\Inductive Automation\Ignition\lib\runtime\jre-win\bin"
For next command, replace "mycertificate.cer" with the path to your locally saved certificate. When prompted the default password is: changeit
Do: keytool -import -trustcacerts -file "mycertificate.cer" -alias sgServerCA -keystore "C:\Program Files\Inductive Automation\Ignition\lib\runtime\jre-win\lib\security\cacerts"
Restart the Seeq Module to establish the connection.
For Ignition on RHEL, the cacerts location defaults to: /opt/ignition/lib/runtime/jre-nix/lib/security/cacerts
If cacerts is not located in these locations in your environment, please contact your systems administrator or Inductive Automation support.
Ignition Gateway Failover
The Ignition module is designed to support failover from a master gateway to a backup gateway. On Ignition v7, requesting a failover from a backup gateway causes the master gateway to enter the state “Activity level=Cold” as seen in the System Events log of the Status > Systems Redundancy page. However, on v8, requesting failover has been observed to leave both the master and the backup in a state of “Activity level=Active”, and this can sometimes lead to the Seeq server sending data requests to the master instead of the backup gateway. If this occurs, restarting the Seeq module in Configuration > Systems > Modules should resolve the issue. This should only happen once - if the Seeq module needs to be restarted more than once following a failover, please contact Seeq support. On either v7 or v8, a failover that occurs as a result of the master gateway service being stopped leads to complete transfer of module responsibility to the backup gateway. In the Seeq Administration Datasources tab, Ignition Gateway datasources will show a connected connection to any gateways with “Activity level=Active” and a disconnected connection to any backup gateways that have ever entered an “Activity level=Active” state long enough for a connection to Seeq to be established. This will appear similar to the following in the Datasources tab:
Tags Not Appearing in Seeq
If a tag does not appear in the Seeq asset hierarchy or when you perform a search on the Data tab, here are some possible reasons why:
The tag is not historized. Seeq can only make use of tags that have been configured to utilize a Tag History Provider to store historical values. It will ignore tags that are not historized. You can tell if a tag is historized because it will have a scroll icon to the right of it in the Ignition Designer's Tag Browser pane.
The tag provider is being filtered out. Administrators can configure the Seeq Ignition Module to only index certain providers, so a tag may be ignored due to that configuration setting.
You’re accidentally searching for or looking at the wrong tag, or have input the tag name incorrectly into Seeq. Confirm that there is no tag name mix-up and that the tags missing in Seeq have the history as the other tags.
You're trying to index tags on a remote tag provider running Ignition v7.x and a gateway running Ignition 8.0.x. Kindly upgrade the gateway to Ignition 8.1.x+.
You're trying to index tags on a remote tag provider running Ignition v8.x and a gateway running Ignition v7.x. Seeq Ignition Module 7 running on the Ignition gateway 7.x won’t be able to read the tags provided by Ignition 8.x remote tag provider. Kindly upgrade the gateway to Ignition 8.1.x+.
Duplicated Tags
You may encounter a situation where you have accidentally duplicated an Ignition asset tree in Seeq. The problem is usually because a new Ignition Gateway has been set up, perhaps as a development or backup gateway, or perhaps you are just moving things around in your Gateway Network. You have to be careful to retain the same Datasource ID within SEEQ → Settings on the new gateway in order to avoid duplication and maintain appropriate linkages for the various worksheets that are using the tags.
In order to recover from accidental duplication, first fix the Datasource ID such that it is correct: You will likely just need to copy the Datasource ID from one instance of the Seeq Ignition Module's settings to the other. Make sure the Ignition Module in the "old" gateway is disabled, and test to make sure tag data can be called up in Seeq from the new gateway. Then, to remove the duplication, follow Removing a Datasource -- being careful to use the Datasource ID that does not match the accurate Datasource ID (but may have the same Datasource Name).
If you are running into other issues with connecting to or access data from Ignition, view our guide for troubleshooting datasource issues.
Performance considerations
The speed with which data is retrieved from the Ignition SQL Tags Historian can be greatly affected by a couple of Ignition configuration items as described in the following sections.
Data Partition Size
Ignition will split historical data into separate tables according to the Partition Length and Units specified for the Tag History Provider. You will want to choose a partition size that results in about 20 million rows. If the row count is larger, it will take a long time to traverse the index for the table and produce the historical data for a particular tag and time range. See Data Partitioning and Pruning in the Ignition documentation for more information.
Default Transaction Isolation Level
A database connection within Ignition can be queried by many simultaneous requests from an application like Seeq. It is important to use the minimum necessary transaction isolation level so that simultaneous queries are minimizing the amount of time they are blocking each other from progressing. In Ignition's Connection Initialization parameters for the database connection (under the Advanced Properties checkbox), set the Default Transaction Isolation Level to Read Uncommitted.
Max Concurrent Requests
By default, the Seeq Ignition Module will process 2 historical queries simultaneously. Other requests will queue up and be processed as others finish.
You can choose to increase the Max Concurrent Requests parameter in SEEQ → Settings to improve overall responsiveness within Seeq Workbench, especially when users have several signals onscreen. However, each database connection in the Ignition Gateway has "connection pooling" and is configured (under the Advanced Properties for the connection) to have Max Active connections in the pool. If all of the connections in the pool are used, Ignition may struggle to write data to the historian and perform other duties. Therefore, it is critical that Seeq's Max Concurrent Requests is smaller than the smallest Max Active value set on any database connection on the gateway. For example, if the smallest Max Active value is 8 (which happens to be the default), you should probably not allow Seeq to utilize more than 4 connections, and therefore Max Concurrent Requests should be set to 4 (at most). If you can increase Max Active to something larger, you can increase Seeq's Max Concurrent Requests by a commensurate amount.
Additionally, view our guide on optimizing datasource performance for general guidance.