Seeq Server / Workbench R22.0.48.01

Welcome to Seeq! If you have any feedback or support questions, please email our support team at [email protected].

For each user that accesses the Seeq Workbench for the first time, a fully interactive tour will present itself to assist the user in learning how to use our software. The tour can be dismissed and accessed later via the system menu in the upper-right corner of Seeq Workbench.

Upgrade Considerations

CSV 2.0

As of version R22.0.48, CSV capabilities have been overhauled. As part of that, the CSVREAD varation of the query operator is no longer available. Any script using CSVREAD will need to use the CSV import tool or Datafile REST API instead.

Signals and conditions imported in prior versions of Seeq will be migrated from CSV V1 to V2 in the background during the first few hours that Seeq server is running after the upgrade. During this time, these items may be unavailable. The migration is complete when there is no new activity in appserver-async-upgrade.log.

Locally Constant Metadata

As of version R22.0.48, validation was added to enforce that formulas that manipulate metadata must not compute the metadata using other data. Formulas that were doing this will no longer be valid. See the Knowledge Base for more information and suggestions to correct broken formulas.

Topic Document HTML Changes

As of version R22.0.48, the topic document HTML for Seeq content now contain an additional `data-seeq-scale` attribute. Any custom tooling for updating topic document content will need to be updated to take this attribute into account.

AF Event Frames Connector

Starting with release R22.0.48.00, the AF Event Frames Connector is included as a licensed component in the Seeq Server installer. If you have an existing version of the connector in your data folder, it should be removed to avoid connector loading issues. Please contact your account manager to get an updated license that includes this component.

AF Data Reference Plugin

Starting with release R22.0.48.00, the AF Data Reference Plugin is included as a licensed component in the Seeq Server installer. If you have an existing version of the plugin on your AF server, it should be removed to avoid compatibility issues. Please contact your account manager to get an updated license that includes this component.

Third party web application security changes

In R22.0.47.02 and later some changes may be required in existing third-party web applications that make calls to the Seeq server and/or embed Seeq in an iframe. The following changes may be required:

• The seeq server must be secure (i.e. https).
• The CSRF token returned in the login x-sq-csrf response header must be supplied in an x-sq-csrf request header in subsequent calls to the Seeq server.
• The library used for http requests (e.g. $http, axios, etc.) may need to enable withCredentials (e.g. withCredentials: true) on requests to Seeq if with credentials is not already enabled.

For more information, see Embedding Seeq in Frames

Export Visibility

As of version R22.0.47, Exports are a publicly-available type. Existing exports can be viewed and managed from the Administration Page. The related API endpoints have changed.

REST API: POST /items/export or ItemsApi#exportItems() has been moved to POST /export or ExportApi#createExport(). The inputs have not changed.

REST API: Exports can be searched for by using GET /items. They can be queried using GET /export and GET /export/{id}. They can be modified using POST /items/export/{id}. Finally, they can be archived using DELETE /items/export/{id} and DELETE /items/export/cleanup.

Features/Rendering/Topics/PoolSize and Threads/Jobs/User/Count

After upgrading from a relaese before R22.0.46.07, the configured setting for Features/Rendering/Topics/PoolSize and Threads/Jobs/User/Count (if any) are reset to their default settings. The role of these parameters in relationship to the performance of the system has changed; the system will need to be re-tuned if needed.

AF Security

Starting with release R22.0.46.01, AF Connector allows synchronization of security for AF Elements and AF Attributes not referencing PIPoints. To use this functionality at least PI AF Client 2017 (AFSDK 2.9) is required.

For synchronizing the security of AF Attributes referencing PIPoints, PI Connector needs to be configured to synchronize PI Identities.

Centralized Configuration

As of version R22.0.46, Seeq has a centralized configuration system that is exposed to administrators through the Seeq CLI and a new 'Configuration' tab in the administration interface. All relevant Knowledge Base articles have been updated to give directions for the new configuration system as well as the previous system.

Highlights

