Plant
??? WaterTreatment
?   ??? Intake
?   ??? Processing
?   ??? Distribution
??? PowerHouse
    ??? Boilers
    ??? Generators

Tag.PUMP01.Running
Tag.Area1/Line1/Temperature

Asset("/Area1/Line1/Temperature")
Asset(client.Context.AssetPath + "State1")

TO DO: Text Development and consolidation

Introduction

This guide focuses on building an effective data model within the platform, utilizing the Unified Namespace architecture. It covers the concepts of DataTemplates, Asset Tree, and DataExplorer tools, and explains how to integrate TagProviders for a comprehensive data management solution.

On this page:

• Introduction
• Design Concepts
  • DataTemplates
  • Advanced DataTypes
  • Server Tags vs Client Tags
  • When to use TagProviders Connections
• Configuration Workflow

Design Concepts

The following main concepts are key to properly organize your data in the Platform. 

• DataTemplates
• Advanced DataTypes
• Server Tags  vs Client Tags
• Root Tags vs Tags in the AssetTree
• When to use TagProviders

DataTemplates

The use of UDT (User Data Types) and their planning at the start of modeling is essential. Gather information about whether your field equipment or other data sources already have that definition, and import them into the platform when possible.

You can also easily create the DataTemplate within the platform and use the Scripts and Devices module to map the data model you defined to the data sources, which can provide the data in a completely distinct way.

In summary, follow conventions when available, and extend with the platform features. All time invested beforehand in properly defining your Unified Namespace is largely recovered during the development and maintenance of the application.

Advanced DataTypes

Each tag supports various types, from basic types such as Digital and Double to advanced ones like Timers, DataTable, and References. Each tag can also be an array of up to three dimensions. The correct selection and use of the Tag Types greatly simplify the use of those tags later in the Displays, Scripts, and Database Connections.

Server Tags vs Client Tags

The concept of Server Tags and Client Tags is explained in the section Client-Server Programming.

Essentially, the Client Tags will hold all the operations (Displays Client Users). As much as possible, you should leverage the built-in Client.DataContext properties and the built tools to persist user configurations.

Root Tags vs Tags in the Asset Tree

Each tag can have a single name, like Temp1, or be positioned inside the Asset Tree, like /Line1/Machine1/Temp1.

When a tag is not positioned in an Asset Folder tree, it's called a 'Root Tag'. Typically, all variables that are internal to your solution and you don't want to expose to other applications connecting with your solution can be kept as a Root Tag. The tags that will be used on the Displays and eventually served to other applications using the MQTT Broker or the OPC Server, or other integration API, should be placed in the Asset hierarchy.

A good practice to avoid the list of Root Tags growing too much is to use DataTemplates. For instance, you can create a Client Root Tag named 'UI' that is based on the Data Template 'UI'. In that template, you can place all custom tags related to managing the User Interface, like ReportStartDate, or any tag you need to create for client context to use in the user interface. Similarly, you can create a Server Tag and a Template named "Admin" for all variables you need for your internal administration of the application, instead of creating multiple variables in the root.

When to use TagProviders Connections

When you have applications connecting with data sources that regularly change Tag Names, addresses, and assets, that is the typical scenario to use TagProviders. The TagProvider features allow you to insert a node in your Asset Tree hierarchy that is dynamically populated with the current tags and assets available at that time from the external data source.

Configuration Workflow

1. Creating DataTemplates:

   • Navigate to Unified Namespace → DataTemplates.

   • Use 'New' to create a User Data Type (UDT) for structuring data.

   • Define properties (variables) in the UDT for your data model.

2. Working with the Asset Tree:

   • Go to Unified Namespace → Asset Tree.

   • Create new asset folders and tags as needed.

   • Organize tags and assets hierarchically for easy navigation.

3. Leveraging Data Explorer Tools:

   • Utilize Data Explorer for visualizing and managing your data model.

   • Explore tags and assets, and modify properties directly from the tool.

4. Integrating TagProviders:

   • Add TagProvider Connections for integrating data from external systems.

   • Configure connections to external data sources like InfluxDB, MQTT, OPC UA, etc.

   • Map external data to your Unified Namespace.

Unified Namespace (Foundation)

Overview

The Unified Namespace (UNS) is the foundational data layer of your FrameworX solution, providing a single source of truth for all real-time and configuration data. It creates a standardized, hierarchical data model that all other modules reference, ensuring consistency across your entire application. Think of the UNS as the central nervous system of your solution - every piece of data flows through and is organized within this structure.

Where It Fits in the Solution

The UNS serves as the data foundation that all other pillars build upon:

• Process Modules - Populate tag values from field devices
• Application Modules - Read and write tags through scripts and databases
• User Interface - Display and modify tag values
• External Systems - Access data through TagProviders and APIs

Core Components

