Get Machines Activity

Overview

The Get Machines (get_machines) Activity is a useful feature for use in your automation packages. With the Get Machines Activity, you can retrieve a list of machines in which Pia agents have been deployed also including details such as Computer Name, User logged In, Status etc.

The Pia agent is an agent service which performs tasks on the user's machine based on the commands sent by Pia. When an automation that involves making changes to the user's machines are run in Pia, these changes are made through the agent. For more information on agents, you can refer to: Agents.

The Get Machines Activity can be used in packages that make changes to the user's computer. An example scenario where this activity may be used is while setting up a VPN for a user. Pia may use the activity to retrieve a list of machines and present the list in chatbot for selection of the machine which requires VPN setup using chat interaction.

Another example where this activity may be used is when setting up a printer or troubleshooting printer issues for the user.

The Get Machines activity can be located by searching for "Get Machines" in the list of activities in the package editor:

Below is the working sample of the activity in a basic package:

# Orchestrator package
conditions: 
- name: 'client_filter' 
  optMode: 'OptOut'
  category: 'Testing'

- name: 'chat'
  option_button: 'Get Machines Test'
  option_text: 'This is a test package'
  option_category: 'Test Category'

steps:

- task: get_machines


## Generating table form def for a Table field (more examples further below)
- task: inline_powershell
  inputs:
    machines_for_users: =get_machines.machines
    script: |
            $machines = @()
            foreach($machine in $(ConvertFrom-Json $machines_for_users))
            {
                Write-Host $machine
                $machines += @{ComputerName = $machine.ComputerName;Status = $machine.Status; Select = $true}
            }
            $formDefProps =@{
                machines = $machines
            }
            Write-Host $(ConvertTo-Json -Depth 5 $formDefProps)
            return @{
                formDef = $(ConvertTo-Json -Depth 5 $formDefProps);
            }

## Displays the list of machines in the Table field
- task: chat_interaction
  inputs:
    text: |
        Here's the list of machines you requested:
    form_name: 'get_machines'
    form_def: =inline_powershell.formDef
    form_display_mode: 'Embed'

In the above example, the information obtained by using Get Machines activity which will be passed into a table form with the following configuration:

When the user runs the package, they will get a list of machines and their status in the following format.

Activity Behaviour

The primary behaviour of the Get Machines activity is to retrieve a list of agents currently available for the client. Since the activity does not output anything directly in the chatbot, the information retrieved from this activity can be converted into required format by using the inline_powershell activity and can be used as an output to the chatbot by using a chat interaction activity.

Additionally, you can set the package to filter the machines to be returned by specifying input properties which is defined further below in this article.

The Get Machines 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

Use properties to modify the behaviour of the activity.

Property Name: client_id
Default Value: $Ctx_CW_Client_Id
Property Required: Yes
Property Description: This is the internal Client ID which defaults to the client id for the ticket associated with this package execution.

Property Name: sam_account_name
Property Required: No
Property Description: User this input property to search for machines which the user is logged into.

Property Name: days_since_login
Property Required: No
Property Description: The Pia agent keeps track of users who have logged into the machines. You can use this to find the users who have logged in the last X days. This is the duration between present and their last logged in date. This is useful in combination with the sam_account_name input property.

Property Name: include_inactive_agents
Property Options: 'true' or 'false'
Default Value: 'false'
Property Required: No
Property Description: This flag determines whether the output includes inactive machines or not.

Property Name: machine_name
Property Required: No
Property Description: This input property allows getting a specific machine by its name.

Property Name: machine_info
Property Options: 'true' or 'false'
Default Value: 'false'
Property Required: No
Property Description: This is to define whether or not to include the extended machine details. You cannot filter on extended details using the get_machines activity but with the extra information, you can do your own filtering. If this is 'true', the data retrieved for each machine object will be as below:

{
    "QualifiedName": "",
    "ComputerName": "",
    "LastLoggedInUser": "",
    "LastCheckedInTime": "",
    "DateRegistered": "",
    "Status": "",
    "LastLoggedInTime": "",
    "IsActive": ,
    "Tags": "",
    "MachineInformation" : {
        "IsVirtual" : "",
        "MachineBuildNumber" : "",
        "MachineOperatingSystem" : "",
        "MachineRoles" : "",
        "MachineSubType" : "",
        "MachineType" : ""
    }
}

Property Name: tags
Property Required: No
Property Description: This input property allows getting machines that have specified tags. You can specify one or multiple tags in a comma separated format. If you specify multiple tags, then only the machines that have all the specified tags will be returned.

