Deployment Package Steps

A deployment package is an ordered list of steps that agents run in sequence — install an application, copy files, run a script, stop and start a service, wait, reboot. This page is the field-level reference for authoring those steps and for scripting the whole create → upload → deploy → monitor workflow over the REST API or the PowerShell module. For the conceptual overview and package types, start with Software Deployment.

Anatomy of a package#

A package has a name, an optional description, a folder name, an ordered set of steps, and a set of uploaded files. The folder name is where the package's files are stored on the server; it must be a single, safe path segment — no path separators and no ... Names that contain a slash, backslash, or .. are rejected.

Step types#

Each step declares a stepType that tells the agent what kind of action to run. The supported types are:

Step fields#

Every step shares the same field set. Only the fields relevant to a given step type need to be populated; the rest can be left at their defaults.

OS conditions#

osCondition lets a single package carry steps that only apply to certain platforms — a step whose condition doesn't match the target is skipped on that agent (and reported as skipped). Values can be combined. The available conditions are:

Run-as identity#

runAs controls which account a step runs under:

Files and rebuilding#

Steps like InstallApplication and CopyFiles reference a fileName that must first be uploaded to the package. Uploading or removing a file automatically rebuilds the package's bundle so its contents stay in sync; you can also rebuild it explicitly at any time. A single package file upload is capped at 1 GB.

Deploying & targeting#

Deploying a package creates a deployment execution. At least one target must be supplied; the three targeting fields can be combined:

• targetAgentIds — specific agents by GUID.
• targetTags — every agent carrying a matching tag.
• collectionId — every member of a collection.

A deploy request also takes a name for the execution, an optional scheduledAt timestamp, and an optional skipCleanup flag:

Monitoring results#

Poll GET api/deployment-packages/executions/{executionId} to follow a deployment. The execution reports rollup counters — totalAgents, completedAgents, failedAgents, runningAgents, and progressPercent — along with the current step, and a per-agent breakdown with per-step results (exit code, captured output, and skip reasons). The overall status is one of:

A step that is skipped because its osCondition didn't match the target, or its condition script evaluated false, is reported as skipped with a skip reason rather than as a failure.

Scripting the workflow#

The Athena PowerShell module (PowerShell 7+) wraps the same API. Three cmdlets cover the package lifecycle:

New-AthenaDeploymentPackage takes -Name, -FolderName, an optional -Description, and an optional -Steps array. Start-AthenaDeploymentPackageDeployment takes -PackageId (also aliased -Id, and accepted from the pipeline), a -Name, target -AgentId, and optional -CollectionId, -Tag, -ScheduledAt, and -SkipCleanup.

A complete create → upload → deploy → monitor run. The package, deploy, and query cmdlets have dedicated commands; the file upload and rebuild have no dedicated cmdlet, so they use Invoke-RestMethod with the bearer token captured at sign-in (see the API Reference for the sign-in round-trip):

# Import the module and sign in (session is reused by later cmdlets)
Import-Module Athena
Connect-Athena -Server athena.example.com -Port 8443

# 1. Define the ordered steps
$steps = @(
  [PSCustomObject]@{
    Name             = "Install 7-Zip"
    StepOrder        = 1
    StepType         = "InstallApplication"
    FileName         = "7z2408-x64.msi"
    Arguments        = "/qn /norestart"
    SuccessExitCodes = "0,3010"      # accept "reboot required"
    OsCondition      = "AllWindows"
    TimeoutSeconds   = 600
  },
  [PSCustomObject]@{
    Name       = "Refresh inventory"
    StepOrder  = 2
    StepType   = "TriggerInventory"
  }
)

# 2. Create the package (Admin role required)
$pkg = New-AthenaDeploymentPackage -Name "7-Zip 24.08" -FolderName "7zip-2408" -Steps $steps

# 3. Sign in for raw calls, then upload the file the step references
#    (uploading a file rebuilds the bundle automatically)
$base  = "https://athena.example.com:8443"
$login = Invoke-RestMethod -Method Post -SkipCertificateCheck `
  -Uri "$base/api/auth/login" -ContentType "application/json" `
  -Body (@{ username = "admin"; password = "<your-password>" } | ConvertTo-Json)
$hdr = @{ Authorization = "Bearer $($login.data.token)" }

Invoke-RestMethod -SkipCertificateCheck -Method Post -Headers $hdr `
  -Uri "$base/api/deployment-packages/$($pkg.Id)/files" `
  -Form @{ file = Get-Item ".\7z2408-x64.msi" }

# 4. Deploy to a tag right now (add -ScheduledAt to schedule for later)
$exec = Start-AthenaDeploymentPackageDeployment -PackageId $pkg.Id -Name "7-Zip rollout" -Tag "workstation"

# 5. Poll the execution until it finishes
do {
  Start-Sleep 5
  $res = Invoke-RestMethod -SkipCertificateCheck -Headers $hdr `
    -Uri "$base/api/deployment-packages/executions/$($exec.Id)"
  $s = $res.data
  "{0}  {1}/{2} agents  {3}%" -f $s.status, $s.completedAgents, $s.totalAgents, $s.progressPercent
} while ($s.status -in "Pending","Running")