Tags - Real-Time Data Points

Tags are the fundamental data variables in your solution:

• Basic Tags - Simple data points (temperature, pressure, status)
• Complex Tags - Structured data using User Data Types
• System Tags - Built-in tags for runtime information
• Reference Tags - Pointers to external data sources
• Array Tags - Collections of similar data points

Asset Tree - Hierarchical Organization

Organize tags in a logical structure matching your process:

• Plant Structure - Site → Area → Line → Equipment
• Functional Groups - By system or subsystem
• Geographic Layout - By location or zone
• Custom Hierarchies - Match your organization
• Dynamic Navigation - Runtime tree browsing

User Data Types (UDTs) - Reusable Templates

Create templates for complex equipment and systems:

• Standard Objects - Motors, valves, pumps, PIDs
• Composite Types - Combine multiple data types
• Inheritance - Base types with variations
• Nested UDTs - Complex hierarchical structures
• Automatic Instantiation - Create multiple instances

TagProviders - External Data Integration

Connect to external data sources without copying data:

• OPC UA - Browse external OPC servers
• MQTT - Subscribe to broker topics
• Databases - Live database queries
• Web Services - REST API connections
• Cloud Platforms - IoT hub integration

Configuration in Designer

Creating Tags

Using the Tag Grid

1. Navigate to Unified Namespace → Tags
2. Click in empty row or press Insert
3. Configure essential properties:
   • Name - Unique identifier (e.g., Tank1_Level)
   • Type - Data type selection
   • Initial Value - Startup value
   • Description - Documentation

Tag Data Types

• Boolean - True/False, On/Off states
• Integer - Whole numbers (-2,147,483,648 to 2,147,483,647)
• Long - Large whole numbers (64-bit)
• Float - Single precision decimal
• Double - Double precision decimal
• String - Text values
• DateTime - Date and time stamps

Bulk Tag Creation

• Copy/Paste - From Excel or CSV
• Fill Down - Replicate patterns
• Import Wizard - From external sources
• Template Generation - Create similar tags
• Scripted Creation - Programmatic generation

Building the Asset Tree

Creating Asset Hierarchy

1. Go to Unified Namespace → Asset Tree
2. Right-click to add levels:
   • Level 1 - Enterprise/Site
   • Level 2 - Area/Department
   • Level 3 - Line/Process
   • Level 4 - Equipment/Device
   • Level 5+ - Components

Organizing Tags in Assets

• Drag and Drop - Move tags to assets
• Auto-Creation - Generate from tag names
• Bulk Assignment - Using naming patterns
• Dynamic Binding - Runtime association
• Template Mapping - UDT to asset linking

Asset Properties

• Name - Display name in tree
• Path - Full hierarchical path
• Category - Asset classification
• Properties - Custom metadata
• Security - Access control

Creating User Data Types

Defining a UDT

1. Navigate to Unified Namespace → User Data Types
2. Click New Type
3. Add members:
   • Value Members - Data points
   • Reference Members - Links to other tags
   • Expression Members - Calculated values
   • Array Members - Collections

Example: Motor UDT

Motor (User Data Type)
??? Running (Boolean) - Motor running status
??? Speed (Float) - Current speed in RPM
??? Current (Float) - Motor current in Amps
??? Hours (Double) - Runtime hours
??? StartCmd (Boolean) - Start command
??? StopCmd (Boolean) - Stop command
??? FaultCode (Integer) - Fault status
??? Properties
    ??? Scaling - Speed 0-1800 RPM
    ??? Alarms - High current, Fault
    ??? History - Log speed and current

UDT Inheritance

Create base types and variations:

• Base Motor - Common properties
• VFD Motor - Adds frequency control
• Servo Motor - Adds position control
• 2-Speed Motor - Adds speed selection

Configuring TagProviders

Adding External Sources

1. Go to Unified Namespace → TagProviders
2. Click New Provider
3. Select provider type:
   • OPC UA Client - Connect to OPC servers
   • MQTT Client - Subscribe to topics
   • Database - Live SQL queries
   • REST API - Web service calls

Provider Configuration

• Connection String - Server address and credentials
• Update Rate - Polling or subscription interval
• Browse Settings - Filter and namespace
• Mapping Rules - Tag name transformation
• Error Handling - Failover behavior

Tag Properties & Configuration

Essential Properties

• Name - Unique identifier in namespace
• Type - Data type of the tag
• Value - Current runtime value
• Quality - Good, Bad, Uncertain
• Timestamp - Last update time

Scaling & Engineering Units

• Raw Range - Device min/max values
• Scaled Range - Engineering unit range
• Units - Engineering unit text (°F, PSI, GPM)
• Decimal Places - Display precision
• Clamp - Limit to range

Advanced Properties

