Service Automation variables

In Service Automation Tasks and PowerShell scripts, three types of variables are available:

Service Automation-specific variables. For example, user attributes of the requesting user in a product request, or data from fields in the request's attached dynamic form. See Service Automation variable reference.
System variables
Custom variables

Use variables in Service Automation

See the following articles for examples of using SA-specific, system, and custom variables:

Service Automation variable reference

$approvalHistory

An array that contains one object per designated responder (see Designated responders) that responded to the current product request (see Product requests).

To log $approvalHistory, use $approvalHistory | ConvertTo-Json -Depth 10.

Availability

Object type	Available?
Pre-defined scheduled tasks	No ❌
Pre-defined product tasks	No ❌
PowerShell scheduled tasks	No ❌
PowerShell product tasks	Yes ✔️
PowerShell data sources	No ❌
Delegated form PowerShell scripts	No ❌

Properties

approved: Whether the designated responder approved (true) or denied (false) the product request.
time: The time & date the request was responded to.
user: A User object for the designated responder who responded to the product request.
comment: The comment that the designated responder entered when responding to the product request.
order: Indicates which response this is, if the approval workflow specifies more than one designated responder. Counts up starting at 0. For example, 0 means they were the first designated responder. 1 means they were the second designated responder.

Example

[
  {
    "approved": "True",
    "time": "2023-08-15T17:36:27.253",
    "user": {
      "userGUID": "d27dbf41-7770-4cef-9657-17e470f5945c",
      "userName": "jdoe",
      "firstName": "John",
      "lastName": "Doe",
      "fullName": "John Doe",
      "contactEmail": "[email protected]",
      "source": "Local",
      "immutableId": "",
      "userAttributes": {
        "language": "EN",
        "phonenumber": "5555555555"
      },
      "createdOn": "2023-02-22T19:34:12.943",
      "managedByUserGUID": "bc61948e-2a84-41fa-9b2a-4d5e94e319db",
      "managedByGroupGUID": "",
      "isEnabled": "True"
    },
    "comment": "This is approved",
    "order": "0"
  },
  {
    "approved": "False",
    "time": "2023-08-15T17:36:50.4",
    "user": {
      "userGUID": "bc61948e-2a84-41fa-9b2a-4d5e94e319db",
      "userName": "Administrator",
      "firstName": "Administrator",
      "lastName": "",
      "fullName": "Administrator",
      "contactEmail": "[email protected]",
      "source": "Local",
      "immutableId": "",
      "userAttributes": {
        "department": "IT",
        "phonenumber": "",
        "language": "EN",
        "privateEmail": "[email protected]"
      },
      "createdOn": "2021-10-26T19:05:37.833",
      "managedByUserGUID": "d8b1fa6d-56f5-4dab-a9c3-7b440461d681",
      "managedByGroupGUID": "",
      "isEnabled": "True"
    },
    "comment": "This is denied",
    "order": "1"
  }
]

$form

An object that contains the form submission for the dynamic form attached to the current product or delegated form.

Availability

Object type	Available?
Pre-defined scheduled tasks	No ❌
Pre-defined product tasks	No ❌
PowerShell scheduled tasks	No ❌
PowerShell product tasks	Yes ✔️
PowerShell data sources	No ❌
Delegated form PowerShell scripts	Yes ✔️

Properties

The name of each property in this object is the form element's Form Key.

Example

{
  "dropDown": "Option 2",
  "dateTime": "2022-06-07T18:40:20.949Z",
  "multiCheckbox": [
    {
      "label": "Option 1",
      "value": true,
      "mustBeTrue": false
    },
    {
      "label": "Option 2",
      "value": false,
      "mustBeTrue": false
    },
    {
      "label": "Option 3",
      "value": true,
      "mustBeTrue": false
    }
  ],
  "textDatasource": "Text value returned from PowerShell datasource",
  "dropDown1": {
    "a": "A dropdown value, returned from a second PowerShell datasource",
    "b": "Another dropdown value, returned from a second PowerShell datasource"
  }
}

