Page History

Key Concepts and Terms

Tag

A process variable representing real-time and historical data, created locally or accessed remotely.

Asset Tree

A hierarchical representation of the solution data, containing variables and DataTemplates that match sensor readings, physical equipment, setpoints, recipes, management data, and all the variables necessary to implement and operate an application.

DataTemplate (UDT)

A user-defined data structure that includes variables and references to other templates, creating a hierarchical data structure.

TagProvider Connection

Enables direct interaction with variables in remote systems without creating specific tags, enhancing data access within the Unified Namespace.

Enumeration

Defines potential values or ranges for a variable, mapping messages and colors to each state.

Runtime Database

An in-memory real-time database for Unified Namespace data, ensuring efficient data management during solution execution.

Understanding the Unified Namespace 

Module Features

• Real-time Elements: The system includes a built-in, real-time, event-driven, in-memory database that manages tags, assets, and events within the application.

• Real-time Tag Types: Unlike typical HMI-SCADA systems with basic tag types, this platform supports advanced real-time entities that match all SQL types and many .NET Framework entities, including JSON objects and complete DataTables in a single real-time tag.

• Dynamic Arrays and References: The system supports tri-dimensional dynamic arrays, lists, and type-safe reference tags with dynamic assignments, creating reusable components for displays, symbols, reports, calculations, and other solution parts.

Tags vs TagProvider Connection

It’s important to distinguish between these two concepts:

The decision to create Tags and the Devices Module to map its data, or to use TagProvider Connections, is discussed at the page Devices Module and TagProviders.

The key concept is that there are two very distinct ways to interface with external data, each with its own limitations and benefits. According to your requirements, one approach or the other will clearly be the best way to set up. For various solutions, it is likely that your Unified Namespace will have some data in local tags, mapped to devices, and some data dynamically driven by remote systems using the TagProvider Connection.

→ See more about TagProvider Connections.

Configuring the Unified Namespace

Configuration Workflow

The Unified Namespace’s Asset Tree is where you build your data definitions. From this central point, you can create or import tags, organize the hierarchy, and monitor the current values of your variables.

When you start a new solution, the Asset Tree includes a built-in “RootTags” folder for all root-level tags, improving visualization for large tag sets.

Typical configuration process:

1. Creating DataTemplates: Define reusable tag data structures.
2. Creating Tags and AssetFolders: Organizing your data.
3. Creating TagProviders: Add links to folders for external data.

Editing the AssetTree

• Create a new folder: Organize and group assets using the new Asset Folder icon Image Added or right-click menu from the Root or parent node.
• Create new Tags: Select a folder and use the New Tag toolbar Image Added button or right-click menu.
• Move Tags: Drag tags to the desired folder.
• Create TagProviders: Use the toolbar icon New TagProvider Image Added or the menu command File > New > TagProvider Connection.
• Link Remote Data: Right-click a folder and use the context menu command "Link Data from TagProvider", or use the toolbar iconImage Added.

→ Read more about Asset Tree.

Defining DataTemplates

DataTemplates allow you to create custom data structures for reusable tag configurations, streamlining data management and improving system efficiency by defining hierarchical structures that represent assets or information models.

→ Read more about DataTemplates.

Defining Tags

The page Unified Namespace / Tags allows you to:

• Create, modify, and delete tag objects.

• Use built-in tools for search and filtering.

• Bulk-edit.

→ Read more about Tags.

Defining Enumerations

Enumerations are sets of named integer values representing discrete options or states, improving code readability and reducing errors. For example, a pump’s states like “Off”, “On”, and “Fault” with values 0, 1, and 2.

To Create Enumerations

1. Go to Unified Namespace / Enumeration.
2. Click ‘New’ on the grid toolbar.
3. Open the ‘Create New Enumeration’ pop-up window.
4. Enter the name of the enumeration and click ‘OK’.
5. Add properties to the enumeration set, such as ‘On’ and ‘Off’ with default values.

