The IMSURGE Thor Agent automatically sends new CSV event reports created by Instantel THOR to IMSURGE. It runs as a Windows service, so it continues monitoring and uploading when its settings window is closed and when no user is signed in.

The application has two visible parts:

  • The IMSURGE Thor Agent Windows service performs the monitoring and uploading.
  • The IMSURGE Thor Agent Configuration tray application shows status, delivery totals, and settings.

The agent reads THOR files but does not change or delete them. It keeps its own temporary copy of each report until IMSURGE confirms that the upload was accepted.

IMSURGE Thor Agent running in Windows Task Manager The agent continues running as a Windows background process.

Before Installation

Have the following information ready:

  • Access to IMSURGE with permission to create Instantel THOR credentials.
  • The location of THOR’s active AutoCallHomeService.log file. The usual location is C:\THORDATA\Logs\AutoCallHomeService.log.
  • A Windows account that can approve an administrator prompt.

In THOR, open the Auto Call Home tab and expand the menu on the left side of the page. Expand Report, then select Generate CSV File for Downloaded Events.

Enable CSV report generation in Instantel THOR Expand Report in Auto Call Home and enable Generate CSV File for Downloaded Events.

In IMSURGE, create a new set of Instantel THOR credentials. IMSURGE automatically generates the upload URL as part of this process. The URL will look similar to:

  https://upload.imsurge.com/data/{randomly_generated_uuid}

You can optionally assign a Basic Authentication username and password while generating the credentials. Copy the generated upload URL and, if assigned, the username and password so they are ready when the agent configuration window opens.

We recommend generating a unique set of IMSURGE credentials for each THOR server on which the agent is installed. This makes each server independently identifiable and easier to manage. The agent will still work if the same upload URL is used on multiple THOR servers.

The computer must be able to make direct outbound HTTPS connections to the IMSURGE endpoint. Explicit proxy and custom-certificate settings are not currently available in the application.

Install and Complete Initial Setup

  1. Run the approved IMSURGE-Thor-Agent-...-win-x64.exe installer.
  2. Approve the Windows User Account Control prompt.
  3. Continue through the installation wizard.
  4. When IMSURGE Thor Agent Configuration opens, enter the settings described below.
  5. Select Save. Installation cannot finish until valid configuration has been saved.
  6. After setup finishes, confirm that the IMSURGE icon appears in the Windows notification area. It may be under the Show hidden icons arrow.

Configuration Fields

IMSURGE Thor Agent configuration Enter the IMSURGE upload URL, active THOR log path, and optional Basic Auth credentials.
Field What to enter
IMSURGE upload URL The complete HTTPS upload URL automatically generated when you create credentials for the Instantel THOR integration in IMSURGE.
THOR log file The full path to the active AutoCallHomeService.log. Use Browse… to locate it if necessary. Do not select Thor.log or a dated archive.
Basic Auth username The optional username assigned when the IMSURGE credentials were created. Leave blank if one was not assigned.
Basic Auth password The matching optional password assigned with the IMSURGE credentials. Leave blank if one was not assigned.

The username and password must either both be provided or both be left blank. The selected THOR log file must already exist. The password is encrypted by Windows before it is stored.

Important First-Start Behavior

When the agent monitors a THOR log for the first time, it starts at the current end of the file. Existing log entries and historical reports are intentionally not uploaded. Only CSV reports announced by THOR after monitoring begins are processed.

If the configured THOR log path is later changed, monitoring also begins at the current end of the newly selected file.

Use the Tray Icon

The tray icon provides status and controls; it is not the background agent itself. Closing or hiding the settings window does not stop event monitoring.

  • Left-click the IMSURGE tray icon to open settings.
  • Right-click the icon to open its status menu.
  • If the icon is not visible, select the Windows Show hidden icons arrow.

The icon tooltip and menu refresh approximately every five seconds.

IMSURGE Thor Agent tray icon and status menu Open the hidden-icons area and right-click the IMSURGE icon to view agent status and delivery totals.

Tray Menu Items