$manager

A User object for the requesting user's manager (see Managers).

Availability

Object type	Available?
Pre-defined scheduled tasks	No ❌
Pre-defined product tasks	Yes ✔️
PowerShell scheduled tasks	No ❌
PowerShell product tasks	Yes ✔️
PowerShell data sources	No ❌
Delegated form PowerShell scripts	No ❌

$product

An object that contains information about the requested product.

Availability

Object type	Available?
Pre-defined scheduled tasks	No ❌
Pre-defined product tasks	Yes ✔️
PowerShell scheduled tasks	No ❌
PowerShell product tasks	Yes ✔️
PowerShell data sources	No ❌
Delegated form PowerShell scripts	No ❌

Properties

productGUID: The GUID that HelloID automatically generated & assigned to the product when it was created. Visible in the product's URL when you Edit a product.
name: The product's Name.
description: The product's Description.
code: The product's SKU.
sourceIdentifier: The product's Source Identifier.
resourceOwnerGroupGUID: The GUID of the group selected in the product's Resource Owner setting.
dynamicFormGUID: The GUID of the dynamic form attached to the product's Form tab. (This form is accessible via $form.)
allowMultipleRequests: The product's Multiple Requests setting.
maxCount: The product's Maximum Account setting.
ownershipMaxDuration: The product's Ownership Duration, if the product has a time limit.
useFaIcon: The product's Type Of Icon setting.
faIcon: The name of the product's FA icon, if the Type Of Icon is set to Use Predefined Icon.
icon: The file name of the product's custom icon, if the Type Of Icon is set to Use Custom Icon.
riskFactor: The product's Risk Factor Enabled setting.
price: The product's Price setting.

Example

{
  "productGUID": "e77ec7ed-59ad-4d62-9711-7989d10c6fa1",
  "name": "Google Chrome",
  "description": "",
  "code": "20221205YVZKPPRRKZ",
  "sourceIdentifier": "",
  "resourceOwnerGroupGUID": "0af6fee0-16a6-4b92-9027-6dc598c92c56",
  "dynamicFormGUID": "a8e3dacf-cbc8-4977-908d-17fd7d18f552",
  "allowMultipleRequests": "True",
  "maxCount": "",
  "ownershipMaxDuration": "0",
  "useFaIcon": "False",
  "faIcon": "",
  "icon": "BEF0A68FE0F5083F45659D2961D1ADA1",
  "riskFactor": "",
  "price": ""
}

$request

An object that contains information about the current product request.

Availability

Object type	Available?
Pre-defined scheduled tasks	No ❌
Pre-defined product tasks	Yes ✔️
PowerShell scheduled tasks	No ❌
PowerShell product tasks	Yes ✔️
PowerShell data sources	No ❌
Delegated form PowerShell scripts	No ❌

Properties

requestId

The GUID that HelloID automatically generated for this product request when it was submitted.

comment

The comment entered by the user who submitted this product request.

requestTime

The date & time the product was requested, according to the Time Zone setting in Company settings.

requestedFor

A User object for the user that this product was requested for.

Usually the same as the user that the product was requested by, but may be different if the product was requested via the Request a product on behalf or Request an owned product on behalf process.

requestedBy

The User object for the user who submitted this product request.

ReturnedBy

A User object for the user who returned the product associated with this product request.

returnComment

The comment entered by the user who returned the product associated with this product request.

ReturnTime

The time that the product was returned.

Example