• System REST API: The /system/configuration REST API endpoint has been modified significantly to accommodate many more options than the handful it previously exposed.
• Seeq CLI: The configuration commands available in the Seeq CLI have changed format slightly to accommodate the increase in functionality. Please see the Knowledge Base article or the command's built-in help for more information.
• Configuration.xml: This file no longer supports customization, and will no longer honor the version that may exist in the data directory. If your Seeq installation has a custom configuration.xml in the Seeq data directory, please contact Seeq personnel for migration assistance.
• Global.properties: Many configuration options have migrated from the global to data directory scope, or vice versa. If you migrate data directories from one server to another, please contact Seeq personnel if the migration appears affected by a configuration issue.
• Default values: Default values for some configuration options changed, including memory allocations for Seeq subsystems. The default value and the value currently in effect are visible in the 'Configuration' tab of the administration user interface.

OPC-UA Connector for Siemens PCS 7 Process Historian

The method of indexing signals in PCS 7 Process Historian (PH) has changed in order to avoid duplicate data. Some Siemens systems involve redundant hardware. The PH OPC-UA server stores the data collected by this redundant hardware as unique signals (PH Tags), which resulted in multiple signals with the same data but different Data Ids appearing in Seeq. PH provides a workaround in the form of PH Virtual Tags, which collect redundant PH Tags. The OPC-UA connector will now index both PH Virtual Tags and non-redundant PH Tags as signals.

When upgrading to R22.0.46, users should be aware that existing redundant signals will be archived. New signals (from PH Virtual Tags) will appear in Seeq with the same names as the old signals (from PH Tags); workbooks will need to be updated to reference the new signals.

Integrated Security

Seeq's access control has changed significantly in R22.0.45 and now supports nearly every type of item. In previous versions of Seeq, access control was limited to only Analyses, Topics, and Folders.

When upgrading to R22.0.45, all Seeq users are granted read and write permission to all globally scoped assets, conditions, scalars, and signals. Permissions for conditions that are scoped to a workbook will be automatically inherited from their parent workbook. Permissions for nested folders and workbooks will be automatically inherited from their parent folder and will add to any local permissions that were already configured.

After upgrading to R22.0.45, user groups in Seeq can be automatically synchronized with Windows Active Directory using the Windows Auth Connector and the LDAP Connector. Security settings in Seeq can be automatically synchronized with an OSIsoft PI server using the OSIsoft PI Connector and the OSIsoft AF Connector. These new automatic synchronization options are all disabled by default in order to preserve the effective permissions of all users in Seeq until if/when a Seeq administrator decides to enable these new security options.

The first indexing after enabling security synchronization in the PI Connector or AF Connector or using property transforms for security settings in other connectors is expected to take significantly longer than previous versions. Subsequent indexing could also take significantly longer than previous versions if a large number of permissions have changed since the last time indexing took place or if those permissions have changed on any assets with many children that inherit permissions.

Connectors and scripts that are not using their own datasource should be updated to do so. They will not be able to manage permissions on any items that are created in the default datasource.

Connectors SDK: R22.0.45.00 changes one method in the Connectors SDK.

External Calculation Python Scripts Upgrade

Seeq Server R21.0.44.03 and later is bundled with a new version of Python External Calculation plugin which improves the performance of scripts execution. Existing scripts are not expected to work until specific changes are made. These changes will result in new checksums, so formulas will have to be updated accordingly. The steps to update the scripts are described in "Upgrade scripts used in R21.0.44.03 and earlier" chapter from "data/plugins/external-calculation/python/readme.html"

.NET Upgrade

Seeq Server R21.0.44 and later will install .NET version 4.6.2, which may require a restart on some servers such as Windows Server 2012.

Python Upgraded

Seeq Server R21.0.44 and later is bundled with Python 3 instead of Python 2. Any scripts that are using Seeq's bundled Python interpreter may need to be upgraded to be compatible with Python 3.

Upgrade Timing

Upgrading Seeq Server to R22.0.48 from R22.0.47 will take roughly 3 hours per 10 million items in the Seeq database. If the Seeq database contains items imported from CSV files, the upgrade will take roughly an additional 5 minutes per 5 thousand of those items. To see how many items imported from CSV files are present in Seeq Server, run seeq db client and execute the following queries.

    select count(*) from items where type='CalculatedSignal' and properties->'Formula'->>'stringValue' LIKE '%CSVREAD%';
    select count(*) from items where type='CalculatedCondition' and properties->'Formula'->>'stringValue' LIKE '%CSVREAD%';
  

Upgrading Seeq Server to R22.0.48 from R22.0.46 will take roughly an additional 2.5 hours per 10 million items in all local Seeq datasources in the Seeq database.

Upgrading Seeq Server to R22.0.48 from R22.0.45 will take roughly an additional 1 hour per 10 million items in the Seeq database.

Upgrading Seeq Server to R22.0.48 from R21.0.44 or R21.0.43 will take roughly an additional 1 hour per 10 million items in the Seeq database.

Upgrading Seeq Server to R22.0.48 from R21.0.42 and earlier will take roughly an additional 1 hour per 20 million items in the Seeq database.

Run seeq db stats -v from the Seeq CLI to see how many items your server's database contains.

Disk Space

Upgrading Seeq Server to R22.0.45 or later from R21.0.44 and earlier requires approximately 12GB of extra disk space for every 10 million items in the Seeq database than previous versions of Seeq. Run seeq db stats -v from the Seeq CLI to see how many items your server's database contains.

Seeq Server R21.0.43.04 and later allocates more disk space (20GB) for the database cache than previous versions. Customers should ensure that the drive with the Seeq data folder has adequate free disk space to accommodate spikes in disk usage.

Ubuntu Installations

If you have configured Seeq to run as a service in Ubuntu following the instructions in the Seeq Knowledgebase, you must alter the ExecStart and ExecStop as follows:

    [Service]
    ExecStart=/opt/seeq/seeq-server/seeq start --from-service
    ExecStop=/opt/seeq/seeq-server/seeq stop
  

Best Practices

Before upgrading, it is recommended that you create a backup of your current Seeq Server. That way you can restore your application version, configuration and data files to known good if for some reason there is an issue with the upgrade. To create a backup, follow the instructions in the Backing Up the Seeq Database article in the Seeq Knowledge Base.

The Seeq Server database schema is upgraded automatically when a new version of Seeq Server first loads a data folder created by an older version of Seeq Server. The blue text at the bottom of the Seeq Server launch interface is intended to give insight into upgrade progress.

When upgrading, it is recommended that you update the Seeq Server and all Seeq Remote Agents at the same time. Each version of Seeq is tested as a whole and breaking changes between the Seeq Server and older Seeq Remote Agents are not tracked.

Changes to Conditions in R21.0.41

In Seeq R21.0.41, conditions have become more flexible, easier to use, and significantly faster for many use cases. In previous versions of Seeq, every condition required a "maximum duration", and this value was often required in tool panels and formula parameters. In Seeq R21, this value is now optional and only required as input when necessary.

Users will notice that conditions that previously had a large maximum duration (and calculations based on them) will be much faster without a maximum duration in R21. Tool panels and formula functions now guide the user to remove maximum duration if possible; for example, see the "Simple" mode in the Value Search tool. One other change is that capsules that extend beyond the view range may show up in the capsules pane as Start off-screen or End off-screen until the view range is extended to encompass the entire capsule.

Any new formulas or tools created in R21 will take advantage of the Conditions 2.0 improvements whenever possible. To see these same performance improvements in existing formulas, they may be updated by a user; please see the Knowledge Base article for details. The article also includes details on new formula functions, automatic formula migrations, changes to tools, and more.

Guest Account

R21.0.41 removes support for logging in as "guest". The account will be permanently disabled. If the guest login option was enabled before the upgrade the "Everyone" group will gain Full Control access to all items owned by the guest account. If you would like to avoid giving "Everyone" Full Control of guest items then disable guest access before upgrading Seeq. After the upgrade, the guest account can be removed using the Administration panel and a user can be assigned to take ownership of the items the guest account owned.

Formula Upgrades

Upon upgrade, Seeq Server will audit all formula-based series to determine if they compile correctly in the new version. If incompatibilities are detected, the Description of the affected item will contain the text Formula failed to compile, please upgrade manually. You can search for such items using the More filters link on the main item search interface.

R21 has several formula upgrades:

• The Stat and PositionInCapsule enumerations used in aggregate() have been replaced with functions. For example, Stat.Average is now average().

    // before
    $signal.aggregate(Stat.Average, $condition, PositionInCapsule.StartOfCapsule)
    // after
    $signal.aggregate(average(), $condition, startKey())
  

• A new runningAggregate function has been added. It outputs the running statistic within each capsule rather than the behavior of aggregate which outputs a single sample per capsule. The runningCount, runningSum, and integral functions have been modified so they work the same way as the more generic runningAggregate function, outputting invalid values instead of zero when capsules are not present and resetting at the beginning of each capsule.