→ Read more about Enumerations.

Using TagProvider Connections

To incorporate data from TagProviders into the Asset Tree:

1. Select or create an AssetFolder.
2. Right-click the folder and execute the command “Link Data from TagProvider”.

The Unified Namespace / TagProvider Connections page allows reviewing the list of defined TagProviders or browsing external data contents.

→ Read more about TagProviders.

Working with the Unified Namespace

Runtime Execution

When solution execution starts, the Unified Namespace definition is loaded into an in-memory real-time database, implemented by the TServer.exe process. This real-time database enables event-driven data exchange of tag and asset values between various modules, such as alarms and displays.

Accessing Assets in Scripts and Expressions

Modules like Alarms and Displays can access any variable from the Unified Namespace using its full name or path. For example, to access a tag when creating an operator display, use “Tag” to access available tags. A property called “Temperature” from a template tag named “Machine1” would have the full path: Tag.Machine1.Temperature.

You can also access values using the Asset() method syntax. For example, if you place the tag defined in the previous example inside a folder called Line1, the path for that value would be:

Asset("/Line1/Machine1.Temperature")

Anchor
BestPractices BestPractices

Best Practices and Troubleshooting

Best Practices and Recommendations

To maximize the benefits of the Unified Namespace, follow these best practices:

Organization of the Data Structure

• Organize tags into a clear hierarchy with folders and templates for easier navigation and understanding.
• Plan data structures carefully, considering the relationships between assets, tags, and templates.
• Use templates for reusable data structures, reducing redundancy.
• Seamlessly integrate external data sources using TagProviders.
• Use consistent naming conventions for tags to simplify navigation and troubleshooting.

Status Monitoring 

• Add specific displays and scripts to regularly monitor system performance and connection status.
• Implement alarm conditions for critical connection losses.

Common Issues and Solutions

Some common issues while working with the Unified Namespace include:

Crash when using recursive data model

• Make sure you're not using recursive Data Models - for example, a template which contains another template that contains another template etc. This may cause the system to overload and crash.

Inconsistency or Missing Data from External Systems:

• Ensure that the external application maintains the Unified Namespace, including variable names and structure.
• Refer to the UNS TagProviders Connections section for diagnosing connection issues.
• For device communication drivers, the tag name will always display correctly in the Unified Namespace, but its value depends on the connection with the remote device.
• Refer to the Devices (Field Communication) section in the documentation for setup and diagnostic information.
• This applies to any external data source, such as remote SQL databases or custom scripting using external APIs.

Inconsistency or Missing Data After Importing:

• Ensure that import files (Excel, CSV, etc.) are properly formatted with the required columns and compatible data types.

In this section:

Real-time Data Model

FrameworX applications are organized around the real-time data. The functional Modules, such as Alarms, Scripts, or Graphical Displays, runs independently using the centralized Data Model to exchange the real-time information.

Image Removed

Key Concepts

In order to organize the real-time data, there are 3 key concepts: Tags, Assets and Templates. 

Tags

In the context of this platform, the term "tag" refer to real-time variables and their associated historical data.

Tags are accessible for read, write and subscription by the various Modules. For example, the Devices Module can map the value of the Tag with field equipments , such as PLC registers; or the Datasets Module can connect tags with SQL databases tables and queries;  or the Scripts Module can perform calculation and analytics with the tags. The graphical Operator Displays shows values mapping to the Tags, independently of the data source for its value.

The Tags can be created in the project (Local Tags) or remote tags from other systems can be dynamically accessed using the Tag Provider connectivity. 

Assets 

The Tags in the projects can be organized in a tree structure, allowing to group variables that are related in the same folder, creating an hierarchical representation of the process. The term asset also refers also to the physical equipment in the production environment, that equipment will relate with a group of Tags, or a Template, that represents the real-time state of that equipment. 

Templates 

