Context Variables Overview

Built-in variables and utilities available in all plugin scripts

What are Context Variables?

Context variables are pre-defined objects that are automatically injected into your plugin scripts. They provide instant access to:

Database operations
HTTP client for API calls
File I/O operations
State management
Configuration access

No imports or initialization needed - just use them directly in your MVEL, JavaScript, or Python plugins.

New to plugins? Check our Quick Reference for a concise overview of all variables.

Available Variables

Essential Variables

`named_jdbc` - Database Access (Recommended)

Type: NamedParameterJdbcTemplate Purpose: Execute SQL queries with named parameters for better readability and safety.

// Query with named parameters
params = ["address": ownerAddr];
result = named_jdbc.queryForMap(
    "SELECT COUNT(*) as count FROM address_utxo WHERE owner_addr = :address",
    params
);

📖 Full Database Guide →

`http` - HTTP Client

Type: PluginHttpClient Purpose: Make HTTP requests with built-in JSON handling.

// GET request
response = http.get("https://api.example.com/data")
 
if (response.isSuccess()) {
    data = response.asJson();
}

📖 Full HTTP Client Guide →

`files` - File Operations

Type: PluginFileClient Purpose: Read/write files with JSON and CSV support.

// Read and write JSON
config = files.readJson("config.json");
if (config.isSuccess()) {
    settings = config.getData();
    // Process...
    files.writeJson("output.json", results);
}

📖 Full File Operations Guide →

`env` - Configuration Access

Type: Environment Purpose: Access environment variables and application properties.

// Get configuration with defaults
apiUrl = env.getProperty("plugin.api.url", "http://localhost:8080");
apiKey = env.getProperty("API_KEY"); // Environment variable

📖 Full Configuration Guide →

`state` & `global_state` - State Management

Type: State Purpose: Plugin or global state with atomic operations.

state: Plugin-specific storage
global_state: Shared across all plugins

// Store progress
state.put("last_block", blockNumber);
 
// Atomic counter
count = state.increment("processed_count");
 
// Thread-safe set operations
state.addToSet("processed_txs", txHash);

📖 Full State Management Guide →

Quick Examples

// Count transactions for an address
params = ["addr": "addr1..."];
result = named_jdbc.queryForMap(
    "SELECT COUNT(*) as cnt FROM tx WHERE address = :addr",
    params
);
count = result["cnt"];

Language Support

All context variables work seamlessly across supported scripting languages:

// MVEL - Direct and concise
result = named_jdbc.queryForMap("SELECT * FROM block WHERE number = :num", ["num": 100]);
state.increment("counter");
response = http.get("https://api.example.com/data");

Best Practices

Handle errors gracefully: Check operation results before using data
Use atomic operations: For counters and concurrent access
Clean up resources: Remove old state data periodically
Never log secrets: Mask sensitive configuration values

Custom Variable Providers

Extend the plugin framework by creating your own Variable Providers:

What is a Variable Provider?

A Java class that implements the VariableProvider interface to add new variables to the plugin context.

How to Create One

Implement the VariableProvider interface
Bundle as a JAR file
Place in plugins/ext-jars folder
Configure in application-plugins.yml
Use the new variables in your plugins

Example Use Cases

Communication: Telegram, Slack, Email variables
Storage: IPFS, S3, Redis variables
Blockchain: Blockfrost, Koios API variables
Monitoring: Prometheus, custom metrics variables

Variable Providers must be thread-safe as they may be accessed concurrently.

Next Steps

Quick Start: See our Variable Quick Reference
Learn by Example: Check Getting Started for complete plugin examples
Advanced Topics: Read the Plugin API Guide

The context variable system makes yaci-store's plugin framework powerful yet simple, providing everything you need to build sophisticated blockchain data processing pipelines.

Plugin API Guide Quick Reference