Menu item Meaning or action
Agent status Shows the actual Windows service state, such as Running, Stopped, Starting, or Stopping.
Version Shows the installed application version.
Pending Reports captured locally that are waiting for an upload attempt or an automatic retry.
Accepted Reports for which IMSURGE returned 202 Accepted. Recent accepted history is retained for 30 days, so this is not an all-time total.
Failed Reports that need administrator attention before another attempt.
Retry failed events Moves all failed reports back to the pending queue immediately. It is available only when failed reports exist.
Start agent Starts the service when it is stopped. Windows may request administrator approval.
Open settings Opens the configuration window.
Stop agent and exit Stops the Windows service and closes the tray application after confirmation. Monitoring remains stopped until the service is started again or Windows restarts.

202 Accepted confirms that IMSURGE stored the upload and queued it for processing. It does not necessarily mean that later parsing or downstream processing has completed.

Change Configuration

  1. Left-click the tray icon, or right-click it and select Open settings.
  2. Update the required values.
  3. Select Save.
  4. Approve the administrator prompt used to restart the Windows service.
  5. Confirm that the success message appears and that Agent status returns to Running.

You can also open IMSURGE Thor Agent Configuration from the Windows Start menu or its desktop shortcut.

Saving settings restarts the background service so the new values take effect. It also returns all failed reports to the pending queue for another attempt. If you only want to retry reports without changing settings, use Retry failed events from the tray menu or Retry failed in the configuration window.

Features and Normal Operation

Automatic Background Monitoring

The service starts automatically after installation and after Windows restarts. It watches only the active AutoCallHomeService.log for new CSV REPORT CREATED entries. Other THOR messages and report formats are ignored.

Safe Handling of THOR Files

The agent waits for each new CSV to become readable and stop changing before making a local copy. It never modifies or deletes THOR’s source CSV or log. Normal THOR log rotation can continue while the agent is running.

Durable Delivery Queue

Each captured CSV is stored locally before it is uploaded. A temporary endpoint outage, service restart, upgrade, or computer reboot does not discard pending reports.

Network errors, timeouts, and IMSURGE server errors are retried automatically. The delay increases after repeated failures, up to approximately one hour between attempts. Errors requiring a settings or source-data correction move the report to Failed instead of retrying continuously.

Duplicate Suppression

The agent records recently accepted reports so a service restart or THOR log rotation does not normally upload them again. If IMSURGE accepts a report but the network connection fails before the agent receives the response, a later retry can still result in a duplicate.

Protected Credentials and Diagnostics

The Basic Authentication password is protected using Windows machine-level encryption. Diagnostic logs do not intentionally include the password or CSV contents.

Application Files and Data Locations

The application stores machine-wide configuration and delivery data under:

  C:\ProgramData\IMSURGE\THOR Upload Agent

C:\ProgramData is hidden by default. To open the folder, paste %ProgramData%\IMSURGE\THOR Upload Agent into the File Explorer address bar and press Enter.

Location Purpose
%ProgramData%\IMSURGE\THOR Upload Agent\config.json Upload URL, THOR log path, username, and encrypted password.
%ProgramData%\IMSURGE\THOR Upload Agent\logs\agent.log Current diagnostic log. Older rotating logs are named agent.log.1 through agent.log.9.
%ProgramData%\IMSURGE\THOR Upload Agent\pending Agent-owned copies of reports awaiting a confirmed outcome.
%ProgramData%\IMSURGE\THOR Upload Agent\agent-state.db Saved monitoring position, delivery states, retries, and recent accepted history.
C:\Program Files\IMSURGE\Thor Agent Installed application files.

Do not manually edit config.json; use the configuration window. Do not rename, move, open for editing, or delete files in pending, and do not modify agent-state.db. In particular, never change queue or database files while the service is running. These actions can cause lost state or duplicate uploads.

Troubleshooting

