Run Microsoft Online Scripts

Provisioning Manager can run a PowerShell script through Atria's Microsoft Online service in the security context of the target tenant. Use this for Microsoft 365 configuration that is not part of Atria's standard MSOL rules.

Read the Provisioning Manager overview, rule value syntax, and Microsoft Online property reference first.

Prerequisites

The customer's internal Azure AD service (Microsoft Entra ID integration) and Microsoft Online connector must be provisioned successfully. The requested connection also depends on the corresponding PowerShell module and Secure Application Model configuration on the MSOL web-service host.

Choose the action

Action	Use when
MSOL Run Customer Script	The script configures the tenant or a customer-wide Microsoft 365 setting.
MSOL Run User Script	The script configures a specific user and needs Atria's user ID and Microsoft user ID.

For an Atria-managed service, place custom rules in Before or After, not Main. Typical locations are:

Event$Customer Service$MSOL$After Provision
Event$Customer Service$MSOL$Before Deprovision
Event$User Service$MSOL$After Provision
Event$User Service$MSOL$Before Deprovision

Use After Provision when the standard tenant, user, mailbox, or licence operation must finish first. Use Before Deprovision when the script must read or remove data before Atria disconnects the object.

Provision events also run for updates. Every script must be safe to run more than once.

Action parameters

The two actions share the following parameters; the user action also has User Id.

Parameter	Required	Value
Customer Id	Yes	Normally `{CustomerID}`.
User Id	User action only	Normally `{UserID}`.
Connect Services	No	Comma-separated connection keywords described below. Leave empty for a local script that needs no Microsoft connection.
Script File	Yes	Path to a `.ps1` file accessible on the machine running the Atria MSOL web service. Request tokens in the path are expanded before execution.
Webservice Connection	Yes	In an MSOL service request, use `{ServiceProperties}("WebServiceConnection")`.
Result Property	No	Request-property name in which Atria stores the script result for later rules.
Timeout	No	Timeout in minutes. The action increases the web-service timeout only when this value is longer than its existing timeout.
Variables	No	One named mapping per entry, in the form `$VariableName = {RequestProperty}`.

Connection keywords

Use lowercase values in new rules for consistency.

Keyword	Result inside the script	Guidance
`exchange`	Exchange Online cmdlets are connected for the target tenant.	Call cmdlets such as `Get-Mailbox` directly. Let Atria own the connection lifecycle.
`graph`	Adds the Microsoft Graph access token as `$GraphToken`.	Use for direct HTTPS requests to Microsoft Graph. It does not run `Connect-MgGraph`.
`mggraph`	Connects the Microsoft Graph PowerShell SDK for the tenant.	Use when the installed `Microsoft.Graph` cmdlets are preferred.
`partnercenter`	Connects Partner Center PowerShell.	Use only for operations permitted by the configured partner application.
`azure`	Connects the legacy AzureAD PowerShell module.	Compatibility option for existing scripts; prefer Microsoft Graph for new work.
`msonline`	Connects the legacy MSOnline module.	Compatibility option. Its cmdlets can require an explicit tenant parameter.

Multiple keywords can be comma-separated, for example:

exchange,mggraph

Only request the connections the script uses. Each additional connection adds startup time and another possible failure point.

Variables available to the script

The action always adds:

Variable	Description
`$RequestProperties`	The current provisioning request property collection. Treat connection objects and protected values inside it as sensitive.
`$CustomerId`	Atria customer database ID.

Connector-backed runs can also add:

Variable	When available
`$TenantId`	The customer has a Microsoft connector with an Azure tenant ID.
`$UserId`	MSOL Run User Script is used.
`$UserAzureId`	The user has a Microsoft connector record.
`$GraphToken`	`graph` is included in Connect Services.

PowerShell variable names are case-insensitive. The table uses the spelling assigned by CORE.

Named entries in Variables add further values. For example:

