If you have already installed OAS you can update your system using the Manual or Automatic update method.
⚠️ You should take care not to delete the installation director or the Config directory containing your options, security and license data. These files can remain and your OAS product will remain activated.
In Windows, the configuration files are located in: C:\ProgramData\OpenAutomationSoftware\ConfigFiles,
In Linux, the configuration files are located in the Config directory of your OAS installation path.
Automatic Update
To upgrade an existing system open the Configure OAS application using “Run as Administrator: mode and then select the Configure > License menu and click on the Update Version button.
It is recommended that you first save your changes. It is also recommended to close all Internet Browser applications if you are using UIEngine.
⚠️ Note that the OAS Engine will be stopped during the update process.
The installation process will first confirm the version number and request your confirmation. Click Yes to proceed.
Do not close the Configure OAS application. A message will be displayed during download and installation. The Configure OAS application will close automatically.
You can verify your software version on any screen in the Configure OAS application.
Manual Update
First download the OAS Platform.
For Windows uninstall Open Automation Software in the Programs and Features settings menu of your Windows operating system. Once uninstalled run the new setup and start the OAS Services.
For Linux simply copy in the extracted files to the OAS Engine directory.
The Tags configuration screen in the Configure OAS application provides the following high level features:
Create, update and delete Tags and Tag Groups
View latest tag value, timestamp and quality
Write to a tag value
Configure tag alarm limits
Configure data route target
Configure tag Sparkplug B parameters
Advanced alarm acknowledgement and scheduling
Turn on tag statistics (Time On and Count and Tag Totals)
👉 To learn about Tag Groups and Tags check out the Tags Overview page 🔗
The Tags configuration screen lists all Tag Groups and Tags on the left hand tree menu. The main right hand side allows you to configure the Tag’s parameters.
Tag Groups and Tags List
The left hand side panel lists all of your tag groups and tags in a hierarchical tree menu. You can think of Tag Groups as folders and Tags are like files in a folder. You can organize your Tags into logical groups and design the data model that best fits the solution you are trying to create.
Tag Groups
The Tags Tag Group is the base or root Tag Group. You cannot delete or rename this Tag Group.
Add Tag Group
To add a Tag Group first select the root Tag Group or the Tag Group where you want to add a Tag Group. This will be the parent Tag Group or the new Tag Group. Either click on the ADD GROUP button or right click on the parent Tag Group and select Add Group. Provide a name in the dialog window that appears. The Tag Group name has to be unique within the parent Tag Group.
Delete Tag Group
To delete a Tag Group first select the Tag Group you want to delete. Make sure it is highlighted. Right click on the Tag Group name and select Delete Group or use the Delete key on your keyboard. Click Yes in the confirmation dialog to delete the Tag Group.
Rename/Duplicate Tag Group
To rename a Tag Group you can use the Duplicate function. This will create a new Tag Group with the new name and same Tag structure. The duplicate Tag Group will be created at the same level in the hierarchy as the Tag Group being copied.
You can also use this to copy an existing Tag structure and create a new copy of it. This is useful when you have a particular data model and you want to re-use the same Tag structure in a new copy.
Tags
Tags are contained in Tag Groups. You can organize your Tags into as many different Tag Groups as you want, including in the root Tag Group, to create an appropriate representation of your data or process.
Add Tag
To add a Tag select the Tag Group in which you want to create the Tag. This can also be the root Tags Tag Group. It is often best to first create your Tag Group structure. Once your Tag Group is selected, either click on the ADD TAG button or right click on the Tag Group and select Add Tag from the context menu. Provide a name in the dialog window that appears.
Delete Tag
To delete a Tag first select the Tag Group you want to delete. Make sure it is highlighted. Right click on the Tag Group name and select Delete Group or use the Delete key on your keyboard. Click Yes in the confirmation dialog to delete the Tag Group.
Duplicate Tag
To duplicate a Tag you can use the Duplicate function. This will create a new Tag with a new name and copy all of the properties from the original Tag. The duplicate Tag will be created in the same Tag Group as the original Tag.
Rename Tag
To rename a Tag first select the Tag and make sure it is highlighted. Edit the Tag name in the Tag Name field and then click on the Apply Changes button or press the Enter key on your keyboard. Click Yes in the dialog window to confirm the update.
The Configure OAS application is the primary configuration tool for configuring the OAS platform. It can be used to configure both locally installed and remote OAS instances as long as the remote instance is reachable via a network from the host where Configure OAS is used.
Currently, Configure OAS can only run on a Windows host, however you can use it to configure any OAS instance running on Windows or Linux, as well as Docker or Raspberry Pi.
In this guide you will learn about the Configure OAS application’s main features and screens.
Installation
Configure OAS is installed by default when you install the OAS platform on a Windows host.
Custom Installation
You can also install the Configure OAS application without installing the main OAS services. This can be useful if you have a configuration or maintenance server that users will use to configure remote OAS instances. This is especially useful if you have Linux or Docker installations and you need to configure them using Configure OAS. To achieve this, make sure you select a Custom installation type when installing OAS.
In this example we will only install the Configure OAS application and the Trend and Alarms Dashboard. Both of these applications can connect to remote OAS instances.
Starting Configure OAS
The Configure OAS application can be started from the Windows start menu. You can find it there by searching for Configure OAS or by locating it in the Open Automation Software start menu folder. The icon will look similar to this example.
Local and Remote Configuration
Because the Configure OAS application is a stand-alone application, it can be used to configure any running OAS instance that can be reached either locally on the same host or on the network where the Configure OAS application is installed. If you are connected to the internet, it can even access any publicly accessible OAS instance host as long as you have the IP address or the host name and the OAS services are exposed.
During login and within the OAS instance you have the option to select the Network Node that you want to connect to. The term Network Node simply means the IP or hostname of the local or remote OAS instance that you wish to configure.
In the login dialog window you can provide a Network Node:
When you open a configuration screen, you can also set the Network Node you want to access:
Note that once you login, those credentials will be used for all configuration actions with an OAS instance. This assumes that you have the same username and password configuration on all your network nodes, otherwise you’ll have to login with different credentials and then update the network node.
Main Window
When you launch the Configure OAS application you will see a toolbar and a blank surface below this.
Logged Out State
By default, the Configure OAS application is in a logged out state with no configuration screens open.
Here is an overview of the menu items:
Menu Item
Description
File
Use the File > Exit menu item to close the application.
Configure
Access to the configuration screens.
Log In
Login as an authenticated user.
Theme
Select a light or dark theme.
Accent
Select the theme accent.
Help
Access further help and resources.
Login
When you access a configuration screen in the Configure menu, Configure OAS will ask you to login. If you have installed OAS for the first time you will be asked to set up a new Admin account password. This will give you full access to Configure OAS. If you are logging in to an existing OAS instance you can use whichever user accounts you have configured for the instance you are configuring. This will depend on your security configuration.
If you have security configured where the Default security group has been restricted and you cancel the login, the configuration screen will still load, but you will see error messages.
Logged In State
After you login, you will see the username that you used to login appear in the toolbar and the Log In menu item will now say Log Off.
Configuration Screens
The Configure OAS configuration screens allow you to configure all of the various OAS platform features. You can access each screen by selecting the screen name from the Configure menu. This menu is organized by OAS features.
Here is a list of available screens and associated Knowledge Base links to help you find more specific information:
You can use this setting to automatically clear and acknowledge Hi and Lo alarms if a HiHi or LoLo alarm occurs respectively. These two set-points are independent so you can use either one or both together. However, note that a Lo or LoLo cannot be cleared by a Hi or HiHi and vice versa.
If you have a Lo and a LoLo alarm threshold configured, then the Lo alarm will be cleared and acknowledged once a LoLo alarm occurs.
Similarly, if you have a Hi and a HiHi alarm threshold configured, then the Hi alarm will be cleared and acknowledged once a HiHi alarm occurs.
You can use all four setpoints if you like, the only thing to note is that if a LoLo occurs and after some time a Hi and then a HiHi occurs, the LoLo will not clear automatically. Similarly, if a HiHi occurs and after some time a Lo and then a LoLo occurs, the HiHi will not clear automatically.
This setting allows you to escalate your alarms without polluting the alarm screen with both alarm setpoints.
Default: Disabled
Keep Alarms when Disabled and Normal and Not Acknowledged
When this setting is disabled, an active alarm will be cleared and acknowledged if the alarm setpoint is disabled.
When this setting is enabled, an active alarm will be cleared, but not acknowledged if the alarm setpoint is disabled.
You can use this to ensure any active alarms cannot vanish from your alarm visualisations if the alarm is disabled for whatever reason. For example, you might disable alarms when you do maintenance to prevent any new alarms, but you don’t want to automatically acknowledge any alarms that were already active.
Default: Disabled
Update Alarm Status Immediately without Alarm Time Delay
Every Tag has a boolean AlarmActive property for each alarm threshold type to indicate whether the alarm is active or not. If the relevant AlarmActive parameter is True it means that the alarm is active.
The following alarm status parameters are available:
HighHighAlarmActive
HighAlarmActive
LowAlarmActive
LowLowAlarmActive
DigitalAlarmActive
ROCAlarmActive
When this setting is disabled, the relevant AlarmActive property will only become True once the alarm delay has expired.
When this setting is enabled, the relevant AlarmActive property will become True as soon as the alarm threshold is met.
This setting is useful if you want to know if an alarm threshold has been met irrespective of the delay or if are using calculation tags where you want to know if a particular alarm setpoint has been reached so you can immediately trigger another condition.
Default: Enabled
Set Alarm Date and Time with Time Delay
This setting relates to the alarm timestamp of real-time alarms and whether it includes the alarm delay or not. This impacts alarm timestamps in real-time alarm data tables, alarm visualizations and alarm logging history.
When this setting is disabled, the alarm timestamp is set to the timestamp of when an alarm limit is reached and does not include the delay.
When this setting is enabled, the alarm timestamp is set to the timestamp of when the alarm limit is reached and the alarm delay expires.
Default: Disabled
Retain All Realtime Alarms to Show All Occurrences in Window
When this setting is disabled each instance of an alarm for a particular tag alarm limit will replace the previous alarm instance if it is still unacknowledged.
Let’s say you have a Digital alarm limit configured on one of your tags. When this alarm occurs, the alarm will be displayed on the alarm screen. Once it clears it will be shown as cleared and unacknowledged. When this alarm occurs again, OAS will remove the previous alarm from the real-time alarms and display the new alarm instead. The old alarm will remain unacknowledged in the database if you have alarm logging enabled.
With this setting disabled only the most recent alarm instance will be shown. In terms of alarm logging, it will still log each alarm instance assuming you have the relevant filters configured.
When this setting is enabled each alarm instance will be retained in the real-time alarm screen.
Let’s say you have a Digital alarm limit configured on one of your tags. When this alarm occurs, the alarm will be displayed on the alarm screen. Once it clears it will be shown as cleared and unacknowledged. When this alarm occurs again, a second alarm instance will be added to the real-time alarms. Previous alarms will only be removed from the screen if you acknowledge the alarm (and your alarm filters are not configured to show inactive and acknowledged alarms.)
This setting allows you to display every instance of an alarm to your operators rather than just the most recent instance. This is an important feature if you require all alarm instances to be acknowledged even if already cleared.
Note that since alarms will never be removed from the real-time alarms table you will need to make sure your OAS host has sufficient memory to deal with the number of expected alarms over time. It is a good idea to use the Remove Old Alarms from Realtime Alarms option to automatically clean out old alarms based on an expiration time.
Default: Disabled
Remove Old Alarms from Realtime Alarms
Removes cleared and acknowledged alarms from real-time alarms when the alarm date and time is older than the given number of hours.
This setting is used together with the Retain All Realtime Alarms to Show All Occurrences in Window feature to ensure memory consumption does not grow beyond a manageable amount.
⚠️ Warning: This feature will remove alarms older than the configured number of hours irrespective of the state, including active and unacknowledged alarms.
Default: 0 hours
Delay Alarm Logging and Notification on Startup
When enabled, this feature ignores alarm limits when OAS first enters runtime mode until the given number seconds elapses.
This setting is useful for allowing your system to reach a steady state before monitoring your alarm limits. This can be useful for things like taking into account device first time connection delays, waiting for external services to start and waiting for the first data poll.
Default: 0 seconds
Remove Carriage Return and Line Feed from Alarm Text
Each Tag alarm limit has the option to create alarm text from dynamic sources. In cases where the alarm text contains carriage return or line feed characters, for example due to the constraints of an external system, this feature can be enabled to remove those characters and ensure your alarm screen and text is not impacted.
Default: Disabled
Enable Writes as Operator Events
This setting can be used to create a log of all write events performed by operators in OAS UI Engine, Windows Forms, WPF and Web controls using the real-time and alarm logging features. When this setting is enabled, any writes to a Tag value will be logged in real-time alarms as an Operator Event alarm type and group.
The operator’s username and the value written will also be logged.
This setting is useful for change auditing. You can use alarm logging with alarm filters to only log Operator Event alarms to keep the operator events separate from normal alarm logging.
Default: Disabled
Remove Cleared Alarms with Comment Containing
This setting allows you to remove an alarm from the real-time alarm screen when a comment is added and the comment contains the string configured in this setting. A comment can be added whilst the alarm still still active, but the alarm will only be removed once the alarm clears.
It is important to note that the alarm will be removed from the real-time alarms, but no acknowledgement state or timestamp will be logged in the alarm history.
Default: Empty string
Redundant Remote Services to Ack Alarms
This setting allows you to specify the alarms that will be acknowledged on a remote redundant OAS instance when alarm are acknowledged on the instance you are configuring. This is useful when you have more than one OAS instance acting as a redundant instance and when an alarm is acknowledged on a primary instance, your redundant instances will also acknowledge the alarm.
This setting is configured by specifying all of the host names or IP addresses of the remote OAS instances where you want alarms to be acknowledged.
Default: Empty list
Common
CSV Export Delimiter
This setting allows you to specify the delimiter that is used when exporting or importing configuration data using CSV files in the Configure OAS application or using an API call.
Default: ,
Array Delimiter
This setting allows you to specify the delimiter that is used when parsing arrays from string values.
Default: ,
Data Log
Override All Data Log Servers
This setting is a global override for the data logging host name or IP address for all data logging groups. When enabled, the server host or IP address specified in the Database Server Name setting will be used for all data logging groups.
Default: Disabled
Database Server Name
This setting defines the server host or IP address for the Override All Data Log Servers setting.
This setting is only visible if the Override All Data Log Servers setting is enabled.
Default: localhost
Maximum Connections / Database
This is the maximum number of Database connections that data logging will use for data logging groups that are using the same database server and authentication. For example, with a value of 10 if there are 30 data logging groups that are all using the same database engine and authentication for a connection, there will be 10 connections made to the database engine with 3 logging groups assigned to each connection.
Default: 10
Data Route
Allow Write to Bad Quality Targets
When disabled writes will not occur to tags with bad data quality. Required for MQTT, Sparkplug B, and AWS.
Default: Enabled
Include Quality with Writes to OPC
Include the OPC Quality in writes to Classic OPC Servers.
Default: Disabled
Write Frequency When Bad Quality
he frequency to write values when the destination data quality is bad.
Default: 10 seconds
Default Files
OAS configuration data is distributed across a number of different files depending on the feature being configured. The Default Files screen allows you to enable or disable automatic loading of configuration files when the OAS service is started. Each feature configuration file path can be independently configured.
Configuration files can only be loaded from a fixed configuration folder. On Windows, it is the C:\ProgramData\OpenAutomationSoftware\ConfigFiles directory. On Linux, default configuration files must be stored in the ConfigFiles folder relative to the OAS installation.
The following default configuration file paths can be specified:
Tag Configuration
Data Logging Configuration
Alarm Logging Configuration
Alarm Notification Configuration
Report Configuration
Data Route Configuration
UDP Broadcast Configuration
UDP Receive Configuration
Live Data Cloud Configuration
A&E OPC Servers Configuration
Default: Tag Configuration – “\DemoFiles\DemoTags.Tags” Alarm Notification Configuration – “\DemoFiles\DemoAlarms.AlarmNotification”
Drivers
Use TimeStamp from Controllers
This setting controls whether to use the timestamp provided by Allen Bradley and Siemens controllers when reading tag values or whether to use the OAS host time.
When this setting is enabled, OAS will use the timestamp provided by the controller when updating a Tag value.
When this setting disabled, OAS will use the current date/time of the host machine.
Default: Enabled
Maximum Driver Threads
This setting defines the maximum number of threads that OAS can use for driver interfaces. This value will depend on available system resources.
Default: 100
Reset Interface on Channel Error
Reset the driver interface on a channel failure when the Driver type is AB Logix, AB Classic, or Siemens.
Default: Disabled
Reset Interface on Device Error
Reset the driver interface on a device failure when the Driver type is AB Logix, AB Classic, or Siemens.
Default: Disabled
Retry Connection Time After Error
The time delay after a channel or device error for AB Logix AB Classic and Siemens.
Default: 60 seconds
Siemens Optimized Polling
Can be disabled to isolate invalid addresses in Siemens Tags. Leave enabled for fastest performance in production.
Default: Enabled
File Data Source
Alarm Group for Errors
The Alarm Group to assign to alarm instances for errors when an error occurs with saving or loading a value to the file.
Default: FileDataSource
History
Enable History Date Format
This property is required when the database engine language is set to something different than the operating system regional language setting.
When enabled, the date time format must be specified. The default format is “yyyy-MM-dd HH:mm:ss”.
Default: Disabled
Maximum Web Alarm Records
The maximum number of alarm history records to return to a web client request.
Default: 100
Live Data Cloud
Disable Live Data Cloud
This property will restrict what remote OAS Engines can self host through this service. When enabled only the specific Live Data Cloud nodes that are added to the Allowed List will be able to self host through this service.
Default: Disabled
MQTT Broker
OAS MQTT Broker ID
The ID of the OAS MQTT broker.
Default: OAS
OAS MQTT Broker Port
This setting defines the port on which the MQTT broker will listen for connections that do not use encrypted connections.
Default: 1883
OAS MQTT Broker SSL Port
This setting defines the port on which the MQTT broker will listen for connections that use encrypted connections.
When this setting is enabled, the OAS MQTT Broker Enable SSL setting should be used to specify the SSL configuration.
Default: 8883
OAS MQTT Broker Enable SSL
Enable encryption over SSL using the private key specified in the MQTT Private Key File setting and the private key password specified in the MQTT Private Key Password setting.
Default: Disabled
MQTT Private Key File
This setting is only visible if OAS MQTT Broker Enable SSL is enabled.
Default: Empty string
MQTT Private Key Password
This setting is only visible if OAS MQTT Broker Enable SSL is enabled.
Default: Empty string
MQTT Client Username
The username for the OAS MQTT broker.
Default: Empty string
MQTT Client Password
The password for the OAS MQTT broker.
Default: Empty string
Topic Aliases
Provides a way to map topic names to a tag names. Only required if the MQTT client cannot adjust topic names to match tag names.
Default: Empty list
Networking
Primary Port Number
The primary TCP port number that is used for service to service communications and client to service communications for this service.
Default: 58727
Backup Port Number
The backup TCP port number that is used for service to service communications and client to service communications for this service.
Default: 58737
Enable Classic TCP (Unsecure)
Enable this property if the remote services or applications are using the classic OAS TCP interface.
Default: Disabled
OAS OPC UA Server Port
The port number that is used for the Open Automation Software OPC UA Server.
Default: 58728
REST API and Web Port Number
The port number that is used for REST API and Web interfaces.
Default: 58725
REST API and Web Use SSL
Use SSL for REST API and Web interfaces.
Default: Disabled
REST API and Web Certificate ID
The Certificate ID for REST API and Web interfaces when the service is running on Windows OS.
Default: None
Client Packet Rate
The communication rate between the service and remote services and client applications. Use a faster rate if you want to have faster communications.
Use the default of 100 ms if there are more than 100 client applications connecting to the service.
Use 1,000 ms if there are more than 1,000 client applications communicating to this service.
Default: 30 milliseconds
Websocket Update Rate
The maximum communications speed from the UI Engine. Set to a value of 0 to allow all tag values with no restriction.
Default: 100 milliseconds
Web / REST WCF HTTP Size
The Max request size for Web HMI and REST API.
Default: 2147483647
Web HMI Session Timeout
The timeout for a Web HMI session that will close if there is no activity over the time period.
Default: 30 minutes
REST API Session Timeout
The timeout for a REST session that will close if there is no activity over the time period.
Default: 30 minutes
Web / REST Remote Tag Timeout
The inactivity timeout for Web HMI and REST API tag monitoring from remote nodes. If there are no tags requested to the remote node within this timeout the continuous communications will stop.
Default: 300 seconds
Network Nodes
Enter IP Addresses, Network Nodes, or Registered Domain Names that will appear under the Client Network browse. Useful when browsing remote services and Classic OPC Servers.
Default: Empty list
OEM
OEM Code
When this string is set the service will perform special operations. You can use any of the following in combination any any combination with each other.
DBLOG – Logs data logging transactions for all logging groups to the directory specified for the error log under System Logging.
DBLOG-Logging Group Name – Logs data logging transactions for only a specific logging group to the directory specified for the error log under System Logging.
NETWORK – Logs all network communications to the directory specified for the error log under System Logging.
THREADS – Logs a transaciton file for execution rates for all threads.
ALARMLOGCLEAREDDATETIMEUPDATESALARMDATETIME – Sets the alarm instance alarm date and time to the cleared date and time when the alarm clears.
HOLDTRIGGERVALUE – Holds the trigger value within the value updates to repost at the end of the data events.
MOVBADQUALITY – Sets the Tag quality to bad if a Calculation Tag with a moving statistic function and the data source is bad.
LOGTRENDCACHE – Logs the status of the internal trend cache to a file beginning with TrendCache at the time the OEM Code is set. Set to blank and back to LOGTRENDCACHE again for each time you want to record to a file.
DISABLETAGCLIENTNETWORKALARM – Disables alarms from tag client network failures.
Default: Empty string
OPC
Browse OPC UA Variables
Browse variables within other variables from OPC UA servers.
Default: Disabled
Value Only in OPC UA Browse
Show only Value of tag when browsing Open Automation Software OPC UA Server.
Default: Disabled
Max Publishing Interval
The Max Publishing Interval for the Open Automation Software OPC UA Server. Requires service restart for change to take effect.
Default: 0 seconds (unlimited)
Allows OAS OPC UA Server
Overrides Default Security to allow tag browsing and reading and writing to tags from Open Automation Software OPC UA Server.
Default: Disabled
Classic RSLinx Fix for Browsing
RS-Linx OPC Server has different versions with various browsing errors. Enabling this setting will implement a workaround for the browsing errors in older versions of RS-Linx. This fix is sometimes incompatible with some older versions of RS-Linx. When enabled select Refresh in the OPC browse window.
Default: Disabled
OPC Server WatchDog Rate
The number of Seconds the OAS Service will expect data from each OPC Server. If the OPC Server does not have a data change within this period the OAS Service will disconnect from the OPC Server and reconnect to try and re-establish the connection.
Set this value to 0 to disable the OPC Server Watchdog feature.
Default: 60 seconds
Use TimeStamp from OPC Servers
All values from OPC UA and Classic Servers include a timestamp. When this property is enabled the timestamp from the OPC server values will be used. When disabled the timestamp for the values will be set to the local CPU clock time when they are received from the the OPC server.
Default: Enabled
Read Values After Write
When enabled a sync read is called for OPC Items after they are written to. This can get the value back from the OPC server quicker, but can also cause extra load on the server if there are a lot of writes.
Default: Disabled
Wait for Device Read and Write
Some OPC Servers do not handle multiple pending requests. This is a workaround for these OPC Servers to only call one device read read or write at a time.
Default: Disabled
Ignore OPC Quality Flags
When this property is enabled the quality attribute of a value returned from OPC Servers will be ignored.
Default: Disabled
Classic OPC Primary and Backup IP/hosts
List of Classic OPC DA OPC Servers as backup OPC Servers to primary OPC Servers.
Both primary and backup OPC Servers can optionally include IP Address or network node name.
Without network node example: EEI.OPCSimulator
With network node example: \\127.0.0.1\EEI.OPCSimulator
Default: Empty list
Remote Services
Client Primary Port Number
The primary TCP port number to communicate with remote services. The remote services would have this TCP Port number specified under the Networking tab in their configuration as the hosting port number.
Default: 58727
Client Backup Port Number
The backup TCP port number to communicate with remote services. The remote services would have this TCP Port number specified under the Networking tab in their configuration as the hosting port number.
Default: 58737
Client Watchdog Rate
A reconnect will occur to remote services if no communication occurs within this timeout.
Default: 10 seconds
Hold Last Good Value On Network Tags when Network Fails
Holds the last good value received from remote services when the network fails. The default for this property is disabled, so normally the tag quality will go to bad quality on network failure. With this property enabled the quality is kept good and just holds the last good value for each tag received.
Default: Disabled
Security User Name
Access to remote services may be restricted by security setup on the remote service. This is the user name used to gain access to remote services.
Default: Empty string
Security Password
Access to remote services may be restricted by security setup on the remote service. This is the password used to gain access to remote services.
Default: Empty string
OPC UA Security Access
Security log in method to local and remote services for browsing tags and reading and writing tag values.
OASServiceUser – Use the Security User Name and Security Password settings when authenticating.
OPCClientUser – Use Username and Password from OPC Client authentication.
Default: OASServiceUser
Retain Values
Retain Values and Alarm Limits of Tags with Data Source of Value
When enabled, the default path for the retain file is “\RetainValues\OAS.RealTimeValues” with a frequency of 0 hours (only at system shutdown).
Default: Disabled
Retain Times and Counts
When enabled, the default path for the retain file is “\RetainValues\OAS.TimeAndCounts” with a frequency of 0 hours (only at system shutdown).
Default: Disabled
Retain Totals
When enabled, the default path for the retain file is “\RetainValues\OAS.Totals” with a frequency of 0 hours (only at system shutdown).
Default: Disabled
Retain Real-Time Trends
When enabled, the default path for the retain file is “\RetainValues\OAS.RealTimeTrends” with a frequency of 0 hours (only at system shutdown).
Default: Disabled
Retain Real-Time Alarms
When enabled, the default path for the retain file is “\RetainValues\OAS.RealTimeAlarms” with a frequency of 0 hours (only at system shutdown).
Default: Disabled
Save Tag Configuration Write To Tag with Data Source of Value
Will store the entire tag configuration each time a write occurs to a Tag with a Data Source of Value or File.
Default: Disabled
Store and Forward
Store Buffer to Disk
Store data logging, alarm logging, AWS IoT Gateway, and Azure IoT data to file when there are network errors at the source, when the the database engine is not reachable or the table to log to is in a locked state. When enabled the values are stored to the directory specified.
When disabled the values will be buffered to RAM, which can use up memory in the database service if not attended to. Use the Maximum Data Log Records and Maximum Alarm Log Records settings to manage the number of records that will be stored in memory.
Default: Enabled
Directory for Buffer
The directory path to store the data logging, alarm logging, AWS IoT Gateway, and Azure IoT buffer files.
This setting is only visible if Store Buffer to Disk is enabled.
Default: \StoreAndForward\
Limit Disk Buffering
When enabled this property will limit how long the buffer files will be retained. Older files will be deleted without being processed to the database engine.
When enabled, the default amount of time to keep the buffer is 24 hours.
Default: Disabled
Buffer Data for Remote IoT Publish
When enabled this property will buffer the local data when a remote OAS Engine cannot communicate to this OAS Engine for the IoT Publish feature.
Default: Disabled
Buffer On Remote Engine Stop
The data source system will buffer data when the remote data logging or driver interface IoT Publish engine is shutdown.
Default: Disabled
Maximum Data Log Records
This setting is only visible if Store Buffer to Disk is disabled.
Default: 10000
Maximum Alarm Log Records
This setting is only visible if Store Buffer to Disk is disabled.
Default: 10000
System Logging
Log System Errors
Log system errors to file.
You can set this to an absolute path or a relative path to the OAS executable. You can also use the word “console” to log to stdout.
When enabled, the default path is “\Log\OASErrors”.
Default: Enabled
Delete Old System Error Logs
This setting is only visible if Log System Errors is enabled.
When enabled, the default amount of time to keep logs is 7 days.
Default: Disabled
Log Communication Errors
Log communication errors to file.
You can set this to an absolute path or a relative path to the OAS executable. You can also use the word “console” to log to stdout.
When enabled, the default path is “\Log\OASCommErrors”.
Default: Disabled
Delete Old Comm. Error Logs
This setting is only visible if Log Communication Errors is enabled.
When enabled, the default amount of time to keep logs is 7 days.
Default: Disabled
Configuration, Feature and Driver Transactions
The OAS system logging configuration supports logging transactions related to configuration, features and drivers. You can individually enable and disable logging for the following:
Log AB and Siemens Comm.
Log Alarm Logging Transactions
Log Alarm Notifications
Log Alarming Communications
Log AWS IoT Communications
Log Azure IoT Communications
Log Calculation Transactions
Log CANBus Communications
Log Configuration Changes
Log Database Communications
Log Data Logging Transactions
Log Data Route Comm.
Log Driver Interface Transactions
Log GPIO Communications
Log Kafka Communications
Log Modbus Communications
Log MQTT Communications
Log MTConnect Comm.
Log OPC DA Communications
Log OPC UA Communications
Log OPC UA Browse
Log OPC UA Alarm and Events
Log Option Configurations
Log Read Database Data
Log Recipe Transactions
Log Report Transactions
Log REST API Transactions
Log System Runtime
Log System Startup
Log Tag Configurations
Log Trending Communications
Log UDP Network Comm.
Default: All disabled
Transaction Log Path
Each of the logging settings listed in the above Configuration, Feature and Driver Transactions, if enabled, will log to a file specified in this property. The file name will start with the configured file path and will be suffixed with the feature or driver name, an optional sub-type and the current date and hour. Each feature or driver may create more than one unique file, depending on how many driver sub-types there are.
For example, a Siemens driver will create a file name such as OASTransactions-Driver-S7-1200-2024-10-25-10.txt.
This file name consists of the following parts:
OASTransactions – the configured file name in the Transaction Log Path property
Driver – a fixed term to indicate that this log relates to a driver
S7-1200 – the Siemens device type
2024-10-25 – the date in ISO format
10 – the current hour
A new log file will be created on the hour every hour.
This property is only visible if one of the logging settings in the Configuration, Feature and Driver Transactions is enabled.
Default: \Log\OASTransactions
Delete Old Transaction Logs
When set, any log file older than the given number of days that originated from any of the Configuration, Feature and Driver Transactions logging settings.
This property is only visible if one of the logging settings in the Configuration, Feature and Driver Transactions is enabled.
Default: Disabled
Log UDI Transactions
Log transactions between OAS and custom drivers that use the Universal Driver Interface (UDI) API to a file specified in this property. The file name will start with the configured file path and will be suffixed with the current date and hour.
A new log file will be created on the hour every hour.
When enabled, the default path is “\Log\OASUDITransactions”
Default: Disabled
Delete Old UDI Trans. Logs
When set, any UDI transaction log file older than the given number of days will be deleted.
This setting is only visible if Log UDI Transactions is set.
Default: Disabled
Include Comm. Errors in Alarms
Include individual communication errors in alarms.
Default: Disabled
Include Comm. Errors in Error Log
Include individual communication errors in communication error log.
Default: Enabled
Include Tag Errors in Alarms
Include individual tag communication errors in alarms.
Default: Disabled
Include Tag Errors In Error Log
Include individual tag communication errors in communication error log.
Default: Enabled
System Startup
Auto Runtime On Service Start
When enabled, the OAS engine will automatically try to enter Runtime mode after the OAS service is started. A delay can be configured using the Time Delay to Start Runtime setting.
Default: Enabled
Time Delay to Start Runtime
The time delay in seconds between starting the OAS service and the engine entering runtime mode.
Default: 1 second
Time Delay to Process Alarms
This setting defines the number of seconds alarms should be ignored after the OAS engine enters runtime mode.
Set Affinity of OAS Engine
Enables the OAS Engine Affinity Mask setting to allow you to set the affinity of the OASEngine process.
Default: Disabled
OAS Engine Affinity Mask
Default: FFFF
Set Affinity of Data Service
Enables the Data Service Affinity Mask setting to allow you to set the affinity of the OASOPC process.
Default: Disabled
Data Service Affinity Mask
Default: FFF
Set Affinity of Report Service
Enables the Report Service Affinity Mask setting to allow you to set the affinity of the OASReports process.
Default: Disabled
Report Service Affinity Mask
Default: FFFF
Classic OPC Service Comm. Rate
The communication rate between the OAS Engine and OAS OPC Service
Default: 100 milliseconds
Report Service Comm. Rate
The communication rate between the OAS Engine and OAS Reports Service
Default: 100 milliseconds
Time
Use UTC TimeStamp
All Tag value timestamps will be stored as UTC date and time in the OAS engine memory. When a tag value is updated on the local OAS engine, the local time of the host will be converted to UTC.
This feature is useful when you need to standardize the timestamps of globally distributed systems and allow each local system to deal with the presentation of local time. All of your Tags and data logging would be stored in UTC time and then converted to local time once presented to the user.
⚠️ Note
If you are writing data into OAS from an external system and the timestamp is also being provided, for example when using the Dotnet Data Connector API or the REST API features, then you must ensure that the timestamps are being provided in UTC format if this setting is enabled or in the same time zone if this setting is not enabled.
If you are moving Tag data between OAS engines and you want to use UTC time then you need to enable it on all connected OAS engines.
Default: Disabled
UTCDateTimeString as ISO 8601
This setting affects how timestamp strings are formatted when a Tag is using a Data Source that is set to Time and a Time Type that is set to UTC Date Time String. The following table shows the difference in format and an example when this setting is disabled and enabled.
Default: Disabled
Custom Timestamp String
This setting affects the formatting of a Tag’s timestamp string stored in the TimestampString parameter of each Tag.
Here is an example of a timestamp format configuration:
You can see this in action by creating a Tag and setting its data source to Tag and its Tag property to the TimestampString parameter. The Value returned should be in the specified timestamp format.
When enabled, the default timestamp string format is “yyyy-dd-MM HH:mm:ss”.
Default: Disabled
Trending
Longest Realtime Time Frame
This setting configures how much real-time Tag value data OAS will store in memory for each Tag that is configured as a Trend Point by allowing you to adjust the buffer time window. It is important to consider both the size of the time window in seconds as well as how many Trend Point Tags you will create in your OAS instance. The time window you specify will be applied to each Trend Point Tag’s data. The more tags you have the more data has to be stored and the longer the time window the more data is stored per tag. The limitations of this feature essentially translates to how much RAM you have available on your server.
Default: 86400 seconds
Enable Stepped Trend
When enabled, the trend window time range will be divided by the Number of Steps setting below and will only update in increments defined by this calculation. In other words, if a trend window is configured to display 60 seconds of data and the number of steps is 4, it will only update every 15 seconds. This reduces the continuous motion of the trend and makes it easier to read.
Trend controls included in Dotnet Trend and Web Trend will display real-time data when in real-time data mode. This trend window will automatically scroll to the left so that the latest data at the current date and time is displayed on the right hand side of the trend. In other words, the x-axis continuously shifts to keep up with the current time.
By default, a trend window will display 60 seconds of data and will update every second. This means that the trend will move every second. When setting the Number of Steps the 60 seconds will be divided by the number of steps and the result will define after how many seconds the trend will update.
The trend will still show all of the data based on the sample rate.
Default: Disabled
Number of Steps
Defines the update interval of a trend control, calculated based on the number of seconds visible in the time range (x-axis) divided by the number specified by this setting.
For example, if the visible time range is 60 seconds and this setting has a value of 6, then the trend will only refresh the x-axis current time every 10 seconds.
This property is only visible if Enable Stepped Trend is enabled.
The Open Automation Software is a flexible, configuration based data platform with a virtually unlimited number of possible use cases and solution implementations. In these situations it is useful to keep in mind some common patterns and best practices around concepts such as performance, security, reliability and redundancy. The Distributed Network Architecture (DNA) means OAS can operate across network boundaries and between private and public networks.
Below is a list of some possible OAS architectures and deployment types to cater for many different use cases.
Concentrator
The Concentrator architecture relies on a single OAS instances for connecting to all of your data sources and also hosts all of your data destinations such as data logging and HMI integration. This architecture can be adjusted for redundancy by adding additional instances and exchanging data between them. This architecture works great when you have a simple network, all of your field devices connect directly to a central server and you do not have any requirements for data processing, logging or visualization at the edge.
Edge
The Edge architecture is commonly used when you have multiple remote sites, each on separate edge networks with multiple field devices at each site, and a centralized operations centre. Each edge location can be licensed for a different number of tags, products and drivers, or you can share features across all edge instances and distribute the tags using flex tag licensing. This means you can configure each edge for local requirements as well as facilitate remote data transfer to a centralized location using the OAS Basic Networking feature. Licenses are typically applied at the edge and the centralized OAS instance acts as a data gateway.
An important benefit of this architecture is that the edge OAS instances can be configured to store and forward data in case of loss of networking. This means not only is data encrypted and compressed in transit, there will also be zero data loss.
Protocol Converter
The Protocol Converter architecture is designed to allow you to move data between devices that use different protocols and to move data from a device directly into the Cloud. You can use any of the OAS supported protocols to read and write your data, such as Allen Bradley, Modbus, MTConnect, OPC UA/DA and Siemens. For Cloud connectivity, OAS supports AWS IoT, Azure IoT, Kafka and generic MQTT messaging.
This architecture uses the Data Route feature to move data from one set of tags to another or to publish data from a set of tags into the Cloud. The Data Route feature handles the data routing without writing any code. For more information see this article on IIot Data Transfer.
IT/OT
The IT/OT architecture is a typical 2-tier networking arrangement for segregation of OT and IT networks where the OAS instance in the OT network is deployed as a concentrator or edge deployment and an additional OAS instance is deployed in a DMZ to make data available to the IT network.
Depending on the security requirements, you can use a number of different configurations to achieve this architecture. If your DMZ OAS instance is simply acting as a data router, clients connecting to the DMZ OAS instance can use standard Basic Networking remote tag notation to reference the OT instance tag names. This way you only need to license the tags on your OT instance, but note that this does not support store-and-forward in case of networking loss.
If you want a copy of your data in the DMZ OAS instance, you will need to replicate the tags stored in the OT OAS instance. You can choose the method that suits you best:
If you want the tags to be read-only in the DMZ then you can use the “Tag” Data Source (Basic Networking). Note that this does not support store-and-forward.
If you want data to be read-write you can use a Proxy configuration (Live Data Cloud). Note that this does not support store-and-forward.
If you want fine-tuned control over which data is copied and when it is copied you can use the Data Route feature on the OT instance to push the data to the DMZ.
If you require a highly isolated OT network with no overlap, you can use the Unidirectional configuration (Unidirectional Network Gateway) to push data directly from the OT network into a DMZ or the IT network in a one-way data configuration.
3-Tier
The 3-Tier architecture is similar to the IT/OT architecture outlined above, except that it also introduces an IT DMZ with a third, public facing OAS instance. All of the details explained in the IT/OT architecture apply to this, but the 3-Tier architecture would be used if you require integration with external clients or third-party Cloud platforms (AWS IoT, Azure IoT and MQTT).
You can move data into your IT DMZ OAS instance using the same principles explained in the IT/OT architecture. Using the Proxy configuration (Live Data Cloud), you can create an alias that represents your OT DMZ instance and thus make the tag data available to external clients using the tag path notation shown in the Proxy architecture below.
Cloud IoT integrations can be achieved using the “Publish Tags” functionality to push messages to the Cloud. You do not have to replicate the tags license in the IT DMZ as it can remotely access the tag data via the OT DMZ OAS instance.
Proxy
The Proxy architecture provides a hosted OAS instance, typically in a DMZ, that acts as a proxy between other networks, external networks or public clients and internal OAS instances. This architecture typically uses Live Data Cloud and can supplement other internal architectures such as Concentrator, Edge and IT/OT.
Using Basic Networking, the OAS instance acts as a data router allowing clients to request data from remote OAS instances without having to directly talk to a remote instance. This is very similar to the IT/OT architecture, but in this architecture only the instance in the DMZ is required to have a static IP. The internal instances can have dynamic IPs and will automatically register themselves with the OAS instance in the DMZ using an alias. Clients can use the alias of the instance they want to request data from as a prefix in the tag path as shown in the Live Data Cloud remote tag access documentation.
Unidirectional
The Unidirectional architecture is designed to protect your vital, safety critical networks by only allowing data to flow in one direction. It works by using a broadcast style protocol called UDP to send data out of the vital network and into one or more non-vital networks based on a simple IP/host and port number configuration. Since UDP does not require acknowledgement, no traffic is required to flow back into the vital network.
This feature, called Unidirectional Network Gateway or UDP Broadcast, is specifically designed for highly critical systems such as nuclear power plants, military networks and other types of safety systems. The main aim of this architecture is to mitigate against network based attacks and remote configuration changes.
Embedded
The Embedded architecture is used when OAS is hosted on a device that supports a Windows IoT or Linux operating system (such as Raspberry Pi) and provides on-board or locally connect I/O capabilities. This allows you to create an all-in-one IoT device powered by OAS and is typically used by OEMs.
View the OAS / System Integrator Partner Program page for a list of advantages OEMs have using OAS to automate setup and deployment of their system and increase availability of their customer’s data.
For any Linux installation, general knowledge of Linux server configuration is required. This includes being comfortable with the following tasks:
managing user accounts
managing files and user permissions
transferring files between machines
networking configuration
configuring services (daemons in systemd)
While OAS is happy to support the OAS installation and any issues related to the product, support does not include managing Linux server configuration and administrative tasks.
OAS Platform Support on Raspberry Pi 4
The Open Automation Software platform can be installed on Raspberry Pi 4 systems with full support of all communication interfaces.
Modbus TCP, Modbus RTU, and Modbus ASCII for Master and Slave
Allen Bradley ControlLogix, CompactLogix, GuardLogix, Micro800, MicroLogix, SLC 500, and PLC-5
Siemens S7-200, S7-300, S7-400, S7-1200, and S7-1500
OPC UA Server and Client
MTConnect
MQTT Broker and Client
Azure IoT Data Hub
AWS IoT Gateway
Raspberry GPIO Pins
NOTE: Classic OPC DA is not included for Linux deployments, but it can be networked from a Windows system running OAS.
All OAS platform features are supported for Raspberry Pi 4.
Data logging and alarm logging to MSSQL Server and SQL Azure, Oracle, mySQL, MongoDB, MariaDB, PostgreSQL, Cassandra, SQLite, InfluxDB, and CSV files
Realtime and historical trending
Realtime and historical alarming
Alarm notification
Live visualization for web user interfaces
Live visualization for remote .NET applications
Full programmatic support of configuration, live, and historical data via REST API and .NET interface
NOTE: Automated reports are not support on Linux systems, but can be triggered over a network connection for execution from a Windows system.
NOTE: While running OAS on a RaspberryPi 4+ is fully supported, the default Raspbian OS is not. Please choose one of the supported Linux distributions HERE, making sure to install a server variant as opposed to a desktop variant. Extensive testing with Ubuntu Server has proven to be the most reliable and simplest to configure.
Installation Video
View the following video for easy to follow instructions to install OAS on a Raspberry Pi 4 device and see the Web HMI Dashboard hosted directly from the Raspberry Pi 4.
The same steps are also listed in the Linux Installation guide so you can follow along with the installation script.
Visit the Web HMI Dashboard for more detail on the self hosted web interface with dynamic user configuration.
The OAS Platform is capable of running in Docker containers on both Windows and Linux, with only a slight variation in configuration. In this article we will walk through the necessary steps for basic containerization, but using these principles you can build your own images and configure them for your particular needs.
00:00 – Introduction
00:15 – Container Installation
00:34 – Application Stack
00:48 – Steps for running docker
01:32 – Create a Docker Image
04:04 – Set of Instructions
05:10 – Commands
05:45 – Run your Container
10:26 – Configure the License Host
14:19 – Remaining Steps
18:06 – Configure Licensing
18:55 – More Information
Prerequisites
The OAS Platform was designed to be a high performance IoT Gateway, Data Logging engine, data visualization server, and more. To benefit from these features, whether the server is running as a stand alone or in a container, be sure to consider the following:
Docker experience – this document assumes some familiarity with containerization concepts, specifically with Docker, and is not intended to be a tutorial on Docker or containers in general. To learn more about Docker, see the following: Docker-What is a Container?
Networking – the server must be able to reach external resources, and if being accessed by any of the OAS SDKs for visualization or programmatic configuration, the server must be accessible from external sources. This is easily accomplished by exposing the necessary ports. Port 58727 is the default port used for TCP communications when using .NET SDKs and the OAS Configuration application. Port 58725 is the default port used for Web Visualization tools as well as the REST API. Running stand alone, you are free to change these ports as needed. However, when running in a container, these default ports should not be changed (more on this later).
Memory and CPU – when running multiple instances of the OAS Platform in containers, expect memory and CPU utilization to increase as a result. The amount of each needed entirely depends on your individual configurations, such as how many Tags are being used in each container, data logging, alarming, etc. Be sure to size your deployment platform only after testing with your intended configurations to determine the footprint. You can refer to the following for suggested CPU and RAM hardware requirements based on Tags and features to be implemented: OAS Recommended Hardware
Containerization Options
Docker containers can be configured to run completely independently or they can run utilizing shared resources on the Host server. OAS supports both scenarios, allowing you to utilize self-contained configuration files or shared configuration files on a Host using mapped volumes. This allows for generic containers to be spun up with identical configurations, or simply to allow the management of configurations external to a container.
Comparison of OAS containers running self-contained and with shared configuration files on the host.
Installing an OAS Image
All Docker versions of the OAS Platform are available on Docker Hub and can be pulled into your local machine with a single command. This makes installation and upgrading extremely convenient. You can browse all OAS images at hub.docker.com/u/oasiot. Once you have chosen the image you would like to use, matching the OS/architecture (e.g. Linux/x64 or Windows/AMD64) execute the pull command, which is provided on the page for each image. For example, the pull command for Linux/x64 is:
docker pull oasiot/oas-linux
This will download the latest version of the image. So, if OAS releases a new version, simply re-run the pull command and you can always be up-to-date. If you would like to pull a specific version, you can use the version tag in the pull command. For example, pulling version 15.00.042 would use:
docker pull oasiot/oas-linux:15.00.042
Using a version tag in your workflow will allow you to keep your installations uniform and predictable.
Running your new container
To run an instance of this image in a container, execute the following command. This will spin up an instance and display the console output in the terminal window. The container can be stopped by hitting CTRL-C. By default, the docker runtime will provide a randomized unique name for the container.
docker run -it oasiot/oas-linux
The container will now be running, and will be assigned an IP address only accessible from the host machine. If you want to map the container’s ports to ports on the host, allowing the container to be reached from external systems, you can use the -p or -P flags in the docker run command. For example this will map the host’s port 58727 to the container’s port 58727, so you can then reach the container from the host’s IP address on port 58727, allowing you use the OAS Configuration application remotely to connect into the container:
docker run -it -p 58727:58727 oasiot/oas-linux
To allow the Docker engine to assign random port mapping, you can use the following command. After doing this, just inspect the running container to see which ports have been assigned:
docker run -itP oasiot/oas-linux
Optional: Creating your own Image
Before any application can be run as a Docker container, it has to be bundled in an image. The process of creating an image involves the creation of a Dockerfile with configuration options, and calling docker build against the file. Whether the target platform for running the container is Linux or Windows, the process is the same, with some slight variations on the contents of the Dockerfile. For more information on Dockerfiles and their syntax, see the online documentation.
To containerize the OAS Platform we will take the following steps:
Ensure that Docker is installed properly on the target platform
Download and extract the OAS Platform distribution for Linux or Windows .NET Core depending on the chosen platform
Copy the contents to the target server in a directory, e.g. /oas-docker/oas-linux, /oas-docker/oas-win
Within the /oas-docker directory, create a text file called Dockerfile with the following contents. If you are familiar with crafting Dockerfiles, you can modify these settings to your preferences, as long as the default ports in the EXPOSE commands are not changed.
As you see, the Windows Dockerfile differs from the Linux version. The FROM entry references the nanoserver tag which is a bare bones Windows runtime host. The same ports are mapped in the EXPOSE lines. The COPY command copies the contents of the oas-win directory to the container’s oas directory. You’ll note the addition of the USER command, which specifies that the context the OAS Platform should run on is the System account with elevated privileges. This is required. Lastly, the ENTRYPOINT is modified to call the OASEngine.exe executable. Also, see the section below titled Windows Containers as you may run wither Linux or Windows applications in containers on the Windows platform.
Build the OAS container image with the following command. This creates and registers a reusable image that can be spun up as multiple side-by-side containers:
docker build --tag oas .
The OAS Platform allows you to customize which ports are used for configuration communications as well as for access with SDKs, the REST API, and WebHMI products. When using OAS within a container, it is important to use the defaults of 58727 for TCP communications and 58725 for HTTP calls. These can be mapped to fixed host ports within the Dockerfile, or mapped dynamically during the execution of “docker run”. The OAS LicenseHost relies on the default underlying ports to allow for license activation, but you may still map these to customized ports if you want to access the containers via localhost.
Options for running a container
Providing a custom name
If you run a Docker container with the previous command, the Docker runtime will assign a random name for that instance. You can provide a custom name for the container to more easily identify the container. This must be a unique name on the server since no two containers can have the same name. This example runs the container, giving it the name “oas_production”:
docker run -it --name oas_production oas
Mapping a host volume
In some cases, you may want several running OAS container instances to share the same configuration files so that when they spin up, they pick up the same settings. To do this, we’ll follow these steps:
Move the ConfigFiles directory to a location on the host machine
Build the docker image
Run the image using the -v host_dir:container_dir option to create a virtual directory in the container mapped to the host
docker run -v /OASConfigs:/oas/ConfigFiles --name oas1 oas
Mapping host directories can also be useful if you are logging data to a SQLite database, as they are file-system based and you would not want data lost when you spin down a container.
You can map multiple volumes for such a configuration, combined with the command above:
docker run -v /OASConfigs:/oas/ConfigFiles-v /SQLiteData:/oas/SQLiteData --name oas1 oas
Then, in your SQLite logging configuration, you would use /oas/SQLiteData as the path for the database.
Licensing
A stand-alone installation of the OAS Platform is licensed directly my using the OAS Configuration application. You select Configure > License, select the machine (typically localhost if working on the current machine) and are presented with a unique License Code for the machine. This is sent to OAS and you will then be provided an encoded License Key that will activate the features you have purchased.
Running the OAS Platform in containers, licensing is handled slightly differently. On the container host machine, you install and run the License Host application, which communicates with all running containers to activate product features, and recognizes new containers as they spin up. When purchasing a license from OAS, you will select product features to enable along with a number of tags, and if deploying OAS within containers, you also select the maximum number of containers you will be running on the host.
Standalone installations of the OAS Platform are licensed directly. Containers acquire their license from the LicenseHost installed on the host
Installing the License Host
Linux
On a Linux system, the installation and execution of the License Host is similar to installing the OAS Platform itself. From the product downloads page, locate the License Host for Linux and download the ZIP archive. Unzip this file and move the contents to your preferred location, then execute the following command on the Linux server to make the application executable:
sudo chmod +x LicenseHost
You can now run the LicenseHost application directly with the ./LicenseHost command, or configure it to be started with the system when it boots up. You can follow the directions for setting up an application as a daemon on Linux from Step 3 of our online documentation, replacing the name and path of the OASEngine with that of the LicenseHost, where applicable.
Windows
On Windows, the LicenseHost installer registers it as a Windows Service. Download and install the License Host and start the service either manually in the Windows Services control panel, or using the OAS License Host application from the Start menu, which acts as a service control for just the License Host. The service is named “OAS License Host” if you choose to start it manually
Managing Licenses with the License Host
After starting the License Host on the container host server, you can connect to it from the OAS Configuration Application to apply or modify a license for that server. Select Configure > Container License from the main dropdown menu and enter the IPAddress of the host server.
Note that the LicenseHost will communicate on port 58729 so the host machine must allow TCP communications on that port so adjust your firewall rules accordingly. If you choose to change this port, locate the appsettings.json file in the distribution of the LicenseHost application and change the port number within it. You can also use this file to secure the License Host by adding a username/password combination.
Configuring the license on the container host is identical to configuring a license on a stand alone installation of the OAS Platform. Your License Code is used to acquire a License Key from OAS Support, and the key contains information about the product features to enable along with the maximum number of containers it will support.
For more information on licensing an OAS server, see the following Knowledge Base article: OAS License Activation
Testing your installation
Once your containerized OAS installation is running, you can connect to the individual containers with the OAS Configuration application and inspect Tags or any other feature. You will need to connect using the container’s assigned IP address, found by inspecting the Host Docker service. If you have not mapped the custom ports to the defaults of 58725 and 58727, you can use these directly with the containers’ IPAddress. If you have mapped ports, you can use the host’s IP address (or localhost on the host itself) with the custom ports.
Considerations for Windows Containers
Assuming you are running Docker Desktop on Windows, you first need to make sure to switch to “Windows Containers”. By default, Docker Desktop assumes you will be using Linux containers with Hyper-V. To make the switch, you can go to the Docker Desktop tool and select “Switch to Windows containers…”
Alternatively, you can use the following Windows PowerShell script to switch:
Below is a video tutorial detailing how to use the Watch Window:
NOTE: Adding a group of tags to the Watch Window will now add the tags within the group selected and all tags in all sub-groups. To add all tags from an OAS Engine select the Tags root object and select Add to Watch.
The Watch Window is a feature of the OAS Configure Application that allows you to view the value of multiple tags at one time. You can use it to view multiple tags from one Service installation or from multiple Service Installations at the same time.
It is free to use with the demo license or an active license for at least any one product feature.
The Watch Window is accessible from the Configure Tags screen. It can be opened by clicking the Watch Window button on the top menu bar.
To add a tag to the Watch Window, select any tag and right click on it. Then choose Add to Watch from the context menu.
The tag you selected will then appear in the Watch Window.
To resize the Watch Window, grab it by the bottom right corner and drag it to the size you would like.
You can also add a Tag Group to the Watch Window. To do this, select the Tag Group, right click on it and choose Add to Watch.
Note: that it won’t add the tags in nested groups, if you want to do that, you must add the sub groups individually as well.
To delete Tags from the Watch Window, simply select the tags you want to delete and click the delete button. You can hold the shift key to select multiple non-adjoining tags and the control key to select multiple adjoining tags.
You can save the current configuration in your Watch Window if you’d like. Choose Save from the top menu and then save the file to a location on your file system.
The configuration files are saved in CSV format so you can open them in Excel and edit them yourself manually. You can specify the Network Node and then the Tag Name right in Excel.
You can create and save multiple configurations for different purposes. It is a very useful feature.
The Watch List feature is free to use with OAS with either the demo license or an active license for at least any one product feature.
If you want to run two separate Watch Windows, you can do that by opening a second instance of the OAS configure application and then open the second Watch Window there. You can see now that I have two separate Watches running independently of each other.