Start with These Checks

  1. Right-click the tray icon and check Agent status, Pending, and Failed.
  2. Confirm Agent status is Running. If it is Stopped, select Start agent and approve the administrator prompt.
  3. Open settings and confirm the upload URL and active THOR log path.
  4. Open %ProgramData%\IMSURGE\THOR Upload Agent\logs\agent.log and review the most recent entries.
  5. If reports are pending or failed, correct the underlying problem before selecting Retry failed events.

Common Symptoms

Symptom or message What it means What to do
Tray icon is missing The tray application may be hidden or not running. The service can still be operating. Check Show hidden icons, then open IMSURGE Thor Agent Configuration from the Start menu. Check the service status in the tray menu when it appears.
Agent status: Stopped The background service is not monitoring or uploading. Select Start agent and approve the administrator prompt.
Agent status: unavailable The tray application cannot read the Windows service state. Close and reopen the configuration application. If it continues, verify that the product is installed and contact support with the diagnostic log.
Pending count increases Reports are safely queued but have not yet been accepted. A network or IMSURGE server problem may be retrying automatically. Confirm internet access and allow outbound HTTPS. Review agent.log. Do not delete pending files.
Failed count is greater than zero One or more reports require administrator attention. Review agent.log, correct the indicated configuration or file problem, then retry failed events.
Configuration error The saved upload URL or THOR log path is missing or invalid. Open settings, enter a complete HTTPS URL and the active THOR log path, then save.
Cannot monitor the THOR log The file is missing, inaccessible, temporarily unavailable, or the configured path is wrong. Confirm THOR is installed and running, verify the path, and ensure the service can read the file. The agent continues trying.
No older reports upload after installation This is expected first-start behavior. Generate or wait for a new THOR CSV event. Historical entries present before installation are not imported.
HTTP 401 IMSURGE rejected the Basic Authentication credentials. Correct both the username and password, save, and retry.
HTTP 403 The computer’s public outbound IP address is not allowed by the endpoint. Ask IMSURGE support to confirm the endpoint allowlist, then retry.
HTTP 404 The import code is unknown or does not identify an HTTP endpoint. Obtain the correct complete upload URL, save it, and retry.
HTTP 422 or an empty queued CSV The request body was empty and will not be retried automatically. Investigate why THOR produced an empty report. After resolving the source problem, retry or contact support.
HTTP 5xx, timeout, or network error IMSURGE or the network was temporarily unavailable. The agent retains the report and retries automatically. Investigate firewall or connectivity issues if the condition persists.
Another HTTP 4xx error IMSURGE rejected the request and automatic retries are paused. Record the status shown in agent.log and contact IMSURGE support before retrying.

Retrying without fixing a permanent error will usually return the reports to Failed.

Collect Diagnostics for Support

When contacting support, provide:

  • The installed version shown in the tray menu.
  • The current Agent status and Pending/Accepted/Failed counts.
  • The approximate time the problem occurred, including the local time zone.
  • The current agent.log and, if requested, the numbered rotated logs.
  • The HTTP status or error message shown in the log.

Do not send Basic Authentication credentials, customer CSV files, config.json, agent-state.db, or files from the pending directory unless IMSURGE support explicitly requests a secure transfer.

Advanced Service Checks

An administrator can check or control the service from an Administrator PowerShell window:

  sc.exe query ImsurgeThorUploadAgent
sc.exe stop ImsurgeThorUploadAgent
sc.exe start ImsurgeThorUploadAgent

Stopping the service pauses both monitoring and uploads. Starting it again resumes from saved state.

Updates and Uninstallation

Run a newer approved installer to update the application. The installer preserves the saved configuration, monitoring position, delivery history, pending reports, and diagnostic logs. During an update, the configuration window opens with the existing values; review them and select Save to complete setup.

Uninstalling removes the service and installed application files, but intentionally retains data under %ProgramData%\IMSURGE\THOR Upload Agent. This protects reports that have not received a confirmed response and supports reinstall troubleshooting.

Only remove the retained ProgramData folder when you are certain its configuration, diagnostics, delivery history, and pending reports are no longer needed. If any pending or failed reports exist, contact IMSURGE support before removing it.