Pia

https://knowledge.pia.ai/docs/
Admin
Pia is a platform that provides automation, smart forms, and triage capabilities with comprehensive...
Tokens:234,219
Snippets:2,097
Trust Score:8.6
Update:10 months ago
Show doc for...
Tokens:
Raw
### Install PIA Agent Command - PowerShell

Source: https://knowledge.pia.ai/docs/portal/implementation/agents

Example command to initiate the PIA Agent installation. It specifies installation parameters such as client ID, certificate clearing, and tenant URL. Ensure to replace placeholders like `<clientid>` and `<partnername>` with actual values.

```powershell
PiaAgent -install -clientid <clientid> -clearcert -tenanturl '<partnername>.pia.ai' -Verbose
```

--------------------------------

### Start Package with Inline Mode and ai_class

Source: https://knowledge.pia.ai/docs/learn/product-documentation/Activities/Start-Package-Activity

This example demonstrates starting a second package in 'inline' mode using its AI classification. The current package execution is paused until the second package completes. This is useful for sequential tasks where the result of the second package is needed before proceeding.

```yaml
# Orchestrator package
conditions:  
- name: 'client_filter'  
  optMode: 'OptOut'  
  category: 'Test Package'  
  
- name: 'chat'  
  option_button: 'First package'  
  option_text: 'This is a test package'  
  option_category: 'Test Category'  
  
steps:  

- task: chat_interaction  
  inputs:  
    text: 'This is first Package'  
  
- task: start_package  
  inputs:  
    mode: 'inline'  
    ai_class: 'Service Request|Test|Test'  
  
- task: chat_interaction  
  inputs:  
    text: 'Back to the first Package'
```

--------------------------------

### Install PIA Agent (PowerShell)

Source: https://knowledge.pia.ai/docs/portal/the_platform/time-logging

Handles the installation of the PIA agent by first downloading the agent executable and then launching it with appropriate arguments. The arguments include installation flags, tenant URL, and client ID if provided. Ensures the agent is downloaded before attempting installation.

```powershell
Function Install-PiaAgent(){
    $result = Download-PiaAgent
    $exeArgs = if(![string]::IsNullOrEmpty($clientid) -and $clientid -ne 0){"-install -tenantname $tenanturl -clientid $clientid"}else{"-install -tenantname $tenanturl"}
    if($result){Launch-Executable -exepath $outfile -arguments $exeArgs}
}
```

--------------------------------

### Start Package with Detached Mode and package_id

Source: https://knowledge.pia.ai/docs/learn/product-documentation/Activities/Start-Package-Activity

This example shows how to start a second package in 'detached' mode using its internal package ID. The second package will start execution after the current package has finished. This is suitable for asynchronous tasks or when the second package does not need to immediately follow the first.

```yaml
# Orchestrator package
conditions:  
- name: 'client_filter'  
  optMode: 'OptOut'  
  category: 'Test Package'  
  
- name: 'chat'  
  option_button: 'First package'  
  option_text: 'This is a test package'  
  option_category: 'Test Category'  
  
steps:  
  
- task: chat_interaction  
  inputs:  
    text: 'This is first Package'  
  
- task: start_package  
  inputs:  
    mode: 'detached'  
    package_id: 'ea7079f1-ef95-4d38-a8d3-744ad0fb3add'
```

--------------------------------

### Install Software using Winget CLI

Source: https://knowledge.pia.ai/docs/portal/the_platform/Pia%20Software%20Manager

This snippet shows how to use the Winget command-line interface to add a software source from Pia's package manager and then install a specific software package. It requires prior setup of the Pia Winget feed with a valid, non-expired security token. Ensure the feed URL and software identifier are correctly specified.

```bash
winget source add --name Pia "https://<YOUR_TENANT_NAME>.pia.ai/winget/<WINGET_TOKEN>"  -t Microsoft.Rest  
winget install "<SOFTWARE_IDENTIFIER_NAME>" -s Pia  

```

--------------------------------

### Pia Automation Package Example: Store and Get Package Data

