M-Power Agent App Overview

Applies to: M-Power Agent v2.x

The M-Power Agent is a small desktop application that connects your M-Power system to your local production environment. It runs quietly in the background and does two things:

• Inbound sync — downloads new order and quote line information (artwork files and job metadata) from M-Power into a folder on your network, ready for your workflow tools (e.g. Switch, OneVision) to pick up.
• Outbound sync — watches a folder for action files created by your workflow tools and sends them back to M-Power (status updates, art approvals, file uploads).

All communication goes to your M-Power system over HTTPS — the agent needs no cloud database or cloud file-server access.

1. Installation

Windows

1. Download the installer (M-Power Agent Setup.exe) from the link provided by M-Power.
2. Run the installer. It installs per-user and starts the agent automatically when finished — no admin rights or install wizard required.
3. The agent appears in your system tray. Closing the window minimises it to the tray; it keeps syncing in the background. To quit completely, right-click the tray icon.

Updates on Windows are built in — click Check for updates on the Home screen to install the latest version.

macOS

1. Download the macOS ZIP from the link provided by M-Power.
2. Unzip it and drag M-Power Agent.app into your Applications folder.
3. Launch it from Applications. The app is signed and notarised, so macOS should open it without warnings; if Gatekeeper prompts on first launch, choose Open.

Note: automatic updates are currently Windows-only. On macOS, install new versions by replacing the app with the latest ZIP from M-Power.

Only one copy of the agent can run at a time — launching it again just brings the existing window to the front.

2. Configuring the API connection

M-Power will provide you with two values:

Open Settings from the top navigation and enter both under API Connection. Use the Show button to check the token was pasted correctly — no line breaks or trailing spaces. Settings save automatically as you change them.

Treat the API token like a password. If it's ever exposed, contact M-Power support and we'll issue a new one (the old one stops working immediately).

3. Inbound sync (M-Power → your folder)

Configured under Settings → Syncing - Inbound.

What lands in the download directory

For each order line: attached files named <jobId>_<jobLineId>_<original filename>, plus (if Metadata is on) <jobId>_<jobLineId>.json or .xml. Quote lines follow the same pattern with the quote and quote line IDs. Which lines appear, and which data fields the metadata contains, is configured on the M-Power side for your site — talk to us if you need extra fields.

Once a line has downloaded successfully it's marked as processed in M-Power and won't download again (unless Test Mode is on, or it's flagged for reprocessing in M-Power).

You can trigger an immediate check at any time with Sync Now under Manual Operation.

4. Outbound sync (your folder → M-Power)

Configured under Settings → Syncing - Outbound.

Each sync cycle, the agent picks up any .json or .xml file in the upload directory (not subfolders), validates it, and sends it to M-Power:

• Success — the file moves to a processed/ subfolder with a timestamp added to its name.
• Failure — the file is removed and replaced with <name>_rejected_<timestamp>.txt containing the reason and the original content, so nothing is silently lost or endlessly retried.

Action file format

Every action file has the same envelope (JSON shown; XML uses the same element names inside an <action> root):

{
  "action_type": "status_update",
  "document_type": "order",
  "document_id": "J1245",
  "action_metadata": { }
}

All four fields are required. document_id is the M-Power document number (e.g. J1245, Q5678). action_metadata carries the action-specific inputs below.

status_update — change a quote or order status

document_type: quote or order

art_approved — mark a file approved on a quote or order

document_type: quote or order

upload_file — attach a file to a quote, order, or a specific line

document_type: quote, order, quote_line or order_line

On success both the action file and the referenced data file are archived to processed/. If the upload fails, the data file stays in place so it can be retried on the next cycle. Large files are handled automatically — the agent splits anything over 8 MB into pieces behind the scenes, so there's no practical size limit.

Any other action_type is accepted and logged by M-Power without further processing — useful for forwarding custom events.

5. Logging

Open Logs from the top navigation.

• Live view (default) — log entries stream in as the agent works: each sync cycle, every file downloaded or uploaded, and any errors, all timestamped.
• Historic view — tick View historic logs, pick a From/To time range, and click View Logs to review past activity.
• Download Logs — exports the logs as a CSV (opens in Excel) — handy to attach to a support ticket.

Logs are stored locally on the machine running the agent and kept for 4 weeks, after which they're cleaned up automatically.

The first things to check when something isn't syncing:

1. The Logs page — the reason is almost always spelled out there (e.g. "API not configured", "Upload directory does not exist", a rejected action file reason).
2. Any _rejected_*.txt files in the upload directory — they contain the exact reason an action was refused, plus the original content.
3. Test Mode — if the same lines keep re-downloading, Test Mode is probably still on.

6. Quick reference

For anything not covered here, contact M-Power support with your CSV log export and (if relevant) the _rejected_*.txt file.