You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

FrameworX Git Export

Overview

FrameworX 10.1 introduces comprehensive Git integration capabilities, enabling version control, collaboration, and DevOps workflows while maintaining the security and performance of a centralized database architecture. This hybrid approach allows teams to leverage modern development practices without compromising industrial-grade reliability.

Key Features

Hybrid Configuration Management

  • Centralized encrypted database remains the single source of truth
  • Automatic Git exports for version control and collaboration
  • Selective export of configuration elements suitable for version control
  • Sensitive data protection through placeholder substitution
  • Bidirectional synchronization between database and Git repository

Git-Friendly JSON Format

  • Consistent formatting for clean diffs
  • Sorted keys to minimize merge conflicts
  • Array-based table exports for efficient storage
  • Metadata preservation including version and export information
  • Binary asset handling with separate files and checksums

Getting Started

Enabling Git Export

  1. Navigate to Project Settings → Version Control
  2. Select Enable Git Export
  3. Configure export directory path
  4. Choose automatic or manual export mode
  5. Select modules/tables for export

Export Modes

Automatic Export

When enabled, FrameworX monitors configuration changes and automatically exports modified objects to Git-compatible JSON files.

? Enable Automatic Export
  Export Trigger: On Version Change
  Export Delay: 5 seconds (batch rapid changes)
  Target Directory: C:\Projects\MyScada\GitRepo

Manual Export

Export entire solution or specific modules on-demand:

  • Export All: Complete solution export
  • Export Module: Selected module only
  • Export Current: Active object in editor

Export Structure

Directory Organization

solution-root/
??? Solution/
?   ??? SolutionCategories.json
?   ??? SolutionSettings.json
??? Displays/
?   ??? Layouts/
?   ?   ??? MainPage.json
?   ?   ??? Overview.json
?   ??? Images/
?   ?   ??? Logo.json
?   ?   ??? Logo.png
?   ??? DisplaysLocalization.json
??? Scripts/
?   ??? Tasks/
?   ?   ??? ServerStartup.json
?   ??? Classes/
?   ?   ??? DataProcessor.json
?   ??? ScriptsExpressions.json
??? UNS/
?   ??? UnsTags.json
?   ??? UserTypes/
?       ??? CustomTemplate.json
??? Alarms/
?   ??? AlarmsGlobalSettings.json
?   ??? AlarmsItems.json
??? .gitignore

JSON File Format

Every exported file follows a consistent structure:

{
  "ExportInfo": {
    "ObjectType": "ScriptsTasks",
    "TableVersionID": 6,
    "SolutionVersionID": 245,
    "ExportDate": "2025-08-23T10:30:00Z",
    "ExportUser": "john.doe"
  },
  "Header": {
    // Object metadata from table columns
  },
  "Body": {
    // Object content or table rows
  }
}

Export Categories

Individual Object Files

Objects with rich editors are exported as individual files:

  • Script Tasks and Classes
  • Display Layouts and Pages
  • SQL Queries
  • Report Definitions
  • Symbol Definitions

Table Export Files

Configuration tables are exported as single files with all rows:

  • Tags (UNS)
  • Alarm Items
  • Device Points
  • Security Settings
  • Expression Definitions

Working with Git

Recommended Workflow

  1. Configure Git Repository

    cd /path/to/solution
git init
git remote add origin https://github.com/company/scada-config.git

  2. Initial Commit

    git add .
git commit -m "Initial FrameworX configuration export"
git push -u origin main

  3. Development Workflow

    # Create feature branch
git checkout -b feature/new-alarm-logic

# Make changes in FrameworX
# Automatic export creates/updates files

# Review changes
git diff

# Commit and push
git add .
git commit -m "Add new alarm logic for Tank-101"
git push origin feature/new-alarm-logic

  4. Code Review Process

    • Create pull request in Git platform
    • Team reviews configuration changes
    • Merge approved changes to main branch

Environment Management

FrameworX supports environment-specific configurations through placeholder substitution:

{
  "DatabaseConnection": "${DB_CONNECTION}",
  "EmailServer": "${SMTP_SERVER}",
  "HistorianPath": "${HISTORIAN_PATH}"
}

Environment variables are resolved at runtime, allowing the same configuration to work across development, staging, and production.

Security Considerations

Sensitive Data Handling

  • Passwords and credentials are never exported to Git
  • Connection strings use environment variable placeholders
  • API keys reference secure vault entries
  • Encrypted values remain in the database only

