Introduction

Go to Automation > PowerShell Scripts to get started.

Also see:

• PowerShell Scripts - Overview

Create a templated PowerShell script

Templated PowerShell scripts are created in Automation > PowerShell Scripts and can be used in Self Service products and tasks. 

In this example, we'll create a templated script that retrieves the current New York weather conditions from the Open-Meteo API.

1. Select the New PowerShell Script button.
   
2. The General tab contains four fields:
   • Name
     The script's name. For this example, we'll use Weather report.
   • Description
     The script's description (optional).
   • Enabled
     Disabled scripts cannot be added to other objects or executed.
   • Script
     Your PowerShell code. For this example, we'll paste the following script. It contains custom HelloID cmdlets.
     

     $locationEndpoint = "https://api.open-meteo.com/v1/forecast?latitude=40.71&longitude=-74.01&hourly=temperature_2m&temperature_unit=$temperatureUnit&windspeed_unit=mph&precipitation_unit=inch"
     Hid-Write-Summary -Message "Looking up New York weather" -Event Information
     $response = Invoke-RestMethod -uri $locationEndpoint
     Hid-Write-Summary -Message "Response: $response" -Event Information
     $result = @{weather = "Current time: $($response.hourly.time[0]); current temperature: $($response.hourly.temperature_2m[0]) degrees $temperatureUnit"}
     Hid-Write-Summary -Message "Result: $($result.weather)" -Event Information
     Hid-Add-TaskResult -ResultValue $result

   
3. On the Variables sub-tab of the Task tab, you can define local variables for use in the PowerShell script. To do so, select a data Type in the drop down, and enter a variable Name and Value. You can access Service Automation variables here. Select the plus (+) button to save a variable.
   
   For this example, we'll add one variable named temperatureUnit, set to the value fahrenheit.
   
4. Select the Save button.
5. The templated Weather report PowerShell script is now available on the PowerShell Scripts Overview screen.
   
6. To use a templated PowerShell script, you need to add it to a Self Service product or task. For instructions, see Use a templated PowerShell script in a Self Service product or Use a templated PowerShell script in a task.

Return results

Use the Hid-Add-TaskResult cmdlet to return the task's results.

Task logging

To log messages, use HelloID's built-in logging cmdlets.

Create an inline PowerShell script

Inline PowerShell scripts are created directly inside other objects (PowerShell data sources, Delegated Forms, Self Service products and Tasks).

Create an inline PowerShell script in a PowerShell data source

See: Create a PowerShell data source.

Return results

The last line of your script should return a hash table with the results, either directly or with Write-Output.

For example:

$result_object = @{givenName = "Bob"; familyName = "Johnson"; title = "Engineer";}
$result_object

Task Logging

PowerShell data sources use native PowerShell logging. 

Use the following:

• Write-Information "Information"
• Write-Host "Equivalent to Write-Information"
• Write-Error "An error"
• Write-Warning "A warning"
• Write-Verbose -Verbose "Verbose requires the -Verbose flag"
• Write-Debug -Debug "Debug requires the -Debug flag"

Task log messages are displayed in the Received Logs tab during preview, and reported in the Data Source Logging tab of the Activities overview during production, as well as in the Data Source Logging tab of the PowerShell data source itself.  

Audit Logging

When you create, edit, or delete a PowerShell data source, that action is automatically logged in the Elastic audit logs. Writing custom messages into audit logs from PowerShell data sources is not currently supported.

Create an inline PowerShell script in a delegated form

See: Create an inline PowerShell script in a delegated form.

Task Logging

Delegated form PowerShell scripts use native PowerShell logging. 

Use the following:

• Write-Information "Information"
• Write-Host "Equivalent to Write-Information"
• Write-Error "An error"
• Write-Warning "A warning"
• Write-Verbose -Verbose "Verbose requires the -Verbose flag"
• Write-Debug -Debug "Debug requires the -Debug flag"

For delegated forms, task log messages are displayed in the Received Logs tab during preview, and reported in the Task Logging tab of the Activities overview during production.

Audit Logging

Audit logs are intended to store information long-term that may be needed for organizational audits or compliance.

In delegated form scripts, you can write messages into the audit log using the following template:

$Log = @{
    Action = "CreateAccount"
    System = "ActiveDirectory"
    Message = "Created account with username name@company.local"
    IsError = $false
    TargetDisplayName = "Jan Willem (1000)"
    TargetIdentifier = "AD-SID"
}

Write-Information -Tags "Audit" -MessageData $Log

• Action
  An enum that describes what the delegated form does. If no value is specified, it is set to Undefined. Optional.
  • Undefined
  • CreateAccount
  • EnableAccount
  • UpdateAccount
  • DisableAccount
  • MoveAccount
  • DeleteAccount
  • GrantMembership
  • RevokeMembership
  • CreateResource
  • UpdateResource
  • DeleteResource
  • SendNotification
  • SetPassword
• System
  The name of the system that the delegated form modified. A free format string. Optional.
• Message
  A message that describes the action taken. A free format string. Required.
• IsError
  A boolean that reports whether the form succeeded ($false; default) or failed ($true). Optional.
• TargetDisplayName
  The display name of the object that the form modified. A free format string. Optional.
• TargetIdentifier
  The unique identifier of the object that the form modified. A free format string. Optional.

View logged messages in the Audit Logging tab of the Activities overview, or access them through reports in Elastic Reports - Overview.

Send emails

In delegated form scripts, you can send emails using the following template:

$email = @{
    from = "admin@helloid.com"
    to = "jdoe@tools4ever.com"
    cc = "jdoe1@tools4ever.com"
    bcc = "jdoe2@tools4ever.com"
    subject = "Created account with username name@company.local"
    body = "<strong>This is the email body.</strong>"
    confidential= $false
}

Write-Information -Tags "Email" $email

When confidential is set to $false, the email is logged in Elastic. When it is set to $true, the email is not logged in Elastic.

When the Write-Information cmdlet is used with the Email tag, it only sends the specified hash table as an email. It does not create a PowerShell log entry.

Create an inline PowerShell script in a task or a Self Service product

See:

• Create an inline PowerShell script inside a task.
• Create an inline PowerShell task inside a Self Service Product.

Return results

Use the Hid-Add-TaskResult cmdlet to return the task's results.

Task logging

Use HelloID's built-in logging cmdlets to log messages.

Variable reference

See the Service Automation variable reference.

Next steps

This example merely fetches the current weather. However, it shows the potential of custom PowerShell in your HelloID environment. You can write scripts that work with your organization's internal infrastructure, query external APIs, or anything else you need.

For some examples of PowerShell-based tasks designed for use with Active Directory, see the Active Directory Task docs section.