Version: Next

PASOE Deployment Scripts

User-friendly scripts for setting up and managing OpenEdge PASOE instances with automatic detection of legacy vs. JSON handler formats.

Files Overview

Main Setup Scripts

setup-pasoe-windows.ps1 / setup-pasoe-linux.sh - Complete PASOE setup with comprehensive action-based commands
update-handlers.ps1 / update-handlers.sh - Quick handler updates (most common use case)

Configuration Files

oeprop.properties - Legacy format configuration (works with all OpenEdge versions)
ROOT.handlers / {serviceName}.handlers - JSON format for migrated instances (OpenEdge 12.2+ with migration)

Quick Start

1. Full Setup (First Time)

# Windows
.\setup-pasoe-windows.ps1

# Linux
./setup-pasoe-linux.sh

2. Update Handlers (Most Common)

# Windows
.\update-handlers.ps1

# Linux
./update-handlers.sh

3. Configure API

Copy/Move Resources/[package]-api-config.json anywhere in PROPATH.

Script Actions

setup-pasoe (Full Setup Script)

Action	Description
`full`	Complete setup: create PASOE + webapp + configure + start
`create`	Create PASOE instance only
`webapp-create`	Create dedicated webapp
`webapp-deploy`	Deploy to specific webapp
`handlers`	Update handlers (auto-detect format)
`configure`	Configure PROPATH and handlers (no create/start)
`start`	Start PASOE instance
`stop`	Stop PASOE instance
`restart`	Restart PASOE instance
`migration-check`	Check migration status
`migration-perform`	Perform PASOE migration
`refresh-agents`	Reloads PASOE agents using `tcman jmx refreshagents`
`legacy-handlers`	Force legacy oeprop method (not fully tested)
`json-handlers`	Force JSON handlers method (not fully tested)

update-handlers (Handler Management)

Both Linux and Windows update-handlers scripts now provide full-featured handler management with identical capabilities (in case there are issues, please let us know):

Action Examples:

# Linux - Update handlers
./update-handlers.sh

# Linux - Update handlers with verbose output
./update-handlers.sh -v

# Linux - Use custom handlers file
./update-handlers.sh -f custom-handlers.properties

# Windows - Update handlers
.\update-handlers.ps1

# Windows - Update handlers with verbose output
.\update-handlers.ps1 -VerboseLogging

# Windows - Use custom handlers file
.\update-handlers.ps1 -HandlersFile custom-handlers.properties

Parameters:

-f, --handlers-file <file> - Use custom handlers file instead of oeprop.properties
-r, --resolution <mode> - Set conflict resolution: increment, overwrite, or prompt
-a, --auto-fix - Auto-fix gaps and duplicates by re-numbering handlers
-v, --verbose - Enable verbose logging
--dry-run - Preview changes without executing
-h, --help - Show help message

Features:

Auto-detects legacy vs JSON handler formats
Intelligent handler merging with conflict resolution
Auto-fix enabled by default for gaps, duplicates, and proper specificity ordering
Custom handlers file support
Dry-run mode for safe testing
Port conflict avoidance against existing PASOE instances
Comprehensive logging and error handling

Setting Default Actions

For development convenience, you can set default actions by editing the script variables. For example, to make the script refresh agents by default during development:

Linux (setup_pasoe_linux.sh):

# Near the top of the script, change:
ACTION="full"
# To:
ACTION="refresh-agents"

Windows (setup_pasoe_windows.ps1):

# Near the top of the script, change:
[string]$Action = "full"
# To:
[string]$Action = "refresh-agents"

Then simply run ./setup_pasoe_linux.sh or .\setup_pasoe_windows.ps1 without arguments to perform your default action.

Configuration

The scripts use these templated variables (populated by the generator):

# Environment paths
DLC="/usr/dlc" # OpenEdge installation path
WORK_DIR="/usr/wrk" # PASOE working directory
PROJECT_PATH="/workspaces/openapi-generator-rust/output/server" # Generated project path

# PASOE configuration
PASOE_NAME="oepas112" # PASOE instance name
ABL_APP="[package]" # ABL application name
WEB_APP="ROOT" # Web application name
SERVICE_NAME="ROOT" # Empty for unnamed, name for named services

# Deployment configuration (with development-friendly defaults)
DEPLOYMENT_MODE="" # development | packaged | production
MIGRATION_STRATEGY="" # auto | legacy | modern | prompt
CONFLICT_RESOLUTION="" # increment | overwrite | prompt
AUTO_MIGRATE="" # true | false

# Handlers configuration
[package].ServiceAdapters.OrdersServiceAdapter: /orders/{orderId}
[package].ServiceAdapters.OrdersServiceAdapter: /orders
[package].ServiceAdapters.OrdersServiceAdapter: /ping

Deployment Modes (only development should be used at this point)

development: Development-friendly defaults, verbose logging
packaged: Optimized for packaged deployments
production: Production-ready configuration with security hardening

Migration Strategies

auto: Automatically detect and use appropriate format
legacy: Force legacy oeprop format
modern: Force JSON format (requires migration)
prompt: Interactive selection of migration approach

Conflict Resolution

increment: Auto-increment handler numbers to avoid conflicts
overwrite: Overwrite existing handlers
prompt: Interactive conflict resolution

Handler Configuration