Source: https://knowledge.pia.ai/docs/learn/product-documentation/Activities/Get-Package-Data-Activity

This example demonstrates the usage of Store Package Data and Get Package Data activities within a Pia automation package. It stores two values and then retrieves one using its key, making it available for subsequent chat interaction.

```Pia Automation
conditions:
- name: 'client_filter'
  optMode: 'OptOut'
  category: 'Hello World'

- name: 'chat'
  option_button: 'Test Get Package Data'
  option_text: 'This is a Test Package'
  option_category: 'Test Category'

steps:
- task: store_package_data
  inputs:
    key: 'uniquekey_1'
    value: 'Hello World'

- task: store_package_data
  inputs:
    key: 'uniquekey_2'
    value: 'Hello'

- task: get_package_data
  inputs:
    key: 'uniquekey_1'

- task: chat_interaction
  inputs:
    text: =get_package_data.value

```

--------------------------------

### Install Pia Agent (PowerShell)

Source: https://knowledge.pia.ai/docs/portal/the_platform/agent/agents

Downloads the Pia Agent executable and then launches it with installation arguments. It requires the 'Download-PiaAgent' function to be available and constructs installation arguments based on whether a client ID is provided.

```powershell
Function Install-PiaAgent(){
    $result = Download-PiaAgent
    $exeArgs = if(![string]::IsNullOrEmpty($clientid) -and $clientid -ne 0){"-install -tenantname $tenanturl -clientid $clientid"}else{" -install -tenantname $tenanturl"}
    if($result){Launch-Executable -exepath $outfile -arguments $exeArgs}
}
```

--------------------------------

### Pia Automation Package Example: Get Package Data

Source: https://knowledge.pia.ai/docs/learn/product-documentation/Activities/get-package-data-activity

This example demonstrates the usage of the Get Package Data activity within a Pia automation package. It shows how to store data using 'store_package_data', retrieve it using 'get_package_data' with a specified key, and then utilize the retrieved value in a subsequent 'chat_interaction' task. The activity retrieves data stored by 'store_package_data' and makes it available via the 'value' output property.

```yaml
conditions:
- name: 'client_filter'
  optMode: 'OptOut'
  category: 'Hello World'

- name: 'chat'
  option_button: 'Test Get Package Data'
  option_text: 'This is a Test Package'
  option_category: 'Test Category'

steps:
- task: store_package_data
  inputs:
    key: 'uniquekey_1'
    value: 'Hello World'

- task: store_package_data
  inputs:
    key: 'uniquekey_2'
    value: 'Hello'

- task: get_package_data
  inputs:
    key: 'uniquekey_1'

- task: chat_interaction
  inputs:
    text: =get_package_data.value
```

--------------------------------

### Pia Automation Package Example with Get Form Data

Source: https://knowledge.pia.ai/docs/learn/product-documentation/Activities/Get_Form_Data_Activity

This example demonstrates a Pia automation package that includes a chat interaction, retrieving a client list, and then fetching data from a specific form named 'nick_form_name'. The retrieved form data can be used in subsequent automation steps.

```yaml
conditions:
  # Define the conditions for the automation package.
  - name: 'client_filter'
    optMode: 'OptOut'           # Set the opt-out mode for the client filter condition.
    category: 'Hello World'     # Category for the client filter condition.

  # Define another condition for chat interactions.
  - name: 'chat'
    option_button: 'Test button'    # Text for the button in the chat interaction.
    option_text: 'Option text'      # Text for the chat interaction option.
    option_category: 'Category'     # Category for the chat interaction option.

steps:
  # Define the steps for the automation workflow.

  # Step 1: Initiate a chat interaction.
  - task: chat_interaction
    inputs:
      text: 'Hello World!'       # Text to be sent in the chat interaction.
      form_name: 'nick_form_name' # Name of the form to be used in the chat interaction.

  # Step 2: Retrieve the list of clients.
  - task: get_clients

  # Step 3: Get data from a specific form.
  - task: get_form_data
    inputs:
      form_name: 'nick_form_name' # Name of the form from which data will be retrieved.

```

