TemplatePlugin — Quickstart

Prerequisites

• AptecoPSFramework installed and configured
• PowerShell 5.1+ or PowerShell 7+

1. Copy the template

Clone or copy this repository into your framework's plugin folder:

# Option A — place directly in the framework plugin folder
Copy-Item -Path "AptecoPSFramework_plugin_template" `
          -Destination "AptecoPSFramework\plugins\MyNewPlugin" -Recurse

# Option B — register a separate folder (recommended for external repos)
Add-PluginFolder -Path "C:\path\to\AptecoPSFramework_plugin_template"

2. Generate a new GUID

Every plugin must have a unique GUID. Open Plugin.ps1 and replace the guid value:

[guid]::NewGuid().ToString()
# e.g. "3f8a1b2c-4d5e-6789-abcd-ef0123456789"

3. Rename the plugin

Search and replace TemplatePlugin with your plugin's name across all files.

4. Adjust settings

Edit settings\defaultsettings.ps1:

Setting	Description
providername	Friendly name shown in logs
messages	Hardcoded message list (replace with API call)
groups	Hardcoded group list (replace with API call)
output.folder	Folder where dummy CSV files are written
preview.*	Sender name, address and subject for previews

5. Load and test the plugin

# Import the framework
Import-Module AptecoPSFramework

# Set your settings file and register the plugin folder
Set-AptecoPSFramework -SettingsFile "path\to\settings.json"
Add-PluginFolder -Path "path\to\AptecoPSFramework_plugin_template"

# Confirm the plugin is registered
Get-Plugin

# Import the plugin by its GUID
Import-Plugin -Guid "c9a1d4e8-3b72-4f0e-a518-7d6c2b9e4f31"

# Smoke-test
Get-HelloWorld
Test-Login

# Load messages and groups
Get-Messages
Get-Groups

6. Replace dummy implementations with real API calls

Each # TODO comment marks a placeholder to replace:

File	What to implement
private\helper\Test-PluginConnection.ps1	API ping / token validation
public\peoplestage\get-messages.ps1	Fetch campaigns/mailings from API
public\peoplestage\get-groups.ps1	Fetch lists/groups from API
public\peoplestage\invoke-upload.ps1	Upload recipient data to platform
public\peoplestage\invoke-broadcast.ps1	Trigger send on platform
public\peoplestage\show-preview.ps1	Fetch and personalise template HTML
public\peoplestage\test-send.ps1	Send a test message via API

7. (optional) Wire up error notifications

Test-PluginConnection.ps1 and invoke-upload.ps1 already call Send-Notification instead of Write-Log at their error points. Send-Notification always logs exactly like Write-Log, but additionally fans the message out via PSNotify (Slack, Teams, Telegram, Email) once you configure it — nothing changes for you if you leave it unconfigured. Configuration lives in the framework's own settings (settings.notifications), not in this plugin's defaultsettings.ps1, since it is a cross-cutting, per-installation concern. See the "Notifications" section in the AptecoPSFramework readme for how to set up PSNotify groups and route severities to them.

File structure

AptecoPSFramework_plugin_template\
├── Plugin.ps1                          ← plugin metadata & GUID
├── quickstart.md
├── settings\
│   └── defaultsettings.ps1             ← plugin configuration
├── public\
│   ├── Get-HelloWorld.ps1
│   ├── Get-PluginDebug.ps1
│   └── peoplestage\
│       ├── get-messages.ps1
│       ├── get-groups.ps1
│       ├── invoke-upload.ps1
│       ├── invoke-broadcast.ps1
│       ├── show-preview.ps1
│       ├── test-login.ps1
│       └── test-send.ps1
└── private\
    └── helper\
        └── Test-PluginConnection.ps1   ← connectivity check (replace with real check)