Restart Agent Machine Activity
Overviewβ
The Restart Agent Machine (restart_agent) Activity is a powerful feature for use in your automation packages. This activity will initiate restart action on the user's computer by sending a command to Pia agent installed on the device.
With the restart agent machine activity, user can initiate a restart on one or more machines at once. This activity does not notify the user prior to restarting their device so you may wish to handle this in your automation prior to using this activity.
One example scenario where this activity may be used is while running troubleshooting packages. For example, this activity may be added as one of the troubleshooting options in a Computer Troubleshooting package.
Another example package where this activity may be used is Windows update package. In this scenario, you may want to restart the computer once windows has been updated.
The Restart Agent Machine activity can be located by searching for "Restart Agent Machine" in the list of activities in the package editor:
Here is a working sample of the activity in a basic package:
# Orchestrator package
conditions:
- name: 'client_filter'
optMode: 'OptOut'
category: 'Testing'
- name: 'chat'
option_button: 'Restart Agent Machine Test'
option_text: 'This is a test package'
option_category: 'Test Category'
steps:
- task: get_machines
alias: agents_for_client
- task: inline_powershell
alias: prepare_data
inputs:
agents_for_client: =agents_for_client.machines
script: |
If(![string]::IsNullOrEmpty($agents_for_client) ){
$agents_for_client = [Array]$(ConvertFrom-Json $agents_for_client)
$agents_for_client = $agents_for_client | Where {$_.Status -eq "Online"}
$allMachines += $agents_for_client | Select @{N='text';E={"$($_.ComputerName) `(User: $($_.LastLoggedInUser)`)"}},@{N='value';E={$($_.QualifiedName)}}
}
Else{
$agents_for_client = @()
}
$allMachines = $allMachines | Where {![string]::IsNullOrEmpty($($_.value))} | Sort -Property text;
$formDefProps = @{
isLastLoggedComputer = ($lastLoggedComputers.Count -gt 0).ToString();
lastLoggedComputer = @($lastLoggedComputers);
computer = @($allMachines);
};
return @{
formDef = $(ConvertTo-Json -Depth 5 $formDefProps);
isNotLoggedComputer = -not [System.Convert]::ToBoolean($formDefProps.isLastLoggedComputer);
}
- task: chat_interaction
inputs:
text: 'Select the machine you would like to restart:'
form_name: 'get_machines2'
form_def: =inline_powershell.formDef
form_display_mode: 'Embed'
- task: restart_agent
inputs:
agent: =get_machines2.form.computer
- task: chat_interaction
inputs:
text: 'Restart action has been initiated.'
In the above example, Pia retrieves a list of devices available for the client and presents a list to the user in chatbot. The user can then select which device to restart.
Activity Behaviourβ
The main purpose of the Restart Agent Machine Activity is to initiate the restart process on the chosen machine. This activity waits until the computer has restarted and is back online before proceeding (use the "wait" input property to control this behaviour).
If the activity is successful, Pia will proceed with executing the package and show a success message in the activity log. However, if the process fails, the package will also fail with a general error. To obtain more specific error information, you can refer to the activity log in the chatbot or live packages screen.
The Restart Agent Machine Activity can be used in all package executions (i.e. packages that are initiated via Schedule or Ticketing System Event or the Chatbot).
Input Propertiesβ
Here are the input properties available in the activity that can be used to modify its behaviour:
Property Name: agent
Property Required: Yes
Property Description: This is the name of the agent to restart. If there are multiple agents, use comma separated format.
Property Name: wait
Property Required: No
Property options: 'true' or 'false'
Property Description: If this is true, the activity uses a scheduled mechanism to wait until the agent comes back online before resuming package execution
Output Propertiesβ
The Restart Agent Machine Activity does not have an Output property.
Examplesβ
Restarting multiple machines at once
# Orchestrator package
conditions:
- name: 'client_filter'
optMode: 'OptOut'
category: 'Testing'
- name: 'chat'
option_button: 'Restart Agent Machine Test'
option_text: 'This is a test package'
option_category: 'Test Category'
steps:
- task: get_machines
alias: agents_for_client
- task: inline_powershell
alias: prepare_data
inputs:
agents_for_client: =agents_for_client.machines
script: |
If(![string]::IsNullOrEmpty($agents_for_client) ){
$agents_for_client = [Array]$(ConvertFrom-Json $agents_for_client)
$agents_for_client = $agents_for_client | Where {$_.Status -eq "Online"}
$allMachines += $agents_for_client | Select @{N='text';E={"$($_.ComputerName) `(User: $($_.LastLoggedInUser)`)"}},@{N='value';E={$($_.QualifiedName)}}
}
Else{
$agents_for_client = @()
}
$allMachines = $allMachines | Where {![string]::IsNullOrEmpty($($_.value))} | Sort -Property text;
$formDefProps = @{
isLastLoggedComputer = ($lastLoggedComputers.Count -gt 0).ToString();
lastLoggedComputer = @($lastLoggedComputers);
computer = @($allMachines);
};
return @{
formDef = $(ConvertTo-Json -Depth 5 $formDefProps);
isNotLoggedComputer = -not [System.Convert]::ToBoolean($formDefProps.isLastLoggedComputer);
}
- task: chat_interaction
inputs:
text: 'Select the machine you would like to restart:'
form_name: 'get_machines2'
form_def: =inline_powershell.formDef
form_display_mode: 'Embed'
- task: restart_agent
inputs:
agent: =get_machines2.form.computer
- task: chat_interaction
inputs:
text: 'Restart action has been initiated.'