How to Extend Automation of Microsoft Online Services

How to Extend Automation of Microsoft Online Services


Since version 12.0, Atria has provided the capability to allow easy management of Azure AD and User-based subscriptions (such as Microsoft 365 and Office 365).  As a CSP provider operating at scale, you may have additional configuration changes you want to make via the many APIs available but the complexity of the Secure Application Model has made this difficult to implement. 

With Atria 12.6.7 we have introduced new Powershell actions which give you the ability to extend our default provisioning processes to meet your own needs, as well as giving you the ability to build your own services using Atria custom services.  The key benefit is that these actions set your Powershell connection up with the right security context needed to perform actions for the tenant or user.  

This allows you to easily use the PartnerCenter connection configured in Atria using the Secure Application Model.  

In order to use any of these actions in any provisioning rules, you must have the Azure AD service provisioned to the customer.

Key benefits
  1. Enables execution of custom PowerShell scripts when provisioning tenants or users
  2. Connection to Powershell providers handled seamlessly by Atria using the secure application model.
  3. Rapidly build custom services to systematically deliver your own Microsoft 365 based services

How it works

There are two actions provided for your use – one for Customer/Tenant context (MSOL Run Customer Script) and one for user context (MSOL Run User Script)
Both are similar – the latter, just adds the user-specific parameters.

Currently, we can provide the correct context for executing the following API Connections:



Use for


Azure Active Directory Powershell 2.0

Azure AD management


Exchange Online Powershell

Exchange configuration (uses Exchange online v1 Powershell)


Microsoft Graph

Provides graph token variable with an access token to allow you to send https requests to Microsoft Graph.


MS Online V1 Powershell module for Azure Active Directory

Older Powershell library for managing AzureAD and Office 365


Microsoft PartnerCenter Powershell

For managing subscriptions, billing, customer details within PartnerCenter


Office 365 Security and Compliance

Security and Compliance Configuration.

Action Parameters

When creating provisioning rules, select one of the new MSOL Run actions.

CustomerID Parameter

The CustomerID is available on all provisioning requests and refers to the Atria numeric identified for the customer.  Use the {CustomerId} variable to refer to the CustomerID in the current request.

UserID Parameter

The UserID is available on all user-related provisioning requests and refers to the Atria numeric identified for the User.  Use the {UserID } variable to refer to the UserID in the current request.
Note: that this parameter is only available on the MSOL Run User Script action.

Connect Parameter

Options are AzureAD, Exchange, Graph, MSOnline, PartnerCenter, SecurityCenter (see above list for details) 
Provide one or more of the above as a comma-separated list to the connect Action parameter.  Atria will set up the connection and your script should just assume this is in place.
There are a few variables available to you without needing to pass them in:

ScriptFile Parameter

This is the location of your AD script.  The script is executed from the Atria MSOL Web Service, so the path to this script has to be accessible and available from the machine where this service is running.


This specifies the details needed to connect the MSOL web service.  This is contained as a parameter in the provisioning request for the Microsoft Online or AzureAD services.  
If you are creating your own service, the webServiceConnection will not be available in the context of your request.  You can use the MSOL Add WebService Connection action to retrieve the correct connection details and add them to your provisioning request.

This action will only work in the primary location as it queries the Atria database to extract the connection data.  Add rules that use this action and communicate with the Microsoft Online service into the pre-request section of your provisioning rules.



This specifies the property for any data you wish to return to the provisioning request from the script.


Specifies the timeout in seconds to use when performing operations against APIs.  

Optional Parameters

Use optional parameters to pass information from the provisioning request into your script.  To add parameters, increase the Optional Parameters property.

Note the Syntax, this is configuring the PowerShell variables in your script.  Each of the $variables defined can be used in your script.  
These parameters are passed by value, any changes made, will not be reflected in the request variables after the action has executed. 

Additional variables available within your script

The following variables are available for use within your script by default – you do not need to pass them in as optional parameters.

Variable Name





A reference to the Atria CustomerID (primary key of customers table)


When tenant exists in Azure AD

The Microsoft AzureAD globally unique tenantID  (GUID)



The Atria numeric UserID (primary key of users table)