--------------------------------

### PowerShell: Install PIA Agent

Source: https://knowledge.pia.ai/docs/portal/implementation/agents

The Install-PiaAgent function orchestrates the installation of the PIA Agent. It first downloads the agent executable and then launches it with appropriate arguments, including tenant URL and client ID if provided. This function is called when the '$install' parameter is set and the agent is not already installed.

```powershell
Function Install-PiaAgent(){  
    $result = Download-PiaAgent  
    $exeArgs = if(![string]::IsNullOrEmpty($clientid) -and $clientid -ne 0){"-install -tenantname $tenanturl -clientid $clientid"}else{" -install -tenantname $tenanturl"}  
    if($result){Launch-Executable -exepath $outfile -arguments $exeArgs}
```

--------------------------------

### Install Azure CLI for PowerShell

Source: https://knowledge.pia.ai/docs/portal/implementation/clients

This PowerShell command installs the Azure CLI, which is a prerequisite for managing Azure resources and authenticating with Azure services like Microsoft Graph API. It downloads the MSI installer, runs it quietly, and then removes the installer file. Ensure PowerShell is run as an Administrator before executing.

```powershell
$ProgressPreference = 'SilentlyContinue'; Invoke-WebRequest -Uri https://aka.ms/installazurecliwindows -OutFile .\AzureCLI.msi; Start-Process msiexec.exe -Wait -ArgumentList '/I AzureCLI.msi /quiet'; rm .\AzureCLI.msi
```

--------------------------------

### Get Service Status Package Configuration

Source: https://knowledge.pia.ai/docs/code-examples

Defines a package configuration for the 'Get Service Status' activity, including chat conditions and extension automation setup. It specifies input variables for the task.

```YAML
#< This is where we've defined a chat condition   
#< This allows us to run it as a chat  
conditions:
- name: 'chat'
  option_text: 'Get Service Status'
  option_button: 'Get Service Status'
  option_category: ''  
  
#< This is where we've defined it as an Extension  
#< Without this it won't be available as an extension  
- name: 'extension_automation'
  
  
#< This is the client filter where we can opt in or out  
- name: 'client_filter'
  optMode: 'OptOut'
  category: 'Testing'
  
steps:
#< Let's do a Get Service Status! 📨  
- task: get_service_status
  inputs:
      serviceName:  'dummy_serviceName'
  

```

--------------------------------

### Get Machines Activity - Output Properties JSON Example

Source: https://knowledge.pia.ai/docs/learn/product-documentation/Activities/Get-Machines-Activity

This is an example of the JSON structure for the 'machines' output property of the Get Machines activity. It represents a list of machine objects, each containing detailed information about a specific machine.

```json
[
  {
    "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":""
  }
]
```

--------------------------------

### Orchestrator Package - Get Machines Activity Example

Source: https://knowledge.pia.ai/docs/learn/product-documentation/Activities/Get-Machines-Activity

This example demonstrates the usage of the Get Machines activity within an Orchestrator package. It includes conditions for filtering, defines a task to get machine data, processes this data using inline_powershell to format it for display, and finally presents the list of machines to the user via a chat interaction.

```yaml
# 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'  
  
```

--------------------------------

### Install Pia Agent via Command Line

Source: https://knowledge.pia.ai/docs/portal/implementation/agents

This command installs the Pia Agent using its executable. It requires the tenant name and client ID specific to your Pia environment. This method is suitable for scripting and automation across multiple clients.

```bash
OrchestratorAgentService.exe -tenantname <tenantname> -clientId <clientid> -install
```

--------------------------------

### Configure Chatbot Interaction Steps

Source: https://knowledge.pia.ai/docs/learn/product-documentation/Activities/Start-Package-Activity

Defines steps for interacting with a chatbot within a package. It includes sending text messages and starting a package with specified inputs.