• Retentive - Maintain value through restart
• Initial Value - Startup value if not retentive
• Min/Max - Value limits for writes
• Deadband - Change threshold for events
• Array Size - For array tags

Security & Access

• Read Security - Who can read value
• Write Security - Who can write value
• Visibility - Show/hide in browsing
• Audit - Log all changes
• Lock - Prevent runtime writes

Data Explorer

Browsing Namespace

Navigate and search the unified namespace:

• Tree View - Hierarchical browsing
• List View - Flat list with filters
• Search - Find tags by name or property
• Recent - Recently accessed tags
• Favorites - Bookmarked tags

Testing Values

Verify tag configuration before runtime:

• Write Values - Test tag writes
• Watch Window - Monitor changes
• Quality Simulation - Test bad quality
• Force Values - Override for testing
• Trace Changes - Log value changes

Import/Export Tools

• Excel Import/Export - Bulk tag management
• CSV Format - Simple data exchange
• XML Export - Complete configuration
• Tag Cross Reference - Usage report
• Documentation - Generate tag lists

Runtime Behavior

Value Updates

How tag values change during runtime:

• Device Writes - From field equipment
• Script Writes - From calculation logic
• Client Writes - From operator UI
• Expression Updates - Calculated values
• Provider Updates - External sources

Quality Management

OPC-compliant quality codes:

• Good - Valid current value
• Bad - Communication failure or error
• Uncertain - Questionable reliability
• Sub-Status - Detailed quality information
• Quality Propagation - Through calculations

Event Generation

Tags generate events on:

• Value Change - Above deadband
• Quality Change - Good to bad
• Write Attempts - Success or failure
• Alarm Conditions - Limit violations
• Security Violations - Unauthorized access

Best Practices

Naming Conventions

• Use consistent hierarchical naming (Area_Equipment_Signal)
• Avoid special characters except underscore
• Include units in name when relevant (Tank1_Level_FT)
• Use standard abbreviations consistently
• Document naming standards

Organization Strategy

• Mirror physical or logical plant structure
• Group related tags in UDTs
• Use asset tree for navigation
• Plan for expansion from start
• Consider maintenance access patterns

Performance Optimization

• Set appropriate deadbands to reduce events
• Use arrays for similar data points
• Minimize expression complexity
• Group related tags for device reads
• Archive unused tags

Data Integrity

• Use retentive tags for critical values
• Set min/max limits to prevent errors
• Configure quality handling in calculations
• Implement redundant data paths
• Regular backup of configuration

Troubleshooting

Common Patterns

Pattern 1: Equipment Module

Create UDT for complete equipment control:

• Status inputs (running, faulted, ready)
• Control outputs (start, stop, reset)
• Analog values (speed, position, load)
• Statistics (runtime, cycles, efficiency)

Pattern 2: Process Area

Organize by ISA-95 levels:

• Enterprise → Site → Area → Line → Cell → Unit

Pattern 3: Calculated KPIs

Use expressions for real-time calculations:

• Efficiency = (Good_Count / Total_Count) * 100
• OEE = Availability * Performance * Quality

Pattern 4: External Integration

Layer external data with TagProviders:

• Local control tags (read/write)
• Remote monitoring tags (read-only)
• Cloud analytics tags (periodic update)

Related Modules

• Devices Module - Populates tag values
• Scripts Module - Processes tag data
• Displays Module - Visualizes tags
• Alarms Module - Monitors tag conditions

AI Assistant Data

<details> <summary>Structured Information for AI Tools</summary>

json

{
  "module": "Unified Namespace",
  "pillar": "Foundation",
  "purpose": "Central data model and single source of truth",
  "components": {
    "tags": {
      "types": ["Boolean", "Integer", "Long", "Float", "Double", "String", "DateTime"],
      "features": ["Scaling", "Retentive", "Arrays", "Security", "Quality"]
    },
    "assetTree": {
      "levels": ["Enterprise", "Site", "Area", "Line", "Equipment"],
      "organization": "Hierarchical navigation structure"
    },
    "UDTs": {
      "capabilities": ["Templates", "Inheritance", "Nesting", "Reusability"],
      "commonTypes": ["Motor", "Valve", "PID", "Tank", "Pump"]
    },
    "tagProviders": {
      "types": ["OPC UA", "MQTT", "Database", "REST API"],
      "purpose": "External data integration"
    }
  },
  "commonTasks": [
    "Create tags",
    "Build asset hierarchy",
    "Define UDTs",
    "Configure providers",
    "Import from Excel",
    "Set security"
  ],
  "dependencies": {
    "feeds": ["Devices", "Scripts", "Providers"],
    "consumers": ["Displays", "Alarms", "Historian", "Reports"]
  },
  "bestPractices": [
    "Consistent naming",
    "Logical hierarchy",
    "Appropriate data types",
    "Security configuration",
    "Documentation"
  ]
}

...