When user exists in Azure AD

The GUID of the user in Azure AD


When Exchange has been specified as a connect option

Holds the connection to the Exchange Remote Powershell session.


When Graph has been specified as a connect option

Holds an access token for Microsoft Graph.


When SecurityCenter has been specified as a connect option

Holds the PowerShell Session connection to the Security and Compliance Endpoint.

Writing your script

All environments are logged in to the tenant, except MSOnline, this runs in the partner context and you will need to pass –TenantId $TenantId to the commandlets to have them run in the context of the customer.
Note that when you attach to provisioning events, their system does not differentiate between a create (the first execution) and an update (any subsequent execution), as such you need to ensure that your script can be re-executed and caters for any objects which may have already been created by a previous execution of the script.  

Where to locate your rules

As the Microsoft Online Service is always interacting with Microsoft services, this is always deployed in the primary Atria location.  Any provisioning rules are best placed in the “Post” provisioning sections.

For your own custom services – place your rules in the “Main” section.

If you are adding processes to an existing service, place your rules in the “Before” or “After" section

Remember that all the variables within the request are available for you to feed in to your Powershell scripts.

Usage Notes and Examples

Getting the connection to the Web Service

In order to execute any PowerShell commands we have to get a connection to the MSOL Web Service.  Add a rule to run the “MSOL Add WebService Connection” action – this will locate the correct connection details and add it for subsequent use.

The rule below will store the connection details in the msolws variable.  

This step is required for all of the examples in this document.

Azure Active Directory (AzureAD)

In this example, we are creating an Azure AD Security group.  

Script : CreateAADSecurityGroup2.ps1

  1. $group = Get-AzureADGroup -SearchString $groupName
  3. if ($group -eq $null) {
  4.     #Create a new security group for the tenant
  5.     New-AzureADGroup -DisplayName $groupName -MailEnabled $false -SecurityEnabled $true -MailNickName "NotSet"
  6. }

Adding the rule to call the script – the groupName is passed in and the AzureAD connection type is specified.  The script is parameterised but in this case we are hard coding the group name to “Senior Management”.  If you wanted to pass in a variable from the request, you would set the variables field to $groupName = {RequestParameter} 

Exchange Online (Exchange)

This example creates an Exchange Transport Rule to prepend all external email with a highlighted block of text  “[Warning - this email was received from an External sender!]”
Note the Invoke-command used with the $Session variable to execute the contained script within the context of the session which Atria has automatically set up within the correct context for the tenant specified in the action parameter.