Output Properties

There is a single property which the Get Machines activity makes available:

Property Name: machines
Property Description: This will return an object in JSON structure containing the following information about the machine:

Qualified Name
Computer Name
Last Logged in User
Last Check in Time
Date Registered
Status (Online/ Offline)
User Last Logged in Time

[
  {
    "QualifiedName":"PIA-RDS01",
    "ComputerName":"PIA-RDS01",
    "LastLoggedInUser":"billy.bob",
    "LastCheckedInTime":"2023-03-21T11:55:15",
    "DateRegistered":"2022-10-24T03:39:28.7675034",
    "Status":"Online",
    "LastLoggedInTime":"0001-01-01T00:00:00",
    "IsActive":true,
    "Tags":""
  }
]

Examples

Get Machines activity with Loop

In the below example, Pia will retrieve a list of online machines for the user to choose from. Pia will then retrieve currently logged in user for each of the machines in a loop.

For this package, a custom activity has been created in Activity Editor as below:

Function VerifyActivity()
{
    # Put code here to verify the command will work given the variables 
    return $true;
}

Function ExecuteActivity()
{
    # Do stuff here

    # Set output variables
    $currentLoggedInUser = whoami

    $activityOutput.out.currentLoggedInUser = $currentLoggedInUser
    # Set execution status
    $activityOutput.success = $true;

    return $activityOutput;
}

This activity retrieves the current logged in user for all the selected machines in the below package:

# Orchestrator package
conditions: 
- name: 'client_filter' 
  optMode: 'OptOut'
  category: 'Testing'

- name: 'chat'
  option_button: 'Get Machines Test2'
  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: |
            write-host 'agents for user' $agents_for_user
            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"}
                #Write-Host "=====agents_for_client: $(ConvertTo-Json -Depth 5 $agents_for_client)"
                $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
  alias: selected_machines
  inputs:
    text: |
        Select the machine to continue:
    form_name: 'get_machines2'
    form_def: =inline_powershell.formDef
    form_display_mode: 'Embed'

# Retrieve currently logged in user in the selected machines
- task: inline_powershell
  alias: loop_condition_processor
  inputs:
    selected_machines: =selected_machines.form.computer
    script: |
            $computers = @()
            $selectedMachines = $selected_machines -split ","
            $totalMachines = $selectedMachines.Length
            $loopData = @{TotalCount =$totalMachines; Machines = $selectedMachines; }
            return @{LoopData = @{Count = $totalMachines; Machines = $selectedMachines; SkipLoopProcesses = $totalMachines -lt 1}}

#Start
- task: inline_powershell
  alias: loop_start_checker
  skip: =loop_condition_processor.LoopData.SkipLoopProcesses
  inputs:
    machines: =loop_condition_processor.LoopData.Machines
    last_run_index: =loop_end_checker.Index
    script: |
            $index = $last_run_index
            if($index -eq $null)
            {
                $index = 0
            }
            else
            {
                [int]$index += 1
            }
            $currentSelectedMachines = $machines[$index]
            return @{CurrentIndex = $index; Machine = $currentSelectedMachines;}

- task: get_logged_in_user
  executionEnvironment: 'AsUser'
  executionEnvironmentKey: =loop_start_checker.Machine

- task: inline_powershell
  alias: 'chat_message_processor'
  inputs:
    machine: =loop_start_checker.Machine
    user: =get_logged_in_user.currentLoggedInUser
    script: |
            $chatText = "The logged in user in machine $machine is $user"
            return @{ChatMessage = $chatText;}

- task: chat_interaction
  inputs:
    text: =chat_message_processor.ChatMessage


#End
- task: inline_powershell
  alias: loop_end_checker
  skip: =loop_condition_processor.SkipLoopProcesses
  inputs:
    total_loops: =loop_condition_processor.LoopData.Count
    last_run_index: =loop_start_checker.CurrentIndex
    script: |
            $continueLoop = $true
            if([int]$last_run_index -ge ([int]$total_loops) - 1)
            {
                $continueLoop = $false
            }
            return @{Index = [int]$last_run_index; Loop = $continueLoop;}

- task: loop
  inputs:
    condition: =loop_end_checker.Loop
    activity: 'loop_start_checker'


- task: chat_interaction
  inputs:
    text: 'Task Completed.'

In this package, Pia retrieves the current logged in user for each of the selected machine and present them in the chatbot as below:

Overview​

Activity Behaviour​

Input Properties​

Output Properties​

Examples​

Overview

Activity Behaviour

Input Properties

Output Properties

Examples