Office 365 Adapter Actions

Office 365 Adapter Actions

These actions use the Microsoft Graph API

For reference, a complete list of filterable attributes can be found here.

addOffice365DistributionGroupMember

Add a member to an Office 365 DistributionGroup

added = addOffice365DistributionGroupMember(session, "testgroup", "johndoe@example.com")

addOffice365MsolGroupMember

Add a member to an Office 365 MsolGroup

added = addOffice365MsolGroupMember(session, "testgroup@example.com", "johndoe@example.com")

• For details regarding the New-MgGroupMember API syntax and field reference, click here

addOffice365MsolRoleMember

Add a member to an Office 365 MsolRole

filter = createRecord()
setRecordFieldValue(filter, "RoleName" "User Account Administrator")
roles = getOffice365MsolRoles(session, filter, 1)
added = addOffice365MsolGroupMember(session, roles[0].ObjectId, "johndoe@example.com")

• For details regarding the New-MgDirectoryRoleMemberByRef API syntax and field reference, click here

addOffice365SPOSiteGroupMember

Add a member to an Office 365 SharePoint Online Site Group

added = addOffice365SPOSiteGroupMember(session, "https://example.sharepoint.com/", "MySiteGroup", "JohnDoe@example.com")

deleteOffice365DistributionGroup

Delete an Office 365 DistributionGroup record by Id.

deleted = deleteOffice365DistributionGroup(session, "testgroup")

deleteOffice365DistributionGroupMember

Delete a member from an Office 365 DistributionGroup.

removed = deleteOffice365DistributionGroupMember(session, "testgroup@example.com", "jdoe@example.com")

deleteOffice365Mailbox

Delete an Office 365 Mailbox record by Id.

deleted = deleteOffice365Mailbox(session, "jdoe@example.com")

deleteOffice365MailContact

Delete an Office 365 MailContact record by Id.

deleted = deleteOffice365MailContact(session, "testContact")

deleteOffice365MailUser

Delete an Office 365 MailUser record by Id.

deleted = deleteOffice365MailUser(session, "testMailUser@example.com")

deleteOffice365MsolGroup

Delete an Office 365 MsolGroup record by Id.

deleted = deleteOffice365MsolGroup(session, "testgroup@example.com")

• For details regarding the Remove-MgGroup API syntax and field reference, click here

deleteOffice365MsolGroupMember

Delete a member from an Office 365 MsolGroup.

deleted = deleteOffice365MsolGroupMember(session, "testgroup@example.com", "jdoe@example.com")

• For details regarding the Remove-MgGroupMemberByRef API syntax and field reference, click here

deleteOffice365MsolRoleMember

Delete a member from an Office 365 MsolRole.

filter = createRecord()
setRecordFieldValue(filter, "RoleName" "User Account Administrator")
roles = getOffice365MsolRoles(session, filter, 1)
deleted = deleteOffice365MsolGroupMember(session, roles[0].ObjectId, "jdoe@example.com")

• For details regarding the Remove-MgDirectoryRoleMemberByRef API syntax and field reference, click here

deleteOffice365MsolUser

Delete an Office 365 MsolUser record by Id.

deleted = deleteOffice365MsolUser(session, "jdoe@example.com")

For details regarding the Remove-MgUser API syntax and field reference, click here

deleteOffice365SPOSiteGroup

Delete an Office 365 SharePoint Online Site Group record by Id.

deleted = deleteOffice365SPOSiteGroup(session, "https://example.sharepoint.com/", "MySiteGroup")

deleteOffice365SPOSiteGroupMember

Delete a member from an Office 365 SharePoint Online Site Group.

deleted = deleteOffice365SPOSiteGroupMember(session, "https://example.sharepoint.com/", "MySiteGroup", "jdoe@example.com")

getOffice365DistributionGroup

Get an Office 365 DistributionGroup record by Id.

distGroup = getOffice365DistributionGroup(session, "testgroup")

getOffice365DistributionGroups

Get Office 365 DistributionGroup records.

filter = createRecord()
setRecordFieldValue(filter, "GroupType", "SecurityEnabled")
mailboxes = getOffice365DistributionGroups(session, filter, 50)

getOffice365Mailbox

Get an Office 365 Mailbox record by Identity.

mailbox = getOffice365Mailbox(session, "jdoe@example.com")

getOffice365Mailboxes

Get Office 365 Mailbox records.

