Basic Usage¶

Introduction¶

The basic usage of 3270Connect involves running workflows defined in a configuration file. The configuration file specifies a sequence of actions to perform, such as connecting to a host, filling fields, and capturing screens.

To run a workflow, use the following command:

3270Connect -config workflow.json

-config: Specifies the path to the configuration file (default is "workflow.json").
-token: Provides a one-time RSA token that replaces any {{token}} placeholder in workflow step text during execution.
-showConnectionErrors: By default, connection failures for the Connect step are informational and do not increment the failed workflow counter. Set this flag to surface connection failures as errors and include them in the failure tally.
WaitForField (config, default true): When enabled, the workflow waits for the terminal to unlock an input field before each step after a successful Connect. Supports both simple boolean and detailed configuration:
Boolean format: "WaitForField": true or "WaitForField": false (uses defaults: 1s delay, 10 retries)
Object format: "WaitForField": { "Delay": 2, "Retries": 5 } (custom delay in seconds and retry count)
Defaults: Delay defaults to 1 second if not specified. Retries defaults to 10 if not specified.
The WaitForField setting applies to all steps in the workflow once connected (not just after the Connect step).
-workflowTimeout: Hard timeout (seconds) per workflow. A zero value disables the per-workflow timeout.
-verboseFailures: Emit concise failure-only logs (step, script port, error) without enabling full verbose mode-useful for high-concurrency runs where you only want failure diagnostics.
-verboseScreenCaptureFailures: When enabled alongside -verboseFailures, automatically captures the terminal screen as plain text whenever a workflow step fails or a WaitForField timeout occurs. Captures are limited to 5 total across all concurrent workflows to prevent disk exhaustion. Files are named using the format failure_[scriptPort]_step[stepIndex]_[timestamp].txt and saved in the current directory. The capture file path is included in the failure log message.
-bar: Enable compact progress bars and hide the live INFO rows. (Deprecated alias: -enableProgressBar.)

Injecting a runtime RSA token¶

Workflows can reference a transient RSA token by placing {{token}} in any Text field. Supply the token when launching 3270Connect:

3270Connect -config workflow.json -token 123456

The placeholder will be substituted immediately before each step runs, ensuring the token is never stored in the workflow file.

Running Workflows¶

Single Workflow¶

To run a single workflow, create a JSON configuration file that describes the workflow steps. Here's an example configuration file:

{
  "Host": "10.27.27.62",
  "Port": 3270,
  "EveryStepDelay": { "Min": 0.1, "Max": 0.3 },
  "WaitForField": true, // optional (default true) to wait before all steps once connected
  "OutputFilePath": "output.html", // optional; if omitted a temp file is used
  "RampUpBatchSize": 10, //optional for concurrency runs
  "RampUpDelay": 1, //optional for concurrency runs
  "EndOfTaskDelay": { "Min": 30, "Max": 90 },
  "Steps": [
    {
      "Type": "Connect"
    },
    {
      "Type": "AsciiScreenGrab"
    },
    {
      "Type": "CheckValue",
      "Coordinates": {"Row": 1, "Column": 29, "Length": 24},
      "Text": "3270 Example Application"
    },
    {
      "Type": "FillString",
      "Coordinates": {"Row": 5, "Column": 21},
      "Text": "user1-firstname"
    },
    {
      "Type": "FillString",
      "Coordinates": {"Row": 6, "Column": 21},
      "Text": "user1-lastname"
    },
    {
      "Type": "AsciiScreenGrab"
    },
    {
      "Type": "StepDelay",
      "StepDelay": { "Min": 1.0, "Max": 2.0 }
    },
    {
      "Type": "PressEnter"
    },
    {
      "Type": "CheckValue",
      "Coordinates": {"Row": 1, "Column": 29, "Length": 24},
      "Text": "3270 Example Application"
    },
    {
      "Type": "AsciiScreenGrab"
    },
    {
      "Type": "Disconnect"
    }
  ]
}

