TaxMTD UC Auto-Filler

The TaxMTD UC Auto-Filler is a Chrome extension that bridges your accounting data to the gov.uk Universal Credit self-employment reporting portal. Instead of manually typing each income and expense line, the extension fills the forms for you -- correctly categorised, with descriptions and amounts pulled directly from your transaction data.

How It Works#

The extension connects your browser to the app via a WebSocket bridge. When you open the UC page in the app and click Auto-fill UC, the app becomes the controller. The extension, running on the gov.uk UC portal tab, becomes the filler. The controller sends fill commands (income amount, expense type, description, amount) and the filler enters them into the correct form fields on the portal.

The flow for each expense entry is:

1. Click "Add another expense" on the UC management page
2. Select the correct expense type radio button (e.g. Transport and travel)
3. Fill in the description and amount on the detail form
4. Submit and return to the management page

The extension handles all of this automatically, including navigating between pages and resuming after each page load.

Installation#

The extension is not on the Chrome Web Store -- you load it directly from the project.

Steps#

1. Open Chrome and navigate to chrome://extensions
2. Enable Developer mode (toggle in the top-right corner)
3. Click Load unpacked
4. Select the extensions/uc-filler folder (or the extracted ZIP folder)
5. The extension icon appears in your toolbar

The extension contains:

Connecting the Extension#

1. Click the TaxMTD UC Auto-Filler icon in your Chrome toolbar to open the popup
2. The server URL defaults to wss://taxmtd.uk/uc-bridge - no changes needed
3. Click Connect
4. The WebSocket status dot turns green when connected

The popup shows two status indicators:

Using Auto-Fill#

Opening the Auto-Fill Panel#

1. Navigate to Tax > Universal Credit in the app
2. Ensure your date range covers the UC assessment period you are reporting
3. Click Auto-fill UC to open the fill panel
4. The app connects to the bridge as the controller and builds a list of fill steps from your data

Fill Steps#

The panel shows one step per entry that needs to be submitted to the UC portal:

• Income step -- your total self-employment income for the period
• Expense steps -- one per subcategory, grouped by UC expense type (e.g. "Transport and travel -- Fuel", "Office and equipment -- Software")

Each step shows the amount, description, and a status badge.

Filling Individual Steps#

1. Open the UC self-employment income/expenses page in another tab
2. Click the Fill button next to a step in the app
3. The extension fills the form on the UC portal, clicks Continue, and navigates through the multi-page flow
4. When complete, the step status changes to done (green)

Fill All#

Click Fill All to run every pending step sequentially. The extension:

1. Fills the current step
2. Waits for the UC portal page to load after submission
3. Automatically advances to the next pending step
4. Stops when all steps are done or an error occurs

Click Stop to halt the queue after the current step finishes.

Skipping and Resetting#

• Skip -- marks a step as skipped (it will not be included in Fill All)
• Reset -- sets all steps back to pending so you can re-run them
• Click a completed step's status badge to toggle it back to pending

Copying to Clipboard#

If you prefer to fill manually, click the copy icon on any step to copy the amount and description to your clipboard.

Category Mapping#

Your app expense categories (e.g. "vehicle-expenses", "office-equipment") are mapped to the 13 UC portal expense types. The default mapping is sensible for most users, but you can override it.

Default Mappings#

Overriding a Mapping#

1. Click the Category Mapping button in the auto-fill panel
2. Each app category shows a dropdown of the 13 UC types
3. Select a different UC type to remap (e.g. change "Vehicle Expenses" from "Transport and travel" to "Vehicle expenses" if you want to report vehicle costs separately)
4. The override is saved per-entity in Directus and persists across sessions

Description Editing#

Each fill step has an auto-generated description derived from the subcategory name (e.g. "Fuel", "Software Subscriptions"). You can edit this inline:

• Click the description text in the fill panel to edit it
• The UC portal enforces a 50-character limit -- descriptions longer than 50 characters are automatically truncated
• Edited descriptions are saved per-entity in Directus (keyed by UC type + original description)
• To revert to the default, clear the field -- the original description is restored

Stale Step Handling#

If you recategorise a transaction or change amounts while a submission is in progress:

1. The app detects the data change and runs a diff against the current steps
2. Steps whose amount has changed are marked stale (amber badge) with a note showing the previous amount (e.g. "Amount changed from 45.00")
3. Steps for subcategories that disappeared (and were never submitted) are removed automatically
4. New subcategories that appear are added as pending steps
5. Steps already marked as done or skipped for disappeared subcategories are kept -- they have already been submitted to the UC portal

Troubleshooting#

Extension not connecting#

• Verify the server URL matches your app (check protocol -- ws:// for HTTP, wss:// for HTTPS)
• Ensure the app is running and the /uc-bridge WebSocket endpoint is accessible
• Check that the extension is enabled in chrome://extensions
• Open the extension's service worker console (click "Inspect views: service worker" on the extensions page) to see connection logs

UC Portal Tab not detected#

• The content script only activates on https://www.universal-credit.service.gov.uk/*
• Refresh the UC portal tab after installing the extension
• Check that the content script is not being blocked by another extension

Back button issue#

The UC portal has both a "Continue" button and a "Back" button, both implemented as <button type="submit">. The extension specifically targets the Continue button by matching input[name="next"] or the primary .govuk-button that is not marked as secondary. If the wrong button is being clicked:

• Check the extension console for [uc-filler] logs to see which button was matched
• Report the issue -- the UC portal may have changed its markup

Duplicate entries on the UC portal#

If you run Fill All and then run it again without resetting:

• Already-completed steps are skipped (Fill All only processes pending steps)
• If you manually reset steps and re-fill, the UC portal will have duplicates -- you must delete the old entries on the portal first

Fill command sent but nothing happens#

• Ensure both status dots in the popup are green
• The content script must be running on the UC portal tab -- if you navigated away and back, refresh the page
• Check that you are on the correct UC page (the self-employment income/expenses management page)

Descriptions getting truncated#

The UC portal has a 50-character limit on expense descriptions. The app automatically truncates longer descriptions to 47 characters plus "..." to fit. Edit the description in the fill panel if the truncated version is unclear.