How to upgrade from Autory 2 to Autory 3¶

Autory 3 can be installed next to Autory 2, but model workbooks and downstream reporting processes may need changes. Use this guide when moving an existing Autory 2 model to Autory 3.

Parts of this upgrade guide are repeated throughout the documentation in the form of tips like these:

Changes from Autory 2 to Autory 3

When upgrading a model from Autory 2 …

Migration checklist¶

Install Autory 3 by following the installation guide.
Keep Autory 2 installed for now if you still use autory_reporting_filter_json or autory_reporting_sqlite_to_json.
Back up the Autory 2 model workbooks and any output folders used for comparison.
Open a terminal and run autory version to confirm which Autory installation is active.
Run autory patch on a copy of each model workbook.
Read the changes to check below and update the model if needed.
Run a small, known comparison scenario and compare the results against Autory 2.
Migrate production runs only after the comparison is understood.

Installation and side-by-side behavior¶

Autory 3 gets installed to %localappdata%\autoactuary\autory3. Installing Autory 3 does not automatically remove Autory 2.

After installing Autory 3, the autory command in a new terminal should point to Autory 3 instead of Autory 2. Run this to confirm:

autory version

For more details about the installation, run:

autory debug

If you need to work with more than one Autory installation on the same computer, see how to handle multiple Autory installations.

New features worth knowing about¶

These are useful Autory 3 improvements. They are not usually migration blockers, but they can make upgraded models easier to run and support.

New model and RunMultiple workbooks¶

Autory 3 can create new model and RunMultiple workbooks from templates. Use autory new model, autory new run-multiple, or the Start Menu create-new shortcut.

Improved terminal output and progress bars¶

Autory 3 shows clearer terminal progress bars for both single model runs and when running multiple models in parallel. To properly support this, the Windows Terminal app is required.

Log viewer¶

Autory 3 writes detailed .AutoryLog files and links to them from the terminal when a run starts, fails, or stops. Use the Autory log viewer to inspect full error details during migration comparisons.

Excel ribbon¶

Autory 3 installs an Autory tab in the Excel ribbon. Autory 2 model workbooks may still have a built-in "Save & Run" button, but the ribbon is the preferred way to start runs from Excel after installing Autory 3.

See how to use the Autory Excel ribbon for the available actions and troubleshooting steps.

Stopping runs¶

Autory 3 handles stopping a run more cleanly than Autory 2. Use CTRL+C in the terminal window to stop a run cleanly. This applies to runs started from the Excel ribbon and to command-line runs.

See how to stop a run for more information.

Result conversion and Feather files¶

Autory 3 includes autory convert results for converting run output into formats used by downstream reporting processes. Models can also use featherToTable to read Feather files directly.

Table column formulas¶

Autory 3 supports tableColumn for formulas that need a whole external or user-provided table column. This is useful with formulas such as MATCH, INDEX, SUM, and MAX.

RunMultiple batches¶

RunMultiple now supports Group and Weight columns for controlling batch order. It also supports PreRunScripts and PostRunScripts for commands that should run before or after the whole batch.

Profiling slow runs¶

Set Profile to TRUE when you need profiling statistics for a slow run. For normal production runs, leave it as FALSE.

`ModelPath` variable¶

ModelPath is now globally available for use in variable library formulas. It resolves to the full path of the model file being run. For models built using Excel, this is the path to the model workbook.

Patching model workbooks¶

Autory 2 model workbooks must be patched before they are used with Autory 3:

autory patch "path/to/model.xlsm"

The patch command makes a backup of the workbook before modifying it. Keep your original Autory 2 workbooks until the migration is complete.

Patched workbooks are not guaranteed to keep working with Autory 2.

See how to patch a model workbook after upgrading Autory for step-by-step instructions.

Changes when upgrading from Autory 2¶

Some of these are breaking changes, meaning you must update your model to get a successful run. Others are deprecations, meaning you will get a warning if you do not update your model, but it might run successfully.

Output files¶

Autory 3 writes projection node results to .feather files by default. Each projection node has its own set of output files.