$UserPrincipalName = {ServiceProperties}("UserPrincipalName")
$UsageLocation = {ServiceProperties}("UsageLocation")
$ExternalSku = {ServicePackage}("ExternalSku")

These mappings pass values into the script. Changing the PowerShell variable does not update the provisioning request. To pass a result to a later rule, configure Result Property.

Web-service connection

MSOL customer- and user-service requests normally contain the connection object at:

{ServiceProperties}("WebServiceConnection")

Pass the object directly to Webservice Connection. Do not put it inside quotes, render it into a log, or pass it through Powershell Execute.

For a custom service whose request does not contain this object, use MSOL Add WebService Connection in a pre-request rule to add the connection before the run-script action. That lookup must execute in the primary Atria location because it reads the platform connection configuration.

Write the script

Store scripts in a controlled directory readable by the MSOL web-service identity. Apply normal source control and change review to the script file; Provisioning Manager stores its path, not the script content.

A script should:

validate required variables before changing anything;
query current state and change only what differs;
use -ErrorAction Stop where a failed command must fail provisioning;
avoid Write-Host for return data;
never print tokens, connection objects, temporary passwords, or the complete $RequestProperties collection;
return a small object only when Result Property is required;
let Atria manage connections created by Connect Services.

Script output and provisioning logs

Thrown errors and action diagnostics can be written to provisioning logs. Keep exception messages useful but free of secrets and personal data that is not required for troubleshooting.

Example: update Exchange mailbox attributes

Configure MSOL Run User Script with:

Parameter	Example value
Customer Id	`{CustomerID}`
User Id	`{UserID}`
Connect Services	`exchange`
Script File	`C:\AtriaScripts\MSOL\Set-MailboxAttributes.ps1`
Webservice Connection	`{ServiceProperties}("WebServiceConnection")`
Timeout	`10`
Variables	`$UserPrincipalName = {ServiceProperties}("UserPrincipalName")`

Set-MailboxAttributes.ps1:

if ([string]::IsNullOrWhiteSpace($UserPrincipalName)) {
    throw 'UserPrincipalName was not supplied.'
}

$mailbox = Get-Mailbox -Identity $UserPrincipalName -ErrorAction Stop
$userProperties = $RequestProperties['ServiceProperties']['UserProperties']
$custom1 = $userProperties['extensionAttribute1']

if ($mailbox.CustomAttribute1 -ne $custom1) {
    Set-Mailbox `
        -Identity $UserPrincipalName `
        -CustomAttribute1 $custom1 `
        -ErrorAction Stop
}

The state comparison makes the script safe for both initial provision and later updates.

Example: call Microsoft Graph with a token

Set Connect Services to graph. The action supplies $GraphToken and $TenantId:

if ([string]::IsNullOrWhiteSpace($GraphToken)) {
    throw 'Microsoft Graph token was not supplied.'
}

$headers = @{ Authorization = "Bearer $GraphToken" }
$uri = 'https://graph.microsoft.com/v1.0/organization/{0}' -f $TenantId

$organisation = Invoke-RestMethod `
    -Method Get `
    -Uri $uri `
    -Headers $headers `
    -ErrorAction Stop

[pscustomobject]@{
    TenantId   = $organisation.id
    DisplayName = $organisation.displayName
}

If Result Property is OrganisationResult, later rules can read the safe result through {OrganisationResult}. Do not return $GraphToken or the request headers.

Validate the rule

Capture a representative non-production request and confirm each mapped property exists.
Test initial provision, a repeated provision/update, and the matching deprovision path.
Confirm the selected Microsoft connection is available on the MSOL web-service host.
Confirm a script failure produces a useful provisioning error without exposing secrets.
If using Result Property, verify its shape in the next rule before enabling dependent actions.

For the underlying MSOL request values, return to the Microsoft Online rule reference.

Choose the action​

Action parameters​

Connection keywords​

Variables available to the script​

Web-service connection​

Write the script​

Example: update Exchange mailbox attributes​

Example: call Microsoft Graph with a token​

Validate the rule​