Documentation

Approver Scripts

Table of Contents

Overview

Approver Scripts provide a flexible way to dynamically determine the approval workflow for reservations. By attaching an Approver Script to a resource, you can customize who needs to approve a reservation based on specific conditions. This allows for tailored approval processes that adapt to various business requirements.

When Approver Scripts Run

Approver Scripts are executed when:

  • A reservation is created for a resource with an attached Approver Script.
  • A reservation for a resource with an attached Approver Script is edited.

Important Note: Approver scripts are evaluated for each resource in a multi-resource reservation independently, before the full reservation is compiled. They do not have access to the other resources in the multi-resource reservation. However, you can look these up from the input JSON to this endpoint by accessing the reservation_form variable in the context.

Context Variables

Approver Scripts have access to the following global variables:

  • approvers: A list of pre-set approvers defined at the resource level.
  • reservation: Details about the current reservation being processed.
  • previous_reservation: If the reservation is being edited, this contains the original reservation details.
  • script: A dictionary containing script metadata, including attached_to_reservable_id and site_reservation_approvers_script_id.
  • reservation_form: The input JSON forms for the reservation, which can be used to look up account numbers or other details.
  • user_logged_in: Information about the user currently logged in.

Approver

The approvers global variable will be a list of objects with the following structure:

Field Type Description
automatic bool If True, the approval is automatic.
silent bool If True, the approver is not notified.
approver_user_id str The 32-character alphanumeric ID of the approver.
approver_site_user_group_id dec or int The numeric ID of the approver user group.
show_group_name bool Whether or not the name of the user group is shown to the user.
sub_approver_type str Specifies the approval logic for a group: "m_of_n", "any", or "all".
sub_approver_m_of_n int Required if sub_approver_type is "m_of_n". Specifies the number of approvals needed.
approver_from list[str] Where this approver came from and will contain one or both of "reservable" and/or "site_user".

Output Format

An Approver Script must return a dictionary with the following structure:

approvers (Required)

A list of approver dictionaries. Each dictionary can have the following keys:

Field Type Description
automatic bool or None If True, the approval is automatic.
silent bool or None If True, the approver is not notified.
approver_user_id str or None The 32-character alphanumeric ID of the approver.
approver_user_email str or None The email address of the approver.
approver_site_user_group_id dec, int, or None The numeric ID of the approver user group.
approver_site_user_group_name str or None The name of the approver user group, case insensitive.
sub_approver_type str or None Specifies the approval logic for a group: "m_of_n", "any", or "all".
sub_approver_m_of_n dec, int, or None Required if sub_approver_type is "m_of_n". Specifies the number of approvals needed.

If approver_from is provided, it will be ignored. Similarly, if both approver_user_id and approver_user_email are provided, approver_user_email is ignored. The same is true for approver_site_user_group_id and approver_site_user_group_name.

Important Notes:

  • For individual approvers, either approver_user_id or approver_user_email must be provided.
  • For group approvers, approver_site_user_group_id must be provided.
  • When using sub_approver_type with "m_of_n", sub_approver_m_of_n is also required.
  • Exactly one of approver_user_id, approver_user_email, or approver_site_user_group_id must be provided.

anyapprovers (Optional)

This boolean value can be used to indicate that any approver can approve the reservation.

Examples

Example 1: Only Require Approvals in the Evening

# Only require approvers if the reservation starts after 5 PM.
if datetime.info(dt=reservation['start'])['hour'] >= 17:
  return { "approvers": approvers }
return { "approvers": [] }

Example 2: Require M-of-N Approvals from a User Group

# Require 3 people in the group with ID 123 to approve.
group_approver = {
    'approver_site_user_group_id': 123,
    'sub_approver_type': 'm_of_n',
    'sub_approver_m_of_n': 3
}

return { "approvers": [group_approver] }

Example 3: Automatic Approval for Certain Users

# When a specific user is making the reservation, approve them automatically.
if user_logged_in['user_id'] == 'a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6':
  updated_approvers = [ app + {"automatic": True} for app in approvers ]
  return { "approvers": updated_approvers }

# Otherwise, just return approvers as originally defined.
return { "approvers": approvers }

Example 4: Skip Approvals for Specific User Group

# Skip approvals for anyone in the Senior Staff user group.
groups = api.users.usergroups(user_id=reservation['reserved_for']['user_id'])
for grp in groups:
  if grp['name'] == 'Senior Staff':
    return {"approvers": [] }
return { "approvers": approvers }