Automate VDI Robot Management

Use these patterns to provision new robots, update Autologin credentials, and determine which robots can be safely started or shut down — all without manual steps in the RPA Console.

What you need before automating VDI robot management

Before you begin, make sure you have:

• An Appian API key associated with a service account that has System Administrator rights in Appian RPA. See Authentication for details.
• The Autologin service installed and configured on your host machines if you plan to use Autologin workflows. See manage-robots-installation-config.md for setup instructions.
• Network access from the machine running your automation scripts to your Appian environment.
• Access to your VDI platform's management tools for starting and stopping virtual machines.

Determine which robots can be shut down

Call the Get eligible robots endpoint to retrieve the current status of all eligible robots. Robots with a status of "Online" or "Standby" are available for work. If no work is queued, these robots can be safely shut down for maintenance or cost savings.

1
2
curl -s -H "Authorization: Bearer ${API_KEY}" \
  "${SITE_URL}/rpa/rest/oo/robot/eligible"

In the response, filter for robots where status is "Online" or "Standby" and no execution is in progress.

Example: Identify robots to shut down (PowerShell)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
$SiteUrl = "https://rpa.example.com"
$Headers = @{ "Authorization" = "Bearer $env:RPA_API_KEY" }

$response = Invoke-RestMethod `
    -Uri     "$SiteUrl/rpa/rest/oo/robot/eligible" `
    -Headers $Headers

$shutdownCandidates = $response.result.robots | Where-Object {
    $_.status -eq "Online" -or $_.status -eq "Standby"
}

Write-Host "Robots that can be shut down:"
$shutdownCandidates | ForEach-Object {
    Write-Host "  $($_.name) (ID: $($_.id), Status: $($_.status))"
}

Determine which robots can be started

Call the Get eligible robots endpoint and filter for robots with a status of "Offline". These robots have no agent and no autologin service running. Cross-reference with your VDI inventory to identify which machines to start.

1
2
curl -s -H "Authorization: Bearer ${API_KEY}" \
  "${SITE_URL}/rpa/rest/oo/robot/eligible"

Example: Identify robots to start (PowerShell)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
$SiteUrl = "https://rpa.example.com"
$Headers = @{ "Authorization" = "Bearer $env:RPA_API_KEY" }

$response = Invoke-RestMethod `
    -Uri     "$SiteUrl/rpa/rest/oo/robot/eligible" `
    -Headers $Headers

$toStart = $response.result.robots | Where-Object { $_.status -eq "Offline" }

if ($toStart.Count -eq 0) {
    Write-Host "All eligible robots are already online or in standby."
} else {
    Write-Host "$($toStart.Count) robot(s) need starting:"
    $toStart | ForEach-Object {
        Write-Host "  $($_.name) (ID: $($_.id))"
        # Start-VDI -RobotName $_.name  # your VDI start command
    }
}

Provision a new robot

When adding a new VDI machine to your robot fleet, use the following workflow to configure it programmatically instead of copying values manually from the RPA Console.

Step 1: Download the installer

Call the Download RPA installer endpoint to get the agent installer binary. Include the Autologin service if the robot will use it.

1
2
3
4
# With Autologin service
curl -s -H "Authorization: Bearer ${API_KEY}" \
  -o rpa-installer.exe \
  "${SITE_URL}/rpa/rest/oo/robot/installer?includeAutologin=true"

Step 2: Install the agent on the VDI

Copy the installer to the VDI and run it. The installer creates the agent directory and service files.

Step 3: Get the robot configuration

Call the Get robot configuration endpoint using the string resource ID for the robot. The resource ID can be found using the existing Node List endpoint.

1
2
3
4
5
RESOURCE_ID="69be887ed2c47a234f4b2c2d"

curl -s -H "Authorization: Bearer ${API_KEY}" \
  "${SITE_URL}/rpa/rest/oo/robot/${RESOURCE_ID}/configuration" \
  | jq -r '.result.propertiesContent' > AppianRPA.properties

Step 4: Write the properties file to the host machine

Write the propertiesContent value to AppianRPA.properties in the agent installation folder on the VDI. The default location is the Appian RPA folder created during agent installation.