Templates are user defined data structures, also known as UDTs (User Data Types). 

Typically, the equipments on the field will have various variables for realtime monitoring. Instead of creating one Tag to each variable, it is possible to create a Template with those variables, then create one Tag with that Template type.  

Defining Local Tags

All tags have a specific type for its value, such an integer, text or DateTime. The many pre-defined Tag Types are the Built-in tag types. In addition, the tag type can be an UDT (User Defined Type) or Tag Template .

Tags have also pre-defined properties, such as Description and Array size. Different tag types may have specific properties, but most properties are available to all Tags.

When creating the Tag, some of those properties are defined in the configuration — such as the Description —, some of the properties are only accessible when the application is running — like Value, Quality and Timestamp. The complete set of Tag properties when running the project is referred as the Runtime Tag Properties. 

Built-in Tag Types

The built-in tag types are based directly as extensions of the .NET datatypes. The tag types are summarized in the following table:

Built-in Tag Types

Tag Type

.Net Type

Description and Value Range

Digital

System.Int32

Binary value, 0 or 1. 

Integer

System.Int32

Integer values, range  -2,147,483,648 through 2,147,483,647

Long

System.Int64

Long integer values, range  -2,147,483,648 through 2,147,483,647

Double

System.Double

Floating point value. ranging -1.79769313486231570E+308 through -4.94065645841246544E-324 for negative values; 4.94065645841246544E-324 through 1.79769313486231570E+308 for positive values

Decimal

System.Decimal

Extended precision floating point., ranging 0 through +/-79,228,162,514,264,337,593,543,950,335 with no decimal point; 0 through +/-7.9228162514264337593543950335 with 28 places to the right of the decimal; smallest nonzero number is +/-0.000

The Decimal type allows calculation with higher precision than the Double type. However, math operations using Decimal can be 40 times slower than using Double. So the Decimal type should only be used when Double precision is not enough.

Text

System.String

Text strings composed of Unicode character. Maximum length of the sting is the integer range. 

Timer

System.Int32

Timer is a built-in integer type that can be used to generate precise timing signals and wave pattenrs. Timers have the following models: 

• SquareWave:  The value toggles between 0 and 1. Image Removed

• Pulse: The tag changes to 0. Then immediately changes to 1. Image Removed

• DelayOff: The tag behaves as a PLC Timer Off. If you set the tag with a value other than the StartValue during runtime, the tag will hold that value for the period specified in the Interval. The tag goes back to its StartValue after the period of time (Interval). 

Image Removed

• Comparer: The tag is set to 1 after the specified comparer Interval, and then goes back to zero at midnight. Image Removed

For SquareWave, Pulse, and Comparer, the tag toggles between 0 and the StartValue (instead of 0 and 1) if you set the tag StartValue.

DateTime

System.DateTimeOffset

From 12:00:00 midnight, January 1, 0001 to 11:59:59 P.M., December 31, 9999

TimeSpan

TimeSpan

Data Interval in Days, Hours, Minutes, Seconds and Milliseconds, where each of those properties can hold a Double value

Guid

Guid

Standard Microsoft Globally Unique Identifier (GUID)

DataTable

System.Data.DataTable

Holds an in-memory DataTable

Image

System.Byte[]

Can hold an Image file or any binary content. The Long value is the maximum size of the content. 

Reference Type

Reference tags allow dynamic addressing of variables. 

The way you use Reference tags in the project is similar to how you use references in .NET programming, as they both have a defined type. The target type for the Reference is defined in the Parameters columns.

Typed references bring advantages in both the engineering stage and in runtime. In the engineering stage, it allows IntelliSense to directly browse the template members if a reference is pointing to a template. In runtime, it allows string data validation. 

All Reference tags have an additional runtime attribute: the Link property, which specifies which tag that the reference will be linked to during execution.