```yaml
- task: chat_interaction
  inputs:
    text: 'This is first Package'

- task: start_package
  inputs:
    mode: 'inline'
    package_id: 'ea7079f1-ef95-4d38-a8d3-744ad0fb3ad'
    handle_errors_in_package: 'true'

- task: chat_interaction
  inputs:
    text: 'Back to the first Package'
```

--------------------------------

### Example AI AutoStart Condition in Pia Package

Source: https://knowledge.pia.ai/docs/learn/product-documentation/conditions/AI-AutoStart-Condition

This snippet demonstrates how to configure the AI AutoStart condition within a Pia automation package. It defines conditions for client filtering and chat interaction, and then sets up the AI AutoStart condition with specific classification and confidence ranges. The subsequent steps show how to process the output of the AI AutoStart condition to determine if the package was initiated by AI.

```yaml
# Pia Automation Package  
conditions:   
- name: 'client_filter'   
  optMode: 'OptOut'  
  category: 'Example AutoStart'  
  tags: 'Agents'  
  
- name: 'chat'  
  option_button: 'Example AutoStart'  
  option_text: 'Testing AutoStart'  
  option_category: 'Example AutoStart'  
  
- name: 'ai_autostart'  
  autostart_classification: 'Incident|Workstation|Slow Performance'  
  low_confidence_range: '0-0.29'  
  medium_confidence_range: '0.3-0.8'  
  high_confidence_range: '0.8-1'  
steps:  
- task: inline_powershell  
  alias: 'ai_autostart_processing'  
  inputs:  
    ai_autostart: =ai_autostart.package_started_by_ai  
    script: |  
        $ai_autostart = [Boolean]::Parse($ai_autostart)  
        if($ai_autostart){  
          $output = "This package was started by AI AutoStart."  
        } else {  
          $output = "This package was not started by AI AutoStart."  
        }  
        return @{  
            started_by_ai = $ai_autostart  
            not_started_by_ai = -not $ai_autostart  
            output = $output  
        }  
  
- task: chat_interaction  
  inputs:  
    text: =inline_powershell.output  

```

--------------------------------

### Powershell Script for Pia Agent Installation and Management

Source: https://knowledge.pia.ai/docs/portal/implementation/agents

This Powershell script provides functions to manage the Pia Agent. It includes logging, checking the agent service status and path, starting the service if stopped, and cleaning up installation files. It can be used for installing the agent with specific client details and tenant URLs.

```powershell
Function Write-PiaLog($message, $show) {
    if ($show) {
        Write-Host $message
    }
}

Function PiaAgent($install, $clientid, $clearcert, $tenanturl, $Verbose) {
    try {
        # Installation logic would be here, using provided parameters
        Write-PiaLog "PiaAgent called with: install=$install, clientid=$clientid, clearcert=$clearcert, tenanturl=$tenanturl, Verbose=$Verbose" -show
    } catch {
        Write-PiaLog $_.Exception.Message
    }
}

Function Check-PiaAgent(){
    $Service = Get-WmiObject Win32_Service -Filter "Name='OrchestratorAgent'"
    return [pscustomobject]@{ 
        status = if($($Service.State)){ $Service.State }else{$null}
        path = $($Service.PathName)
    }
}

Function Check-PiaService(){
    Start-Sleep -Seconds 3
    if((Check-PiaAgent).status -eq 'Stopped'){
        try{
            Start-Service 'OrchestratorAgent'
            Write-PiaLog "Service started" -show
        } catch {
            Write-PiaLog "Failed to start service" -show
        }
    }
}

Function CleanUp-PiaInstall(){
    if(Test-Path $outfile){ # Assuming $outfile is defined elsewhere
        Remove-Item $outfile -Force
    }
}

# Example usage for installation:
PiaAgent -install -clientid <clientid> -clearcert -tenanturl '<partnername>.pia.ai' -Verbose
```

--------------------------------

### Connect to Tenant and Check Pia Agent Status (PowerShell)

Source: https://knowledge.pia.ai/docs/portal/the_platform/agent/agents

