Breaking Changes in v24

Please read the following before upgrading to v24 to view the breaking changes that are occurring. Some services have been removed while new services have been added. As such, the configuration for certain aspects of the software have been moved within the Canary Admin client, mainly those concerning security which is now handled by the new Identity service.

The software must be running v23.2.1 prior to upgrading to v24.

Supported OS

V24 is compatible with Windows Server 2019/Windows 10 (1903) and later.

Retired Products

The following components are not compatible with v24.

• Mirror service - If using the Mirror service, we recommend using a Collector to log data to the Mirror Historian prior to upgrading.
• HDA server - The Read API, ODBC Connector, and Publisher service are the supported methods for extracting data from the Historian.
• Trend Link - Axiom is the supported reporting application.
• Central Admin - Not to be confused with the Canary Admin, the Central Admin was used to configure the Device Collector for Modbus, Allen Bradley, and Siemens devices. Please contact support@canarylabs.com to learn about a path forward before upgrading.

Endpoints

Several unsecured endpoints have been removed for the Historian (55281), Views (55231, 55235), and Axiom (80). New endpoints have been added to accommodate new services that may need allowed in the firewall. For a complete list of the endpoints that Canary uses for interoperability, see Canary Endpoints/Ports.

New Services

• Identity
  The Identity service acts as the single point of authentication and authorization for all Canary clients. As such, the access control lists for ALL Canary services are found within the Identity tile>Security>Access Control Lists screen.
  
  Prior to v24, Canary used Windows AD for user authentication. You will now have the option of choosing other identity providers (IDP) as the Identity service supports OAuth2.0/OpenID Connect. The user will be prompted with a new login screen when using Axiom, Excel, or the Canary Admin. See https://helpcenter.canarylabs.com/category/identity-v24 for more information on the Identity service.

• Store and Forward (SaF)
  The SaF service is the new method of logging data from a Collector to the Historian. The Sender and Receiver services are still included for backwards compatibility, but any Collector server running v24 software will use SaF. When upgrading your Historian server, be sure to include the Receiver service along with SaF so that data will continue to flow through the system. Once all Sender services have been updated to use the new SaF service, the Receiver service will no longer be needed on the Historian server. For more information on the SaF service, see Store and Forward.
  
  A proxy server will need to be reconfigured to use the new SaF service when upgrading to v24. See How to Configure a Proxy Server.
   
• Licensing
  When upgrading to v24, a new license will need to be issued as the old license is no longer compatible. With the new Licensing service, licenses can be pushed back to Canary's License Web Portal to be used on another server. See How to Transfer a License for more details.
  
  New licenses come with a Max Version Year property. This property controls which versions of the software the license is compatible with. When renewing a subscription or customer care, a new license is issued which will increase this Max Version Year. If a user tries to upgrade their system to a version that exceeds the Max Version Year, a warning will be thrown in the installation process. See Versioning and License Compatibility for more details.
  
  A Views license is now available which includes the 25 API licenses and any Excel Add-in clients that have been purchased.

Historian

• Database Files
  The new Historian will create .hdb3 files which are not compatible with older versions. Old .hdb2 files will remain untouched unless they need to be recovered for some reason, at which point, they will be converted to .hdb3 files.
   
• Remote Historian View
  If the Historian was configured to use the secure gRPC endpoint (55282) to allow a remote Views service to connect, the Access list will need to be reconfigured in the Identity tile>Security>Access Control Lists screen under the Historian>Access ACL. See How to Add a Remote Historian View.

Views

• External Properties are now configured in the Views tile>Configuration>Settings screen.
• Views Security is now located in Identity tile>Security>Tag Security. A single Identity service is used to connect to other Views services on the network to configure their Tag Security.
• If there is a local Historian view with a name other than the DNS hostname of the computer, its name will change to the DNS hostname in v24. There may be Axiom apps, calculations, etc. that reference the old name and need to be updated.

Axiom

• There is no longer an unsecure option (http) to connect to Axiom. All clients must connect and authenticate over https.
• Charts and Applications are combined into a single browse screen when opening a file. See Open File Menu.
• There are more granular ACL's for Axiom's features that include: scripting, saving to the Read Only folder, changing preferences for Everyone, using the Data Entry Control, and creating reports. These are modified in the Identity tile>Security>Access Control Lists screen. See a complete list of all ACL's here.
• Windows file and folder security is not currently supported for Axiom in v24.0. Previously, you could restrict access to files and folders through Windows (Setting File/Folder Permissions in Axiom - Version 23). This functionality will be available in a future release.
• If the Axiom service is installed remotely from the Identity service, it must be configured to use an API token for running Automated Reports.

Calculations

• Calculations will use a single SaF session per destination to write its data to a Historian. Prior to v24, each calculation used its own Sender session.
• Removing old data and rebackfilling works differently in that the tag is not obsoleted. The range of data is deleted and new data is inserted. Any data residing before the backfill time will remain intact. Calcs are only obsoleted when removing the calculation itself.

API's

• .NET API
  A new .NET api has been introduced in v24 which uses gRPC. The previous .NET api used WCF and is not compatible with v24. Please visit our GitHub page (https://github.com/CanaryLabs/SampleCode/tree/master/Samples/V24) to see an example of data retrieval and data storage using the new .NET api.
   
• Web Read API
  The web Read API is backwards compatible if making a secure connection over https (55236). It is recommended that the client use an apiToken (equivalent to an accessToken in v23) in the request for authentication. This allows the user to bypass the /getUserToken request. (See How to Create an API Token.) If the client is passing in credentials to get a userToken, the user must be linked to a Canary user. This functionality is only supported if using Windows AD as an identity provider in the Identity service.
  
  The anonymous http (55235) connection is no longer available. All web Read api connections must go through the secure endpoint.
  
  See Using the Read API for more information.
   
• Web Write API
  The web Write API is backwards compatible if using the Sender service, although it is recommended to update the client to use the new Store and Forward service. The new SaF api uses apiTokens, similar to the Read API.
  The following settings are no longer supported when requesting a Session token:
  • fileSize
  • packetSize
  • packetDelay
  • packetZip
  • receiverPort
  • trackErrors
  • supressInfoMessages
  • supressTimestampErrors
  See Using the Write API for more information.
   
• ViewsWebAPICallLog
  If using the ViewsWebAPICallLog, the config file will need moved to C:\ProgramData\Canary\Log\Profiling.

ODBC

Any ODBC clients that are configured to connect securely will need to be reconfigured using an API token. See Installing the ODBC Client. By default, the ODBC client makes an anonymous connection. In order for that to continue to work, the Anonymous identity provider option must be enabled within Identity tile>Configuration>Providers>External Provider Options. It is recommended to use an API token instead as enabling the Anonymous option opens up the anonymous logon for other components of the Canary system such as Axiom, Excel, and the Canary Admin.

Tag Security

Views security has been moved to the Identity tile>Security>Tag Security screen. Prior to v24, it was primarily used for restricting read access. With v24, it also controls write access. If Tag Security is enabled, remote Canary Collectors must be configured with an API token and given Write permissions to the local Historian view. See How to Configure a Remote Collector when Tag Security is Enabled.