SetExternalEmailTransportRules.ps1 (stored on the same server as the MSOL Web Service)

  1. #Create mail flow rule for adding External warning message for external mails
  3. Invoke-Command -Session $Session -ScriptBlock {
  5. $Disclaimer = "<p><div style='border:solid #9C6500 1.0pt;padding:2.0pt 2.0pt 2.0pt 2.0pt'><p class=MsoNormal style='line-height:12.0pt;background:#FFEB9C'> <b><span style='font-size:10.0pt;color:#9C6500'></span></b><span style='font-size:10.0pt;color:black'> [Warning - this email was received from an External sender!]<o:p></o:p></span></p>"
  7. $RuleExists = false
  8.     try { $tr = Get-TransportRule "External Email Warning"
  9.           $RuleExists = true }
  10.     catch
  11.         { $RuleExists = false }
  13.     # If the rule exists, then update it, else create the rule
  14.     if ($RuleExists)
  15. {
  16.          #update transport rule
  17.          Set-TransportRule "(Atria) External Email Warning" `
  18. -FromScope NotInOrganization `
  19.                     -SentToScope InOrganization -Priority 0 `
  20. -ApplyHtmlDisclaimerText $Disclaimer `
  21.                     -ApplyHtmlDisclaimerLocation Prepend `
  22. -ApplyHtmlDisclaimerFallbackAction Wrap
  24.         }
  25.     else {
  26.          #create new transport rule
  27.          New-TransportRule "(Atria) External Email Warning" `
  28. -FromScope NotInOrganization `
  29.                     -SentToScope InOrganization -Priority 0 `
  30. -ApplyHtmlDisclaimerText $Disclaimer `
  31.                     -ApplyHtmlDisclaimerLocation Prepend `
  32. -ApplyHtmlDisclaimerFallbackAction Wrap
  33.         }

The rules to be added are as follows:

The second rule executes the script – we specify the {customerid} which is available in the request and use the msolws variable we added to the request in the prior step.
We need to connect to Exchange Online Powershell so we specify “Exchange” for the connect parameter.
The scriptFile refers to the script, the path must be resolvable in the context of the Microsoft online web service.  

Microsoft Graph (Graph)

Microsoft Graph is becoming the foundation for easy integration with Microsoft services, Graph has a restful API which can be easily invoked from within Powershell to both extract data and perform changes.
Microsoft Graph has an advanced permissions system, the Atria application must be granted the correct permissions in order to execute the Graph query/command.  You may need to add additional permissions in order to execute your scripts.  

Example script – the Graph URI is passed as the $ResourceURI parameter

  1. $HeaderParams = @{
  2.             'Content-Type'  = "application\json"
  3.             'Authorization' = "Bearer $GraphToken"
  4.             }
  5. $Results = Invoke-RestMethod `
  6. -Headers $HeaderParams `
  7. -Uri
    $ResourceURI `
  8. -UseBasicParsing `
  9. -Method "GET" -ContentType "application/json"
  10. Return

Microsoft Online PowerShell (MSOnline)

This runs in the context of the partner – you will need to ensure that you add the –TenantID $TenantID parameter to all commandlets in your script to ensure they act on behalf of the correct customer!

In this example, we have written a simple script that will create an Azure AD security group using the MSOL Powershell library. 

Script : CreateAADSecurityGroup.ps1

  1. $group = Get-MsolGroup -SearchString $groupName
  3. if ($group -eq $null)
  4. {
  5.     #Create a new security group called Senior Management for the tenant
  6.     New-MsolGroup -DisplayName $groupName -TenantId $TenantID
  7. }

The rule we have added is also dependent on the msolws

With this group being created, You could pass this into another that retrieves the members of this group, using the Msol User Run Script, and example of this is below.

  1. $group = get-msolgroup -searchstring $groupName -TenantId $TenantID
  2. if($group){
  3.     #Group Exists, continue
  4. }
  5. Else{
  6.     throw ‘Specified Group does not exist’
  7. }

  8. #Get Group from AzureAD
  9. $user = Get-MsolGroupMember -GroupObjectId $group.objectID -TenantId $tenantId
  10. if($Users -eq $null)
  11. {
  12.     Return ‘Group has no members’
  13. }
  14. #If user isn't in group, add them to MFA Enable Group
  15. else{
  16. Return $Users
  17. }


Connecting to multiple services

You can connect to multiple services if needed. So if you have one large script that talks to multiple Powershell interfaces, you can comma separate the providers you need on the connect parameter of the rule.

    • Related Articles

    • Microsoft Online Service Planning

      Overview The Microsoft Online Service for Atria allows Customers and the service desk to manage tenants, licenses, users and features of Office 365 – with no access to the 365 admin portal. It reduces your risk, while still being able to effectively ...
    • Connecting Atria to Microsoft Partner Center

      As of October 2023, Microsoft no longer supports DAP. We have updated the scripts within the platform as of 15.16 to create new GDAP level permissions. Please see below for more information. Objective This article shows you how to set up a secure ...
    • Microsoft Online Group Management in Atria

      Introduction to Group Management Groups are a fundamental feature used to control access and make information sharing easier.  In the Microsoft 365 platform, there are four core group types, all of which have a core component in Azure AD.  Many ...
    • Microsoft Online - How to configure your Customer plan

      Overview The Microsoft Online service within Atria has been designed from the Ground Up with Customization and flexibility in mind. This means, that it can likely cater with most configuration scenarios you may come across with Microsoft Online ...
    • Microsoft Online - Purchase a new Subscription

      Overview Within Atria, you are able to quickly navigate to a customer and purchase a new Microsoft 365 Subscriptions based on what is configured within the Catalog. This enables you to quickly purchase licenses to be able to allocate to users, or ...