Migrate a Device to Another Environment
A step-by-step runbook for moving devices from a source Capture environment to a target environment, using the migration proxy described in the Overview.
Read the Overview first if you have not already — in particular what is forwarded and reads stay on the source environment.
At a glance
| Step | Result |
|---|---|
| 1. Prepare the target environment | Company, devices and storage exist and accept data |
| 2. Open the network path | Source environment can reach the target Data API and AuthServer |
| 3. Configure the forwarding endpoints | The company knows where to forward to |
4. Switch the device to Both | Data lands in both environments |
| 5. Verify the target environment | Proof the data is correct and complete |
6. Switch the device to NewOnly | Source environment stops storing data for this device |
| 7. Repoint and decommission | Device talks to the target environment directly |
Steps 1, 2 and 5 are performed in the target environment; steps 3, 4 and 6 in the source environment.
Migrate one pilot device end to end first, then batch the rest. Migration targets are set per device — there is no bulk switch.
Step 1 — Prepare the target environment
This is the step that decides whether migration works at all. The proxy authenticates on the target environment as the device, so the device must already exist there with identical credentials.
1a. Create the company
Create the company in the target environment (Identity & Access → Companies). It does not have to carry the same name, but keeping names identical makes verification far easier.
1b. Register each device as an offline gateway
For every device you intend to migrate, register it in the target environment via Sources → Edge Gateways → + → Offline gateway, choosing the offline type that matches what the device is (Logger, External Connection or ServiceTool). See Add Edge Gateways for the general flow.
Two fields must be filled in exactly:
- Activation UID — the same value as in the source environment. This is the device's identity and the username the proxy logs in with. Copy it from the device's page in the source environment.
- Password — leave this empty for a normal new device, but for a migration paste the password from the device's downloaded authconfig in the source environment.
In the source environment, open the device and download its authconfig. The password field in that file holds the device's credential in encrypted form. Paste that value, as-is, into the Password field when creating the offline gateway in the target environment.
Capture recognises it as an encrypted value and restores the device's original password, so the
migrated device ends up with credentials identical to the source. Leaving the field empty generates a
new password instead — forwarding would then fail with 401, and the physical device would no
longer be able to log in after cutover.
1c. Give the devices somewhere to write
Configure retentions (storage targets) for each device in the target environment, creating them
in the Storage Hub app first if needed. A device with no valid retention will have its inserts
rejected, and in Both mode that rejection is silent from the device's point of view — it only shows
up in the source environment's logs and in your verification at step 5.
1d. Confirm the target accepts data
Before involving the proxy, prove the target environment works on its own: log in as the device against the target AuthServer and post a test payload to its Data API. See Authentication and Insert Data.
If this does not work by hand, it will not work through the proxy — and diagnosing it through the proxy is considerably harder.
Checklist before moving on
- Company exists in the target environment
- Every device registered with the same Activation UID
- Password pasted from each device's source-environment authconfig
- Retentions assigned
- A manual login + insert against the target environment succeeds
Step 2 — Open the network path
The source environment must be able to reach two endpoints in the target environment over outbound HTTPS:
| Endpoint | Purpose |
|---|---|
| Data API base URL | Where forwarded inserts are sent |
| AuthServer login URL | Where the proxy logs in as the device |
Both must be reachable from the source environment's network. For customer-owned environments this typically means a firewall or private-networking change on your side, plus a valid TLS certificate on a publicly resolvable hostname.
Both URLs are entered on the company in the next step. The login URL is the full login path,
not just the host — for example https://auth.your-env.example.com/auth.
Step 3 — Configure the forwarding endpoints
On the company in the source environment (Identity & Access → Companies), set:
- Forwarding endpoint — base URL of the target environment's Data API. Leaving it empty disables forwarding for the whole company.
- Forwarding auth endpoint — the full login URL of the target environment's AuthServer.
These are configured once per company, so every device in the company shares one target. Each company has its own pair of endpoints, independent of every other company — so a company migrating to its own environment is unaffected by, and cannot affect, anyone else's migration.
Step 4 — Switch the device to Both
On the device's edit screen in the source environment, set Migration target to Both.
From now on, every insert from that device is written locally and forwarded to the target environment, concurrently. The device is unaffected: it keeps receiving the source environment's response, and forwarding problems are logged but never fatal.
Allow about 2 minutes for the change to take effect (why).
Both is where you should spend most of the migration. It is fully reversible, costs the device no
extra latency (the local write and the forward run in parallel), and lets both environments answer
reads correctly. Stay here until you are confident, not just until data appears.
Step 5 — Verify the target environment
Do not treat "data is arriving" as sufficient. Compare the two environments over a window that is long enough to include the device's slower and less frequent signals.
- Completeness — same measurements and signals present, not just some of them
- Volume — comparable message and point counts over the same interval
- Values and timestamps — spot-check numerically, including timezone and precision
- Gaps — no periodic holes, which would suggest intermittent forwarding failures
- Payload types — verify binary and blob payloads specifically if the device sends them
- Downstream — rebuild the dashboards, reports, alerts and UNS structures you depend on and confirm they behave identically. None of that is migrated for you.
Confirm the forwarding logs are clean for the device — see Troubleshooting. Any recurring warning in step 4 means silent data loss in the target environment that you may not detect by sampling alone.
Everything up to this point is reversible and lossless. After step 6, data that fails to reach the target environment is not stored anywhere else.
Step 6 — Switch the device to NewOnly
Set Migration target to NewOnly. The source environment now stops processing the device's data entirely — no time-series write, no blob offload, no message-bus publish — and relays the target environment's response back to the device verbatim.
What changes for the device and its consumers:
- If the target environment cannot be reached, the device receives HTTP 503 and applies its normal retry and buffering behaviour. Nothing is written in the source environment as a fallback.
- Validation errors from the target environment now reach the device directly, so it gets accurate feedback instead of the source environment's verdict.
- Reads on the source environment stop returning new data for this device. Dashboards, reports, alerts and API queries there go stale from this moment. Reads are not proxied.
Rollback is immediate and manual: set the migration target back to Both (or OldOnly). Data
written to the target environment while on NewOnly stays there — it is not backfilled into the
source environment.
Step 7 — Repoint the device and decommission
NewOnly is a transitional state, not a destination — the source environment is still in the data
path and remains a dependency. Finish the job:
- Reconfigure the device (its CloudManager / cloud connection settings) to post directly to the target environment's Data API. Because the credentials were preserved in step 1, no new activation or credential exchange is needed.
- Move any remaining data consumers — integrations, exports, external API clients — to the target environment.
- Set the migration target back to OldOnly once the device no longer posts to the source environment, and remove the company's forwarding endpoints when the last device in the company has been migrated.
- Decide what happens to the device's historical data in the source environment. Historical data is not migrated by this feature — export it beforehand if you need it in the target environment.
Troubleshooting
Check the source environment's Data API logs for the device; each entry identifies it by name and company. Forwarding outcomes are logged per request, so per-device behaviour is visible without extra monitoring.
| Symptom | Most likely cause | Fix |
|---|---|---|
| No data at all in the target environment, and no forwarding entries in the logs | The migration target change has not propagated yet, or the device authenticates as a user rather than a device | Wait ~2 minutes; confirm the setting is saved on the correct device |
| Log reports missing forwarding credentials | The company's Forwarding auth endpoint is empty, or the device has no stored credentials in the source environment | Set the auth endpoint (step 3); check the device's authconfig exists in the source environment |
| Forwarding fails with 401 | The device does not exist in the target environment, or its password there does not match | Recreate the device in the target environment with the same Activation UID and the password pasted from the source authconfig (step 1b) |
| Forwarding fails with 4xx other than 401 | The target environment rejects the payload — commonly a missing retention or an unknown device | Verify a manual insert against the target environment (step 1d) |
| Log reports circuit open | 5 consecutive forwards failed, so forwarding is being skipped | Fix the target environment; the circuit closes automatically within 60 seconds of recovery |
| Forwarding times out | Target environment slower than the 30 second forwarding timeout, or the network path is blocked | Check reachability and target-environment performance (step 2) |
Device receives 503 while on NewOnly | The forward could not be completed — circuit open, timeout, or network error | Treat as an outage of the target environment; consider reverting to Both while investigating |
| Data arrives, but with gaps | Intermittent forwarding failures that Both mode correctly swallowed | Review the forwarding warnings before cutting over — do not proceed to step 6 |
Related pages
- Environment Migration Overview — how the proxy works and what it guarantees
- Add Edge Gateways — offline gateway registration
- Data API — Authentication
- Data API — Insert Data