This output structure is faster and more reliable for parallel runs. It also makes it possible to reuse the results of previous projection nodes from their .feather files.

JSON files, CSV files, and SQLite database files are no longer created by default. Use autory convert results to convert Autory 3 output into those formats.

To create a long-form SQLite database similar to the default Python-Excel output in Autory 2:

autory convert results --in path/to/results --out results.sqlite --output-format sqlite --table-orientation long

To create Autory-specific JSON files similar to the default VBA-engine output in Autory 2:

autory convert results --in path/to/results --out path/to/results/.json --output-format autory_results_json --split-by valnType,hLevel --name-pattern "{valnType}_h{hLevel}"

To run a conversion automatically after a model run, add an autory convert results ... command to PostRunScripts or to the RunMultipleOptions table.

Reading results from other Autory runs¶

Autory 3 does not reuse projection node results from the .xlsx output workbooks used for review. See reusing results from previous runs for details.

Run control¶

The output_folder run control option was renamed to OutputFolder. The old spelling still works in Autory 3, but a warning will be logged.

Several older run and output filtering options were replaced by formula-based filters:

OutputTimeStepFilter decides which time steps are written to output.
OutputProjectionNodeFilter decides which projection nodes are written to output.
RunProjectionNodesFilter decides which projection nodes run.

The patch command migrates the older workbook options where it can. If a model also sets run control options from a YAML file, JSON file, command line, or RunMultipleRuns table, update those names manually.

Deciding which time steps to output¶

Old output time-step controls are replaced by OutputTimeStepFilter:

Autory 2 option	Autory 3 alternative
`OutputFromProjectionDate`	Use a date or time-step condition, for example `Date>=DATE(2024,5,31)` or `t>=5`.
`OutputProjectionPeriods`	Use a time-step limit, for example `t<=12`.
`OutputProjectionMonthsIntervalMonths`	Use a time-step interval condition, for example `MOD(t-1,3)=0` for every third time step.

Combine these into one formula when more than one old option was used. For example, use AND(Date>=DATE(2024,5,31),t<=12,MOD(t-1,3)=0).

Deciding which projection nodes to output¶

Old output projection-node controls are replaced by OutputProjectionNodeFilter:

Autory 2 option	Autory 3 alternative
`OutputCapValuationDates`	No separate option. If it was `TRUE`, include the old valuation-date limits in `OutputProjectionNodeFilter`; if it was `FALSE`, leave those date limits out.
`OutputFromHLevel`	Use `hLevel>=...`, for example `hLevel>=2`.
`OutputFromValnDate`	Use `valnDate>=...`, for example `valnDate>=DATE(2024,12,31)`.
`OutputToHLevel`	Use `hLevel<=...`, for example `hLevel<=3`.
`OutputToValnDate`	Use `valnDate<=...`, for example `valnDate<=DATE(2025,12,31)`.
`ValnTypesToOutput`	Use a valuation-type condition, for example `OR(valnType="Summary",valnType="Detail")` instead of `Summary\|Detail`.

Combine these into one formula when more than one old option was used. For example, use AND(hLevel>=2,hLevel<=3,OR(valnType="Summary",valnType="Detail")).

Deciding which projection nodes to run¶

Old run projection-node controls are replaced by RunProjectionNodesFilter:

Autory 2 option	Autory 3 alternative
`CapValuationDates`	No separate option. If it was `TRUE`, include the old valuation-date limits in `RunProjectionNodesFilter`; if it was `FALSE`, leave those date limits out.
`RunFromHLevel`	Use `hLevel>=...`, for example `hLevel>=2`.
`RunFromValnDate`	Use `valnDate>=...`, for example `valnDate>=DATE(2024,12,31)`.
`RunOnlyOneValnType`	No separate option. Use a valuation-type condition in `RunProjectionNodesFilter`, for example `valnType="Summary"`.
`RunOnlySomeValnTypes`	No separate option. Use a valuation-type condition in `RunProjectionNodesFilter`, for example `OR(valnType="Summary",valnType="Detail")`.
`RunToHLevel`	Use `hLevel<=...`, for example `hLevel<=3`.
`RunToValnDate`	Use `valnDate<=...`, for example `valnDate<=DATE(2025,12,31)`.
`runValnTypeToRun`	Put this valuation type directly in `RunProjectionNodesFilter`, for example `valnType="Summary"`.
`runValnTypesToRun`	Put these valuation types directly in `RunProjectionNodesFilter`, for example `OR(valnType="Summary",valnType="Detail")` instead of `Summary\|Detail`.