In this example, an EveryStepDelay range keeps the steps paced, the StepDelay step adds a longer pause before pressing Enter, and an EndOfTaskDelay holds the virtual user after completion to mirror real think-time. The workflow connects to a host, captures the screen, fills both fields, presses Enter, captures the screen again, and then disconnects. By default, WaitForField will wait before all steps once connected.

You can customize the WaitForField behavior using the object format:

  "WaitForField": { "Delay": 2, "Retries": 5 }

This example uses a 2-second delay per retry and allows up to 5 retries. If you disable the global setting ("WaitForField": false), you can still add an explicit step where you need it:

    { "Type": "WaitForField", "Delay": 2 }

Place it after Connect or after navigation steps (e.g., PressEnter) when the host is slow to render the next screen.

Concurrent Workflows¶

You can run multiple workflows concurrently by specifying the -concurrent and -runtime flags:

-concurrent: Sets the number of concurrent workflows to run (default is 1).
-runtime: Specifies the duration to run workflows in seconds (only used in concurrent mode).

For example, to run two workflows concurrently for 60 seconds, use:

3270Connect -config workflow.json -concurrent 2 -runtime 60

Configuration¶

Headless Mode¶

You can run 3270Connect in headless mode using the -headless flag. Headless mode is useful for running workflows without a graphical user interface.

3270Connect -config workflow.json -headless

Verbose Mode¶

To enable verbose mode for detailed output, use the -verbose flag.

3270Connect -config workflow.json -verbose

Failure-only verbose logging¶

To log only failing steps (without the volume of full verbose output), use the -verboseFailures flag. This is helpful when running many concurrent workflows and you just want to capture which steps failed.

3270Connect -config workflow.json -verboseFailures

Screen capture on failures¶

When troubleshooting intermittent automation failures in high-concurrency environments, you can enable automatic screen captures using the -verboseScreenCaptureFailures flag. This flag works in conjunction with -verboseFailures to capture the terminal screen whenever a workflow step fails or a WaitForField timeout occurs.

3270Connect -config workflow.json -verboseFailures -verboseScreenCaptureFailures

Key features: - Captures are saved as plain text files in the current directory - Files are named using the format failure_[scriptPort]_step[stepIndex]_[timestamp].txt - Limited to 5 total captures across all concurrent workflows to prevent disk exhaustion - The capture file path is automatically included in the failure log message

Example failure log with screen capture:

Workflow failure on scriptPort 5001 at step 4 (CheckValue): CheckValue failed. Expected: LOGIN, Found: ERROR | Screen captured to: failure_5001_step4_1234567890.txt

Screen readiness (WaitForField)¶

The WaitForField configuration controls whether the workflow waits for the terminal to unlock an input field before each step once connected. It applies to all steps in the workflow (not just after the Connect step).

Configuration formats:

Boolean format (backward compatible):
"WaitForField": true - Enabled with defaults (1s delay, 10 retries)
"WaitForField": false - Disabled globally
Object format (customizable):
"WaitForField": { "Delay": 2, "Retries": 5 } - Enabled with custom settings
Delay: Timeout in seconds per retry attempt (default: 1)
Retries: Maximum number of retry attempts (default: 10)

Usage examples:

// Use defaults
"WaitForField": true

// Custom delay and retries
"WaitForField": { "Delay": 2, "Retries": 15 }

// Disable automatic waiting
"WaitForField": false

Per-step override: You can also add an explicit WaitForField step wherever you need an extra wait (e.g., after PressEnter). Use the Delay parameter in the step to override the timeout for that specific wait.

Workflow timeout¶

-workflowTimeout: Hard timeout (seconds) applied to each workflow run. Default 120; set to 0 to disable. When the timeout is hit, the workflow stops without counting as a connect failure.

startPort Flag¶

The -startPort flag allows you to specify the starting port for the sample application. This help to prevent port usage conflicts when running 3270Connect multiple times on the same machine.

Use it as follows:

3270Connect -config workflow.json -startPort 5000

Examples¶

Let's explore some common use cases with examples:

1. Running a Basic Workflow¶

Run a basic workflow defined in "workflow.json":

3270Connect -config workflow.json

2. Running Multiple Workflows Concurrently¶

Run two workflows concurrently for 60 seconds:

