View source for Analytica Command Line/Automation

[[category:File Commands]]
[[Category:Analytica User Guide]]
{{ReleaseBar}}

''New in [[Analytica 7.2]].'' See also the parent page, [[Analytica Command Line]].

__TOC__

== Why automation mode exists ==

A dialog box is fine when a person is sitting in front of Analytica. It is fatal when nobody is. A single unexpected "Save changes?" or "This variable failed its Check" dialog will stop an overnight benchmark, a QA sweep, or an AI agent's session dead, and you often will not find out until much later that nothing after that point ran.

Launching with <code>/Automation</code> answers those dialogs for you:

:<code>Analytica.exe /Automation MyModel.ana</code>

Every modal dialog that would block gets an answer — either a sensible built-in default, or an answer computed by a handler function you register with [[RegisterAutomationModalHandler]]. The run keeps going.

Three things are worth being clear about up front:

* '''It is not a headless mode.''' The main window, diagrams, result windows, HTML dialogs, and Assista all work exactly as usual. You can watch the run happen, and you can take over with the mouse at any point. If you want Analytica without a user interface, that is a different thing entirely.
* '''It changes nothing unless you ask for it.''' Without the flag, every dialog behaves exactly as it always has. Automation mode is a property of the process, set once from the command line.
* '''The defaults are chosen to protect the model under test,''' not to make progress at all costs. Where "keep going" and "do not touch anything" conflict, automation picks "do not touch anything" — see [[#What the built-in defaults do]].

== Getting started ==

=== Just run it ===

Start with no handler at all. The built-in defaults handle a surprising amount on their own:

:<code>Analytica.exe /Automation /eval:Run_batch "Claim analysis.ana"</code>

If your model already runs unattended except for the occasional dialog, this may be all you need.

=== See which dialogs your scenario actually poses ===

Before writing any handler, find out what you are dealing with. Add a trace file:

:<code>Analytica.exe /Automation /AutomationTrace:C:\Temp\run1.jsonl MyModel.ana</code>

Every dialog is appended to <code>run1.jsonl</code> as one JSON object per line, recording what it said and how it was answered. See [[#The trace log]].

You can also run the trace ''without'' <code>/Automation</code>:

:<code>Analytica.exe /AutomationTrace:C:\Temp\baseline.jsonl MyModel.ana</code>

This is '''observe mode'''. Dialogs appear and block normally, exactly as for any other user, and the log records what ''you'' chose. It is the easiest way to walk a scenario by hand once and get a complete inventory of its dialogs, along with the answers a human considered correct — which is a good starting specification for the handler you are about to write.

== What the built-in defaults do ==

With no handler registered, dialogs are answered as follows.

{| class="wikitable"
! Dialog !! Automatic answer !! Why
|-
| Message boxes ([[MsgBox]] and internal ones) || The default button — the one '''Enter''' would press || Matches what a user pressing through quickly would get
|-
| [[AskMsgText]] || The «default» text || The value the model already proposed
|-
| [[AskMsgNumber]] || The «default» number ||
|-
| [[AskMsgChoice]] || The «default» option ||
|-
| '''Save changes?''' on close or quit || '''No''' — discard || An unattended run must never overwrite the model it is testing
|-
| Evaluation warnings (Check failures, bad values) || Ignore ''this one'' || See the note below
|-
| "Stop evaluating and edit the definition?" || '''No''' || The error is already recorded; opening an editor mid-run helps nobody
|-
| File open / file save prompts || Fail, as if cancelled || Guessing a filename is worse than failing. A handler can supply a real path
|-
| Other template-based dialogs || Cancel, ''without running the dialog'' || Cancelling a dialog that never opened has no side effects
|-
| Externally-changed linked module || Later (keep what is in memory) ||
|-
| Legal agreement, license prompts || Accepted || So a fresh machine does not hang at startup
|-
| Unrecognized command-line option || Continue || Never <code>exit(-1)</code> in the middle of a batch
|}

Two of these deserve emphasis.

'''Save changes is answered No.''' This is deliberately the opposite of what Analytica's existing headless/server path does, which silently saves. A benchmark that mutates its fixture model between runs is not measuring what you think it is measuring, and a QA run that rewrites the model under test destroys the evidence. If your automation genuinely wants to save, make that explicit — have your handler answer <code>'Yes'</code> to the <code>'SaveChanges'</code> dialog, so the intent is visible in the trace.

'''Warnings are ignored once, not switched off.''' Pressing "Ignore Warnings" interactively silences warnings for the rest of the session. Automation deliberately does not do that: each warning is cleared individually, so the tenth warning is still reported to your handler and still written to the trace. You get a complete record instead of a log that goes quiet after the first problem.

Dialogs raised on a worker thread (during parallel evaluation, for instance) always take the built-in default and are recorded with <code>"source":"offthread-default"</code>. Your handler is only consulted on the main thread.

== Writing an automation handler ==

When the defaults are not enough — when the answer depends on ''which'' dialog it is, or when you want to record something, or ask a person or an orchestrator — register a handler:

:<code>[[RegisterAutomationModalHandler]]( ''handler'' )</code>

The handler is any callable: a handle to a [[UDF]], a local (lambda) function, or a Python callable. It takes one parameter, receives a struct describing the dialog, and returns the answer. It may be registered at any time, but it is only consulted when the process is running with <code>/Automation</code>, so it is harmless to leave the registration in a model that people also use interactively.

The simplest useful handler answers nothing and just watches:

<code><pre>
Function Log_dialogs( s : atom ) :=
    ( WriteTextFile( 'dialogs.log',
                     s->seq & '  ' & s->kind & '  ' & s->caption & Chr(13) & Chr(10),
                     append: True, warn: False );
      Null )              { Null means: use the built-in default }
</pre></code>

:<code>[[RegisterAutomationModalHandler]]( [[Handle]](Log_dialogs) )</code>

=== What the handler receives ===

The parameter is an <code>AutomationDialogStruct</code> with these fields, read with the <code>-></code> operator:

{| class="wikitable"
! Field !! Meaning
|-
| <code>kind</code> || The family of dialog: <code>'MsgBox'</code>, <code>'Ask'</code>, <code>'AskText'</code>, <code>'AskNumber'</code>, <code>'AskChoice'</code>, <code>'FileOpen'</code>, <code>'FileSave'</code>, <code>'Warning'</code>, <code>'Redefine'</code>, <code>'SaveChanges'</code>, <code>'LinkedModuleChanged'</code>, <code>'Win32Dialog'</code>, <code>'MacAppDialog'</code>, <code>'Alert'</code>, <code>'Comment'</code>, <code>'CmdLineWarning'</code>
|-
| <code>id</code> || A stable identity for the specific dialog when one is known, such as <code>'SaveQuitting'</code> or <code>'CheckFailure'</code>, or the internal name of a template dialog. [[Null]] otherwise
|-
| <code>caption</code> || The title bar text
|-
| <code>body</code> || The message text
|-
| <code>buttons</code> || A list of the button names offered, such as <code>['Yes','No','Cancel']</code>. [[Null]] when the dialog is not a button dialog
|-
| <code>defaultAnswer</code> || What the built-in default would answer, as text. Useful for logging, and for "default unless I say otherwise" logic
|-
| <code>obj</code> || A [[Handle]] to the object the dialog is about, when there is one. [[Null]] otherwise
|-
| <code>att</code> || The attribute involved, as text, when relevant
|-
| <code>seq</code> || The sequence number of this dialog, matching the <code>seq</code> in the trace log
|}

=== What the handler returns ===

{| class="wikitable"
! Return !! Effect
|-
| [[Null]] || Use the built-in default. This is the right answer most of the time
|-
| Text || For a button dialog, the name of the button to press: <code>'Yes'</code>, <code>'No'</code>, <code>'OK'</code>, <code>'Cancel'</code>, <code>'Ignore'</code>, <code>'Retry'</code>, <code>'Abort'</code>. For <code>'AskText'</code>, the text to enter. For <code>'FileOpen'</code> or <code>'FileSave'</code>, the full path of the file to use
|-
| Number || For <code>'AskNumber'</code>, the value. For <code>'AskChoice'</code>, the 1-based index of the option to choose
|}

Answering a file dialog with a path is often the single highest-value thing a handler does: instead of the prompt failing, the run proceeds with exactly the file your driver wants, chosen at the moment it is asked for.

A handler that returns [[Null]] for everything behaves exactly like no handler at all, which is how you stand a handler down without unregistering it.

=== A worked example ===

<code><pre>
Function Bench_handler( s : atom ) :=
  Var body := If IsNull(s->body) Then '' Else s->body;
  ( { 1. Record everything, whatever we decide below. }
    WriteTextFile( 'bench-dialogs.log',
                   s->seq & Chr(9) & s->kind & Chr(9) & s->defaultAnswer & Chr(9) & body & Chr(13) & Chr(10),
                   append: True, warn: False );

    { 2. Feed the scenario the input file it is about to ask for. }
    If s->kind = 'FileOpen' Then Bench_input_path

    { 3. This scenario is supposed to reach the end; a Check failure means it did not. }
    Else If s->kind = 'Warning' Or s->id = 'CheckFailure' Then
       ( WriteTextFile( 'bench-failures.log', 'FAILED: ' & body & Chr(13) & Chr(10),
                        append: True, warn: False );
         Null )

    { 4. Everything else: whatever the built-in default is. }
    Else Null )
</pre></code>

=== Rules the handler runs under ===

* '''Main thread only.''' Dialogs raised on worker threads take the built-in default (traced as <code>offthread-default</code>).
* '''No re-entry.''' If your handler itself causes a dialog — and a [[WriteTextFile]] easily can — that inner dialog takes the built-in default rather than calling your handler again. It is recorded as <code>reentrant-default</code>, so you can see it happened.
* '''Errors are contained.''' If your handler raises an error, the built-in default is used, the trace records <code>handler-error-fallback</code>, and the run continues. A broken handler degrades to the defaults; it does not stop the run and never pops up a dialog of its own about the failure.
* '''It cannot dirty the model.''' The handler runs with model-dirtying and autosave suppressed, so merely observing a dialog cannot mark the model changed. Note this means a handler is not the place to modify the model.
* '''The error state is preserved.''' Most of these dialogs occur while an error or warning is pending. That state is saved before your handler runs and restored afterwards, so your handler sees a clean slate and does not disturb the error being reported.
* '''It is timed.''' The wall-clock time your handler takes is recorded in the trace as <code>handlerMs</code>, so you can see how much your instrumentation perturbs a benchmark.

== The trace log ==

<code>/AutomationTrace:''filename''</code> writes [https://jsonlines.org JSON Lines] — one self-contained JSON object per line, appended, each written in a single operation so that concurrent processes never interleave a record.

A run starts with:

<code><pre>
{"ev":"start","pid":66668,"exe":"...\\Analytica.exe","ver":"7.2.0.318","cmdLine":"...","automation":true,"t":"2026-08-07T11:29:47.694"}
</pre></code>

and then one record per dialog:

<code><pre>
{"ev":"dialog","seq":5,"t":"2026-08-07T11:29:48.108","thread":80872,"kind":"MsgBox",
 "caption":"Overwrite?","body":"...","buttons":["Yes","No"],
 "response":"No","source":"handler","handlerMs":0.939}
</pre></code>

The field to look at first is <code>source</code>, which says where the answer came from:

{| class="wikitable"
! <code>source</code> !! Meaning
|-
| <code>default</code> || The built-in default answered
|-
| <code>handler</code> || Your registered handler answered
|-
| <code>handler-error-fallback</code> || Your handler raised an error; the default was used and the run continued
|-
| <code>reentrant-default</code> || The dialog was raised while your handler was running, so the default was used
|-
| <code>offthread-default</code> || The dialog was raised off the main thread, so the handler was not consulted
|-
| <code>shown</code> || Observe mode: the dialog was actually displayed and this is what the user chose
|}

Registering a handler also writes a <code>{"ev":"handlerInstalled", ...}</code> record, so you can confirm from the log alone that your library really did get loaded and registered.

Body text is truncated at 4 KB, with <code>"bodyTruncated":true</code> added when that happens.

Because the file is appended rather than truncated, a driver can create it, start tailing it, and then launch Analytica — no polling for the file to appear, and no race at startup.

=== Reading the trace back in Analytica ===

The log is ordinary text, so a model can read its own trace:

:<code>Var lines := [[SplitText]]( [[ReadTextFile]]('run1.jsonl'), Chr(10) );</code>
:<code>[[ParseJSON]]( lines[@Line = 2] )</code>

This is handy for a QA model that runs scenarios and then asserts on which dialogs appeared.

== Putting it in a library ==

You will usually want the handler in a library rather than in the model under test, so that the model stays exactly as shipped and the automation is bolted on from outside. Load it with <code>/lib:</code>:

:<code>Analytica.exe /lib:BenchmarkDriver.ana /Automation /AutomationTrace:C:\Temp\run1.jsonl MyModel.ana</code>

Libraries named with <code>/lib:</code> load before the model, into <code>SysLib_Customizations</code>, and stay loaded as models are closed and opened. So a driver library can register its handler once at startup and keep answering dialogs across many models in one session. See the <code>/lib:</code> entry on [[Analytica Command Line]].

To have the library register itself as it loads, put the [[RegisterAutomationModalHandler]] call in a button in the library and mark that button to evaluate proactively, or call it from the driver's entry point before it opens the first model.

== Uses ==

=== A benchmark driver ===

Everything that makes benchmarks unreliable — a stray dialog stalling one run, a fixture model quietly rewritten between runs, a scenario that silently stops halfway — is what this mode is for.

* Launch each run with <code>/Automation</code> and a per-run <code>/AutomationTrace:</code> file.
* Let the built-in Save-changes default protect your fixture models. Verify it by checking that the <code>.ana</code> file's timestamp is unchanged after the run.
* Have the handler answer <code>FileOpen</code> with the scenario's input file, so the same model can be run against many datasets without editing it.
* Treat the trace as part of the result. A run whose trace contains a <code>Warning</code> or <code>CheckFailure</code> record did not really succeed, even if it finished.
* Watch <code>handlerMs</code> to confirm your instrumentation is not itself distorting the timings.

=== An AI agent, such as Claude Code ===

An agent driving Analytica has the same problem as a benchmark, only worse: it cannot see a modal dialog, and a blocked Analytica just looks like one that stopped responding.

Combine automation mode with the [[MCP server in Analytica]]:

:<code>Analytica.exe /Automation /mcp:6541 /AutomationTrace:C:\Temp\agent.jsonl MyModel.ana</code>

Now the agent's tool calls cannot deadlock behind a dialog. Some things worth doing in the handler in this setup:

* '''Make dialogs visible to the agent.''' Write each dialog to a file, or into a model variable, that you expose through an <code>{@mcpTool}</code> UDF. The agent can then ask "what did Analytica ask me while that ran?" and get a real answer instead of guessing why a call returned nothing.
* '''Answer according to what the agent is trying to do.''' A handler can read a model variable that the agent set through another tool, and use it to decide — for instance, permitting a save only while an "allow writes" flag is on.
* '''Ask the orchestrator.''' <code>[[RunConsoleProcess]]</code> with <code>block: True</code> lets the handler call out to a broker process and wait for its answer, so a genuinely ambiguous dialog can be escalated to the agent, or to a person, instead of being defaulted. Keep the timeout on the broker's side.
* '''Talk to a browser-based driver.''' If the agent is already attached through <code>/remote-debugging-port:</code>, the handler can call <code>ExecuteJavaScript</code> on a <code>CefWindow</code> object to signal what just happened. This is fire-and-forget and does not block the run.

=== Automated QA ===

* Drive a scenario with <code>/eval:</code> to press a button, and let automation answer whatever the button's script raises.
* Use observe mode first to capture what the dialogs ''should'' be, then assert against that inventory in later runs. A new record appearing in the trace, or an expected one disappearing, is exactly the kind of regression that is otherwise easy to miss.
* Have the handler answer the specific dialog the test is about with a specific button, and leave everything else on the defaults. That keeps each test's intent obvious.

== Limitations ==

* Not every dialog in Analytica is intercepted yet. A number of older dialogs, mostly in OLE linking and a few utility dialogs, are still shown and still block. If you hit one, the trace will show nothing at that point while the process sits there — comparing the trace against a run that finished is the quickest way to spot it. Please report any you find.
* The handler is only consulted on the main thread. Dialogs from worker threads take the defaults.
* A handler cannot modify the model; it runs with dirtying suppressed.
* Automation mode applies to desktop Analytica. The server (ACP) already answers dialogs through its own web mechanism, and ignores <code>/Automation</code>. The <code>/AutomationTrace:</code> log does work in either.

== See Also ==
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [[Analytica Command Line]]
* [[RegisterAutomationModalHandler]]
* [[MCP server in Analytica]]
* [[Running a model in a command line workflow]]
* [[MsgBox]]
* [[AskMsgText]]
* [[AskMsgNumber]]
* [[AskMsgChoice]]
* [[WriteTextFile]]
* [[RunConsoleProcess]]
* [[Libraries]]
</div>