Essentially, the Link property is a string property that needs to receive the target tag name before using the reference tag. You can assign a string directly or by using a string expression. The best way to set the link property is to use the method GetName(), which will create the string based on the current tag name. This way, you can rename the tag without having to search the strings. This also shows the tag names linked on the cross-reference utility. 

Examples:

@Tag.Reference1.Link = @Tag.TagName.GetName();

@Tag.Reference1.Link = @Tag.TagName.GetName();

@Tag.Reference1.Link = "Tag.TagName";

@Tag.Reference1.Link = "Tag.TagNa" + "me";

The reason for using the GetName() method instead of using strings directly is that with GetName() you retain the benefits of Cross-Reference and Refactoring. 

Creating and Editing Tags

To create new local tags:

• Go to Edit → Tags → Objects and insert a new row with the tag properties defined in the columns.
• or, in any configuration windows, just  click the  <<< IMAGE >>>. New Tag button on the Top Toolbar
• or, when at the Edit → Tags → Assets, use the NewTag toolbar button <<Image>> to create a tag at the selected asset level
• or, by copy-paste the data form Excel or another project;
• or, using the other Importing tags tools.

To edit the properties of existing local tags:

• Go to Edit → Tags → Objects and edit the row with the tag definition you want to modify. Multiple rows selection is allowed. << Link editing data grids >>.
• Select a Tag Name at the top toolbar << Image >> and click the Tag Properties button at the toolbar << Image >>

Either creating a new tag, or editing tags, in the datagrid view or the properties dialogs, the tag has the following configuration fields: 

Tag main configuration properties 

Field

Description

Parent

Specify the Parent Level where the Tag is located in Asset tree.

Name

Enter a name for the tag. The system lets you know if the name is not valid.

• If you edit the name of an existing tag, the system automatically updates the name throughout the project.

Type

Select the tag type, which may be a built-in type or a user-defined Tag Template.

Parameters

Configure any parameters. The parameters vary based on the tag type. Once the type is entered, you can double-click the parameters field to see a dropdown menu with any applicable parameters.

• DeadBand — It is used as a limitation to save new values to the tag. It defines the difference necessary between the old value and the new value. It is also possible to set the DeadBand as an percentage and with decimal numbers such as: 10.5; 10%; 300%; 17.8%.

      Example 1: If the DeadBand is Set to 5 and initial value of the tag is 0, the next input possible to be saved, need to be >=5 or <=-5.

      Example 2: If the current value of the tag is 100 and the deadband is set to 10%, the next input possible to be saved, need to be >=110 or <=90.

• EnumerationSet: You can also use dictionaries to "translate" tag values into text. These dictionaries are called Enumeration Sets.

For example, a device may have a value of 0  or 1 . Rather than display "0" or "1", you can display the strings "on" or "off."

The definition for the Enumeration Set dictionary is on Tags → Enumeration Sets

When configuring a display component to use these tags, set the TextOutput to one of the following:

• Tagname or Tagname.Value: show the numeric value of the tag.
• Tagname.ValueAsString or Tagname.DisplayValue: show the enumeration string.

Array

When this field is blank, the tag is not an array.

When the field contains an integer value of N, an Array is created from position 0 to N.

For example, if the field contains the value 5, the Array is created from Tag[0] to Tag[5]. This means that 6 elements are created.

Two programming styles are accommodated by this method; one that counts elements from 0 to less than 5, and one that counts from 1 to 5.

Description

String message with additional information about the Tag, maximum string length is 1024

String with the Engineering units of measure, simplifying the visualization of the value on Displays, and allowing the dynamic change of metric systems. More information at Dictionaries Units <<<<. Link ???>>>>

Select this option to save the value of the tag and its internal properties to the database every time the value changes. This retains the value when the application shuts down and makes the value available when the next next application starts.

• None — Does not retain the value or properties.
• ValueOnly — Retains only the value.
• Properties — Retains all properties, including the value.
• PropertiesOnly — Retains all properties, except the value.