Step 5: Set Autologin credentials (if using Autologin)

Call the Update Autologin credentials endpoint. Pass the resource ID in the URL path and the Windows credentials in the request body.

1
2
3
4
5
curl -s -X PUT \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"username": "CORP\\svc_robot", "password": "[windows-password]", "domain": "CORP"}' \
  "${SITE_URL}/rpa/rest/oo/robot/${RESOURCE_ID}/autologin-credentials"

Step 6: Start the agent

Start the RPA agent service on the VDI. The agent will connect to the Console using the configuration from step 4.

Full provisioning script (PowerShell)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
param(
    [Parameter(Mandatory=$true)] [string]$SiteUrl,
    [Parameter(Mandatory=$true)] [string]$ResourceId,
    [Parameter(Mandatory=$true)] [string]$InstallPath,
    [Parameter(Mandatory=$true)] [string]$WindowsUser,
    [Parameter(Mandatory=$true)] [string]$WindowsDomain
)

$ApiKey  = $env:RPA_API_KEY
$WinPass = $env:WINDOWS_PASSWORD  # Retrieved from secrets manager at runtime
$Headers = @{ "Authorization" = "Bearer $ApiKey" }

# 1. Download installer
Invoke-WebRequest `
    -Uri     "$SiteUrl/rpa/rest/oo/robot/installer?includeAutologin=true" `
    -Headers $Headers `
    -OutFile "$InstallPath\rpa-installer.exe"

# 2. Install on VDI (via your remote execution mechanism)

# 3. Get robot configuration and write properties file
$config = Invoke-RestMethod `
    -Uri     "$SiteUrl/rpa/rest/oo/robot/$ResourceId/configuration" `
    -Headers $Headers

if ($config.invocationResult -ne "OK") {
    Write-Error "Failed to get robot config: $($config.exceptionThrownText)"
    exit 1
}

$config.result.propertiesContent | Out-File `
    -FilePath "$InstallPath\AppianRPA.properties" `
    -Encoding UTF8
Write-Host "Properties file written to $InstallPath\AppianRPA.properties"

# 4. Set Autologin credentials
$body = @{
    username = $WindowsUser
    password = $WinPass
    domain   = $WindowsDomain
} | ConvertTo-Json

$autologinResponse = Invoke-RestMethod `
    -Uri     "$SiteUrl/rpa/rest/oo/robot/$ResourceId/autologin-credentials" `
    -Method  PUT `
    -Headers ($Headers + @{ "Content-Type" = "application/json" }) `
    -Body    $body

if ($autologinResponse.invocationResult -ne "OK") {
    Write-Error "Failed to set Autologin credentials: $($autologinResponse.exceptionThrownText)"
    exit 1
}

# 5. Start agent service (via your remote execution mechanism)

Write-Host "VDI provisioning complete for resource $ResourceId."

Update Autologin service credentials

When Windows account passwords are rotated, update the Autologin service credentials using the Update Autologin credentials endpoint.

Step 1: Call the update endpoint

Pass the resource ID in the URL path and the new Windows credentials in the request body. The new credentials take effect on the next Autologin sign-in cycle, not immediately.

1
2
3
4
5
6
7
8
9
curl -s -X PUT \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "CORP\\svc_robot",
    "password": "[new-windows-password]",
    "domain": "CORP"
  }' \
  "${SITE_URL}/rpa/rest/oo/robot/${RESOURCE_ID}/autologin-credentials"

Step 2: Verify the update

Confirm the response contains "invocationResult": "OK".

Step 3: Test the robot connection

Check the RPA Console or call Get eligible robots to confirm the robot's status is "Online" or "Standby" after the credential update. If the robot goes offline, verify the Windows credentials are correct and that the Autologin service has restarted.

Routine maintenance automation

For scheduled maintenance windows, combine the workflows above into a single script:

1. Call Get eligible robots to identify idle robots.
2. Use your VDI platform's API to shut down the idle VMs.
3. Perform maintenance (patching, updates, and so on).
4. Restart the VMs.
5. Poll Get eligible robots until the robots return to "Online" or "Standby" status.
6. Alert your team if any robot fails to come back online within the expected time window.

Feedback