Workflow 1: Apply / Upload Template (LE)

You are at https://api.litmus.io/workflows/apply-upload-template.md Parent: https://api.litmus.io/workflows/agents.md If this is the wrong workflow, back out to the index above.

1. Apply / Upload Template (LE)

UI trigger: System -> Device Management -> Templates -> Apply Template (downloads a template file, then re-uploads it)

LE 4.4.x: this workflow uses the current /config/template API. The older /dm/template flow still works (collection folder Old method of template apply) but is deprecated -- see the bottom of this page.

What the UI does invisibly: when a user uploads a template, the UI creates an upload session sized to the file, uploads the bytes, then saves (or applies) it -- the user just sees a file download/upload dialog. Saved templates are listed under Manage Templates and can be previewed and re-applied later.

Sensitive data: a downloaded template embeds live secrets (account APIKeys, connector credentials, certificates). Treat the file as a secret.

Step table (current method)

Download (steps 1-2), resumable tus-style upload and save (steps 3-6), then preview and apply the saved template (steps 7-8).

Step Name in Collection Method Endpoint Body / Notes Output
1 Step 1: List Template Inventory GET {{edgeUrl}}/config/template No body. Lists exportable items per subsystem (references only, not full config). Inventory of {id, name} refs ({type, name} for OPC UA nodes)
2 Step 2: Download Template POST {{edgeUrl}}/config/template JSON with chosen refs per category ({id,name} objects copied from the inventory; {type,name} for opcua). Always send the five arrays accounts, connectors, devices, flows, opcua (use [] for ones you skip). Template bundle JSON -- save to a file
3 Step 3: Create Apply Session POST {{edgeUrl}}/config/session {"size": <file_bytes>} {"id": "<session_id>", "size": N, "offset": 0} -- save id as {{config_session_id}}
4 Step 4: Upload Template PATCH {{edgeUrl}}/config/session/{{config_session_id}} multipart/form-data, single file part (application/octet-stream, filename blob). Headers: Upload-Length: <size>, Upload-Offset: 0. Resumable -- repeat with the returned offset until offset == size. {"id", "size", "offset"}
5 Step 5: Save Uploaded Template PUT {{edgeUrl}}/config/template/{{config_session_id}} ApplyOptions, all optional: name + description, encryptionKey, failFast, saveOnly. With saveOnly: true and a name the template is saved to the template store without applying. With saveOnly: false it is applied immediately (mutating). {"sessionId", "templateId"} when saved -- save templateId as {{template_id}}; {"sessionId", "components":[...]} when applied
6 Step 6: Close Apply Session DELETE {{edgeUrl}}/config/session/{{config_session_id}} No body. Releases the session (also use it to abort an abandoned upload; open sessions each hold their reserved size). Session closed
7 Step 7: Preview Apply POST {{edgeUrl}}/config/templates/{{template_id}}/preview {"mode": "legacy" \| "use" \| "merge-apply", "parameters": {}, "encryption_key": ""}. Dry run, applies nothing. Rate limited (429). plan_id, per-component participating + reason, additions / conflicts / kept
8 Step 8: Apply Saved Template POST {{edgeUrl}}/config/templates/{{template_id}}/apply {"mode", "encryption_key", "fail_fast"}. Mutating: use hard-resets every section in the template to exactly its contents; merge-apply restarts most services. templateId, sessionId, per-component results with created / updated / skipped / failed counts

Upload only counts as complete when Step 4 reports offset == size. The session id doubles as the template id in the Step 5 path. Read Step 7 components[].participating and reason before Step 8.

Deprecated: old /dm/template flow

Still present in the collection under Templates -> Old method of template apply. Not recommended for new work; documented here for older devices.

Download (old): POST {{edgeUrl}}/dm/template -- body is JSON with bare device-ID strings and per-area boolean flags ("country": true). Discover eligible items with GET {{edgeUrl}}/dm/template.

Apply (old, 3 steps):

Step Name in Collection Method Endpoint Body / Notes Output
0 Step 0: Apply Template DELETE {{edgeUrl}}/dm/template/v2 No body. Clears any stale upload session. 200 OK
1 Step 1: Apply Template POST {{edgeUrl}}/dm/template/v2 {"size": <file_bytes>} {"id": "<session_id>"}
2 Step 2: Apply Template PUT {{edgeUrl}}/dm/template/v2/{id_from_step1}/resume Binary file bytes in body 200 OK, template applied

Key differences from the current flow: the old apply combines upload + apply into one Step 2 call and needs an explicit Step 0 "clear session"; the new flow splits upload (PATCH) from apply (PUT) and drops the clear step.

View this page as Markdown