Attempts to connect to a specified tenant URL on port 443 to verify network reachability. It then checks the status and path of the Pia Agent. If the agent is not installed, it proceeds to install it.

```powershell
try{
    $test = New-Object System.Net.Sockets.TcpClient;
    $test.Connect($tenanturl, 443);
    $test.Dispose();
    Write-Host "$tenanturl is reachable"
}catch{
    $test.Dispose()
    Write-Warning "$tenanturl is unreachable. Exiting."
    exit;
}

$agent = Check-PiaAgent
if(![string]::IsNullOrEmpty($($agent.path))){
    if(Test-Path $($agent.path) -ea SilentlyContinue){
        Write-PiaLog "Installed Version: $((Get-ItemProperty -Path $($agent.path))).VersionInfo.FileVersionRaw.Tostring()" -show
    }
}
$agentURL = 'https://piapackagefiles.blob.core.windows.net/share/agent/OrchestratorAgentService.exe'
$outfile = 'C:\Windows\Temp\Pia.OrchestratorAgentService.exe'

if($install -and !$uninstall -and !$reinstall -and $($agent.status) -eq $null){
    Write-PiaLog "Installing" -show
    Install-PiaAgent
    Check-PiaService
}
if(!$install -and $uninstall -and !$reinstall -and $($agent.status) -ne $null){
    Write-PiaLog "Uninstalling" -show
    Uninstall-PiaAgent
}
if(!$install -and !$uninstall -and $reinstall){
    Write-PiaLog "Reinstalling" -show
    Reinstall-PiaAgent
    Check-PiaService
}
CleanUp-PiaInstall
}
```

--------------------------------

### Basic Start Package Activity in Orchestrator

Source: https://knowledge.pia.ai/docs/learn/product-documentation/Activities/Start-Package-Activity

This snippet demonstrates a basic implementation of the Start Package activity within an Orchestrator package. It shows how to define conditions and tasks, including triggering a child package ('start_package') in 'detached' mode based on 'ai_class'.

```yaml
# Orchestrator package  
conditions:   
- name: 'client_filter'  
  optMode: 'OptOut'  
  category: 'Test Package'  
  
- name: 'chat'  
  option_button: 'Test'  
  option_text: 'This is a test package'  
  option_category: 'Test Category'  
  
steps:  

- task: chat_interaction  
  inputs:  
    text: 'This is a first Package'  
  
- task: start_package  
  inputs:  
    mode: 'detached'  
    ai_class: 'Service Request|Test|Test'  


```

--------------------------------

### Install Pia Extension via Registry (PowerShell)

Source: https://knowledge.pia.ai/docs/portal/implementation/chatbot-browser-extension

This PowerShell script configures registry settings to force install the Pia browser extension on Microsoft Edge. It creates necessary registry keys and adds the extension's ID and URL to the allowlist and forcelist. Requires administrator privileges to run.

```powershell
Function CheckAlreadyExists($n, $o, $v) { if($o."$n" -eq $v) { return $null; };  return $o;  }
Function GetKeyNumber($k, $v) { $n = 0; $o = ""; while ($o -ne $null) { $n += 1; $o = Get-ItemProperty -Path $k -Name $n -ErrorAction SilentlyContinue; $o = CheckAlreadyExists -n $n -o $o -v $v }; return $n; }
Function EdgePolicyEntry ($path, $val) { Set-ItemProperty -Path $path -Name $(GetKeyNumber -k $path -v $val) -Value $val }

$_ = New-Item -Path "HKLM:\SOFTWARE\Policies\Microsoft\Edge" -ErrorAction SilentlyContinue
$_ = New-Item -Path "HKLM:\SOFTWARE\Policies\Microsoft\Edge\ExtensionInstallAllowlist" -ErrorAction SilentlyContinue
$_ = New-Item -Path "HKLM:\SOFTWARE\Policies\Microsoft\Edge\ExtensionInstallForcelist" -ErrorAction SilentlyContinue

EdgePolicyEntry -path "HKLM:\SOFTWARE\Policies\Microsoft\Edge\ExtensionInstallAllowlist" -val "leaddjklpmkihmbnpconeffceakcfjfj"
EdgePolicyEntry -path "HKLM:\SOFTWARE\Policies\Microsoft\Edge\ExtensionInstallForcelist" -val "leaddjklpmkihmbnpconeffceakcfjfj;https://edge.microsoft.com/extensionwebstorebase/v1/crx"

```

