Getting Started

Getting Started with Phantom.js

This guide will help you get started with Phantom.js in your OIE scripting projects.

Installation

For Mirth Connect / Open Integration Engine / BridgeLink

Compatible with version 4.5.2 and above

Step-by-Step Instructions:

1. Copy the library code:

   • Open phantom.js or phantom.min.js from this repository
   • Copy the entire contents of the file

2. Navigate to Code Templates:

   • Go to Channels → Edit Code Template
   • Click New Library
   • Select New Code Templates

3. Create the library:

   • Paste the copied Phantom.js code into the editor
   • Set Context to Select All Context (or choose specific contexts as needed)
   • Give it a name (e.g., "Phantom.js Library")
   • Click Save

4. Use in your scripts:

   • The library will be available as phantom in your script context
   • No additional setup required
   • You can now use all Phantom.js operations in your channel scripts

Note: You can use either phantom.js (readable) or phantom.min.js (minified, smaller size). Both work identically.

For Development/Testing

# Clone the repository
git clone https://github.com/OS366/phantom.git
cd phantom

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

Basic Usage

Phantom.js is a plug-and-play library - no initialization required! Once installed, it's immediately available in your scripts.

Note: Initialization with phantom.init() is optional and only needed if you want to customize settings (e.g., phantom.init({ silent: false })).

String Operations

// Trim whitespace
var cleaned = phantom.strings.operation.trim("  hello world  ");
// Output: "hello world"

// Capitalize
var name = phantom.strings.operation.capitalize("john doe");
// Output: "John doe"

// Replace
var text = phantom.strings.operation.replace("hello", "he", "hi");
// Output: "hillo"

Number Operations

// Basic math
var sum = phantom.numbers.operation.add(10, 5);
// Output: 15

var product = phantom.numbers.operation.multiply(3, 4);
// Output: 12

// Rounding
var rounded = phantom.numbers.operation.round(3.14159, 2);
// Output: 3.14

Map Operations

// Save to channel map
phantom.maps.channel.save("userId", "12345");

// Retrieve from channel map
var userId = phantom.maps.channel.get("userId");
// Output: "12345"

// Check if exists
if (phantom.maps.channel.exists("userId")) {
    // Process user data
}

JSON Operations

// Parse JSON string
var obj = phantom.json.operation.parse('{"name":"John","age":30}');

// Get nested value
var name = phantom.json.operation.get(obj, "name");
// Output: "John"

// Set value
var updated = phantom.json.operation.set(obj, "city", "NYC");

// Check if key exists
phantom.json.operation.has(obj, "name");
// Output: true

Common Patterns

Pattern 1: Data Transformation

// Get data from map
var rawData = phantom.maps.channel.get("rawData");

// Transform it
var cleaned = phantom.strings.operation.trim(rawData);
var upper = phantom.strings.operation.toUpperCase(cleaned);

// Save back
phantom.maps.channel.save("processedData", upper);

Pattern 2: Validation and Calculation

// Get values
var price = phantom.maps.channel.get("price");
var quantity = phantom.maps.channel.get("quantity");

// Validate and calculate
if (phantom.numbers.operation.isNumber(price) && 
    phantom.numbers.operation.isNumber(quantity)) {
    
    var total = phantom.numbers.operation.multiply(
        phantom.numbers.operation.parse(price),
        phantom.numbers.operation.parse(quantity)
    );
    
    phantom.maps.channel.save("total", total);
}

Pattern 3: String Processing Pipeline

var input = phantom.maps.channel.get("input");

// Process through multiple operations
var step1 = phantom.strings.operation.trim(input);
var step2 = phantom.strings.operation.toLowerCase(step1);
var step3 = phantom.strings.operation.capitalize(step2);

phantom.maps.channel.save("output", step3);

Error Handling

All operations throw Error("Invalid operation") on invalid input:

try {
    var result = phantom.numbers.operation.divide(10, 0);
} catch (e) {
    // Handle error: "Invalid operation"
    logger.error("Division failed: " + e.message);
}

Next Steps

• Explore String Operations for all string utilities
• Check out Number Operations for all number utilities
• Learn about Map Operations for working with maps
• See Examples for real-world use cases
• Review Best Practices for tips and patterns