Integrate RPA Management APIs with External Tools

Use these patterns to integrate the Appian RPA management APIs with external orchestration tools, scripts, and Appian processes. Adapt them to your environment.

Set up authentication

All Appian RPA API calls require an API key sent as a Bearer token in the Authorization header:

1
Authorization: Bearer <apiKey>

See Authentication for the full requirements.

Create a dedicated service account

Create a dedicated Appian service account for your automation scripts. Use the System Administrator user type so the account has the necessary rights in Appian RPA. Avoid using a personal user account — if that account is deactivated, your automation will break.

Store API keys securely

Never hardcode API keys in scripts or commit them to source control. Instead:

• Store the API key in your organization's secrets manager (for example, HashiCorp Vault, AWS Secrets Manager, or Azure Key Vault).
• Inject the key as an environment variable at runtime.
• Rotate the API key on a regular schedule, just as you would rotate other credentials.

Handle errors and retries

All error responses follow the same format:

1
2
3
4
5
{
    "invocationResult": "KO",
    "result": null,
    "exceptionThrownText": "Error description..."
}

To handle errors:

1. Check invocationResult — if "KO", the operation failed.
2. Check the HTTP status code for the error category (400, 401, 403, 404, 409).
3. Log exceptionThrownText for debugging.

Retry logic for transient failures

Network issues and temporary server load can cause API calls to fail. Build retry logic into your scripts with exponential backoff to handle transient failures gracefully.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
function Invoke-WithRetry {
    param(
        [scriptblock]$ScriptBlock,
        [int]$MaxRetries = 3,
        [int]$BackoffBase = 2
    )
    for ($attempt = 0; $attempt -lt $MaxRetries; $attempt++) {
        try {
            $response = & $ScriptBlock
            if ($response.invocationResult -eq "OK") { return $response }
            throw "API error: $($response.exceptionThrownText)"
        } catch {
            if ($attempt -lt $MaxRetries - 1) {
                $wait = [math]::Pow($BackoffBase, $attempt)
                Write-Warning "Attempt $($attempt + 1) failed. Retrying in ${wait}s..."
                Start-Sleep -Seconds $wait
            } else {
                throw
            }
        }
    }
}

Circuit breaker pattern

For high-frequency automation, consider implementing a circuit breaker: if a series of consecutive API calls fail, stop retrying and alert your team rather than continuing to call a potentially unavailable endpoint.

Graceful degradation

Design your workflows so that a failed API call doesn't cause a cascading failure. For example, if a credential rotation fails, log the failure and alert your team, but don't automatically roll back other changes that may have already succeeded.

Logging and monitoring

Structured logging

Write log output in a structured format so your logging platform can parse and query it. Include the following fields in every log entry:

• Timestamp (ISO 8601 format).
• Endpoint called.
• Request parameters (excluding passwords and secrets).
• Response invocationResult.
• Error message, if any.

1
2
3
4
5
6
7
8
9
10
11
function Write-ApiLog {
    param($Endpoint, $Params, $Result, $Error)
    $entry = @{
        timestamp = (Get-Date -Format "o")
        endpoint  = $Endpoint
        params    = $Params
        result    = $Result
        error     = $Error
    } | ConvertTo-Json -Compress
    Write-Host $entry
}

Alerting on failures

Set up alerts for API call failures so your team can respond quickly. At minimum, alert on:

• Consecutive failures for the same endpoint.
• Credential update failures (these can cause robot downtime if not resolved quickly).
• Robot configuration failures during provisioning.

Integration examples

PowerShell scripts for credential and VDI management

PowerShell is well-suited for Windows-based automation and integrates naturally with Active Directory and Windows credential management. See the example scripts in Automate credential rotation and Automate VDI robot management.

Integration with Appian processes

You can call the RPA management APIs from within an Appian process model using an HTTP connected system. An HTTP connected system lets you trigger credential rotation or robot provisioning as part of a larger Appian workflow — for example, as part of an onboarding process that provisions a new robot when a new team is set up.

To set this up:

1. Create an HTTP connected system in Appian pointing to your RPA environment's API base URL.
2. Configure the connected system to use your service account's API key as a Bearer token.
3. Use the Call Integration smart service in your process model to call the credential or VDI management endpoints.

Integration with enterprise orchestration platforms

The Appian RPA APIs accept standard HTTP requests, so they work with any orchestration platform that supports REST calls, including:

• Ansible: Use the uri module to call RPA API endpoints as part of a playbook.
• Jenkins: Use the httpRequest plugin to call RPA APIs in a pipeline stage.
• GitHub Actions: Use curl in a workflow step.

In all cases, store the API key as a secret in the orchestration platform's secret store rather than in the pipeline definition.

Feedback