--------------------------------

### Using Get Download Token Activity in a Pia Package

Source: https://knowledge.pia.ai/docs/learn/product-documentation/Activities/Get-Download-Token-Activity

This example demonstrates how to use the Get Download Token activity within a Pia package to upload an image via a form and then download it using a PowerShell script. It shows the sequence of tasks: chat interaction for image upload, getting the download token, and using inline PowerShell to download the image.

```yaml
# Pia Automation Package  
conditions:   
- name: 'client_filter'   
  optMode: 'OptOut'  
  category: 'Hello World'  
  
- name: 'chat'   
  option_button: 'The name of the button in Pia'  
  option_text: 'Text which is displayed in the Pia Chatbot'  
  option_category: 'Pia Chatbot Category'  
  
steps:  
- task: chat_interaction  
  inputs:  
    text: 'Upload your image!'  
    form_name: 'upload_image_example'  
  
- task: get_download_token  
  inputs:  
    data: =chat_interaction.form.image_to_upload  
  
- task: inline_powershell  
  inputs:  
    piaTenantUrl: $Base_Url  
    downloadToken: =get_download_token.token  
    script: |
            $WebClient = New-Object System.Net.WebClient  
            $bytes = $WebClient.DownloadData("$piaTenantUrl/Chat/Download?token=$downloadToken")  
  
            Write-Host "The image is $($bytes.count) bytes in size."  

```

--------------------------------

### Basic Package with Chat Suggest Packages Activity

Source: https://knowledge.pia.ai/docs/learn/product-documentation/Activities/Chat-Suggest-Packages-Activity

Demonstrates the usage of the chat_suggest_packages activity within a basic Pia automation package. It showcases how to configure package options and a message for user selection. This example assumes a YAML-based configuration for Pia packages.

```yaml
# Pia Automation Package  
conditions:   
- name: 'client_filter'   
  optMode: 'OptOut'  
  category: 'Hello World'  
  
- name: 'chat'   
  option_button: 'Chat Suggest Package'  
  option_text: 'This is a test package'  
  option_category: 'Test Category'  
  
steps:  
- task: chat_interaction  
  inputs:  
    text: 'Hello!'  
  
- task: chat_suggest_packages  
  inputs:  
    package_options: '1e310d26-e169-4ff5-9dc9-01b84734781f, 1730ef05-7a7e-4048-b5e9-18d2b522c4bd'  
    message: 'Select the package that you want to run:'  
  
- task: chat_interaction  
  inputs:  
    text: 'Hello Again'  

```

--------------------------------

### Basic Azure Get API Token Activity Usage in Pia Automation

Source: https://knowledge.pia.ai/docs/learn/product-documentation/Activities/azure_get_api_token_activity

This example demonstrates a basic configuration of the Azure Get API Token activity within a Pia Automation package. It shows how to specify the scope for retrieving a Graph API token and then use that token in an inline PowerShell script. The activity is configured to continue on error.

```yaml
# Pia Automation Package  
conditions:   
- name: 'client_filter'   
  optMode: 'OptOut'  
  category: 'Hello World'  
  lockTo: '2'  
  
- name: 'chat'   
  option_button: 'Azure Get API Token'  
  option_text: 'Text which is displayed in the Pia Chatbot'  
  option_category: 'Pia Chatbot Category'  
  
steps:  
- task: azure_get_api_token  
  alias: 'graph_token'  
  continue_on_error: 'true'  
  inputs:  
    Scope: "https://graph.microsoft.com"  
  
- task: inline_powershell  
  inputs:  
    token: =azure_get_api_token.Token  
    script: |   
      Write-Host $token  
  

```
Tokens:
Raw