Access Control

  • Git export respects FrameworX user permissions
  • Export operations are logged in the audit trail
  • File integrity verified through checksums
  • Binary assets include SHA-256 hashes

Best Practices

What to Export

? Export to Git:

  • Application configuration
  • Display definitions
  • Script code
  • Alarm rules
  • Report templates
  • Static settings

? Keep in Database Only:

  • Runtime tag values
  • Historical data
  • User passwords
  • Session information
  • Temporary data
  • High-frequency updates

Branching Strategy

Recommended Git branching model:

main
??? develop
?   ??? feature/new-screens
?   ??? feature/alarm-updates
?   ??? feature/script-optimization
??? hotfix/critical-alarm-fix
??? release/v2.1

Commit Guidelines

Write clear, descriptive commit messages:

Good:  "Add temperature monitoring for Reactor-3"
Good:  "Fix alarm delay calculation in Tank-Level script"
Bad:   "Updated stuff"
Bad:   "Changes"

Troubleshooting

Common Issues

Export not triggering automatically

  • Verify automatic export is enabled
  • Check export directory permissions
  • Ensure VersionID is incrementing on changes

Large file sizes

  • Consider splitting large tag databases
  • Use table export format for better compression
  • Implement .gitignore for temporary files

Merge conflicts

  • Use consistent export user accounts
  • Coordinate team changes through branches
  • Leverage Git merge tools for resolution

Advanced Features

Custom Export Filters

Define which objects to export:

// ExportFilter.cs
public bool ShouldExport(ConfigObject obj)
{
    // Skip temporary objects
    if (obj.Name.StartsWith("_temp")) return false;
    
    // Skip test configurations in production
    if (Environment == "Production" && 
        obj.Name.Contains("test")) return false;
    
    return true;
}

Post-Export Hooks

Execute custom actions after export:

# post-export.bat
cd %EXPORT_DIR%
git add .
git commit -m "Auto-export: %DATE% %TIME%"
git push origin develop

Import Validation

FrameworX validates imported configurations:

  1. Schema validation against ObjectType
  2. Referential integrity checking
  3. Version compatibility verification
  4. Checksum validation for binary assets

API Reference

Export Commands

// Export entire solution
FrameworX.Git.ExportSolution(targetPath);

// Export specific module
FrameworX.Git.ExportModule("Scripts", targetPath);

// Export current object
FrameworX.Git.ExportObject(currentObject, targetPath);

Configuration Options

<GitExport>
  <Enabled>true</Enabled>
  <AutoExport>true</AutoExport>
  <ExportPath>C:\GitRepo</ExportPath>
  <ExportDelay>5000</ExportDelay>
  <IncludeModules>
    <Module>Scripts</Module>
    <Module>Displays</Module>
    <Module>Alarms</Module>
  </IncludeModules>
</GitExport>

Performance Considerations

Export Performance

Configuration SizeExport TimeFile CountTotal Size
Small (< 100 objects)< 1 sec50-100< 1 MB
Medium (1,000 objects)3-5 sec200-5005-10 MB
Large (10,000 objects)15-20 sec1,000+50-100 MB
Enterprise (50,000+)60-90 sec5,000+500+ MB

Optimization Tips

  1. Use selective export for large systems
  2. Enable compression for repository storage
  3. Implement .gitignore for generated files
  4. Schedule exports during low-activity periods
  5. Use shallow clones for CI/CD pipelines

Integration with CI/CD

Example GitHub Actions Workflow

name: Validate FrameworX Configuration

on:
  pull_request:
    branches: [ main, develop ]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    
    - name: Validate JSON Schema
      run: |
        for file in $(find . -name "*.json"); do
          python validate_schema.py $file
        done
    
    - name: Check Tag Naming Convention
      run: python check_naming.py ./UNS/UnsTags.json
    
    - name: Verify No Credentials
      run: |
        ! grep -r "password\|credential\|secret" --include="*.json"

Migration from Other Systems

From Pure Database Systems

  1. Enable Git export in FrameworX
  2. Export complete configuration
  3. Initialize Git repository
  4. Establish branching strategy
  5. Train team on Git workflows

From File-Based Systems

  1. Import existing files to FrameworX database
  2. Verify data integrity
  3. Enable selective Git export
  4. Maintain file organization if desired
  5. Implement security improvements

Roadmap

Current Capabilities (v10.1)

  • ? JSON export for all configuration types
  • ? Automatic and manual export modes
  • ? Binary asset support
  • ? Metadata preservation
  • ? Selective module export


Support Resources

Last Updated: December 2025 | FrameworX Version: 10.1

  • No labels