The scripts support multiple handler configuration formats and automatically convert between them:

Configuration File Formats

Legacy Format (oeprop.properties)

The scripts accept handlers in oeprop.properties format with two variations:

Full Path Format:

+{AblApp}.{WebApp}.WEB.handler1=[package].ServiceAdapters.OrdersServiceAdapter: /orders/{orderId}
+{AblApp}.{WebApp}.WEB.handler2=[package].ServiceAdapters.StoreServiceAdapter: /store/order

Simple Format (handler number only):

handler1=[package].ServiceAdapters.OrdersServiceAdapter: /orders/{orderId}
handler2=[package].ServiceAdapters.StoreServiceAdapter: /store/order

JSON Format (Modern - OpenEdge 12.2+ with migration)

The ROOT.handlers or {serviceName}.handlers file uses JSON format:

{
  "version": "2.0",
  "serviceName": "ROOT",
  "handlers": [
    {
      "uri": "/orders/{orderId}",
      "class": "[package].ServiceAdapters.OrdersServiceAdapter",
      "enabled": true
    }
  ]
}

Handler Format Detection

The scripts automatically detect which handler format to use:

Legacy Format (oeprop)

Used when: No {serviceName}.handlers or ROOT.handlers file exists
Method: oeprop commands from oeprop.properties
Compatible: All OpenEdge versions

JSON Format (Migrated)

Used when: {serviceName}.handlers or ROOT.handlers file exists
Method: Copy JSON file + tcman jmx refreshWeb

Service Types

Unnamed Services (Default)

SERVICE_NAME is empty
Uses ROOT directory
Handlers file: ROOT.handlers
URL format: http://host:port/{webapp}/web/{uri}

Named Services

SERVICE_NAME has a value
Uses {serviceName} directory
Handlers file: {serviceName}.handlers
URL format: http://host:port/{webapp}/web/{serviceName}/{uri}

Examples

Development Workflow

# Initial setup
./setup-pasoe-linux.sh full

# After code changes - just update handlers
./update-handlers.sh
# or use the setup script
./setup-pasoe-linux.sh handlers

# Dry run to preview changes
./update-handlers.sh --dry-run

Production Deployment

# Create PASOE instance
./setup-pasoe-linux.sh create

# Configure without starting
./setup-pasoe-linux.sh configure

# Start when ready
./setup-pasoe-linux.sh start

Webapp Management

# Create dedicated webapp
./setup-pasoe-linux.sh webapp-create

# Deploy to specific webapp
./setup-pasoe-linux.sh webapp-deploy

# Stop and restart PASOE
./setup-pasoe-linux.sh stop
./setup-pasoe-linux.sh restart

Migration Workflow

# Check migration status
./setup-pasoe-linux.sh migration-check

# Perform migration to JSON format
./setup-pasoe-linux.sh migration-perform

# Merge handlers with conflict resolution
./setup-pasoe-linux.sh handlers --auto-fix

Advanced Handler Management

# Use custom handlers file
./update-handlers.sh -f custom-handlers.properties

# Auto-fix gaps and duplicates
./update-handlers.sh --auto-fix

# Overwrite existing handlers
./update-handlers.sh --resolution overwrite

# Interactive conflict resolution
./update-handlers.sh --resolution prompt

# Verbose output with dry run
./update-handlers.sh --verbose --dry-run

# Windows examples
.\update-handlers.ps1 -HandlersFile custom.properties -AutoFix -Verbose
.\update-handlers.ps1 -Resolution overwrite -DryRun

Troubleshooting

# Check what would happen
./setup-pasoe-linux.sh handlers --dry-run

# Get help
./setup-pasoe-linux.sh --help
./update-handlers.sh --help

Error Handling

OpenEdge not found: Check DLC path configuration
PASOE not found: Run create action first
Handler files missing: Ensure configuration files are present
Permission issues: Run with appropriate privileges

Platform Support

Windows: PowerShell scripts (.ps1)
Linux: Bash scripts (.sh)

Security Notes

Scripts validate OpenEdge installation before proceeding
Configuration files contain sensitive paths - protect accordingly
Consider running with least privilege in production

Support

For issues or questions:

Check the logs for detailed error messages (use --verbose on linux or -VerboseLogging on windows)
Use --dry-run to preview actions
Verify OpenEdge installation and DLC paths
Ensure PASOE instance exists before updating handlers

Files Overview​

Main Setup Scripts​

Configuration Files​

Quick Start​

1. Full Setup (First Time)​

2. Update Handlers (Most Common)​

3. Configure API​

Script Actions​

setup-pasoe (Full Setup Script)​

update-handlers (Handler Management)​

Setting Default Actions​

Configuration​

Deployment Modes (only development should be used at this point)​

Migration Strategies​

Conflict Resolution​

Handler Configuration​

Configuration File Formats​

Legacy Format (oeprop.properties)​

JSON Format (Modern - OpenEdge 12.2+ with migration)​

Handler Format Detection​

Legacy Format (oeprop)​

JSON Format (Migrated)​

Service Types​

Unnamed Services (Default)​

Named Services​

Examples​

Development Workflow​

Production Deployment​

Webapp Management​

Migration Workflow​

Advanced Handler Management​

Troubleshooting​

Error Handling​

Platform Support​

Security Notes​

Support​