How To: Login PI bulk administration through RESTfull API and Powershell
For a large Login PI deployment a method was needed to change the workload on all profiles. The Login PI RESTfull API (API) easily enables this. To get started create a Powershell script. For this blogpost the Windows Powershell ISE was used.
Create the variables that will be reused. In this case the PI base URL. This script will be ran directly on the PI server. This script assumes PI is installed on the default port 8080. These values will need to be changed if the PI server is configured for SSL. See https://loginvsi.zendesk.com/hc/en-us/articles/115004469265-Login-PI-Configure-Management-Console-for-SSL.
The second variable is the workload that the script will set on every profile. In this case one of the default workloads.
Next the script will collect all the available profiles on the PI server. The script first defines where those profiles will be retrieved. The PI base URL was defined earlier. The profilesapi/profiles path was retrieved using a method that will be described in a future blog post.
Using the profiles API URL the script will retrieve all available profiles using the invoke-restmethod command. Note that UseDefaultCredentials is specified. Login PI uses authenticated API endpoints. This parameter specifies that the credentials of the user running the Powershell script should be passed to the API endpoint for authentication. This assumes that the user account running the script is a Login PI administrator. The profiles are stored in a variable for later use.
Once all the available profiles are collected the script will iterate through the profiles. Using a so called for each loop each available profile in the collection of profiles is put in a variable so that each profile can be operated on separately.
Inside the for each loop the ID of the profile is stored in a separate variable. Next the API URL used for setting the workload is defined. This URL is made up out of the PI base URL, the profile ID for the profile currently being processed by the for each loop and the URL path components for the API endpoint.
Login PI uses JSON as the syntax to define data. Powershell can convert a hashtable to a JSON object. So the script defines a hashtable with the appropriate names for the different fields expected by the workloadsettings API endpoint. Note the office language, operating system language and office version are hardcoded. These IDs can be determined by looking at the list of these values in the PI dashboard.
Please note that your values can differ but are likely the same.
Once the JSON data is properly formatted by the ConvertTo-JSON command the API URL is called using Invoke-RestMethod using the UseDefaultCredentials parameter discussed earlier. The Invoke-RestMethod command is also configured to use content type JSON. This lets the API endpoint know that the data is in the JSON format/syntax. Last but not least the HTTP method PUT is used. The JSON data is attached in the body of the request.
Finally the script will ask the PI server to parse the new workload. Using the same principles discussed earlier. A request URL is created out of the PI base URL, profile ID and API endpoint URL components. The resulting URL is then invoked using the POST method. No body is attached as the parseworkload API endpoint doesn’t require a body. It simply uses the profile ID that is part of the request URL to understand which workload to parse. Last but not least the script outputs on which profile the workload has been changed.
A future blogpost will describe how to enhance this script to allow a CSV file to potentially specify a different workload per profile.
Please note that much of the structure of this script was originally written by Henk Hofs. I merely adapted it to fit my needs.
Disclaimer: many of the API endpoints mentioned in this blog post are not supported. Meaning they may change from release to release. This blogpost is therefor provided AS-IS.