Get Clients Activity

Overview

The Get Clients (get_clients) activity is a built in activity in the Pia package editor. This activity retrieves a list of all the clients and the details they have been configured with in the Partner portal which can be used by the package to perform actions on a group of clients with similar configuration.

The activity may be useful to know if your client is configured correctly before you attempt an action in your automation. You may also use the Get Clients activity to retrieve a list of clients with similar configuration and to schedule a task for those clients.

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

Below is the code snippet that shows how you can use the Get Client Config Form activity to retrieve required data directly from the Global Configuration Form:

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

- name: 'chat' 
  option_button: 'Get Clients Activity'
  option_text: 'This is a test package.'
  option_category: 'Pia Chatbot Category'

steps:
- task: get_clients

- task: inline_powershell
  alias: 'chat_generator'
  inputs:
    clientdata: =get_clients.clients
    script: |
        $clientdata = $(ConvertFrom-JSON $clientdata)

        Write-Host "Your Pia Clients are:"
        $sb = [System.Text.StringBuilder]::new()
        [void]$sb.AppendLine("Your Pia Clients are:")
        foreach($client in $clientdata) {
            [void]$sb.AppendLine(" - $($client.ClientName)")
        }

        return @{ text = $sb.ToString()}

- task: chat_interaction
  inputs:
    text: =chat_generator.text

The above package will retrieve a list of clients available in Pia and present them as below:

Activity Behaviour

The primary purpose of the Get Clients activity is to retrieve the list of clients available in Pia portal and their current configuration. You can use the input properties in the activity to retrieve a filtered list of clients based on tags assigned to them, the chatbot enabled roles and/or the client's status.

The Get Client Config 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: tags
Property Required: No
Property Description: Retrieves a list of clients with the specified Tags. Use comma separated format for more than one tag. Example: Cloud Hybrid, on prem.

Property Name: chatbot_enabled_roles
Property Required: No
Property Options: 'Engineer' or 'Client'
Default Value: 'Engineer'
Property Description: Retrieves a list of clients where the Pia chatbot is enabled for client or engineer or both (currently called Pia status). Use comma separated format for multiple. Example: Engineer, Client.

Property Name: client_status
Property Required: No
Property Options: 'Active' or 'Inactive'
Default Value: 'Active'
Property Description: Retrieves a list of clients that are supported or not supported i.e. Active or Inactive.

Output Properties

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

Property Name: clients
Property Description: This will return a list of clients based on the input parameters provided.

Here, a Json object is returned containing the values as below:

[{
    "ClientId": 2,
    "ClientName": "Pia Testing - Cloud Hybrid",
    "ChatbotEnabledRoles": "Engineer, Client",
    "ClientStatus": "Active",
    "Tags": "Cloud Hybrid",
    "RestrictedClient": true,
    "IsMsGraphApiAuthorised": true,
    "MsGraphApiAuthorisationDate": "",
    "MsGraphApiAuthorisationTenantId": "",
    "MsGraphDelegates": [{
        "Upn": "",
        "Scopes": "",
        "RefreshTokenLastRefreshedDate": "",
        "ExpiryStatus": "Valid"
    }],
    "ParentClient": null,
    "ChildClients": [{
        "ClientName": "Pia Testing - Generic 1",
        "Id": 43
    }],
    "Approvers": [{
        "ApproverName": "Test Smith",
        "ApproverId": 1,
        "Scopes": "Test"
    },
    {
        "ApproverName": "Test2 Smith",
        "ApproverId": 2,
        "Scopes": "Get Approval"
    },
    {
        "ApproverName": "Test User3a",
        "ApproverId": 7,
        "Scopes": ""
    }],
    "IsItGlueConfigured": true
}]