Automation API and wnd-automate

Sessions and their short names

Each open session gets a letter from A to Z, in the order it opened. The status line shows it while the API is on, such as Session A. A session keeps its letter while it stays open, like an EHLLAPI presentation space ID. Programs can also use the connection’s name, such as Production.

Rows and columns count from 1, as in EHLLAPI. Screen text comes back as Unicode, one character for each position.

Script with wnd-automate

wnd-automate sends one request each time it runs. Any language that can start a program can use it, including PowerShell, a batch file or a shell script.

It’s installed with WND Terminal. On Windows it’s wnd-automate.exe in the app’s folder, such as C:\Program Files\WND Terminal. On a Mac it’s inside the app, at /Applications/WND Terminal.app/Contents/MacOS/wnd-automate.

wnd-automate list
wnd-automate A wait-text "Logon ===>" 20
wnd-automate A keys "wnduser@E"
wnd-automate A wait-ready 10
wnd-automate --json A fields

Add --json to get WND Terminal’s answer as JSON. The exit code tells a script what happened.

A logon script

This shell script opens the saved connection called Production, logs on to TSO and saves the screen to a file.

set -e
wnd-automate open Production 60
wnd-automate Production wait-text "Logon ===>" 30
wnd-automate Production keys "@0${TSO_USER}@E"
wnd-automate Production wait-ready 30
wnd-automate Production text > screen.txt

This PowerShell example clears the screen and lists its input fields.

wnd-automate A keys "@C"
wnd-automate A wait-ready 10
$fields = (wnd-automate --json A fields | ConvertFrom-Json).fields | Where-Object { -not $_.protected }
$fields | Format-Table row, col, length, text

Keys

Keys are written the way EHLLAPI’s SendKey writes them. "wnduser@E" types wnduser and presses Enter.

WND Terminal checks the whole string before it types anything. A code it doesn’t know, or a key it doesn’t have, is refused with the key’s name. After Enter or another key that goes to the host, it waits for the answer before it types the rest. So "@ETSO@E" works as it would for a person at the keyboard.

Writing your own client

Programs can also talk to the pipe or socket directly. Each message is one JSON object on one line. The first request must be hello, and every request carries an id that comes back in the answer.

→ {"id":1,"op":"hello","version":1,"client":"logon"}
← {"id":1,"ok":true,"result":{"app":"WND Terminal","protocol":1,"can_open":true}}
→ {"id":2,"op":"wait_text","session":"A","text":"Logon ===>","timeout":20}
← {"id":2,"ok":true,"result":{"found":true,"row":3,"col":1,"pos":161}}
→ {"id":3,"op":"keys","session":"A","keys":"jsmith@E"}
← {"id":3,"ok":true,"result":{"sent":2,"keyboard_locked":true}}

Each EHLLAPI function has a request that does the same job.

File transfer requests

file_list, file_get, file_put, job_submit and job_output use a saved site of the file transfer client (FTP, FTPS or SFTP), without a session. Each request connects, does one thing and closes. The site’s password goes with the request and is never kept or logged. The organization’s file transfer rules apply, and every transfer is in the audit log as done by a program.

Programs written for other emulators

WND Terminal comes with EHLLAPI and WinHLLAPI DLLs (32-bit and 64-bit, under the names programs load), COM objects with the Extra!, PCOMM and Reflection object models, and the .NET library WndTerminal.Automation. They all use the requests on this page, so programs written for another emulator keep working without changes, under the same rules. IT turns them on with MSI properties. See EHLLAPI, COM and .NET. The Migration readiness report lists scripts that drive an emulator, so you know which ones to test.

What programs can’t do

• Read hidden fields. Password fields always read as blanks. Programs can type into them.
• See masked values. Card numbers and IT’s MaskPatterns are masked in everything a program reads, and a search can’t find them by their real digits.
• Read the screen when copying is off. With AllowCopy = false, programs can’t read the screen’s text. They can still search and wait for text.
• Get round the policy. Connections a program opens go through the license and IT’s connection rules like any other.
• Type over someone. A program can reserve a session’s keyboard, and the person is told why their typing is refused. While Fill from Excel or Ask WND is typing in a session, programs can’t type there.
• See what the person types. There’s no keystroke intercept. What a program types isn’t kept as recent typing or recorded into a macro.

Turning it off, and the audit log

The API is on unless IT turns it off. Set AllowAutomation to false, or enable Turn off the automation API (EHLLAPI-style scripting) in Group Policy. Nothing then listens, and About WND Terminal says your organization turned it off. A policy that can’t be read turns it off too. See Policy settings.

The audit log records each program that connects (automation.attach) and disconnects (automation.detach), with its program name and process ID. Keys and reads aren’t recorded. See Audit log to Splunk and Sentinel.

For routines a person runs from the keyboard, a macro is usually simpler. Macros run inside WND Terminal, in the desktop app and in a browser.