VOW Helper
Reference for the VOW Helper desktop app. For install and usage walkthroughs see the VOW Helper guide.
File types
The following file types can be checked out for local editing via the Helper. Files of any other type cannot be opened with the Edit document action.
| Type | Extensions |
|---|---|
| Word document | .docx, .doc, .odt |
| Spreadsheet | .xlsx, .xls, .ods |
| Presentation | .pptx, .ppt, .odp |
| Plain text | .txt, .csv |
File actions
Actions available on each checked-out file on the helper's Files screen.
| Action | Availability | Notes |
|---|---|---|
| Edit | When a local copy exists | Opens the file in the OS-default application for its type (Word, Excel, image viewer, etc.). Hidden for a failed download (no local file yet). |
| Send back | When Ready to edit | Uploads the current local contents to VOW, unlocks the attachment, and removes the local copy once the file is no longer open in an editor. |
| Retry | When the file failed | Re-attempts the operation that failed. A failed download re-fetches the report and its attachments; a failed send back re-uploads; a failed discard re-attempts the unlock. Replaces Send back as the primary action on a failed file. |
| Discard | When the file is closed in your editor and no operation is in progress | Unlocks the attachment in its origin system and deletes the local copy without uploading. If the unlock fails the file is kept and flagged Discard failed (with a Retry), and an alert warns it may still be locked. |
| Discard report & attachments | Report row | Discards the report and its related attachments only, leaving any other editing files for the record in place. When there are no other editing files it's equivalent to Discard all. |
| Open folder | Group context menu | Opens the file's parent directory in your OS file manager. Useful for inserting related attachments into a report. |
| View in VOW | Group context menu | Opens the source record in VOW in your default browser. |
| Discard all | Group context menu | Bulk version of Discard — drops every checked-out file belonging to the group without uploading. Any files that couldn't be unlocked are kept and summarised in a single alert. |
File statuses
A status badge on each file tells you where it is in the edit/send-back lifecycle.
| Status | Meaning |
|---|---|
| Ready to edit | File is downloaded and idle. Click Edit to open it. |
| Downloading… | Helper is fetching the file from VOW. |
| Opening… | Helper is launching the OS-default application for the file. |
| Editing | The file is currently open in Word, Excel, or another editor. |
| Sending back… | Upload in progress. |
| Discarding… | Helper is unlocking the file on VOW and removing the local copy. |
| Close file to finish cleanup | A Send back or Discard succeeded but the local file can't be removed until your editor releases it. |
| Download failed | The file couldn't be downloaded (e.g. a wrong or missing API key). The primary action becomes Retry. The card keeps the file name where one is known. |
| Upload failed | A Send back didn't complete. Retry re-attempts the upload using your edited local copy. |
| Discard failed | The attachment couldn't be unlocked in its origin system during a discard. The file is kept so Retry can try again. |
The status names the failed operation so you know what Retry will do. Auth-related failures spell out which system to check — and, for a non-default system, name it (e.g. "check the API key for the Staging system in Settings").
Origin chip
A record downloaded from a non-default system shows a small Staging or Dev chip in its card header, so it's obvious at a glance when you're editing against a test or development system. Records from the default VOW system show no chip. The same record opened from two different systems appears as two separate cards.
Unavailable attachments
When you open a record's details sheet, any supplementary attachment whose backing file is missing on the server is shown with a red File unavailable on server badge. The record card's related files link also gains a warning icon and a "— some unavailable" note. The download itself still succeeds; the affected attachments are simply omitted from the local Attachments folder. This usually means the underlying file was never fully uploaded or has been lost on the server — contact support if it persists.
Settings
Configuration fields on the helper's Settings page.
Connection
| Setting | Notes |
|---|---|
| VOW server | Choose between the Live site, the Test system, or a Dev host. Most users should leave this on Live. The selected system also determines which API key the helper uses. |
| Dev host | Shown when VOW server is set to Dev. Enter the host (and optional port) of your VOW instance, e.g. localhost:3000. Primarily intended for development use. |
| API key | Your personal VOW API key for the currently selected system. Each system (live / test / dev) stores its own key in your operating system's secure keychain — switching systems shows that system's key. Use Add / Change / Delete to manage it. |
| Test connection | Confirms the helper can reach the selected system and authenticate with that system's API key. |
The helper keeps a separate API key for each system, so you can edit against Live, the test system, and a dev host without re-pasting keys. Incoming edit links are downloaded — and sent back — using the key for the system they came from, regardless of which system is selected in Settings. Keys stored by an earlier version are moved into your operating system's keychain automatically the first time you upgrade.
On Linux the keychain is the desktop's Secret Service keyring (GNOME Keyring or KWallet). If no keyring service is available, the helper keeps your keys in its own encrypted vault instead.
Danger zone
Destructive resets at the bottom of the Settings page.
| Action | Notes |
|---|---|
| Clear checked-out files & downloads | Removes every checked-out record and deletes the downloaded files (including any stale editor lock files left behind). Your settings and API keys are kept. Anything still locked in VOW must be unlocked there. |
| Reset everything | Clears checked-out files and downloads and wipes your settings and all API keys, then restarts the helper. Use this for a clean slate. |
File storage
| Setting | Notes |
|---|---|
| Local file directory | Where checked-out files are stored on disk. Use the folder picker to change it. Avoid locations managed by file-sync services like OneDrive or iCloud Drive. |
| Auto-cleanup threshold | Number of days (1–30) before a stale local file is removed on startup. Default: 5. |
| Sync with filesystem | Reconciles the helper's internal list of checked-out files with what's actually on disk. Useful if you've moved or deleted files outside the helper. |
App preferences
| Setting | Notes |
|---|---|
| Theme | Light, Dark, or System (follows your OS theme). |
| Log verbosity | Controls how much detail is shown in the in-app log panel: Error, Warn, Info, Debug, Trace. All log levels are always written to the log file regardless. |
| Open logs | Opens the helper's log directory in your OS file manager. |
Updates
The helper keeps itself up to date and surfaces an available update with a banner across the top of the window. For the walkthrough see the VOW Helper guide.
| Element | Notes |
|---|---|
| Update banner | Appears when a newer version is available. Persistent until the update is installed. |
| Update & restart | Banner action shown when no files are checked out. Downloads and installs the update, then relaunches the helper. |
| Review files | Banner action shown when files are still checked out. Opens the Files screen so you can send back or discard them first — installing restarts the helper. The banner switches to Update & restart once the last file is cleared. |
| Check for updates | Manual check on the About page. Reports You're on the latest version when up to date. |
Checks run automatically on startup, on a periodic background interval while the helper is open, and after the last checked-out file is sent back. A failed check (e.g. no network) never blocks the app — it's logged and retried on the next trigger.
Window behaviour
| Behaviour | Notes |
|---|---|
| Close to tray | Closing the helper window hides it to the system tray. The app keeps running so edit links continue to work. |
| Single instance | Only one instance of the helper runs at a time. Launching the app again (or clicking an edit link) shows the existing window instead of starting a new process. |
| Quit | Use the tray icon menu's Quit item, or your OS's standard quit shortcut, to fully exit the helper. |