Extending ISC: Building a Custom Campaign Email Reminder System

[trettkowski (Tyler Rettkowski)]

Introduction

• Why: A frequently requested feature on the SailPoint Ideas Portal (GOV-I-799) is the ability to configure the frequency of campaign email reminders. By default, SailPoint Identity Security Cloud (ISC) sends automated reminder emails once a week throughout the campaign lifecycle. However, out-of-the-box (OOTB) functionality does not currently support adjusting this interval or automatically stopping reminders once a campaign passes its deadline.
• When to Use This Approach:
  • Native ISC Reminders: Best suited for standard, recurring certifications where a predictable, weekly follow-up schedule meets business requirements.
  • Custom Reminder Workflow: Recommended for high-priority compliance cycles (such as SOX or executive entitlement reviews) with strict, compressed deadlines requiring follow-ups every 1 to 3 days, daily reminders as deadlines approach, or consolidated notifications across multiple active campaigns.
• Problem: The fixed weekly reminder schedule offers limited flexibility. When campaigns require an accelerated follow-up cadence, or when administrators need notifications to cease strictly at the campaign deadline, native configuration options cannot accommodate those requirements.
• Goal: The solution presented in this article provides end-to-end control over certification campaign email follow-ups. By combining an interactive form, a SailPoint workflow, and PowerShell scripts executed through Privileged Task Automation (PTA) via the Privileged Access Gateway (PAG), administrators can fully customize reminder intervals and consolidate multiple campaign notifications into a single reviewer email.

Solution Overview

• Tech Stack: 1 Form + 1 Workflow + 2 PowerShell Scripts + 1 HTML Email Template.
• High-Level Flow: Through an interactive form, administrators can select active campaigns, determine if they want to send an immediate reminder, configure the time frequency (in days), and decide if reminders should stop once the end date is reached. The workflow calculates the necessary iterations using an inline PowerShell script and uses a serial loop to pause (Wait step) and execute the reminder emails via a second PowerShell script running via PTA.

User Interface

• Input Fields:

  • Select All Active Campaigns Or Individual Campaigns - Toggle Field
  • Campaign Selector - Dropdown Field (Only appears if the toggle above is set to false)
  • Send Reminder Now? - Toggle Field (Controls whether to send an immediate reminder or wait until the first frequency interval hits)
  • Stop on End Date? - Toggle Field (Controls whether notifications should stop if the campaign due date has passed)
  • Select Time Frequency - Dropdown Field (1-15 Days)

• User Experience: We use an interactive form to act as a launcher for the workflow. This allows administrators to quickly select the target campaigns and define the frequency parameters without hardcoding anything. The form utilizes dynamic showing/hiding so the campaign selector only appears if you opt not to select all active campaigns.

Form Definition Code:
Form-CertificationCampaignFrequencySelector.json (8.1 KB)

Back End Workflow

Here is a visual representation of the workflow architecture:

flowchart TD
    A["Interactive Trigger"] --> B["Get Active Campaigns"]
    B --> C["Interactive Form Launcher"]
    C --> D["Set Variables and Format Time"]
    D --> E["Calculate-Iterations.ps1 via PTA"]
    E --> F["Serial Loop: Check Counter vs Iterations"]
    F -->|"True"| G{"Send Reminder Now and First Loop?"}
    F -->|"False"| Z["Workflow Complete"]
    G -->|"Yes"| H["Send-ReminderEmails.ps1 via PTA"]
    G -->|"No"| I["Wait Step Duration"]
    I --> J["Send-ReminderEmails.ps1 via PTA"]
    H --> K["Increment Counter"]
    J --> K
    K --> F

• Trigger & Setup: The workflow utilizes the Interactive Trigger so the form can be presented to the user. It first queries for active campaigns to populate the form dynamically.
• Time Conversion (Define Variable): The “Select Time Frequency” form input returns a string like “1 Day” or “3 Days”. However, the workflow’s Wait step requires standard duration formats like “1d” or “3d”. The workflow handles this using a “Define Variable” step with string replacement transforms to convert the dropdown text into a usable workflow duration format.
• Calculate Iterations: A crucial step is calculating how many loop iterations are required. We execute a PowerShell script (Calculate-Iterations.ps1) via the Windows Server PTA integration. It returns a JSON object with the iterations count.
• Serial Loop: A counter variable is initialized at 0. A “While” Serial Loop runs as long as the counter is less than the iterations returned from the calculation script. Inside the loop, a Choice step evaluates the “Send Reminder Now?” flag. If it’s the first iteration and the flag is true, it immediately executes the reminder script. Otherwise, it pauses using a Wait step for the converted frequency (e.g., “3d”), triggers the Send-ReminderEmails.ps1 script, and finally increments the counter.

