Go to Automation > PowerShell Scripts to get started. Learn more about PowerShell scripts here.
Note that all PowerShell scripts created here are executed by a HelloID Agent in your on-premise environment, within the user context of the HelloID Agent Service's logon account. It is not possible to execute these scripts in your HelloID cloud tenant.
Create a PowerShell Script
In this example, we'll be creating a script that retrieves the current weather conditions for a given city and state from the Yahoo! Weather API.
- Click New PowerShell Script in the PowerShell Scripts overview window.
- On the General tab, you are presented with four fields.
- Name: Give the script a name. In this example, we're calling it "Local Weather Report".
- Description: Optionally, you may provide a description of the script.
- Enabled: Disabled scripts are not available to be assigned to tasks or Self Service products. We're going to leave it enabled for our example.
- Script: This is where you put your PowerShell script. Copy and paste the script below into that field. Note that this script contains custom HelloID cmdlets. Learn more about them here.
$endpoint = "https://query.yahooapis.com/v1/public/yql?q=select%20item.condition%20from%20weather.forecast%20where%20woeid%20in%20(select%20woeid%20from%20geo.places(1)%20where%20text%3D%22$city%2C%20$state%22)&format=json&env=store%3A%2F%2Fdatatables.org%2Falltableswithkeys"
Hid-Write-Status -Message "Getting weather information for $city, $state" -Event Information
$response = Invoke-RestMethod -uri $endpoint
$temp = $response.query.results.channel.item.condition.temp $weather = $response.query.results.channel.item.condition.text
Hid-Write-Summary -Message "Current $city Temperature: $temp" -Event Information -Icon fa-cloud Hid-Write-Summary -Message "Current $city Condition: $weather" -Event Information -Icon fa-cloud
- Next, navigate to the Variables tab.
- Add two variables, one named city and one named state. Provide values of your choice, using a two-letter abbreviation for the state.
- Note: Variables added to a PowerShell script can be referenced within the script by using a dollar sign followed by the name of the variable. In this case, it would be $city and $state. These are default values that can be overridden when the script is assigned to a task, event, or Self Service product.
- Click Save when you are finished.
- Your new PowerShell script has been added to the list and is available for use in tasks, events, and Self Service products.
Use a PowerShell Script in a Task
To use your custom PowerShell script, you must add it to a task. The task acts as a "container" for the script, letting you use the script anywhere you can use a task (e.g., task data sources, self service products, advanced delegated forms, etc). If you haven't already done so, learn about creating a task before moving on.
- Start creating a new automation task. Find or search for the Custom PowerShell Script task and click the Add button.
- On the General tab, name the task whatever you want and select your desired agent pool. In this example, we'll name our task "Local Weather Report".
- On the Task tab, select your new PowerShell script form the Template dropdown menu. Alternatively, deselect the Use Template option to provide a new script directly inside the task. This encapsulates the script by permanently tying it to this particular task, so that it cannot be used or edited elsewhere. This is analogous to how tasks themselves can be encapsulated inside other objects like self service products and delegated forms.
- Optional: The variables in a HelloID PowerShell script are just the default values. You can override them by going to the Variables tab when creating a new task.
- Update the settings and the schedule of the task as you see fit. Click Save when you are finished.
- You will now have a new task available in the task list. Click on the task's Play button to run it.
- We are then taken to the progress log. Here, we can see that the script is executing. We also get a line of logging that corresponds to the custom Hid-Write-Status cmdlet.
- On the summary tab, we can see two lines in the summary log that correspond to the custom Hid-Write-Summary cmdlet, showing the local weather conditions.
This example was a simple script. All it did was report the current weather in the task summary. However, this example should give you an idea of the potential for using custom PowerShell in your HelloID environment. You can script tasks within your own internal infrastructure or reach out to external systems via their API. Each organization's needs is different, and the possibilities are endless.
For some examples of PowerShell-based tasks designed for use with Active Directory, see the Active Directory Task docs section.