Taking Control of Aggregation Schedules with Workflows and PAG

[trettkowski (Tyler Rettkowski)]

Introduction

• Why: Managing, backing up, and manipulating aggregation schedules at scale in SailPoint Identity Security Cloud (ISC) can be a common operational headache. Native functionality does not provide a single-click mechanism to “pause” all aggregations during major maintenance windows, nor an out-of-the-box way to export and import schedule configurations across environments or during disaster recovery scenarios.
• Problem: Performing bulk modifications across dozens or hundreds of sources traditionally requires repetitive manual UI navigation or running custom, ad-hoc API scripts without an audit trail. Administrators lack a centralized, self-service interface to safely pause tenant-wide aggregations and restore them with confidence.
• Goal: Deliver an automated, enterprise-ready toolkit utilizing SailPoint Workflows and the Privileged Action Gateway (PAG) that gives administrators push-button control over aggregation schedules—incorporating safety checks, automated backups, and audit logging.

Solution Overview

• Tech Stack: 1 Form + 1 Workflow + 2 PowerShell Reporting Scripts executed via PAG.
• High-Level Flow: The solution centers around a Workflow Form that allows administrators to select from several powerful Actions:

  1. Export: Scans all sources in the tenant in parallel, captures their Account and Group aggregation schedules, and writes them to a local CSV file on the PAG server (C:\Scripts\Aggregation Exports).

     Additionally, the CSV file is automatically emailed to the individual who ran the launcher. This is achieved by passing the launcher’s email address to the PowerShell script using the $.getIdentity.attributes.email variable, which is fetched dynamically via the Get Identity action using the $.trigger.launchedBy.id expression from the trigger payload.

Email Output Example:

2. Import: Reads a previously exported CSV file and restores the schedules back into SailPoint.

   How it captures options: When the Workflow triggers, it first runs Get-AggregationScheduleFiles.ps1 via PAG. This script scans the local C:\Scripts\Aggregation Exports directory for all .csv files and returns them as a JSON array of label/value pairs. This array is seamlessly mapped into the inputForForm_array_importoptions attribute of the Interactive Form, providing the user with a dynamic dropdown of all available export files.

   How updates are executed: Once a file is selected, the Manage-AggregationSchedules.ps1 script is launched with the chosen filename. It imports the selected CSV, iterates through each row, and uses the API endpoint /sources/v1/:id/schedules to systematically DELETE any existing schedule and POST the restored CRON expressions back to each source.

3. Back Up And Remove All: A highly useful feature for maintenance windows. This action reads current schedules, securely backs them up directly into the Source object’s connectorAttributes, and then deletes the active schedules, effectively “pausing” all aggregations tenant-wide.

   How the backup works: The script executes a PATCH request to the /sources/v1/:id endpoint (using the application/json-patch+json content type) to inject custom keys directly into the source’s configuration. Specifically, it saves the current CRON strings into two new variables: BackUpAccountAggregationCRON and BackUpGroupAggregationCRON. By utilizing connectorAttributes, the data stays safely attached to the source itself within SailPoint, preventing the need to manage external backup files during a maintenance window.

4. Restore All: Reads the backed-up CRON strings from the Source objects and re-activates all schedules, returning the tenant to normal operation.

   How the restore works: The script queries all sources and checks their connectorAttributes specifically for the BackUpAccountAggregationCRON and BackUpGroupAggregationCRON variables. If a source does not have these variables (meaning it had no active schedule when the backup was taken), the script safely skips it and moves to the next source. If it does find the backup variables, it issues a POST request to recreate the schedule, followed by a final PATCH request (op: "remove") to clean up the backup variables from the source configuration so no stale data is left behind.

Architectural Decision: Why PAG & PowerShell vs. Native Workflows?

A common question when designing workflow automations in SailPoint is whether to rely strictly on native workflow actions or extend capabilities using the Privileged Action Gateway (PAG):

