Skip to main content

HelloID

Product actions

You can configure Actions (aka tasks) to run during various stages of the Product request lifecycle.

2022-12-06_12-12-33.jpg

To get started, Add a product action. You can find Pre-defined tasks in the Code snippet library.

Alternatively, Add a product action from the Task catalog.

Logging in product actions

Note

The following does not apply to product actions added from the Task catalog.

Product actions use native PowerShell logging.

  • 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"

Tip

HelloID interprets Write-Error messages as task failure, in which case the task execution will be labeled Failed in Self Service > Request History.

When testing your script, you can preview log messages on the Received Logs tab. To view them in production, View product request history.

Control which PowerShell log levels are shown on the Received Logs tab using the $VerbosePreference, $InformationPreference, and $WarningPreference variables. Levels set to Continue will be shown. Levels set to SilentlyContinue will not.

Warning

Product actions that run frequently and log a lot of lines can quickly fill up your system's database. Limit the amount of logging to avoid running out of database space and hitting the Performance limits.

Audit logging in product actions

HelloID's Audit logs store information long-term for organizational audits or compliance. Audit logs are separate from PowerShell script logging.

Note

The following does not apply to product actions added from the Task catalog.

In product actions, write custom messages into the audit logs using the following template:

$Log = @{
	Action = "CreateAccount"
	System = "ActiveDirectory"
	Message = "Created account with username [email protected]"
	IsError = $false
	TargetDisplayName = "Jan Willem (1000)"
	TargetIdentifier = "AD-SID"
}

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

To preview audit logs while testing your script, go to the Received Audit Logs tab. To view audit logs in production, View product request history or view them in the main Audit logs interface.

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

A string that contains the name of the system that the delegated form modified. Optional.

Message

A string that describes the action taken. Required.

IsError

A boolean that reports whether the form succeeded ($false; default) or failed ($true). Optional.

TargetDisplayName

A string that contains the display name of the object that the form modified. Optional.

TargetIdentifier

A string that contains the unique identifier of the object that the form modified. Optional.

Email sends in product actions

Note

The following does not apply to product actions added from the Task catalog.

Product actions support email sends via the following template:

$email = @{  
    from = "[email protected]"  
    to = "[email protected]"  
    cc = "[email protected]"  
    bcc = "[email protected]"  
    subject = "Created account with username [email protected]"  
    body = "<strong>This is the email body.</strong>"  
    confidential= $false  
}  
  
Write-Information -Tags "Email" -MessageData $email

When confidential is set to $false, the email and its contents are automatically logged in the Audit logs. When it is set to $true, the email is not logged.

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.

The from address must either 1) have a verified domain (see Configure a custom 'from' address for emails), or 2) be set to [email protected]. Otherwise, the send will fail.

To enter multiple email addresses in the To, Cc, or Bcc fields, enclose the entire list in double quotes and separate each address with a comma. For example: to = "[email protected],[email protected],[email protected]"

Tip

Emails are only sent when the script runs in production. No emails are sent when the script is tested in preview.

In this section: