> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/powershell-universal/automation/triggers.md).

# Triggers

Trigger PowerShell Universal scripts automatically on events like job completion, server startup, user login, git sync, or computer status changes.

> Triggers require a [license](/powershell-universal/licensing.md).

Triggers automatically start PowerShell Universal scripts when platform events occur. Use them for global error handling, notifications, integrations, and event-driven automation.

> Triggered jobs do not start additional triggers. Triggers are stored in `triggers.ps1`.

## Trigger events

You can create triggers for the following events:

* Job Started, Cancelled, Completed, Completed with Error, Requesting Feedback, Failed, and Timed Out
* App (Dashboard) Started, Stopped, and Session Expired
* Event Hub Connected and Disconnected
* Health Check Failed
* Server Started and Stopping
* New User Login and User Login
* Use of a Revoked App Token
* API Authentication Failed and API Error
* Git Sync
* License Expired and License Expiring
* Computer Offline
* Notification Created

### Notification Created

The **Notification Created** event runs when PowerShell Universal creates a notification through the notification service or Notification API. Use it to route platform alerts to systems such as Teams, email, ticketing, or monitoring tools.

The trigger script receives the created notification in the `$Notification` parameter. It includes the notification ID, title, description, level, creation time, source job, script, dashboard, license, identity, and stack trace when available.

```powershell
param($Notification)

if ($Notification.Level.ToString() -eq 'Error') {
    Send-MailMessage -To 'operations@example.com' `
        -Subject $Notification.Title `
        -Body $Notification.Description
}
```

Create the trigger in **Automation > Triggers** by selecting **Notification Created** as the event type, or define it in a configuration repository:

```powershell
New-PSUTrigger `
    -Name 'Route error notifications' `
    -EventType NotificationCreated `
    -TriggerScript 'RouteNotification.ps1'
```

Notifications generated when a triggered job starts do not raise this event. This prevents notification triggers from recursively creating more notification-triggered jobs.

### New User Login

The New User Login event occurs when a user first accesses PowerShell Universal. The script receives a `$User` parameter with user information.

```powershell
@{
    Name = 'username'
    Roles = @()
}
```

### User Login

The User Login event occurs when a user accesses PowerShell Universal. The script receives a `$data` parameter with user information.

```powershell
@{
    UserName = 'username'
    RemoteIpAddress = ''
    LocalPort = ''
    RemotePort = ''
}
```

### Use of a Revoked App Token

The revoked app-token event occurs when a revoked app token is used. The script receives a `$data` parameter containing the app-token contents as a string.

### Git Sync

The Git Sync event occurs for both successful and unsuccessful Git synchronizations. The script receives a `$data` parameter with the Git status.

```csharp
public class GitStatus
{
    public long Id { get; set; }
    public string CommitId { get; set; }
    public DateTime Timestamp { get; set; }
    public TimeSpan SyncTime { get; set; }
    public int Changes { get; set; }
    public string Location { get; set; }
    public string Remote { get; set; }
    public GitStatusResult Result { get; set; }
    public string ResultMessage { get; set; }
    public string ComputerName { get; set; }
}
```

### Computer Offline

The Computer Offline event provides the computer object in the `$Data` parameter.

```powershell
class Computer {
    [long]$Id
    [string]$Name
    [DateTime]$HeartBeat
    [ComputerStatus]$Status
    [bool]$Maintenance
    [bool]$Deleted
    [List[ComputerTag]]$Tags
    [string]$Version
    [DateTime]$FileSyncTimestamp
    [string]$DeploymentVersion
    [string]$DeploymentName
    [string]$GitSettings
    [string]$GitBranch
    [ComputerType]$Type
}
```

## Global triggers

Global triggers run the assigned script whenever the selected event occurs. For example, this trigger runs `Script.ps1` whenever any job starts:

```powershell
New-PSUTrigger -Name 'Job started' -EventType JobStarted -TriggerScript 'Script.ps1'
```

## Resource triggers

Resource triggers run only when an event occurs on the selected resource. For example, this trigger runs when the selected dashboard stops:

```powershell
New-PSUTrigger `
    -Name 'Dashboard stopped' `
    -EventType DashboardStopped `
    -TriggerScript 'Script.ps1' `
    -Dashboard 'Dashboard'
```

## Event metadata

A job created by a trigger receives metadata about the event that invoked it. Job triggers receive a `$Job` parameter and dashboard triggers receive a `$Dashboard` parameter. Server-status triggers do not receive a parameter. Notification triggers receive `$Notification`.

```powershell
param($Job)
$Job
```

## Conditions

Use the `-Condition` parameter of `New-PSUTrigger` to determine whether the trigger should run. The condition runs locally on the server and must return `$true` or `$false`.

For example, this condition runs only when the `Environment` environment variable is set to `production`:

```powershell
New-PSUTrigger -Condition { $Env:Environment -eq 'production' }
```

## PowerShell cmdlets

Manage triggers with `New-PSUTrigger`, `Get-PSUTrigger`, `Set-PSUTrigger`, and `Remove-PSUTrigger`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.devolutions.net/powershell-universal/automation/triggers.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.