• Why PAG + PowerShell for this solution:
  • High-Throughput Parallel Processing: Large enterprise tenants often manage 100+ sources. Iterating through hundreds of sources sequentially via native Workflow HTTP Request loops is constrained by execution timeouts and API pagination overhead. PowerShell Runspace pools allow multi-threaded concurrency (10–15 parallel threads), reducing execution from 20+ minutes down to seconds.
  • Dynamic File System & Dropdown Population: Native workflow forms cannot dynamically read local directories. The helper script (Get-AggregationScheduleFiles.ps1) reads the export directory on disk and injects the filenames into the interactive form dropdown in real time.
  • Local File Archiving & Transport: Exporting schedules directly into timestamped CSV artifacts on the PAG server and automatically dispatching them via SMTP provides an off-platform backup trail that survives tenant configuration changes.
• When a Native Workflow-Only Approach Suffices:
  • If your tenant has a small footprint (e.g., fewer than 10–15 sources) or if you only need to pause/resume specific, targeted sources, you can build a 100% native Workflow. Using the native HTTP Request action against /sources/v1/:id/schedules inside a simple loop avoids the requirement for an on-premises PAG server or local Windows host.

Prerequisites

To successfully implement this solution, your environment will need the following in place:

• Privileged Action Gateway (PAG): A configured PAG instance to bridge SailPoint Workflows with your local scripts.
• Local Windows Server: A server to host the PowerShell scripts and provide a directory (e.g., C:\Scripts\Aggregation Exports) to write and read the CSV backup files.
• SMTP Setup: Valid SMTP credentials and server details for the main script to dispatch the exported .csv files to your email.
• API Credentials: A SailPoint Personal Access Token (Client ID & Secret) with the appropriate scopes (idn:sources:manage and idn:sources:read) for the script to execute the API calls.

Safe Use, Testing & Backup Validation

Because actions like Back Up And Remove All and bulk Import operate tenant-wide, operational discipline and safety controls are essential before running them in production:

1. Pre-Flight Testing in Sandbox:
   • Always deploy and validate the Form, Workflow, and PowerShell scripts in your sandbox or staging tenant first.
   • Run the Export action and verify that the generated CSV contains the expected source IDs, names, and non-null CRON expressions.
2. Backup Validation Before Deletion:
   • When using Export, inspect the generated CSV file in C:\Scripts\Aggregation Exports (or your received email) to ensure the row count matches your total scheduled sources.
   • When using Back Up And Remove All, spot-check 2–3 active sources via the SailPoint Admin UI or the /sources/v1/:id API to verify that BackUpAccountAggregationCRON and/or BackUpGroupAggregationCRON have been successfully written to connectorAttributes before assuming the backup succeeded.
3. Safety Confirmations in the Form:
   • The Workflow Form includes required confirmation toggles for destructive actions. Administrators must explicitly acknowledge and toggle the confirmation checkbox before the workflow triggers a tenant-wide pause or overwrite.
4. Post-Execution Verification:
   • After Pausing: Navigate to a source in the ISC Admin UI and check the schedule is turned off.
   • After Restoring: Run a fresh Export action and compare the new CSV against your original baseline backup using a diff tool to confirm 100% parity.

User Interface

• Input Fields:

  • Options: Export, Import, Back Up And Remove All, Restore All.
  • Import Options: A dynamic dropdown populated with the available CSV files on the server (using a helper PowerShell script).
  • Warnings: Toggle confirmations for the tenant-wide Pause/Restore actions.

• User Experience: By using a dynamic workflow form, we ensure admins don’t need to manually type file paths or rely on hardcoded variables. The helper script (Get-AggregationScheduleFiles.ps1) fetches the available export files directly from the server for easy selection.

Form Definition Code:
Form-AggregationScheduleManager.json (7.2 KB)

Back End Workflow

• Trigger: This solution utilizes an Interactive Trigger so we can launch it directly from the Launchers UI.
• Helper Script via PAG: The first step runs the Get-AggregationScheduleFiles.ps1 script to load the available CSVs from the server and populate the interactive form dropdown.
• Interactive Form: The user is presented with the dynamic form to select their desired action.
• Main Script Execution: Based on the form selection, the workflow passes the arguments to the Manage-AggregationSchedules.ps1 script which does the heavy lifting via APIs.

Workflow Code:
Workflow-AggregationScheduleManager.json (9.3 KB)

PowerShell Execution & API Highlights

