Example: Membership Runbook

A Step-by-Step Guide for Azure Automation with Hybrid Workers and PowerShell 7.2

This tutorial provides guidance for implementing an Azure Automation runbook that synchronizes membership changes from ServiceChanger to on-premises Active Directory and Entra ID using Azure Arc-enabled Hybrid Worker(s).

System Requirements

Required PowerShell Modules (on all Arc VMs)

  • Active Directory Module: Install-WindowsFeature -Name RSAT-AD-PowerShell

  • Azure Arc Agent: Installed and connected to Azure

  • WinRM Configuration: Enabled for Azure AD Connect remoting

Optional Configuration (for Email Alerts)

  • SMTP Service Account: Access to email server (Office 365, Exchange, etc.)

Arc-enabled Architecture Benefits

  • Enhanced security through Azure managed identity integration

  • Improved connectivity and reliability via Azure Arc agent

  • Centralized management through Azure portal

  • Multiple VMs provide automatic redundancy and load balancing


Step 1: Configure Azure Automation Variables

Navigate to your Azure Automation Account and create the following variables under Shared Resources > Variables:

Core Configuration Variables

Configuration Details:

  • Name: SC_ApiKey

  • Type: String

  • Encrypted: Yes

  • Value: [Your ServiceChanger API Key]

  • Description: ServiceChanger API authentication key

Obtain your API key from ServiceChanger application: Settings > ServiceChanger API Key

Azure AD Connect Variables

Configuration Details:

  • Name: SC_AADConnectServer

  • Type: String

  • Encrypted: No

  • Value: ADCONNECT-CLUSTER.domain.local (server name or cluster VIP)

  • Description: Azure AD Connect server where delta sync will be executed

Email Alert Variables (Optional)

  • Name: SC_SmtpUsername

  • Type: String

  • Encrypted: Yes

  • Value: [SMTP service account email address]


Step 2: Create and Configure the Runbook

Navigation Path: Azure Portal → Automation Account → Process Automation → Runbooks

  1. Select "+ Create Runbook"

Runbook Configuration

Setting
Value

Name

ServiceChanger-AD-MembershipSync

Runbook Type

PowerShell

Runtime Version

7.2

Description

Enterprise AD membership synchronization with ServiceChanger API using Arc Workers

Code Deployment

  1. Open the newly created runbook

  2. Insert the runbook code below

  3. Save your changes

  4. Publish the runbook


Step 3: Email Alert Configuration (Optional)

Email notifications are triggered only for critical runbook failures that prevent completion

To enable email notifications:

  1. Edit the runbook

  2. Customize environment-specific settings:

  1. Modify the parameter at the top of the script:

Alternative: Pass the parameter when starting the runbook manually or configure it in the schedule.

  1. Save and republish the runbook


Step 4: Schedule Configuration

Schedule Creation

  1. Select "+ Link to schedule"

  2. Choose "Link a schedule to your runbook"

  3. Configure the new schedule:

Setting
Recommended Value

Name

ServiceChanger-Sync-Schedule

Frequency

Recurring

Recur every

1 hour

Time zone

Your organizational timezone

Execution Settings

  • Run on: Hybrid Worker

  • Hybrid Worker Group: [Your configured group name]


Step 5: Testing and Validation

Initial Test Execution

  1. Execute "Start" within the runbook interface

  2. Monitor the Output tab for execution logs and status

  3. Verify successful completion and review log entries

Validation Checklist


Troubleshooting Guide

Common Error Scenarios

Error Message: "Failed to load Azure Automation Variables"

Resolution Steps:

  • Verify all required variables exist with correct naming (case-sensitive)

  • Confirm encrypted variables are properly marked as encrypted

  • Validate variable names for typographical errors

  • Ensure the Automation Account has proper permissions

  • Check specifically for new Azure AD Connect variables (SC_AADConnectServer, SC_AADConnectUsername, SC_AADConnectPassword)

Support Resources

Technical Support: The runbook includes comprehensive error handling and detailed logging. All operations generate timestamped log entries with specific error descriptions for troubleshooting purposes.


Last updated