Creating Cloud PowerShell Scripts

The only data stream installed with the cloud PowerShell plugin is Run Script, which provides an expansive toolkit to interact with the data you retrieve.

The following information give tips and ideas for using the data stream to enhance and display the data you're interested in.

Configuring variables

When configuring the PowerShell data source, you're given the option of adding custom Variables. Creating variables here has the added bonus of being able to encrypt the value by clicking the padlock icon

These variables can then be accessed via the $variable library when formatting scripts, which is especially useful when working with API keys or other secrets, as then you do not have to expose them in the script itself.

Formatting scripts

Special variables

When entering a Script in the Run Script data stream, you can use the following variables to interact with SquaredUp properties:

• $variable: A dictionary of the variables entered in the plugin configuration when configuring the data source. For example, to access the value of a variable entered there named foo, you can enter $variable['foo'] or $variable.foo.
• $timeframe: An object containing properties about the dashboard timeframe, for example:
  Copy

  {
    "unixStart": 1697375649,
    "start": "2023-10-15T13:14:09Z",
    "unixEnd": 1697462049,
    "end": "2023-10-16T13:14:09Z",
    "enum": "last24hours",
    "interval": "PT15M"
  }

  What is the dashboard timeframe?

  The dashboard timeframe setting, located on the toolbar at the top of a dashboard, lets you easily toggle the time span that a dashboard displays data for.

  Selecting a new timeframe immediately updates the data for every tile on the dashboard that is configured to inherit that dashboard's timeframe.

• $targetNodes: The objects from the knowledge graph in scope. Intended for advanced users.

Returning data to tiles

Typically, PowerShell scripts supplied to this plugin are used to call third-party APIs to retrieve data, which can then be enhanced for visualization.

If the data returned from the script is a primitive scalar, it is only suitable for use with the Scalar visualization.

Otherwise, if the data is structured, it can always be used with the Table visualization. Other visualizations will also be suitable if appropriate columns (object properties) are present.

Examples

The following examples are taken from the pre-built PowerShell Example Data dashboard, which you can choose to install when adding the data source or add afterwards from the data source overview page.

Last 10 Orders

This example makes an API request to the SquaredUp sample data endpoint, converting the JSON to a PowerShell object. It then loops through the Customer objects to find orders that fall within the dashboard timeframe. Finally, the most recent 10 objects are then returned as the $result.

#Make request to the API endpoint and convert the response from JSON to a PowerShell Object
$request = Invoke-WebRequest -URI 'https://download.squaredup.com/api/plugins/powershell/sample-data'
$request = $request.content | ConvertFrom-Json

#Seperating response data into 2 lists
$customers = $request.customers
$orders = $request.orders
$result = @()

# Loop through returned list of customer objects and check for matching orders
ForEach ($customer in $customers) {
    forEach ($order in $orders) {
        if ($order.orderDateTime -gt $timeframe.start -and $order.orderDateTime -lt $timeframe.end) {
            #If matching order is found within the dashboard timeframe, add order details along with customer details to the results array
            if ($order.customerId -eq $customer.id) {
                $result += New-Object -TypeName psObject -Property @{"Customer name" = $customer.name; "Customer Number" = $customer.id; "customer address" = $customer.address; "Customer email" = $customer.email; "Order Number" = $order.orderNumber; "Date" = $order.orderDateTime; "Currency" = $order.currency; "item" = $order.item; "Quantity" = $order.quantity; "total" = $order.total }
            }
        }
    }
}

# Return the results selecting only the most recent 10 objects 
$result | Sort-Object orderDateTime | select-Object -Last 10

Orders per day

This example makes an API request to the SquaredUp sample data endpoint, converting the JSON to a PowerShell object. It then loops through each of the Orders objects belonging to each Customer object to find orders that fall within the dashboard timeframe. The order and customer details are then added to the returned $results array.

#Make request to the API endpoint and convert the response from JSON to a PowerShell Object
$request = Invoke-WebRequest -URI 'https://download.squaredup.com/api/plugins/powershell/sample-data'
$request = $request.content | ConvertFrom-Json

#Seperating response data into 2 lists
$customers = $request.customers
$orders = $request.orders
$result = @()

#Loop through returned list of customer objects and check for matching orders
ForEach ($customer in $customers) {
    forEach ($order in $orders) {
        #If matching order is found within the dashboard timeframe, add order details along with customer details to the results array
        if ($order.orderDateTime -gt $timeframe.start -and $order.orderDateTime -lt $timeframe.end) {
            if ($order.customerId -eq $customer.id) {
                $result += New-Object -TypeName psObject -Property @{"Customer name" = $customer.name; "Customer Number" = $customer.id; "customer address" = $customer.address; "Customer email" = $customer.email; "Order Number" = $order.orderNumber; "Date" = $order.orderDateTime; "Currency" = $order.currency; "item" = $order.item; "Quantity" = $order.quantity; "total" = $order.total }
            }
        }
    }
}

return $result 

Was this article helpful?