• High Performance (Parallel Processing): Iterating through hundreds of sources sequentially via REST APIs is incredibly slow. The main script (Manage-AggregationSchedules.ps1) utilizes PowerShell Runspace Pools (multi-threading) to process 10-15 sources concurrently, drastically reducing execution time from minutes to seconds.
• API Adherence: The scripts adhere to SailPoint’s newest API structures, specifically utilizing the sources/v1 endpoint for patching source attributes, and the sources/v1/:id/schedules endpoint.
• Complete Audit Trail: Implements a comprehensive, timestamped logging framework. Every action, parameter, and API exception is logged to a logs.txt file in the script directory, providing perfect visibility for troubleshooting PAG executions.
• Error Handling, Rate Limiting & Mid-Flight Recovery:
  • API Resilience & Throttling: All API requests incorporate error trapping for HTTP 429 (Rate Limit Exceeded) and transient network timeouts. If a rate limit is encountered, the script backs off exponentially before retrying.
  • Per-Source Graceful Degradation: The script encapsulates each source update in individual try...catch blocks. If one source encounters an issue (e.g., locked source or invalid CRON syntax), the failure is logged as a [WARN] to logs.txt, and the runspace continues processing all remaining sources rather than crashing midway.
  • Partial Failure Recovery: In the event of a partial run, the administrator can inspect logs.txt to identify the skipped source IDs. Because the backup data is stored directly in connectorAttributes, running Restore All again is idempotent, it will safely re-process any source that still has the backup attributes present.
  • Fatal Failures: A custom Throw-Error function catches fundamental system faults (e.g., failed OAuth authentication, unreadable CSV file, or unavailable network gateway) to immediately halt the script and return an explicit error code to the SailPoint Workflow engine.

PowerShell Scripts:

• Helper Script: Get-AggregationScheduleFiles.ps1 (1.5 KB)

• Main Script: Manage-AggregationSchedules.ps1 (12.4 KB)

Considerations & Best Practices

• PAG Compatibility: The scripts are written to ensure compatibility with Windows Server PowerShell 5.1 (using -UseBasicParsing for Invoke-RestMethod) and enforce TLS 1.2 for secure API authentication.
• Permissioning: The launcher should only be granted to admins, as this provides the ability to enable/disable aggregations completely across the tenant.
• Token Security: The main script uses standard OAuth Client Credentials. Ensure the client ID and secret have the necessary idn:sources:manage and idn:sources:read scopes.
• Credential & Secret Protection:
  • Never Hardcode Secrets: While the example script displays placeholder variables (YOUR_CLIENT_ID, YOUR_CLIENT_SECRET), production deployments should never store plaintext API secrets in .ps1 files.
  • Recommended Storage: Store your Client ID and Secret in Windows Credential Manager, read them from system environment variables, retrieve them via Azure Key Vault / HashiCorp Vault, or pass them as secure workflow inputs through the PAG.
  • Least Privilege: Ensure the API Personal Access Token or OAuth Client uses only the minimum scopes required: idn:sources:read and idn:sources:manage.
• Log Sanitization & Access Control:
  • Token Masking: Bearer tokens and HTTP Authorization headers are stripped and excluded from all Write-Log operations to prevent sensitive credentials from ever landing in logs.txt.
  • Directory Permissions (ACLs): Restrict NTFS file permissions on C:\Scripts\Aggregation Exports and logs.txt. Only the PAG service account and authorized server administrators should have read/write access to these paths.
• PAG & Headless Compatibility: The scripts enforce TLS 1.2 ([Net.SecurityProtocolType]::Tls12) and use -UseBasicParsing with Invoke-WebRequest to guarantee reliable operation in headless Windows Server PowerShell 5.1 environments.
• Administrative Governance: Access to launch this interactive workflow form should be restricted via SailPoint role permissions exclusively to trusted Administrators.

Conclusion

• Summary: By using this solution, administrators can confidently execute bulk updates, perform safe maintenance pauses, and maintain strict version control of their aggregation schedules without writing a single line of ad-hoc API code.
• Call to Action: If you have any questions or ideas to expand on this exporter/importer, feel free to post below!