/run-job

description: Run a quick job on a device in Datto RMM
argument-hint: "<device> <component> [variables] [wait]"
arguments: [device, component, variables, wait]

Run Job

Run a quick job (component script) on a device in Datto RMM.

Prerequisites

• Valid Datto RMM API credentials configured
• `DATTO_API_KEY` and `DATTO_API_SECRET` environment variables set
• `DATTO_PLATFORM` configured (pinotage, merlot, concord, vidal, zinfandel, syrah)
• Device must be online for quick jobs
• Component must exist and be accessible

Steps

1. **Resolve device identifier**

• If a UID was given, use it; otherwise `datto_find_device` with the hostname (`exactMatch: true`), optionally scoped by `siteUid`
• If several devices match, stop and ask which one

2. **Verify device is online**

• `datto_get_device` and check its online state and last seen time

3. **Resolve component**

• Use the component UID the user gave, or find it in the Datto RMM ComStore (the connector has no component-search tool)

4. **Validate component variables**

• Confirm every variable the component needs is supplied as a key-value pair

5. **Run the quick job (after approval)**

• `datto_run_quickjob` with `deviceUid`, `componentUid`, `jobName` and `variables`. It is **admin** tier and runs code on the customer's device; get explicit approval for the exact component and device first
• It returns a job UID

6. **Check the result**

• `datto_get_job` (read) for status: queued, running or completed
• `datto_get_job_components` (read) to show what the job ran
• When completed: `datto_get_job_results` for exit code and error message, and `datto_get_job_stdout` / `datto_get_job_stderr` for what the script printed. These three are **admin** tier in Conduit because job output can contain anything the script printed
• If the job is still running, poll `datto_get_job`; do not launch it again

Underlying REST: `POST /api/v2/device/{deviceUid}/quickjob` creates the job; the read tools wrap the job, job-result, stdout and stderr endpoints.

Parameters

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | device | string | Yes | - | Device hostname or UID | | component | string | Yes | - | Component name or UID | | variables | string | No | - | Variables as `key=value,key2=value2` | | wait | flag | No | false | Wait for job completion |

Examples

Basic Job Execution

/run-job "ACME-DC01" "Clear Temp Files"

With Variables

/run-job "ACME-DC01" "Clear Temp Files" --variables "days=30,path=C:\\Temp"

Wait for Completion

/run-job "ACME-DC01" "Clear Temp Files" --wait

Using Component UID

/run-job "ACME-DC01" "c1d2e3f4-a5b6-7890-cdef-123456789abc" --wait

Full Example

/run-job "ACME-DC01" "Disk Cleanup" --variables "drives=C,days=7,logs=true" --wait

Output

Job Queued (No Wait)

Job Queued Successfully

Job UID:      j1k2l3m4-n5o6-7890-pqrs-123456789def
Device:       ACME-DC01
Component:    Clear Temp Files
Status:       Queued

Variables:
  days: 30
  path: C:\Temp

Job will run when the device checks in (typically within 5 minutes).

To check status: /job-status j1k2l3m4-n5o6-7890-pqrs-123456789def

Job Running (With Wait)

Running job on ACME-DC01...

Component:    Clear Temp Files
Started At:   2024-02-15 10:45:00 UTC
Status:       Running

[=========>          ] 50% - Executing...

Job Completed Successfully

Job Completed Successfully

Job UID:      j1k2l3m4-n5o6-7890-pqrs-123456789def
Device:       ACME-DC01
Component:    Clear Temp Files
Duration:     45 seconds
Exit Code:    0

Output:
----------------------------------------------------------------------
Scanning temporary directories...
Found 156 files older than 30 days
Deleting files...
Successfully deleted 156 files (2.3 GB freed)
----------------------------------------------------------------------

Errors: None

Job Failed

Job Failed

Job UID:      j1k2l3m4-n5o6-7890-pqrs-123456789def
Device:       ACME-DC01
Component:    Clear Temp Files
Duration:     12 seconds
Exit Code:    1

Output:
----------------------------------------------------------------------
Scanning temporary directories...
Error: Access denied to C:\Temp\locked.file
----------------------------------------------------------------------

Errors:
----------------------------------------------------------------------
ERROR: Could not delete locked file
Process exited with code 1
----------------------------------------------------------------------

Suggestions:
- Check if file is in use by another process
- Verify script has appropriate permissions
- Run job again after resolving file lock

Job Timeout

Job Timed Out

Job UID:      j1k2l3m4-n5o6-7890-pqrs-123456789def
Device:       ACME-DC01
Component:    Long Running Script
Duration:     300 seconds (timeout)
Status:       Timeout

The job exceeded the maximum execution time.

Partial Output:
----------------------------------------------------------------------
Step 1 complete...
Step 2 complete...
Step 3 in progress...
----------------------------------------------------------------------

The job may still be running on the device.
Check device logs or run a shorter test job.

Error Handling

Device Offline

Cannot run job - Device is offline

Device:     ACME-DC01
Status:     Offline
Last Seen:  2024-02-15 08:30:00 UTC (2 hours ago)

Quick jobs require the device to be online.

Options:
1. Wait for device to come online
2. Schedule a job instead (run when device connects)
3. Contact on-site personnel to check device

Component Not Found

Component not found: "Clear Temp Filess"

Did you mean one of these?
- Clear Temp Files (UID: c1d2e3f4-...)
- Clear Browser Cache (UID: c2d3e4f5-...)
- Disk Cleanup (UID: c3d4e5f6-...)

Use the exact component name or UID.

Missing Required Variable

Missing r