Skip to main content

Scripts API Reference

This section provides detailed technical documentation for the API available for advanced logic programming. Scripts can execute both in synoptics (screens) and on the server, depending on the configured triggers.

Runtime Environment​

The language used is JavaScript (ES6+). The system natively supports asynchronous programming, allowing the use of await for I/O operations.

Global Scope Objects​

The system automatically injects the following constructors and services into the global namespace:

1. Variable Management (Tags)​

The Tag object is the primary interface for interacting with the real-time communications server.

Tag(name?: string)​

Retrieves one or multiple project variable instances.

  • Parameters:
    • name (Optional): string. Unique name of the Tag to retrieve.
  • Returns:
    • If name is omitted: Returns Tag[].
    • If name is specified: Returns the specific Tag instance or undefined.

Properties​

value​
  • Type: any
  • Description: Reactive access to the variable's value.
    • Read: Returns the last known value.
    • Write: Emits a write command to the data bus (WebSocket).

Usage Example​

// Simple read and write
const motor = Tag("MOTOR_01_ON");
console.log(motor.value); // true/false
motor.value = true; // Start motor

// State Toggle
motor.value = !motor.value;

// Bit manipulation (Bitwise XOR)
const statusWord = Tag("STATUS_WORD");
statusWord.value ^= 0x01; // Invert the first bit

2. Persistence (Data Design)​

DataDesign enables asynchronous CRUD operations against the database engine.

DataDesign(name: string)​

Gets the reference to a data collection.

  • Parameters:
    • name: string. Name of the collection (Data Design).
  • Returns: DataDesignInstance.

Methods​

async get(query: object)​

Retrieves records matching the filter.

async insert(values: object)​

Inserts a new document into the collection.

async updateMany(query: object, values: object)​

Updates multiple records matching the query.

async deleteMany(query: object)​

Deletes records matching the query.

Usage Example​

const logger = DataDesign("EventLog");
const rpm = Tag("MACHINE_RPM").value;

// Log stop event
if (rpm === 0) {
  try {
    await logger.insert({
      timestamp: new Date(),
      event: "STOP_DETECTED",
      value: rpm,
      userId: User?._id,
    });
  } catch (err) {
    console.error("Error saving log", err);
  }
}

3. Interface Elements (DOM)​

Direct manipulation of visual elements in the synoptic.

Item(name: string)​

Searches for an HTML element in the current synoptic.

  • Parameters:
    • name: string. Name attribute defined in the element properties.
  • Returns: HTMLElement | undefined.

target​

Contextual variable available exclusively in scripts triggered by element events (e.g., On Click).

  • Type: HTMLElement.
  • Description: Direct reference to the element that originated the event.

Usage Example​

/* Dynamic style change based on temperature */
const temp = Tag("OVEN_TEMP").value;
const panel = Item("TempStatusPanel");

if (panel) {
  if (temp > 200) {
    // Alarm Style
    panel.style.backgroundColor = "#ff4d4d"; // Red
    panel.style.border = "2px solid #b30000";
    panel.innerText = "ALERT: OVERTEMPERATURE!";
  } else {
    // Normal Style
    panel.style.backgroundColor = "transparent";
    panel.innerText = "Normal Temperature";
  }
}

4. External Communication (http)​

HTTP client for integration with external REST APIs.

Methods​

  • async http.get(url: string)
  • async http.post(url: string, body: any)
  • async http.put(url: string, body: any)
  • async http.delete(url: string)

Usage Example​

/* External ERP Synchronization */
try {
  const response = await http.get("http://mes-server/api/next-order");

  if (response && response.id) {
    // Assign received values to SCADA Tags
    Tag("CURRENT_ORDER_ID").value = response.id;
    Tag("BATCH_SIZE").value = response.quantity;
  }
} catch (error) {
  dialog({
    title: "Connection Error",
    message: "Could not retrieve manufacturing order from MES.",
  });
}

5. System and Navigation​

Auxiliary functions for application control.

Synoptic​

  • open(name: string): Navigates to the specified synoptic.

User Interfaces​

  • dialog(options: {title: string, message: string}): Shows a native system alert modal.
  • openLogin(): Forces the login screen to appear.
  • User: Global object with current session information (User._id, User.role, etc.).