graphics-error-scraper

WebCTRL is a trademark of Automated Logic Corporation. Any other trademarks mentioned herein are the property of their respective owners.

Overview

This repository provides two tools for automatically checking graphics errors in a WebCTRL system:

1. Command-Line Tool - A standalone executable for system administrators to run automated checks from the command line
2. Browser-Based Tool - An embeddable HTML page that runs directly in WebCTRL graphics for end users

Both tools are designed to help system administrators and operators proactively monitor the health of their WebCTRL graphics. They should function on WebCTRL 8.0 and later versions.

---

Option 1: Command-Line Tool

The command-line tool is a standalone executable that uses Puppeteer, a Node.js library that automates the Chrome browser. Chrome is used behind the scenes to interact with the WebCTRL system as a real user would.

Installation

1. Download the latest release from the following link: graphics-error-scraper.zip
   • This will work only for 64-bit Windows OS.
   • For other operating systems, you are free to build from source.
2. Unzip the contents to a convenient location on your computer.

Usage

Run the tool from the command line with the following options:

Usage: graphics-error-scraper [options]
  -u, --url <url>             Target URL (required)
  -U, --username <username>   Username (required)
  -p, --password <password>   Password (required)
  -o, --output <file>         Output file (default: errors.json, use - for stdout)
  -f, --force                 Overwrite output file if it exists
  -i, --ignoressl             Ignore SSL certificate errors (required for insecure HTTP)
  -t, --timeout <ms>          Timeout for page actions in milliseconds (default: 180000)
  -h, --headless <bool>       Headless mode (true/false, default: true)
  -v, --verbose               Verbose logging (flag or "true")
      --version, -v           Print version and exit

Note: For this tool to function correctly, the WebCTRL user account must have the Automatically collapse trees option unchecked in his or her settings.

Example

graphics-error-scraper -u https://webctrl.example.com -U admin -p hvac1234 -o results.json

• The tool will log in to the specified WebCTRL system, expand all geographic tree nodes, and check each graphic for errors.
• Results are saved to the specified output file in JSON format, or printed to the console if -o - is used.

[
  {
    "displayPath": "Automatic Controls Equipment Systems / Office Building / Utilities / Building Electric Meter Totalizer",
    "gqlPath": "#aces_electric_meter_totalizer",
    "graphicName": "Default",
    "graphicFile": "aces_electric_meter_totalizer.view",
    "actionErrors": [
      {
        "details": "Uncaught Could not find trend report or an embedded trend at real_pwr_tn",
        "type": "UI_Error",
        "number": 0,
        "line": 449
      }
    ]
  }
]

---

Option 2: Browser-Based Tool

The browser-based tool (embed.html) provides a simpler alternative that runs directly in the user's browser without requiring any downloads or installations. This tool can be embedded into a WebCTRL graphic as an HTML content control.

Prerequisites

• REST API Addon must be installed on your WebCTRL system
  • Download from: https://github.com/automatic-controls/rest-api-addon

Installation

1. Download the pre-made view file: error-scraper.view
2. Upload the view file to your WebCTRL system
3. Add the graphic to any location in your geographic tree

Alternatively, you can manually embed embed.html into an HTML content control in any existing graphic.

Usage

1. Open the graphic in WebCTRL
2. The tool will automatically display in the HTML control
3. Optional: Enter a root GQL path to scope the check to a specific area of your system (e.g., #building_1)
   • If left blank, the tool will check all graphics in the entire system
4. Click the button to run the error check
5. Results will be displayed directly in the browser

Advantages

• No Installation Required - Runs entirely in the browser using JavaScript
• Easy Access - Available directly within WebCTRL for all users
• Scoped Checking - Option to check only a specific branch of the geographic tree instead of the entire system
• Instant Results - View errors immediately without switching applications