Automation Runbook Job

The Automation Runbook job type runs a published PowerShell (5.1 or 7.x), PowerShell Workflow or graphical runbook in an Azure Automation account. Each Polysync execution creates one Automation job, polls it to completion, and reads the runbook's result back as output parameters. The runbook is identified by its name — Polysync stores that in the Job's External Id.

This job type is supported on the Azure Automation platform. Python runbooks use the Automation Python Runbook job type instead.

Required job fields

External Id — the runbook name (e.g. Restart-AppServers). Set automatically on import.
Job Type — Automation Runbook (set automatically on import).

Optional job setting:

Hybrid Worker Group — the Hybrid Runbook Worker group the job runs on (the Automation job's runOn). Leave it blank to run in the Azure sandbox. To let each task choose its own group, also add a parameter named Hybrid Worker Group to the Job: a task value wins over the Job setting and is never sent to the runbook.

Job discovery

Discovery reads each runbook's definition and imports its declared parameters, in declaration order, as Input parameters. A mandatory parameter is marked required. The parameter's PowerShell type and default are shown in its hint; the default is not copied into Polysync, so the runbook keeps owning it.

Runbook parameter type	Polysync data type
`[string]`, `[datetime]`, `[double]`, `[long]`, `[pscredential]`, other	String
`[int]`	Int
`[bool]`, `[switch]`	Bool
`[array]`, `[string[]]`, any `[T[]]`	JsonArray
`[object]`, `[hashtable]`	JSON
`[securestring]`	Secret

Parameter handling

Polysync sends the job's parameters by name:

Only names the runbook declares are sent (PowerShell names are matched case-insensitively). Other task values — pass-through values from parent tasks, the Hybrid Worker Group setting — stay out of the job's recorded input.
Input and Input & Output parameters are sent; Output parameters are not.
Leave a parameter blank to use the runbook's default. Blank values are not sent.

Every value travels as text and Azure Automation converts it to the declared type. Use these formats:

Type	Send	Notes
`[int]`, `[long]`, `[double]`	`7`, `12345678901`, `1.25`
`[bool]`	`true` / `false`
`[switch]`	`true` (present) / `false` (absent)
`[datetime]`	`2026-10-02T10:00:00Z`	ISO 8601
`[array]`, `[string[]]`	`["a","b","c"]`	A JSON array; plain `a,b,c` arrives as one element
`[object]`	`{"a":1}`	Arrives as a `PSCustomObject`
`[hashtable]`	—	Not supported through the API. Azure Automation turns the JSON into a `PSCustomObject`, which PowerShell cannot bind to `[hashtable]`. Declare the parameter `[object]` instead.
`[securestring]`	—	Not supported through the API (Cannot convert … to System.Security.SecureString). Read secrets inside the runbook from a credential asset or Key Vault.
`[pscredential]`	the name of an Automation credential asset	PowerShell 5.1 only; PowerShell 7 does not support credential parameters.

Values are stored with the job. Azure Automation keeps each job's input for 30 days and shows it in the portal. Do not pass secrets as runbook parameters.

Output parameters

Runbooks have no declared outputs. To return values, write a JSON object as the last output record:

$result = @{ rowsProcessed = 42; resultNote = "done" }
Write-Output ($result | ConvertTo-Json -Compress)

When the job completes, Polysync reads the job's output stream and takes the last line that is a JSON object; earlier lines (progress text) are ignored. Each top-level property fills the Output or Input & Output parameter of the same name (matched case-insensitively). Add Output parameters on the Job's Parameters tab, or change the Direction of an imported parameter. Child tasks can then map them through task dependencies.

Execution flow

Polysync reads the runbook: a runbook that has never been published is refused with an instructive message, and the runbook's type and declared parameters decide what is sent.
It creates an Automation job — PUT …/automationAccounts/{account}/jobs/{guid} with the runbook name, the parameters and runOn (the Hybrid Worker Group, or blank for the Azure sandbox).

The dispatcher polls GET …/jobs/{guid}:

Automation job status	Polysync status
New, Activating	Starting
Running, Resuming, Suspending, Stopping, Blocked	Running
Completed	Success
Failed	Failed — with the job's exception text
Suspended	Failed — the job waits for a manual resume or stop in Azure Automation
Stopped	Cancelled — or Failed when a cloud job reached the three-hour fair-share limit

On Completed, Polysync reads GET …/jobs/{guid}/output and fills the output parameters.
Cancel sends POST …/jobs/{guid}/stop; the job ends Stopped and the run is Cancelled.

Monitor URL

The run links to the job in the Azure portal, where its input, output, errors and all streams are shown: https://portal.azure.com/#@/resource/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Automation/automationAccounts/{account}/jobs/{jobId}

Troubleshooting

Symptom	Likely cause	Fix
Runbook … has never been published	The runbook is still a draft (state New)	Publish it in Azure Automation
Cannot process command because of one or more missing mandatory parameters	A mandatory parameter was blank	Give the parameter a value on the task
Cannot process argument transformation on parameter …	A value is not in the declared type's format	Use the formats in the table above
You have requested to create a runbook job on a hybrid worker group that does not exist	Wrong Hybrid Worker Group name	Use the group name exactly as shown in the Automation account
Output parameters stay empty	The runbook did not write a JSON object as its last output record, or the names differ	Write `ConvertTo-Json -Compress` output last; match the parameter names
Run fails with concurrent-job quota is used up	Too many jobs running in the account	Retry later, or cap concurrency with a Contention Profile

Documentation