The values for Retentive Tags are stores at the database defined at Datasets → DBs → Retentive, and it can be customize to use any database. 

Retentive can be applied to Tags of Domain Server, in this case, you can easily allow the cold-start from the Project, without losing Operator-Inputed values or other Tags that shall keep the last value in between a shutdown and a startup.

Retentive can be applied to Tags of Domain Client, in this case, you can falsity create concepts as User Configuration settings, that are stored and located according the client or user connection. 

Defines if the tag value has Server (global) or Client (instance) scope.

Server (Default): the value of tag is unique, synchronize across all operator stations accessing the project. All tags used by Devices Communications and Historian must be or Type Server.

Client: The value of tag is local at each Client Displays Instance accessing the project. Common use for client tags are to manage the user interface.

Select the value visibility of your tag to external connection and the built-in OPC server.

Private: Tag is visible only to the local project and redundant pair.
Protected: Tag is visible on the external connections for read-only operations. 
Public: Tag is visible on the external connections, for both reading or writing. 

If not defined, the visibility is Public by default. 

Allows to define metadata labels to the tag. Categories are useful for project organization during the engineering phase.

Categories are also useful when copy pasting tags directly the draw area, automatically creating symbols. 

For more information on Categories, go to  Dictionaries ? Categories. 

Tag Value formatting 

The format property defines the display format of tag values. For example, N1 defines a number with one decimal place, like 2.1

These formats follow the specifications provided in Microsoft .NET.

Numerical values formatting

Specifier

Description

N0

Number with no decimal places

Nn

Number with n decimal places (replace n by any integer number)

X

Hexadecimal (supported only for integral types)

C

Currency

R

A string that can round-trip to an identical number

P

Number multiplied by 100 and displayed with a percent symbol

G

The more compact of either fixed-point or scientific notation

F

Integral and decimal digits with optional negative sign

E

Exponential notation

D

Integer digits with optional negative sign

Date/time formats 

Specifier

Description

T (only)

Long time pattern (equivalent to HH:mm:ss).

d (only)

Short date pattern (equivalent to M/d/yyyy (month/day/year) for en-us).

dd

Show the day of the month as a number from 01 through 31.

ddd

Show the abbreviated name of the day of the week.

dddd

Show the full name of the day of the week.

MM

Show the month as a number from 01 through 12.

MMM

Show the abbreviated name of the month.

yy

Show the year as a two-digit number.

yyyy

Show the year as a four-digit number.

hh

Show the hour as a number from 01 through 12.

HH

Show the hour as a number from 00 through 23.

mm

Show the minute as a number from 00 through 59.

ss

Show the second as a number from 00 through 59.

fff

Show the millisecond as a number from 000 through 999.

tt

Show the A.M./P.M. designator.

Import Tag Definitions 

There are many ways to import Tag definition to the project:

• Just Copy from other Projects and in this Project.
• Copy Paste from Excel
• Importing CSV files 
• Using the Import Tag Wizards
• Using the EngWrapper API 

Import from Excel

Importing Tag and PLC Addresses

You can copy and paste the contents of an Excel table. As long you include the title of the columns when you copy and paste the contents of the table, the tables in your project can have different columns or can be ordered differently. The system will put the data in the expected columns, even if the order is different in the source.

To create and import Tags:

• In Excel, make a table with the columns that are shown below. 

Image Removed

To successfully import the tags, you need the TagName, Type, and Address columns. 

• After you chose the device protocol and create a new node, click the Import button. Then, choose the .CSV file that contains the tag's information and click the Ok button. 

 Image Removed

• The Tags and Points will be created automatically in  Tags.

 Image Removed

• Device → Points 

Image Removed

After you use the Import tool for the first time, the system will save whatever settings you used. The import button turns into the "Sync" button. This make the button execute a synchronization that verifies the previously imported addresses and the new ones.

Import from CSV Files

Individual CSV File

In this scenario, we are importing items for each individual table that is available throughout the Engineering Environment.

