Invoke-CUAction: Run an Action

Introduction

With the Invoke-CUAction cmdlet, you can run an action as you would do from the Real-Time DX console or in the web UI.

Syntax

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

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 operation on a particular item, such as user sessions, machines, processes, and so on.

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

Input parameters

Output

How to run

In this example, we show you how to run the Analyze Logon Duration 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 make use of the Invoke-CUQuery cmdlet which is a powerful method 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. Now, let's grab this sessionID and 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, we can use the Get-CUActionSignature cmdlet.

   Get-CUActionSignature -ActionId $ALD.Id
   

   

5. Now we have all input parameters for the Invoke-CUAction cmdlet. Let's 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.

Examples

Example 1 - Run an action that requires user credentials

For some actions, you need to provide 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 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. Retrieve the input parameters for the action

   Get-CUActionSignature -ActionId c65e3712-2c27-4bf5-a08b-686d48da5b0b
   

   As you can see, this action has two input parameters:
   

5. Replace the default value "1" with "2" and run the action

   Invoke-CUAction -ActionId "c65e3712-2c27-4bf5-a08b-686d48da5b0b" -Table "Computers" -RecordsGuids "63e8be03-595b-4b6b-8eba-4faee44045ec" -UserInput '"{\"arg_1\":\"2\", \"creds\": { \"saved\" : true, \"user\" : \"\", \"domain\" : \"\", \"cypher\" : \"\", \"monitor\" : \"\", \"keyId\" : \"dede1f6f-490b-4b97-b9c9-99799021494b\", \"publicKey\" : \"\"}}"'