filter = createRecord()
setRecordFieldValue(filter, "LastName", "Doe")
setRecordFieldValue(filter, "FirstName", "John")

mailboxes = getOffice365Mailboxes(session, filter, 2)

getOffice365MailContact
Get an Office 365 MailContact record by Id.

contact = getOffice365MailContact(session, "testContact")

getOffice365MailContacts

Get Office 365 MailContact records.

filter = createRecord()
setRecordFieldValue(filter, "LastName", "Doe")
setRecordFieldValue(filter, "FirstName", "John")
mailboxes = getOffice365MailContacts(session, filter, 2)

getOffice365MailUser

Get an Office 365 MailUser record by Id.

mailUser = getOffice365MailUser(session, "testMailUser")

getOffice365MailUsers

Get Office 365 MailUser records.

filter = createRecord()
setRecordFieldValue(filter, "LastName", "Doe")
setRecordFieldValue(filter, "FirstName", "John")
mailboxes = getOffice365MailUsers(session, filter, 2)

getOffice365MsolGroup

Get an Office 365 MsolGroup record by Id.

filter = createRecord() setRecordFieldValue(filter, "GroupType", "Security") mailboxes = getOffice365MsolGroups(session, filter, 50)

For details regarding the Get-MgGroup API syntax and field reference, click here

Recent Changes:

• The “Identity”/”DisplayName” field was used as the unique identifier for Microsoft Online, but the “Id” field is used by Microsoft Graph. The Exchange Agent will automatically handle this change when retrieving a specific group (i.e. A group can be found by providing either “DisplayName” or “Id”).
• The “Identity” field will no longer be returned on the group objects. If the value is needed in Connect logic, utilize “DisplayName” or “Id” instead.
• The “Id” field is now returned by group objects and should be used to reference groups

getOffice365MsolGroups

Get Office 365 MsolGroup records.

filter = createRecord()
setRecordFieldValue(filter, "GroupType", "Security")
mailboxes = getOffice365MsolGroups(session, filter, 50)

For details regarding the Get-MgGroup API syntax and field reference, click here

Recent Changes:

• The “Identity” field will no longer be returned on the group objects. If the value is needed in Connect logic, utilize “DisplayName” or “Id” instead.
• The “Id” field is now returned by group objects and should be used to reference groups

Filter Changes

• Careful consideration should be taken when updating Connect action sets utilizing the optional filter parameter. Microsoft provides documentation for using filters

getOffice365MsolRole

Get an Office 365 MsolRole record by Id.

role = getOffice365MsolRole(session, "fe930be7-5e62-47db-91af-98c3a49a38b1")

​For details regarding the Get-MgDirectoryRole API syntax and field reference, click here

Notes:

• You may find that not all roles returned from Get-MsolRole are returned by Get-MgDirectoryRole. If this is the case, look at the “Import MsolRoles to MgDirectoryRoles” section for reference.

getOffice365MsolRoles

Get Office 365 MsolRole records.

filter = createRecord()
setRecordFieldValue(filter, "RoleName" "User Account Administrator")
roles = getOffice365MsolRoles(session, filter, 1)

For details regarding the Get-MgDirectoryRole API syntax and field reference, click here

getOffice365MsolUser

Get an Office 365 MsolUser record by Identity.

user = getOffice365MsolUser(session, "jdoe@example.com")

For details regarding the Get-MgUser API syntax and field reference, click here

getOffice365MsolUsers

Get Office 365 MsolUser records.

filter = createRecord()
setRecordFieldValue(filter, 'Filter', 'startsWith(DisplayName, "Mi")')
users = getOffice365MsolUsers(session, filter, 200)

For details regarding the Get-MgUser API syntax and field reference, click here

Notes:

• Careful consideration should be taken when updating Connect action sets utilizing the optional filter parameter. Microsoft provides documentation for using filters.

getOffice365SPOSiteGroup

Get an Office 365 SharePoint Online Site Group record by Id.

siteGroup = getOffice365SPOSiteGroup(session, "https://example.sharepoint.com/", "MySiteGroup")

getOffice365SPOSiteGroups

Get Office 365 SharePoint Online Site Group records.

siteGroups = getOffice365SPOSiteGroups(session, "https://example.sharepoint.com/", 50)

openOffice365Connection

Open a connection to Office 365.

Global.office365URL = "https://10.10.10.10/idautoExchangeAdminWS"
Global.office365User = "office365admin@example.net"
Global.office365Pwd = <Password>
session = openOffice365Connection(Global.office365URL,Global.office365User, Global.office365Pwd)

