Approval Point Activity

Overview

The Approval Point (approval_point) activity allows you to define a step in your automation where Pia will send approval request to the configured approvers before moving on to the next step. With this activity, you can create approval points in your automation which can be later be configured through the Tech Assist screen.

When an Approval Point is added to an automation, it becomes visible and configurable when creating approval rules from within the Approvals tab in the Tech Assist screen. Anyone with the appropriate access level can adjust the approval requirements, even after the automation has been deployed.

This activity can be inserted at any step within a custom automation. For example, if your custom RMM alert automation requires approval immediately before resolving an alert, you can place an approval point right before the action. (Note: Pia's pre-built automations already contain predefined extension points. However, if you wish to add additional approval points or custom approval point logic into a pre-built automation, you can do so with an Extension Automation).

The Approval Point activity can be located by searching for "Approval Point" in the list of activities in the package editor:

Below are some examples that show how you can use the Approval Point Activity in your custom automations:

Approval Point in a Tech Assist Automation

# Pia Automation Package
conditions: 
- name: 'client_filter' 
  optMode: 'OptOut'
  category: 'Hello World'

- name: 'chat' 
  option_button: 'Approval Test for Tech Assist'
  option_text: 'Testing Approval'
  option_category: 'Pia Chatbot Category'

steps:
- task: chat_interaction
  alias: 'get_username'
  inputs:
    form_name: 'select_user'
    text: 'Enter the name of the user who requires a password reset'

- task: approval_point
  inputs:
    unique_id: '8c72d892-2a99-4329-b3f8-746f70bd51f2'
    name: 'Prior to Reset Network Password'
    approval_for: 'Reset password for {=get_username.form.userPrincipalName}'
    condition_text: 'Resets to the password for the selected user'
    approval_group: 'Pia: Reset Network Password'

For the above example to work, you will need to create a form with the static name 'select_user'. This form will have a single text field and have the reference name set to 'userPrincipalName'.

Approval Point in a SmartForm Automation

# Pia Automation Package
conditions: 
- name: 'client_filter' 
  optMode: 'OptOut'
  category: 'Hello World'

- name: smartform
  portal_form_title: 'Smartform Approvals'
  portal_form_description: 'Approval Test for SmartForms'

steps:
- task: smartform_interaction
  alias: 'user_form'
  inputs:
    form_name: 'select_user'


- task: approval_point
  inputs:
    unique_id: '8c72d892-2a99-4329-b3f8-746f70bd51f2'
    name: 'Prior to user account creation'
    approval_for: '{=user_form.form.name}'
    approval_group: 'Pia: Staff Onboarding'
    condition_text: 'Creating a user account for new staff members'

For the above example to work, you will need to create a form with the static name 'select_user'. This form will have a single text field and have the reference name set to 'name'.

Approval Point in an Extension Automation

Here is the extension automation:

# Pia Automation Package
conditions: 
- name: 'client_filter' 
  optMode: 'OptOut'
  category: 'Hello World'

- name: extension_automation

steps:

- task: approval_point
  inputs:
    unique_id: '8c72d892-2a99-4329-b3f8-746f70bd51f2'
    name: 'Approval Point in an Extension'
    approval_for: 'This is to see if we can approve extension based approvals'
    condition_text: 'must be approved to move on'

Here is the parent automation:

# Pia Automation Package
conditions: 
- name: 'client_filter' 
  optMode: 'OptOut'
  category: 'Hello World'

- name: 'chat' 
  option_button: 'approval parent'
  option_text: 'Text which is displayed in the Pia Chatbot'
  option_category: 'Pia Chatbot Category'

steps:

- task: chat_interaction
  inputs:
    text: 'Hello'

- task: extension_automation
  inputs:
    description: 'Extension to test Approval'
    data: '{}'
    data_schema: '{}'
    extension_unique_id: '33d10eb6-43f1-4061-8e62-e429e0a3fab3'

Once the automations have been created, you can configure approval rules for each of these automations. Refer to this article to see the steps for configuring an approval rule.

Activity Behaviour

The Approval Point activity is designed to let you incorporate Pia’s approval‑management capabilities directly into your custom automations. By adding approval points where they are actually needed, you give your clients far more control over how and when approvals are triggered, without requiring an automation engineer to modify the workflow later.

When an automation reaches an approval step, Pia first checks whether the user running the automation is listed as an approver or is in the exempt list; if they are, the approval step is skipped, and the automation continues. If they are not an approver, Pia sends an approval request to the designated approver and proceeds only if that approver responds positively. A declined response ends the automation, while a lack of response triggers an escalation email to the fallback approver and a notification to the user in the approval log within the chat.

To view the activity behavior in Pia, click here.

Input Properties

Use properties to modify the behaviour of the activity.

Property Name: Unique Id
Property Required: Yes
Property Description: This should be a unique id used to identify the approval point. Please specify a GUID you can generate online here: https://www.guidgenerator.com/.

Property Name: Name
Property Required: Yes
Max Characters: 100
Property Description: A short name for the approval point which can be used to identify it for the purpose of configuring approval rules.

Property Name: Approval For
Property Required: No
Max Characters: 300
Property Description: A one line summary of the request details at the point of approval. This should tell the approver what changes they are approving. e.g. "$16 Office 365 Premium license required for New User Onboarding of Mark Richardson".

Property Name: Condition Text
Property Required: Yes
Max Characters: 300
Property Description: Describe the condition for when an approval request will be sent to approvers. You will need to specify in the format of "Approval Condition as: [condition_text] must be approved by an authorized approver." e.g. if condition_text is set to "All New User Onboarding / Account Requests", this would display to the user as "Approval Condition: All New User Onboarding / Account Requests must be approved by an authorized approver.

Property Name: Stop On Reject
Property Options: 'True' or 'False'
Default Value: True
Property Required: No
Property Description: This will stop the automation (and its parent automations) if the approval is rejected or times out. Set this to false if you want to handle timeout or rejection directly in your automation.

Property Name: Client Id
Default Value: $Ctx_Client_Id
Property Required: Yes
Property Description: This is the internal Client ID - defaults to the client id for the currently running automation.

Property Name: Approval Group Name
Property Required: No
Property Description: Use this property to group approval points together across more than 1 automation. This should be the text name of the automation which you can set in other automations which use the same name. When you use this property, set "Unique Id" the same across each extension point which should share the same approval rules across automations in the same Approval Group.

Output properties

Here are the output properties for thus activity.

Property Name: Approval Outcome
Property Description: This is the response given by the approver when a approval request is sent to them. Pia will capture one of the three responses: 'approved', 'declined', 'timed_out'.

Property Name: Approval Result
Property Description: This is the Json array of objects representing who approved and when. Since multiple approvers are allowed (via approval steps) this array may have multiple objects.

Example for 2 steps verification where first person approved and second person declined

[
    { 
        email: 'sam.smith@company.com', 
        datetime: 'UTC_TIMESTAMP_HERE', 
        name: 'Sam Smith', 
        action: 'approved', 
        step: 1 
    }, 
    {
        email: 'tommy.keithh@company.com', 
        datetime: 'UTC_TIMESTAMP_HERE', 
        name: 'Tommy Keithh', 
        action: 'declined', 
        step: 2, 
        comments: 'This is not required anymore.'
    } 
]

Example for timeout

[
    {
        email: 'sam.smith@company.com',
        datetime: 'UTC_TIMESTAMP_HERE',
        name: 'Sam Smith',
        action: 'timed_out',
        step: 1 
    } 
]