Automating the Aras Batch Loader with a Minimalist CLI

Loading data with the Batch Loader can feel a bit repetitive at times, especially if you’re repeating the same steps for different projects or environments. So, we built a lightweight command line interface (CLI) wrapper to take the repetition out of the process. It’s a simple way to make your Batch Loader workflows more predictable, automatable, and easier to customize.

This command-line tool supports standalone configurations that can be cloned from the graphical user interface (GUI), reliably pairs data files with their corresponding AML templates, executes the AML query, and generates auditable per-file logs.

It doesn’t change how the Batch Loader works under the hood. It just makes the workflow smoother, more consistent, and better suited for automation tasks like migrations and scheduled imports.

Note: The Aras Batch Loader requires an Enterprise License. You can check your activated feature licenses by logging in to Aras Innovator as an admin and navigating to Administration > Feature Licenses in the TOC.

Key benefits include:

• Separation of settings: Keep CLI connection settings distinct from the UI’s configuration file
• Flexible execution: Run the tool from any folder by specifying the runtime directory
• Predictable automation: Execute scheduled jobs, retries, or full rollback sequences without manual input

This wrapper isn’t a replacement for standard utilities. It’s a lightweight, scriptable driver that makes the built-in CLI easier to automate.

GUI vs. CLI: when to use each

• GUI: Best for basic loads, learning, and setup. The graphical interface is great when you’re just getting started, experimenting with templates, or configuring reusable setting files. It provides visibility into how batch loading works before moving to more advanced automation.
• CLI: Best for automation and repeatability. The CLI shines in scenarios where you want to schedule or chain multiple loads, run unattended jobs, or minimize human error. It’s ideal for long-running or multi-step imports, rollback-enabled migrations, or integration into continuous delivery pipelines where consistency and traceability are key.

How the pipeline works

Each data file goes through a simple but robust processing pipeline.

The script locates the appropriate template, builds and executes the command, and logs the results.

 

 

 

 

 

 

Initial configuration

Before your first use, update these fields in the CLIBatchLoaderConfig.xml file:

• server, db, user, password: Your Innovator connection details.
• loader_dir: The path to the BatchLoader runtime folder.
  Tip: Run the script from a separate directory to avoid config and data conflicts.
• delimiter, first_row: Match these settings to your data file format.

<BatchLoaderConfig>
    <server>https://YOUR-INNOVATOR-URL</server> 
    <db>YOUR_DATABASE_NAME</db>
    <user>admin</user> 
    <password>innovatorpassword123</password> 
    <max_processes>1</max_processes>
    <threads>1</threads>
    <lines_per_process>250</lines_per_process>
    <delimiter>\t</delimiter>
    <encoding>utf-8</encoding>
    <first_row>2</first_row>
    <log_level>3</log_level>
    <loader_dir>..\..\..\BatchLoader</loader_dir>
</BatchLoaderConfig>

File naming conventions

Use a simple, lexicographical naming convention so the script processes files in the correct order, especially when dependencies exist between items and relationships.

Hard requirements: Template name must match the data file’s base name (stem). The script looks up the template by the data file’s stem and skips the file if no match is found.

Processing order: Normal mode loads data files in ascending lexicographic order. Use zero‑padded numeric prefixes to control sequence.

Recommended order for multi-step loads:

1. Parent/base items (e.g., Parts)
2. Child/related items (e.g., Documents)
3. Relationship files last (e.g., Part‑Document relationships)

Delete mode reverses the order automatically so relationships are removed before their related items. Retry mode processes *.failed files alphabetically as well.

Naming patterns

• Data files: NNN-Name.txt
• Template files (either location works): – <templates_dir>/NNN-Name.xml – /NNN-Name_Template.xml

Please refer to the CONVENTIONS.md file in the project repository before your first run.

Getting started on Windows

• Verify Python. Make sure Python is installed and accessible from the command line
• Initialize configuration. Create a clean CLI configuration from your BatchLoader runtime folder.

python3 .\batchloader.py --init-config --init-from-runtime --bl-dir "C:\\path\\to\\BatchLoader" --bl-config .\CLIBatchLoaderConfig.xml

• Set connection details. Open CLIBatchLoaderConfig.xml and input your server, database, and credentials.
• Run a load. Execute the batch loader script.

python3 .\batchloader.py

• Review logs. Check the generated log files. If any .failed files appear, use --retry to reprocess them.

Please refer to the README.md file in the project repository for exact configuration copy and run commands.

Modes of Operation

The wrapper supports three modes:

Normal Mode

Processes each .txt file, finds its matching template, runs the batch load, and creates per-file logs.

python3 .\batchloader.py

Retry Mode

Reprocesses only rows that failed in a previous run, using .failed files and their original templates.

python3 .\batchloader.py --retry

Delete Mode

Deletes all data in previous CLI run by generating delete templates on the fly. It will process files in reverse order to remove relationships before other items.

python3 ./batchloader.py --delete

Warning: Use delete mode at your own risk. We recommend that you back up your environment and use sample data only.

Troubleshooting

Connection issues

• Confirm your Aras Innovator Server endpoint.
• Common mistakes: using the wrong protocol (http vs https) or copying the full /Client or /Server path from your browser. Correct format: http://localhost/InnovatorServer

Missing runtime

• Check that --bl-dir or <loader_dir> points to your BatchLoader runtime folder.
• Look for BatchLoaderCmd.exe and its DLLs in that directory.

Non-zero exit codes

• A non-zero exit means one or more files failed.
• Review the corresponding .log file in logs/ for details, then rerun with --retry once corrected.

Permission errors

• Verify your credentials and confirm that the Batch Loader feature is licensed under Administration > Feature Licenses in Aras Innovator.

Header mismatches

• If you see Column count mismatch or Header not found, ensure your <delimiter> and <first_row> settings match your data file’s format.

Next steps

Start with a simple Part or Document load to get comfortable with the workflow, then progress to more complex relationship imports. The generated logs provide an auditable trail for every operation.

For community discussions and support, visit the Aras Community forums  or file an issue on the GitHub project.