purgeOffice365UserRecycleBin

Purge deleted users from Office 365 Recycle Bin.

purgeOffice365UserRecycleBin(session)

saveOffice365DistributionGroup

Create/Update an Office 365 DistributionGroup record.

groupTemplate = createRecord(, )
setRecordFieldValue(groupTemplate, "Name", "testgroup")
saveOffice365DistributionGroup(session, groupTemplate)

saveOffice365Mailbox

Create/Update an Office 365 Mailbox record.

mailboxTemplate = createRecord()
setRecordFieldValue(mailboxTemplate, "Name", "JDoe")
setRecordFieldValue(mailboxTemplate, "Password",Password>)
setRecordFieldValue(mailboxTemplate, "MicrosoftOnlineServicesID", johndoe@example.com")
mailbox = saveOffice365Mailbox(session, mailboxTemplate)

saveOffice365MailContact

Create/Update an Office 365 MailContact record.

contactTemplate = createRecord()
setRecordFieldValue(contactTemplate, "Name", "testContact")
setRecordFieldValue(contactTemplate, "ExternalEmailAddress", "testContact@example.com")
contact = saveOffice365MailContact(session, contactTemplate)

saveOffice365MailUser

Create/Update an Office 365 MailUser record.

mailUserTemplate = createRecord()
setRecordFieldValue(mailUserTemplate, "EmailAddresses", "testMailUser@example.org")
mailUser = saveOffice365MailUser(session, mailUserTemplate)

saveOffice365MsolGroup

Create/Update an Office 365 MsolGroup record.

groupTemplate = createRecord()
setRecordFieldValue(groupTemplate, "DisplayName", "testGroup")
group = saveOffice365MsolGroup(session, groupTemplate)

• For details regarding the New-MgGroup API syntax and field reference, click here
• For details regarding the Update-MgGroup API syntax and field reference, click here

Recent Changes

New Group Fields

• DisplayName
  • It’s unlikely that groups were being created without the “DisplayName” field, but it was not required with Microsoft Online and is required by Microsoft Graph
• MailNickname
  • This is a new field in Microsoft Graph. The Exchange Agent will set the “MailNickname” field to the “DisplayName” value if it is not specified.
• MailEnabled
  • This is a new field in Microsoft Graph. The Exchange Agent will set the “MailEnabled” field to “false” if not specified.
• SecurityEnabled
  • This is a new field in Microsoft Graph. The Exchange Agent will set the “MailEnabled” field to “true” if not specified.

Notes:

• Special consideration should be taken when updating the “DisplayName” for a group (i.e. may also want to consider updating “MailNickname”).
  • See bullet point above regarding “MailNickname” not being specified on group create

saveOffice365MsolUser

Create/Update an Office 365 MsolUser record.

userTemplate = createRecord()
setRecordFieldValue(userTemplate, "GivenName","Homer"
setRecordFieldValue(userTemplate, "Surname", "Simpson"
setRecordFieldValue(userTemplate, "DisplayName", "Homey")
setRecordFieldValue(userTemplate, "Password",<//Password//>)
setRecordFieldValue(userTemplate, "FaxNumber", "555-call-homr")
setRecordFieldValue(userTemplate, "OfficeLocation", "Power Plant")
setRecordFieldValue(userTemplate, "UserPrincipleName", "Homey@" + testDomain)
setRecordFieldValue(userTemplate, "UsageLocation", "US")
setRecordFieldValue(userTemplate, "LicenseAssignment", "mydomain:ENTERPRISEPACK")
msolUser = saveOffice365MsolUser(session, userTemplate)

For details regarding the New-MgUser API syntax and field reference, click here
For details regarding the Update-MgUser API syntax and field reference, click here

Recent Changes:

New User Fields

• AccountEnabled
  • This is a new field in Microsoft Graph. The Exchange Agent will set the “AccountEnabled” field to “true” if not specified.
• MailNickname
  • This is a new field in Microsoft Graph. The Exchange Agent will set the “MailNickname” field to the “DisplayName” value if it is not specified.
• Password
  • If you create users without a password, you will need to update your Connect logic to supply a random password. Microsoft Online would automatically generate a random password when creating users without “Password” specified, but this is not the case with Microsoft Graph.

User Field Changes

• “FirstName” will be “GivenName”
• “LastName” is now “Surname”
• “Fax” is now “FaxNumber"
• “Office” is now “OfficeLocation”

Notes:

• Special consideration should be taken when updating the “DisplayName” for a user (i.e. may also want to consider updating “MailNickname”).
  • See bullet point above regarding “MailNickname” not being specified on user create
• The “LicenseOptions” field will no longer accept an “AccountSkuId” in its JSON objects. Instead, it will accept “SkuId” or “SkuPartNumber”.
  • “LicenseOptions” are used for disabling specific plans within a license (e.g. “[{“SkuId”:”SkuId1”,”DisabledPlans”:[“YAMMER_ENTERPRISE”]}]”)

saveOffice365SPOSiteGroup

Create/Update an Office 365 SharePoint Online Site Group record.

Import MsolRoles to MgDirectoryRoles

The following PowerShell script provides an example of how to import MSOL roles into Microsoft Graph. Run this in an Administrator PowerShell on the Windows machine where the Exchange Agent is installed with the appropriate credentials.

> $user = "admin_user@domain.onmicrosoft.com"
> $password = ConvertTo-SecureString 'password123' -AsPlainText -Force
> $basicCred = New-Object System.Management.Automation.PsCredential($user,$password)
> Connect-MsolService -Credential $basicCred
> $appId = "<azure_app_id>"
> $tenantId = "<azure_tenant_id>"
> $certThumbprint = "<cert_thumbprint>"
> $certPath = 'Cert:\LocalMachine\My\' + $certThumbprint
> $cert = Get-ChildItem -Path $certPath
> Connect-MgGraph -ClientId $appId -TenantId $tenantId -Certificate $cert
> Get-MsolRole | ForEach-Object {
    $template = (Get-MgDirectoryRoleTemplate -DirectoryRoleTemplateId $_.ObjectId)
    if ($template -ne $null) {
   	 $filter = "RoleTemplateId eq '" + $template.Id + "'"
   	 $role = Get-MgDirectoryRole -Filter $filter
   	 if ($role -eq $null) {
   		 New-MgDirectoryRole -RoleTemplateId $role.Id
   	 }
    }

Important Notes

• Office 365 supports a new higher-level management object, MsolUser, that should be preferred to managing users via the Mailbox object.
• While a Mailbox can still be created directly, the corresponding MsolUser must be assigned a license or the Mailbox will be disabled after a grace period.
  • The corresponding MsolUser is not available immediately (probably due to AD replication latency) so immediately trying to add a license after creating a Mailbox directly will usually fail.
  • Creating a Mailbox directly requires the field MicrosoftOnlineServicesID as opposed to WindowsLiveID (Live@EDU) or UserPrincipalName (Exchange).
• After a MsolUser is created and assigned an appropriate license, a Mailbox will be automatically created after some delay.
• While an initial password can still be set when creating a Mailbox, subsequent password changes can only be made to the MsolUser.
• Setting the initial password on a MsolUser uses the Password field, but subsequent password changes can use either the Password or NewPassword field.
• Licenses can be added on the initial creation of MsolUser using the LicenseAssignment field. Subsequent addition or removal of licenses use the AddLicenses or RemoveLicense field. In either case, assigning a license will fail if the UsageLocation field has not been set.
• The licenses available for assignment for a particular domain can be determined by going to the server hosting the Exchange agent and opening the “Microsoft Online Services Module for Windows PowerShell” from the desktop. Then run the following commands:

  Connect-MsolService -Credential ( Get-Credential )
  (Get-MsolAccountSku).AccountSkuid
  

• You can disable specific applications that would normally be enabled by a license using the LicenseOptions field. The LicenseOptions field is a record that has two fields: AccountSkuID, which is the name of the license; and DisabledPlans, which is an array of the names of specific modules to be disabled for the user. The names of the modules that are available within a given license can be determined by going to the server hosting the Exchange agent and opening the “Microsoft Online Services Module for Windows PowerShell” from the desktop. Then run the following commands:

  Connect-MsolService -Credential ( Get-Credential )
  forEach ( $sku in Get-MsolAccountSku) {
  echo $sku;
  forEach ( $service in $sku.ServiceStatus) {
  echo $service.ServicePlan.ServiceName}
  }
  

• Creating a MsolGroup will create a security group (as opposed to a distribution group), after initial creation, MsolGroup can be used for listing or adding/removing members from both security and distribution groups.
• There is a timing issue with user creation on the Office 365 backend. We are recommending that you not set Location, Time Zone, or Language at user creation time. If you wish to set these attributes you should update them in a later action.