Workflow Code:
Workflow-CertificationReminderFrequency.json (12.7 KB)

PowerShell Scripts & Email Template

Because there is no native workflow action to trigger ad-hoc campaign reminders, this solution manages email generation and dispatch using PowerShell executed via PTA/PAG.

• Calculate-Iterations.ps1: Connects to the ISC API to determine the furthest deadline among the selected campaigns and calculates the time difference in days from the current date. Because SailPoint workflows enforce a 30-day maximum execution ceiling, the script caps the iteration window at 30 days. It then divides the total duration by the selected frequency to return the exact iteration count needed for the workflow loop.
• Send-ReminderEmails.ps1: Orchestrates the core logic for reviewer aggregation and email delivery:
  1. Queries /certifications/v1 for the target campaign IDs.
  2. Filters out completed or signed-off items to isolate pending decisions.
  3. Groups pending certifications by reviewer.id.
  4. Dynamically populates an HTML table for each reviewer and replaces the placeholders within the email template.
  5. Dispatches a single, consolidated SMTP email to each reviewer. (A significant advantage of this approach is that a reviewer assigned to three active campaigns receives one consolidated email listing all pending items, rather than multiple fragmented notifications.)
• Email-Template.html: Referenced by Send-ReminderEmails.ps1 to structure the outgoing message. This template can be customized to align with your organization’s branding or styled to mirror standard SailPoint notifications.

Script Downloads:
Calculate-Iterations.ps1 (5.4 KB)

Send-ReminderEmails.ps1 (9.5 KB)

Email-Template.html (1.5 KB)

Note: Both PowerShell scripts generate a logs.txt file in their resident directory to help you debug the inputs passed, recipients emailed, and any potential errors.

Considerations & Best Practices

• Avoiding Duplicate Reminders:
  • Coordinate with Native ISC Reminders: Before launching this custom workflow, review your campaign definition or campaign template settings in ISC. To prevent reviewers from receiving redundant notifications, consider disabling or adjusting the built-in reminder schedule when relying on this workflow for notifications.
  • Prevent Overlapping Workflow Runs: Ensure only one workflow instance runs for a given set of campaigns at a time. Launching multiple concurrent workflow instances targeting the same campaigns will cause reviewers to receive duplicate emails on overlapping schedules.
• Credential Security & Least Privilege:
  • Avoid Plaintext Credentials: The sample scripts include placeholder variables for demonstration purposes. In production environments, never hardcode client secrets or SMTP passwords. Instead, retrieve credentials securely using Windows Credential Manager, system environment variables on the PAG/PTA host, or an enterprise secret store (such as CyberArk or HashiCorp Vault).
  • Principle of Least Privilege: Ensure the API Personal Access Token (PAT) or OAuth Client used by the scripts is restricted to read-only campaign and certification scopes (e.g., idn:campaigns:read, idn:certifications:read) rather than full administrative privileges (ORG_ADMIN).
  • Secure SMTP Communication: Always transmit outbound email traffic over TLS (port 587) or appropriate authenticated internal relay endpoints.
• Workflow Monitoring & Failure Handling:
  • Monitoring Execution Progress: Monitor active executions directly within the Workflows > Execution History tab in ISC. You can inspect step execution statuses, input/output payloads, and confirm loop progress.
  • Host-Level Script Logging: Both PowerShell scripts generate a timestamped logs.txt file in their resident execution directory on the PTA host. This log details parsed campaign inputs, identified reviewers, API response codes, and email dispatch status.
  • Error Handling & Resilience: Both scripts implement robust try/catch error trapping. If an API call fails (for instance, due to an expired token or network blip), the script terminates with an explicit error message logged to logs.txt, preventing partial or erroneous email deliveries.
• Workflow Duration Limits:
  • Because workflow executions in ISC have a 30-day maximum lifecycle, Calculate-Iterations.ps1 caps the iteration count to 30 days. If your certification campaign remains active past 30 days, simply relaunch the interactive form to initiate a new reminder cycle.
• Canceling or Modifying Reminders:
  • If a campaign concludes early, or if administrators wish to alter the reminder frequency mid-campaign, navigate to the ISC Workflows dashboard and cancel the in-flight execution. A new workflow run can then be launched with updated parameters.

Conclusion

• Summary: This solution addresses a common requirement in identity governance by giving administrators full autonomy over certification reminder frequency. By combining interactive forms, workflows, and Privileged Task Automation (PTA), organizations can implement flexible, consolidated reminder schedules tailored to their governance requirements.
• Call to Action: If you have questions, feedback on the PowerShell implementation, or alternative approaches for managing reminder cadences, please share your thoughts in the comments below!