In your Engineering Environment, you should find a toolbar located on the top of the display with green arrow in it.

In Tabs that do not contain a table, the import icon is unfocused and is unable to be selected.

Image Removed

For Tabs that do contain grids, the import button is available when the grid is on focus (selected). When the import button is clicked, a dialog window will open.

Browse for the csv file and click Open.

Image Removed

Examples

To better understand how to use this feature, we are going to add Alarm Items into our sample project.

Assuming we have two Tags, Tag1 and Tag2, in our project. Each tag must have an alarm configured to it.

1. Tag1 - Belongs to ’Critical’ Alarm Group and triggers an alarm when its value is lower than 20.

2. Tag2 - Belongs to ’Warning’ Alarm Group and triggers an alarm when its value is higher than 80.

The import steps are:

• Go to  Alarms → Items, create a dummy row, and copy it (Ctrl + C).
• On your external Table Editor (e.g. Excel, Google Docs, Notepad, etc), paste the copied content.

Image Removed

3. Fill your table with the required information.

Image Removed

4. Save the file as a ‘.csv’.

5. Go back to the  Alarms → Items page and click the Import CSV File Button.

Image Removed

Extended CSV Files

In this scenario, we are using a single .csv table to import information on Tags, Devices, Alarms and historian items.

In your Engineering Environment, navigate to Run → Extensions → Import. You should see many supported files that can be imported into a project.

Select the CSV file and browse for your Table File.

Image Removed

The table must obey a certain format. The required columns can be obtained by following the same method as in the previous section; copy from project and paste on Sheet Editor.

The difference in this method is that the final table is a concatenation of the various grids from the project.

Examples

To illustrate the usage of this feature, we will add a couple of items to our sample project. The following items will be added:

Tags:

• MyTag1: Integer DataType and StartValue = 0.
• MyTag2: Digital DataType.

Alarm Items:

• MyTag1:

1. HiHi alarm limit (configured for ‘Critical’ alarm group) set to 95
2. Lo alarm limit (configured for ‘Warning’ alarm group) set to 10

• MyTag2:

1. Hi alarm limit (configured for ‘Critical’ alarm group) set to 1 and Message ’Tag Alarm is Hi’.
2. LoLo alarm limit (configured for ‘Warning’ alarm group) set to 0, Priority set to 1 and Message ’Tag Alarm is LoLo’.

Historian:

• MyTag1: Added to default Historian Table ‘Table1’.
• MyTag2: Added to default Historian Table ‘Table1’.

The table that contains all the columns and rows required to import the items described above can be found in the pictures below (with additional columns):

Following the importation procedure in Run → Extensions → Import, select the CSV option, browse for the filled csv file, and click Import.

Image Removed

Image Removed

Image Removed

Creating Templates

Templates allow you to create new tag types based on a data structure using existing built-in types and previously defined Templates.

To create a tag template:

• Go to Tags → Templates.
• Click New.
• The "Create New Tag Template" dialog will open.
• In the "New Type Name" field, enter a name for the tag type. In the Description, enter a description of the tag. Click OK. The Templates tab displays with the name of the new template at the top of the tab.
• Click the insertion row to create a new attribute for this tag template.

• Enter or select information, as needed. The properties are the same ones for Tags. See Creating and Editing Tags above.

• To delete a template, select it from the User Custom Type drop-down list, then click Del.
• On the Objects tab, you can now use this new template in the Type column.

Assets allow to organize the tags of your project into a hierarchy.

For an example on how the Asset tree can be used the projects, go to Self-aware Asset Displays

The Tag Namespace

The Tag namespace exposes properties and methods of the .NET objects used by the Tag Objects.

This section describes only some commonly used properties, for the full list properties and methods is available at Namespaces Reference.

Data Quality field, according OPC standards:

0: bad quality
64: undefined quality
192: good quality

Date and time of the last change on the tag value