Invoke-CUAction: Run an Action

Syntax with -UserInput Parameter

Invoke-CUAction [-ActionId] <string> [-Table] <string> [[-UserInput] <string>] [-RecordsGuids] <string[]> [<CommonParameters>]

Syntax with Implicit Credentials

$Secure = ConvertTo-SecureString "PassWord" -AsPlainText -Force
$creds = New-Object -TypeName ControlUp.PowerShell.User.Cmdlets.Actions.Credentials
$creds.Domain="smartx.dom"
$creds.Password=$Secure
$creds.User="UserName"
Invoke-CUAction -ActionId "ActionIDString" -Table "TableName" -RecordsGuids "RecordsGuidsString" -Credentials $creds 

Syntax with Shared Credentials

$creds = New-Object -TypeName ControlUp.PowerShell.User.Cmdlets.Actions.Credentials
$creds.Saved=$true
$creds.KeyId="KeyIDString"
Invoke-CUAction -ActionId "ActionIDString" -Table "TableName" -RecordsGuids "RecordsGuidsString" -Credentials $creds -debug

How to run

1. Import the ControlUp.PowerShell.User module into your PowerShell session:

$pathtomodule = (Get-ChildItem "C:\Program Files\Smart-X\ControlUpMonitor\*ControlUp.PowerShell.User.dll" -Recurse | Sort-Object LastWriteTime -Descending)[0]
Import-Module $pathtomodule

2. Execute the cmdlet by providing the required input parameters to trigger a specific action on a particular item, such as user sessions, machines, or processes:

Invoke-CUAction -ActionId "b636f434-2843-4a5c-a21a-eed7a02d0946" -RecordsGuids "e99b0de6-2b0f-495a-ba0e-3d1c1dfe88d9" -Table "Sessions" -Credentials $creds

Input parameters

Output parameters

Run an action

In this example, we show you how to run the Analyze Logon Duration action script on a user session.

1. Retrieve the ActionID and the Table:

   $actions = Get-CUAvailableActions
   $ALD = $actions | Where-Object {$_.Title -eq 'Analyze Logon Duration'} | select-object Id, Title, Table
   

   

2. You can see that the ALD script needs to run on a user session. To get session information, we use the Invoke-CUQuery cmdlet to retrieve real-time information from the monitor's in-memory database:

   (Invoke-CUQuery -Scheme Main -Table Sessions -fields sUserAccount, eConnectState, sServerName -TranslateEnums -Where "sUserAccount = '[domain]\[username]'" -sort eConnectState).Data
   

   

3. Copy this sessionID, assign it to the $ALD variable, and add it as a property:

   $userSession = (Invoke-CUQuery -Scheme Main -Table Sessions -fields sUserAccount, eConnectState, sServerName -TranslateEnums -Where "sUserAccount = '[domain]\[username]'" -sort eConnectState).Data
   
   $userSession.key
   

4. The ALD script requires input parameters which we need to provide to the Invoke-CUAction cmdlet. To collect all input parameters for the ALD script, use the Get-CUActionSignature cmdlet:

   Get-CUActionSignature -ActionId $ALD.Id
   

   

5. Now that we have all input parameters for the Invoke-CUAction cmdlet, run the action:

Invoke-CUAction -ActionId b636f434-2843-4a5c-a21a-eed7a02d0946 -RecordsGuids db421154-361e-4054-85f6-bcdbd23c7b43 -Table Sessions -UserInput '"{\"arg_0\":\"-DomainUser\",\"arg_2\":\"-CUDesktopLoadTime\",\"arg_4\":\"-SessionId\",\"arg_6\":\"-SessionName\",\"arg_8\":\"-ClientName\"}"'

Error codes

Below, you can find the API error code that is returned for each request. If the returned error code is 0, it indicates that the action was successfully executed.

Example: Run an action that requires user credentials

For some actions, you must provide shared user credentials that are stored in your Credentials Store.

1. Get the ActionID with the Get-CUAvailableActions cmdlet.

2. Use the Get-CUCredentials cmdlet to retrieve the key ID of the shared credential:
   

3. Use the Get-CUComputers cmdlet to retrieve the ID of the machine on which the action should run. In our example, we run the Get Citrix Connection Failures action which needs to run on a Citrix Delivery Controller:

   Get-CUComputers | where {$_.FQDN -eq 'CUXENDDC-19A.controlUp.demo'}
   

   

4. Run the action:

   Invoke-CUAction -ActionId "c65e3712-2c27-4bf5-a08b-686d48da5b0b" -Table "Computers" -RecordsGuids "63e8be03-595b-4b6b-8eba-4faee44045ec" -Credentials $creds -debug