{
  "requestId": "d99edbe1-e672-496c-9faf-9e581bf21bb1",
  "comment": "",
  "requestTime": "2023-08-15T18:02:53.793",
  "requestedFor": {
    "userGUID": "0854cd61-4c72-45d6-8441-329d5370067e",
    "userName": "tsmith",
    "firstName": "Tom",
    "lastName": "Smith",
    "fullName": "Tom Smith",
    "contactEmail": "[email protected]",
    "source": "Local",
    "immutableId": "",
    "userAttributes": {
      "phonenumber": "5555555555",
      "language": "EN"
    },
    "createdOn": "2022-10-21T21:56:08.477",
    "managedByUserGUID": "d27dbf41-7770-4cef-9657-17e470f5945c",
    "managedByGroupGUID": "",
    "isEnabled": "True"
  },
  "requestedBy": {
    "userGUID": "0854cd61-4c72-45d6-8441-329d5370067e",
    "userName": "tsmith",
    "firstName": "Tom",
    "lastName": "Smith",
    "fullName": "Tom Smith",
    "contactEmail": "[email protected]",
    "source": "Local",
    "immutableId": "",
    "userAttributes": {
      "phonenumber": "5555555555",
      "language": "EN"
    },
    "createdOn": "2022-10-21T21:56:08.477",
    "managedByUserGUID": "d27dbf41-7770-4cef-9657-17e470f5945c",
    "managedByGroupGUID": "",
    "isEnabled": "True"
  },
  "returnedBy": "",
  "returnComment": "",
  "returnTime": ""
}

$requester

A User object for the user who submitted the current product request or delegated form.

Availability

Object type	Available?
Pre-defined scheduled tasks	No ❌
Pre-defined product tasks	Yes ✔️
PowerShell scheduled tasks	No ❌
PowerShell product tasks	Yes ✔️
PowerShell data sources	Yes ✔️
Delegated form PowerShell scripts	Yes ✔️

$requestedFor

A User object for the user who the product was requested for.

Usually the same as the user that the product was requested by, but may be different if the product was requested via the Request a product on behalf or Request an owned product on behalf process.

Availability

Object type	Available?
Pre-defined scheduled tasks	No ❌
Pre-defined product tasks	No ❌
PowerShell scheduled tasks	No ❌
PowerShell product tasks	Yes ✔️
PowerShell data sources	Yes ✔️
Delegated form PowerShell scripts	No ❌

$resourceOwnerGroup

Warning

Only available in pre-defined product tasks (see Add a pre-defined product task). In other tasks & scripts, instead use $product.resourceOwnerGroupGUID.

Availability

Object type	Available?
Pre-defined scheduled tasks	No ❌
Pre-defined product tasks	Yes ✔️
PowerShell scheduled tasks	No ❌
PowerShell product tasks	No ❌
PowerShell data sources	No ❌
Delegated form PowerShell scripts	No ❌

Properties

name: The name of the group selected in the product's Resource Owner setting.
groupGUID: The GUID of the group selected in the product's Resource Owner setting.

Example

{
  "name": "Admins",
  "groupGUID": "0af6fee0-16a6-4b92-9027-6dc598c92c56"
}

User object

An object that contains the data of a HelloID user. See Users.

The $approvalHistory, $manager, $request, $requester, and $requestedFor variables contain user objects.

Properties

userGUID: The GUID that HelloID automatically generated & assigned to the user when it was created. Visible in the URL when you Edit a user.
userName: The user's Username.
firstName: The user's First Name.
lastName: The user's Last Name.
fullName: The user's First Name + Last Name.
contactEmail: The user's Email.
source: The user's Source field.
immutableId
userAttributes: The user's Custom user attributes.
createdOn: The date & time the user was created.
managedByUserGUID: The GUID of the user's Manager.
managedByGroupGUID
isEnabled: The user's Enabled setting.

Example

{
  "userGUID": "d27dbf41-7770-4cef-9657-17e470f5945c",
  "userName": "jdoe",
  "firstName": "John",
  "lastName": "Doe",
  "fullName": "John Doe",
  "contactEmail": "[email protected]",
  "source": "Local",
  "immutableId": "",
  "userAttributes": {
    "language": "EN",
    "phonenumber": "5555555555"
  },
  "createdOn": "2023-02-22T19:34:12.943",
  "managedByUserGUID": "bc61948e-2a84-41fa-9b2a-4d5e94e319db",
  "managedByGroupGUID": "",
  "isEnabled": "True"
}

In this section:

HelloID