Help & User Guide
Everything you need to know about using NatalieTool.
Getting Started
NatalieTool has two parts: a web app you access in your browser, and a Local Agent that runs on your Windows machine. The web app handles the UI and AI. The Local Agent handles everything that touches your machine — SQL Server, file operations, and Vertex Returns imports.
First-Time Setup
Data Generator
The Data Generator is the main tool. It creates test companies, generates transaction data, and runs imports against your local Vertex Returns database — all in one operation.
Two Modes
| Mode | When to use it |
|---|---|
| Create Everything | Build a brand-new company from scratch — company record, divisions, departments, locations, returns, deductions, transaction data, and import. Start to finish. |
| Generate Tax Data | Add transaction data to a company that already exists in your database. Useful when you need more data for a company you've already set up. |
Two Methods
| Method | How it works |
|---|---|
| AI-Powered ~3-4 minutes |
Describe what you want in plain English. The AI interprets your prompt, queries your database for real geocodes and tax rates, and builds everything to match. Best for complex or realistic scenarios. |
| Random / Deterministic ~30 seconds |
Pick states, location counts, volume, and a date range from a form. Fast and predictable. Best when you need data quickly and don't care about the specifics. |
Create Everything — Step by Step
Generate Tax Data (Existing Company)
Same flow, but you select an existing company from a dropdown instead of creating one. A summary bar shows the company's current locations, returns, divisions, and departments — click it to open a detailed company report in a new tab.
Writing Good AI Prompts
The AI understands Vertex Returns concepts. You can mention:
- States and cities — "5 locations across Dallas, Houston, and Austin"
- Tax categories — "Cat 1 and Cat 3" or "Retail Sales and Consumer's Use"
- Volume — "heavy volume" or "200 transactions per location"
- Date ranges — "January through June 2026" or "full year"
- Organizational structure — "with 3 divisions" or "include departments"
- Filing frequency — "monthly filing" or "quarterly returns"
- Nexus states — "sells online to New Jersey" (generates Seller's Use / Cat 2 transactions)
- Revenue targets — "$50M annual revenue"
- Deductions — "include exempt transactions"
Example prompts:
Random / Deterministic Options
| Field | What it controls |
|---|---|
| States | Which states to place locations in. Hold Ctrl to select multiple. |
| Location Count | Total number of locations to create, distributed across selected states. |
| Tax Categories | Standard (1–4) or All. Controls which transaction types are generated. |
| Volume | Transactions per location per filing period: Light = 100 | Medium = 800 | Heavy = 1,500 | Custom = you choose |
| Filing Period | Start and end month. Defaults to the database's current MIF month. |
What's in the Download Package?
The ZIP file (COMPANYCODE_package.zip) contains:
| File | Purpose |
|---|---|
| setup_company.sql | T-SQL script to create the company, locations, returns, and related records. Run this first if you're setting up manually instead of using the Import button. |
| setup_deductions.sql | T-SQL script to configure deduction code mappings (Exempt / Non-Taxable) in CompanyDeductions and StateDeductions. |
| *.txt (one per period) | TAX2000 import data files — delimited transaction records with tax amounts calculated from your database's actual rates. |
| README.txt | Summary of what was generated, including company details, locations, returns, and step-by-step manual import instructions. |
TAX2000 Import File Generator
A simpler tool for generating individual TAX2000 import files. Unlike the Data Generator, this tool only creates data files — it doesn't create companies, run imports, or package anything.
How It Works
The page shows the current database MIF month (e.g., "Current database: June 2026") so you know what tax content release you're generating against.
When to Use This vs. the Data Generator
| Use TAX2000 Generator when... | Use Data Generator when... |
|---|---|
| You just need data files to import manually | You want the full pipeline — company creation, import, everything |
| The company already exists and is fully configured | You're starting from scratch or need the import run for you |
| You want direct control over what gets generated | You want a one-click end-to-end experience |
Import Setups
Extract import setup configurations from one database and load them into another. This lets you share proven import configurations across environments without manual re-entry.
What's an Import Setup?
An import setup defines how Vertex Returns reads your TAX2000 data files — the file format (delimited or fixed-width), delimiter, text qualifier, field mappings, and validation rules. Each setup maps to an Import Type (e.g., Separate Tax, Combined Tax) and contains a list of field positions.
Extracting a Setup
Loading a Setup
What's in the JSON File?
The exported file contains:
- Setup metadata — name, import type, file format, delimiter, validation flags
- Field mappings — every field position, width, and start offset
- Source info — which server and database it was extracted from, and when
Database Migration
Migrate data from SQL Server to Babelfish/PostgreSQL using the Vertex Returns EF CLI tool. This is an advanced tool for teams moving to cloud-native databases.
Prerequisites
- The Local Agent must be running with PostgreSQL and Babelfish connection details configured in Agent Settings.
- The EF CLI tool is automatically downloaded and managed by the Local Agent. No manual installation required.
Operations
| Operation | What it does |
|---|---|
| Migrate Data | Full migration — copies both schema and data from a SQL Server database to Babelfish/PostgreSQL. Optionally specify a tenant GUID or drop the tenant schema first. |
| Apply Migrations | Runs Entity Framework schema migrations only. No data is transferred. Use this when you need to update the target database schema without touching data. |
| Reset Database | Drops all tables and functions from the Babelfish qsutr32 database. This is destructive and cannot be undone. A confirmation dialog appears before execution. |
| Drop Tenants | Removes tenant schemas from PostgreSQL. Specify a GUID to drop one tenant, or leave blank to drop all. This is destructive and cannot be undone. |
All operations stream their output in real time in a terminal-style display. Green text = stdout, red text = stderr. When the operation finishes, a status indicator shows success (green) or failure (red) with the exit code.
↑ Back to topLocal Agent Settings
Configure the companion service that runs on your machine. All settings are stored in the Windows Registry and encrypted where appropriate.
| Setting | What to enter |
|---|---|
| SQL Server | Your SQL Server instance name, e.g., localhost\SQLEXPRESS or .\MSSQLSERVER. Uses Windows Authentication — no username/password needed. Click Test Connection to verify. |
| Import Input Path | Directory where generated data files are written. Click Validate to check the path exists. |
| Import Error Path | Directory where import error output is written. Click Validate to check. |
| PostgreSQL Endpoint | Host, port (default 5432), username, and password for the PostgreSQL database. Only needed if you use the Database Migration tool. |
| Babelfish TDS Endpoint | Host, port (default 1433), username, and password for the Babelfish TDS endpoint. Only needed for Database Migration. |
Agent Log
Click View Log to see the agent's activity log. The log shows every API call, errors, and diagnostic information. Use Download to save the log as a text file — handy when you need to share it for troubleshooting.
Program Files Cache
Vertex Returns program files are downloaded automatically when needed during import. The agent fetches the correct version from the cloud, verifies its integrity (SHA256 hash), and caches it locally. You never need to manage this manually — the cache status is displayed here for informational purposes.
↑ Back to topTroubleshooting
"Local Agent is not detected"
This means the web app can't reach the Local Agent on your machine. Try these in order:
- Is the agent installed? If not, go to the Setup page and download it.
- Is the agent running? Check your system tray or Task Manager for NatalieTool.LocalAgent.exe. It should auto-start on login, but you can also run it manually from the Start menu.
- Did your browser block localhost access? Click the lock or tune icon in your browser's address bar. Find "Access to local network" (or "Access other apps and services on this device") and set it to Allow. Then reload the page.
- Is another application using port 9500? The agent scans ports 9500–9549 for an available port. If all 50 ports are occupied (extremely unlikely), close some applications and restart the agent. Check the agent log for details.
Browser Download Warnings
The installer is code-signed by Vertex, but browsers flag executables from newer sites until they build download reputation. This is normal.
Chrome may show "this file isn't downloaded often":
- Click the ⇧ arrow (or Show more) on the download bar.
- Choose Keep anyway.
Edge SmartScreen may block the download entirely:
- Use the .zip download option on the Setup page instead. Extract the zip, then run the installer from inside it.
Windows SmartScreen may show "Windows protected your PC" when you run the installer:
- Click More info (it's small, below the warning text).
- Click Run anyway.
Database Not Listed
The database dropdown only shows databases that:
- Are in the ONLINE state
- Contain a DatabaseReleaseInfo table (i.e., they are valid Vertex Returns databases)
- Are accessible via the SQL Server instance configured in Agent Settings
If your database isn't listed, verify the SQL Server connection in Agent Settings and make sure the database is online.
Import Fails or Shows Errors
If the import reports errors:
- Click the error count link in the import summary to open an error report showing exactly which records failed and why.
- Common causes: missing return configurations, geocode mismatches, or program files version mismatch.
- If the import was interrupted, you can click the import button again — a confirmation dialog lets you re-run.
Program Files Not Available
If the import can't find the right program files, the agent attempts to download them automatically from the cloud. If this fails:
- Check your internet connection.
- The required version may not have been published yet. Contact your administrator.
- Check the agent log for download errors.
Still Stuck?
Download the agent log from the Agent Settings page (View Log → Download) and send it to your NatalieTool administrator. The log contains timestamped entries for every operation, including errors and diagnostic details.
↑ Back to top