Trial #40: Populate Active Directory with iSAMS Pupil Data

Problem:

If you work at a school using iSAMS, it is probably your trusted data source for pupil info such as preferred name. But who maintains AD to make sure changes propagate to your Global Address List?

Solution:

PowerShell makes the management of Active Directory very easy using the ActiveDirectory Module.

I have published a client and PowerShell Module the the iSAMS Batch API.

This can be installed from the PowerShell Gallery:

Install-Module -Name IsamsBatchApi

We can use these modules to acquire the data and and make changes to Active Directory.

Acquiring the Pupil Data

The simplest way to get the data is using an API Key

$pupils = Get-IsamsCurrentPupil -ApiKey "0A1C996B-8E74-4388-A3C4-8DA1E30ADA57"  -IsamsInstance "https://school.isams.cloud"  

However, this authentication method will be phased out in the future and you will need to Connect using OATH

Connect-Isams -ClientID "Your_ID" -ClientSecret "Your_SECRET" -IsamsInstance "https://school.isams.cloud" 
$pupils = Get-IsamsCurrentPupil 
Disconnect-Isams

Matching with Active Directory

In our environment, the iSAMS property SchoolCode matches the AD property SamAccountName which is also a valid -Identity property of the Get-ADUser.

Therefore we can iterate over our pupils and attempt to get our AD users like this.

$pupils | 
    ForEach-Object {
        $user = Get-ADUser $_.SchoolCode -Properties EmployeeID, EmployeeNumber, DisplayName
        # Some action
    }

However, the iSAMS property SchoolCode is not a perfect primary key - there is no guarantee of uniqueness and it might change throughout a pupils school career. Therefore, I prefer to use the iSAMS properties Id and SchoolId which I write into the AD properties EmployeeID and EmployeeNumber.

Set-ADUser $user -EmployeeID $_.Id -Confirm
Set-ADUser $user -EmployeeNumber $_.SchoolId -Confirm  

Example Script

You may be able to use the following script as a starting point for your own environment.

I store restricted information in a config file using a method I describe in my next post

The following will persist details with at least some obfuscation to file.

@{
    BatchAPI = @{
        Host = Read-Host -Prompt "Input your iSAMS instance e.g. https://school.isams.cloud"| ConvertTo-SecureString -AsPlainText -Force | ConvertFrom-SecureString
        ClientID = Read-Host -AsSecureString -Prompt "Input your Client ID e.g. 6283d2d5-2518-4999-9db0-cc5c81750069" | ConvertFrom-SecureString
        ClientSecret = Read-Host -AsSecureString -Prompt "Input your Client Secret e.g. 69bd76b9-00ca-44d7-8e86-72368c33c33f" | ConvertFrom-SecureString
    }
    ActiveDirectory = @{
        PupilSearchBase = Read-Host -Prompt "Input the OU you pupils are stored in e.g. OU=Pupils,DC=domain,DC=local"| ConvertTo-SecureString -AsPlainText -Force | ConvertFrom-SecureString
        StaffSearchBase= Read-Host -Prompt "Input the OU you staff are stored in e.g. OU=Staff,DC=domain,DC=local"| ConvertTo-SecureString -AsPlainText -Force | ConvertFrom-SecureString
    }
} | 
    ConvertTo-Json > config.json

The following script loads this information so it need not be input manually every time it is run. It will prompt for user confirmation when a new match between AD and iSAMS is found before writing the iSAMS primary key to the AD user. AD Users with a matching iSAMS ID will have other properties updated to match iSAMS as required. Furthermore, a set of pupils that may need to be created in AD are collected in the variable $isamsUsersToCreate.