Combine these into one formula when more than one old option was used. For example, use AND(hLevel>=2,hLevel<=3,valnDate>=DATE(2024,12,31),valnType="Summary").

Writing per-iteration results¶

LoopWriteIterationsToSqlite has no direct Autory 3 run control replacement. Autory 3 writes per-iteration results to .feather files when iterative calculations are used. To create a SQLite file from those iteration results, run:

autory convert results --in path/to/results --use-iterations --out iterations.sqlite --output-format sqlite

If you also need per-iteration results in output workbooks, use LoopWriteIterationsToWorkbook.

Run multiple¶

The old autory run config command was removed in Autory 3. Use autory run multiple instead.

SQL syntax¶

Autory 3 uses DuckDB-style SQL for internal queries. This affects queries used by functions such as csvToTable, excelTable, and table.

Autory 2 often accepted SQLite-specific syntax. The most common issue is SQLite's support for double-quoted string literals:

SELECT * FROM "tbl" WHERE "name" = "John Doe"

In Autory 3, write string literals with single quotes:

SELECT * FROM "tbl" WHERE "name" = 'John Doe'

Double quotes are still appropriate for identifiers such as table names and column names. The old double-quoted string syntax still works in Autory 3, but a warning will be logged. See SQL queries for more detail.

Workbook and model structure¶

The ValuationTypes table changed. Autory 3 adds ProjectionStartType and ProjectionStartFormula. It also combines the old EndDate and NrOfPeriods columns into ProjectionEndFormula.

This means a valuation type's projection start date can now be set explicitly. It no longer always has to be inferred as the earliest precedent projection node date.

The old variable dimensionality names still work in Autory 3, but using the old names will cause warnings to be logged.

Constant is now Scalar.
Proj is now TimeVector.

The patch command updates these names in Excel model workbooks. If you maintain JSON or YAML model files, update those manually.

Iterative calculations¶

Iteration output columns are named loop_1, loop_2, etc. in Autory 3. Older output consumers that expect columns named loop0, loop1, etc. need to be updated.

Blank or NULL values read by loopTable now resolve to NA() instead of 0. This makes missing inputs visible instead of silently treating them as zero.

Formula expansion¶

Autory 3 removed UseOldAutomaticFormulaExpansion. Formulas are not automatically expanded just because a config value contains [].

Use expandFormula explicitly when you want formula expansion.

Reporting commands¶

The old reporting commands are no longer available in Autory 3:

autory_reporting_filter_json
autory_reporting_sqlite_to_json

Use autory convert results instead. If you still rely on these commands, keep Autory 2 installed until your reporting process has been migrated.

`vcsTag` in output results¶

The old VBA JSON output included vcsTag in the output results. Autory 3 output does not add this value automatically.

If a downstream process still needs a VCS tag, add it as a normal variable in the model. For example, a variable can read the latest import log entry from the VcsTableImportLog table using excelTable and TableLookup:

TableLookup(
    ExcelTable(
        ModelPath,
        "VcsTableImportLog",
        "SELECT * FROM tbl WHERE ""Table"" = 'masterVarLib' ORDER BY ""Timestamp"" DESC LIMIT 1"
    ),
    "masterVarLib",
    "Tag"
)

VBA engine¶

The VBA engine is deprecated in Autory 3 and will be removed in Autory 4. New features added in Autory 3 are only available with the Python-Excel engine. Successfully migrating a model to Autory 3 means that it should be run with the Python-Excel engine.