Skip to content

Creating Jobs

The Jobs page is used to queue on-demand script execution jobs that PowerShell Orchestrator agents retrieve and execute. A job represents a single request for a specific registered agent to execute a selected PowerShell script and forward the output to a configured syslog target.

Understanding jobs:

Jobs are the core unit of work in PowerShell Orchestrator. When a job is created it is saved with a status of Pending. The assigned agent retrieves the job on its next poll cycle (default: every 20 seconds), downloads and executes the script locally, forwards the output to the configured syslog target, and reports the result back to the server.

Scripts are stored centrally on the PowerShell Orchestrator Server and downloaded to the agent on demand at execution time — agents do not need to have scripts pre-installed locally.

Prerequisites:

Before creating a job confirm the following:

  • At least one PowerShell Orchestrator Agent is registered and showing as Online in the Clients page
  • At least one target is configured in the Targets page
  • At least one PowerShell script is available in the server script library
  • The intended agent has the required permissions and PowerShell modules to execute the selected script

Accessing the Jobs page:

  1. Log in to the PowerShell Orchestrator Server web interface at https://<server-name>:52866
  2. Navigate to Jobs in the main navigation

Viewing the job queue:

The Jobs page displays all jobs with the following information:

Column Description
Job ID Unique identifier for the job
Script Name The PowerShell script assigned to the job
Client The agent assigned to execute the job
Target The syslog destination for script output
Status Current job state with color-coded indicator
Created When the job was created
Started When the agent began execution
Completed When execution finished
Duration Total script execution time

Job status indicators:

Status Color Description
Pending 🟡 Yellow Job queued and waiting for the agent to pick it up
Running 🔵 Blue Currently executing on the agent
Completed 🟢 Green Successfully finished
Failed 🔴 Red Execution error or timeout

Queuing a new job:

  1. Click Queue New Job
  2. Configure the job:

Script: Select the PowerShell script to execute from the available script library. Scripts are stored centrally on the server and downloaded to the agent at execution time.

Client: Select the registered agent that will execute the script. Confirm the agent shows as Online before selecting it.

Target: Select the syslog destination where script output will be forwarded.

Script Parameters (if applicable): If the selected script requires parameters, input fields will appear for each parameter:

  • Required parameters are marked with an asterisk (*)
  • Optional parameters can be left blank
  1. Click Queue Job

The job is saved with a status of Pending. The assigned agent will claim and execute it on its next poll cycle.

Viewing job results:

To view the full details and output of a completed or failed job:

  1. Click on the job in the Jobs list
  2. The job detail view displays:
    • Standard Output — the script’s standard output stream
    • Error Output — any errors generated during execution
    • Exit Code — the PowerShell exit code returned by the script
    • Full Execution Log — the complete execution log from the agent

Canceling a job:

To cancel a job that is in Pending or Running status:

  1. Locate the job in the Jobs list
  2. Click Cancel
  3. Confirm the cancellation

Canceling a Running job sends a termination signal to the agent. The agent will attempt to stop script execution gracefully. Script output generated before cancellation may still be forwarded to the configured syslog target.

Investigating failed jobs:

If a job shows a status of Failed work through the following checks:

  1. Click on the failed job to review the error output and exit code
  2. Check the agent logs for more detailed error information:

C:ProgramDataPSOrchestratorAgentlogs

Common failure causes:

Cause Resolution
Agent offline when job was claimed Confirm agent is Online before creating jobs
Script execution timeout Increase DefaultTimeoutSeconds in agent appsettings.json
PowerShell version mismatch Confirm PowerShellVersion setting in agent appsettings.json matches the script requirements
Missing PowerShell module on agent Install the required module on the agent machine
Incorrect script parameters Review and correct the parameter values
Insufficient permissions Confirm the agent service account has required permissions for the script

Best practices:

  • Always confirm the assigned agent is Online before queuing a job — a job assigned to an Offline agent will remain in Pending status until the agent reconnects
  • Review script parameters carefully before queuing — incorrect parameters are a common cause of script execution failures
  • Monitor job progress from the Jobs page and review output as soon as the job completes
  • For recurring executions of the same script use the Schedules feature rather than manually queuing the same job repeatedly
  • Review the full execution log for failed jobs before retrying — understanding the root cause prevents repeated failures
  • Retain job execution records as an audit trail of script activity across your environment

[Your administrator should document which scripts are available in the server library and the intended purpose of each so team members can select the correct script when creating jobs.]