3270Connect -config workflow.json -concurrent 2 -runtime 60

3. Running in Headless Mode¶

Run a workflow in headless mode:

3270Connect -config workflow.json -headless

4. Using the API Mode¶

Run 3270Connect in API mode and interact with it using HTTP requests.

API Mode: Discover how to run 3270Connect as an API server for advanced automation.

5. Running a 3270 sample application to help with testing the workflow features¶

As well as performing workflows on a 3270 running instance, 3270Connect can emulate a 3270 sample application using the github.com/racingmars/go3270 framework. Full credit go to racingmars for this great open source repo.

Note

Run a test 3270 sample application to assist with testing 3270Connect workflow features:

Available Apps

[1] Example 1 application from https://github.com/racingmars/go3270
[2] Dynamic RSS Reader

3270Connect -runApp

or

3270Connect -runApp [number]

Once running and listening on port 3270, run a separate 3270 Connect to run a workflow against the sample 3270 application. The "workflow.json" provided with the root folder of the repo works with the sample application.

Docker Usage¶

Linux¶

Pull the latest image:

docker pull 3270io/3270connect-linux:latest

Run the container with a configuration file:

docker run -it -v $(pwd)/workflow.json:/app/workflow.json -v $(pwd)/output.html:/app/output.html -p 3270:3270 3270io/3270connect-linux:latest -config /app/workflow.json

Run in headless mode:

docker run -it -v $(pwd)/workflow.json:/app/workflow.json -v $(pwd)/output.html:/app/output.html -p 3270:3270 3270io/3270connect-linux:latest -config /app/workflow.json -headless

Run in verbose mode:

docker run -it -v $(pwd)/workflow.json:/app/workflow.json -v $(pwd)/output.html:/app/output.html -p 3270:3270 3270io/3270connect-linux:latest -config /app/workflow.json -verbose

Run multiple workflows concurrently:

docker run -it -v $(pwd)/workflow.json:/app/workflow.json -v $(pwd)/output.html:/app/output.html -p 3270:3270 3270io/3270connect-linux:latest -config /app/workflow.json -concurrent 2 -runtime 60

Run a test 3270 sample application:

docker run -it -p 3270:3270 3270io/3270connect-linux:latest -runApp

Run a specific test 3270 sample application:

docker run -it -p 3270:3270 3270io/3270connect-linux:latest -runApp [number]

Windows¶

Pull the latest image:

docker pull 3270io/3270connect-windows:latest

Run the container with a configuration file:

docker run -it -v ${PWD}/workflow.json:/app/workflow.json -v ${PWD}/output.html:/app/output.html -p 3270:3270 3270io/3270connect-windows:latest -config /app/workflow.json

Run in headless mode:

docker run -it -v ${PWD}/workflow.json:/app/workflow.json -v ${PWD}/output.html:/app/output.html -p 3270:3270 3270io/3270connect-windows:latest -config /app/workflow.json -headless

Run in verbose mode:

docker run -it -v ${PWD}/workflow.json:/app/workflow.json -v ${PWD}/output.html:/app/output.html -p 3270:3270 3270io/3270connect-windows:latest -config /app/workflow.json -verbose

Run multiple workflows concurrently:

docker run -it -v ${PWD}/workflow.json:/app/workflow.json -v ${PWD}/output.html:/app/output.html -p 3270:3270 3270io/3270connect-windows:latest -config /app/workflow.json -concurrent 2 -runtime 60

Run a test 3270 sample application:

docker run -it -p 3270:3270 3270io/3270connect-windows:latest -runApp

Run a specific test 3270 sample application and listening port:

docker run -it -p 3270:3270 3270io/3270connect-windows:latest -runApp [number] -runApp-port [portNumber]

3270Connect Basic Usage¶

Conclusion¶

The 3270Connect command-line utility offers a flexible way to automate interactions with terminal emulators. Whether you need to connect to hosts, manipulate screens, or run multiple workflows concurrently, 3270Connect has you covered. Explore its features, experiment with different workflows, and streamline your terminal automation tasks.

That's it! You're now ready to use 3270Connect for your terminal automation needs, including the API mode for more advanced automation scenarios.