• convertUnits('%') didn't properly scale the values. Existing usages have been migrated to setUnits('%')

Formula functions with the term 'series' have been updated to reflect new terminology. "capsuleSeries" is now "condition", "sampleSeries" is now "signal", and "toSeries" is now "toSignal". Upgrades to existing formulas will be made automatically.

If you need help upgrading a formula, do not hesitate to contact Seeq support.

Seeq API and Seeq SDKs

Applies to upgrades from all previous versions.

In R22.0.45, many APIs have been changed. Some usages will need to be updated.

In R21.0.44, changes to the C# bindings for the APIs may require existing applications / connectors to be rebuilt with R21.0.44 versions of our SDKs. If you see System.MissingMethodException exceptions at runtime, you will need to recompile.

In R21, the Items API's #searchItems function has been modified. The ceiling argument is no longer present and an optional asset argument has been added to allow searches to be limited to within an asset tree's scope. This means any custom code or custom connector using this API endpoint will need to be recompiled to work correctly with R21.

In R21, the Connectors API endpoint has been removed. The Agents endpoint or Datasources endpoint should be used instead.

Seeq Connector SDK

Applies to upgrades from all previous versions.

In R21.0.44, Seeq runs all Java connector code on the Java 11 platform instead of Java 8. Please make sure that any custom Java connectors are compatible with Java 11. This includes any Java dependencies such as libraries or database clients.

In R21, the Seeq Connector SDK has significantly revised the interfaces that are implemented by various flavors of connector. Take the following steps to upgrade your connector code (described using Java naming, but C# has equivalent changes):

1. Add a destroy() method to your Connector class. It can be empty.
2. Change your Connection class to implement the SignalPullDatasourceConnection interface.
3. Remove the getDatasourceServices() and getDatasourceFlow() methods/fields from your Connection class. They are no longer necessary in light of the new SignalPullDatasourceConnection interface.
4. Change the signature of getSamples() in your connection class to take the new GetSamplesParameters input structure. The fields of this structure contain all of the inputs that were previously passed in directly.

Embedding Seeq

In R21, embedding Seeq in dashboards or other web pages is no longer allowed by default. You can enable embedding by changing a configuration file, as described in the Seeq Knowledge Base article Embedding Seeq in Frames.

PI Display Digits

In R22.0.47, PI signals that have Display Digits configured will now have a corresponding Number Format item property assigned to them. Signals with a positive Display Digits will have a Number Format that truncates the digits to the right of the decimal place to the specified value. Signals with a negative Display Digits will have a Number Format that specifies the corresponding number of significant digits to display. These number formats only affect the display of numbers and do not affect calculations.

Change Notes

Version R22.0.48.01

Version R22.0.48.00

Version R22.0.47.03

Version R22.0.47.02

Version R22.0.47.01

Version R22.0.47.00

Version R22.0.46.08

Version R22.0.46.07

Version R22.0.46.06

Version R22.0.46.05

Version R22.0.46.04

Version R22.0.46.03

Version R22.0.46.02

Version R22.0.46.01

Version R22.0.46.00

Version R22.0.45.03

Version R22.0.45.02

Version R22.0.45.01

Version R22.0.45.00

Version R21.0.44.04

Version R21.0.44.03

Version R21.0.44.02

Version R21.0.44.01

Version R21.0.44.00

Version R21.0.43.09

Version R21.0.43.08

Version R21.0.43.07

Version R21.0.43.06

Version R21.0.43.05

Version R21.0.43.04

Version R21.0.43.03

Version R21.0.43.02

Version R21.0.43.01

Version R21.0.43.00

Version R21.0.42.10

Version R21.0.42.09

Version R21.0.42.08

Version R21.0.42.07

Version R21.0.42.06

Version R21.0.42.05

Version R21.0.42.04

Version R21.0.42.03

Version R21.0.42.02

Version R21.0.42.01

Version R21.0.42.00

Version R21.0.41.02

Version R21.0.41.01

Version R21.0.41.00

Version R21.0.40.07

Version R21.0.40.06

Version R21.0.40.05

Version R21.0.40.04

Version R21.0.40.03

Version R21.0.40.02

Version R21.0.40.01

Version R21.0.40.00