Introduction to Microsoft Onboarding and Offboarding#

Onboarding#

Onboarding a Microsoft user involves adding or syncing in users to Automate from the Microsoft portal (Microsoft Entra) with the correct licenses, moving users to the correct site, and provisioning them with the correct services.

Related Topics

Onboarding Elements#

The table describes the elements relevant for onboarding Microsoft users:

Element

Description

M365 User (Msoluser)

The base anchor for the user, and typically the first element pulled into Automate for a Microsoft user. Limited update options are available for this user. Automate can update usage location and licenses, depending on how the system is set up.

Usage location

Usage location is updated completely independent from licensing, provided a value for usage location is included in a configuration template (CFT) via Quick Add Group, Subscriber from Profile, or a field display policy (FDP).

If usage location updates aren’t required (either you’re not using it or the permissions don’t allow it), then exclude it from the CFT. The LicenseAssignment permission allows usage location update. Note that the Microsoft API sets the same usage location; it says it’s updating usage location even if permissions don’t exist.

Licenses

For onboarding, Quick Add Subscriber, Subscriber from Profile, or the field display policy (FDP) honors settings in the Quick Add Group configuration template (CFT) for the M365 user. Direct licenses are applied if they’re included.

If the CFT does not include any licenses, it won’t try to apply licenses. Regardless of the license settings in the CFT, usage location can still be set. If using group licenses, this overrides any direct licenses configured in the onboarding CFTs.

Msoluser Onboarding Scenarios#

The table describes Automate’s behavior for the M365 user (Msoluser) during onboarding, depending on whether templates exist in your Quick Add Group:

Scenario

Description

No M365 template in your Quick Add Group

Used when the LicenseAssignment permission is not assigned to the application. In this case:

  • Msoluser is left untouched - usage location and license is not updated.

M365 user template exists in your Quick Add Group

  • Usage location entry:

    • Automate updates the usage location according to definition in the CFT

  • License data (LicenseAssignment permission required):

    • Automate adds any license/s defined in the CFT (direct license assignment to the user)

    • Any existing licenses the user has (direct) are maintained

MS Group Add template exists in your Quick Add Group

Used to add group memberships to the user/s (for licensing or other purposes). The user is assigned to the group/s in the CFT, in addition to any existing group memberships the user has.

Common Onboarding Scenarios and Setup#

The table describes example common onboarding scenarios and the setup required, whether using Quick Add Subscriber, Subscriber from Profile, or a field display policy (FDPs):

Example onboard scenario

Setup

No update to Msoluser at all (usage location and/or licenses)

Do NOT include a M365 template in the Quick Add Group.

Update usage location, no license update

  • Include a M365 CFT in your QAG. The CFT must include the usage location logic you require (for example, macro from site default, etc).

  • Leave the license fields blank in the CFT.

Update usage location, and update license (direct licensing)

Include a M365 CFT in your Quick Add Group that includes the usage location logic and licenses you require (e.g. macro from site default, etc).

Update usage location and group assignment (for license or other purposes)

  • Include a M365 CFT in your Quick Add Group that includes the usage location logic you require (e.g. macro from site default, etc.)

  • Include a Add Group CFT in your Quick Add Group that includes the groups you wish to add to the user.

Offboarding#

Offboarding of Microsoft users in Automate is the process whereby the user is de-provisioned (their services are removed), and they’re moved back to the customer level. When offboarding, the user’s Usage Location remains unchanged. Since Automate doesn’t automatically manage user licenses (you’ll need to grant Automate permissions to do this for Microsoft user licensing), the users licenses remain in place when offboarded unless Automate has license management permissions.

Note

When offboarding and moving a user from the site back to the customer level, if that user had a Self-service role at the site, their Self-service role is retained when they move to the customer level and this Self-service role is retained if you later move that user to another site.

Related Topics

Offboarding Workflow#

The Microsoft Quick offboard subscriber (QOS) workflow is as follows:

  • The number assigned to the user in Microsoft Teams is removed and Enterprise Voice is disabled.

    Any other setting defined in the Teams configuration template (CFT) in the Quick Add Group, such as policies, are applied.

  • The number is released in the Automate number inventory, and is either made available or placed into cooling, depending on your setup.

  • M365 user (Msoluser) is updated based on configuration:

    Licenses

    • (Default) Remove licenses

      The default behavior is that all licenses are removed from the user. The LicenseAssignment permission is required in the system. If this permission is unavailable, the transaction ignores the error from Microsoft and continues to execute but leaves the licenses unchanged.

    • (Recommended) Leave licenses as is

      You’ll need to configure Automate to leave the licenses unchanged if you don’t wish to manage licenses. See the note below. It is recommended that you configure this behavior rather than relying on the default behavior (Remove licenses).

    Remove from group(s)

    This behavior is based on the Remove Groups configuration template included in the Quick Add Group.

  • Move the user and related Microsoft service records (Msoluser, Csonlineuser, Exchange, etc.) back to the tenant level in the hierarchy (typically, customer).

    The user’s role is also updated to a Self-service role at that level in the hierarchy. The user is then ready for onboarding again if needed (for example, in another site).

Common Offboarding Scenarios and Setup#

The table describes example common offoarding scenarios and the setup required when using Quick Offboard Subscriber:

Example onboard scenario

Setup

No update to Msoluser at all (usage location and/or licenses)

To set this up, see the section headed Configuration to not remove licenses

Remove licenses (direct licensing)

System default behavior, so no additional configuration required.

Remove licenses via removal of group/s

To set this up, see the section headed Adjusting the Quick Add Group for offboarding for the steps to include a Remove Group CFT in your Quick Add Group that includes the group(s) you need to remove from the user.

Configuration to not remove licenses#

If you don’t want to remove licenses from users during the Quick Offboard process, then apply the following configuration in Automate:

  • Use the MicrosoftSubscriberMsolUser_Update configuration template (CFT) to configure license handling.

  • By default, Automate attempts to remove all licenses assigned to the user. To change this behavior, clone the MicrosoftSubscriberMsolUser_Update CFT to a lower level in the hierarchy (the hierarchy where you want to change the default behavior). For example:

    • Clone the CFT to Provider level if you want to apply it everywhere

    • Clone the CFT to a particular Customer level (if it’s customer-specific)

    Note

    • Clone the CFT in the Automate Admin portal without making any changes to it.

    • Ensure the cloned CFT name is not changed.

    • After cloning the CFT, the licenses array in the CFT should be blank. If it’s not blank for some reason, clear the licenses array in the cloned CFT before saving it.

    • To change back to the default behavior to clear the licenses, you can delete the cloned CFT to return to the sys level instance of the CFT.

      Note

      While the sys level CFT appears to have no license value in the CFT when viewing via the Admin portal, it actually does have a value (pwf.licenses). To see this value, you can export the CFT. However, when you clone the CFt to the lower level, this value is not part of the clone and the license value will be blank.

Adjusting the Quick Add Group for offboarding#

Automate ships with a default Quick Add Group (System Quick Add Group Un License User) for the Quick Offboard Subscriber process.

You can clone this Quick Add Group to a lower level in the system and change the Teams CFT in order to manipulate what it does. This allows the Teams CFT to update policies - for example, to reset from assigned policies to a set of default policies for non-voice users. If you want to just remove the number and disable Enterprise Voice, you won’t need to do this as this will happen by default.

Note

The M365 user template from the Quick Add Group is not used in the Quick Offboard Subscriber workflow, so this won’t impact the behavior regardless of how it is set.

Subscriber updates when offboarding#

With regard to subscriber updates in terms of usage location and licenses when offboarding, similar to onboarding, the LicenseAssignment permission is required to update the Usage Location and License fields via the Subscriber page.

If permissions aren’t granted and you’re using direct licenses, it is recommended that you adjust your field display policy (FDP) for relation/MicrosoftSubscriber to make the Usage Location and License fields read-only for clarity to administrators.

Note

If you follow the steps in Quick Offboard to retain licenses on the user, any changes to licenses via the subscriber won’t be applied. This is for the case where you won’t be managing licenses from Automate.

License Management when Onboarding and Offboarding#

Automate requires the LicenseAssignment permission to manage Microsoft licenses.

To avoid system errors, it is recommended that you do not use the Msoluser device model (device/msgraph/msoluser) to make changes, particularly when license permissions aren’t assigned. Instead, it is recommended that you use relation/MicrosoftSubscriber or other Automate functionality to update users.

If a user has any group assigned license, Automate won’t attempt any direct license assignment at all, via onboarding or via relation/MicrosoftSubscriber updates, regardless of what may be included in Automate configuration templates or in the Microsoft portal.

When offboarding, if Automate is set up to remove a user’s direct licenses, this is only possible when Automate is also removing all the license groups. If any license group remains, the direct licenses aren’t removed. For example, if a user has base licenses (for example, E3) assigned via group, and you want VOSS Automate to add MCOEV as a direct license, this won’t be possible. In this case, it is only possible to add the MCOEV license via a group license assignment, since it is possible to assign or remove additional groups.

The group license assignment during onboarding and offboarding is not only used for licenses, so it can be used to add or remove non-license groups together with direct licensing, or for no licensing, as needed.

Move a User Between Sites Using Offboard and Onboard#

To move a user between sites in Automate, the recommended approach is to offboard the user from a voice perspective, then onboard the user in the new site. Moving the user in this way allows the user to be assigned a new number and updated policies, for example, emergency, from the new site.

To move a user between sites:

  1. Run Quick Offboard Subscriber for the subscriber that needs to be moved.

    • The subscriber’s existing voice configuration is removed, and if configured, their licenses are left in place. Other services aren’t impacted.

    • The user and their related services are moved back to the customer level, ready to be onboarded in the new site.

  2. Onboard the user into the new site, using your typical process - for example, Subscriber from Profile, or Quick Add Subscriber.

    The user is moved to the new site with the correct voice services for the new site.

Note

You can follow this workflow even if the user is going to be keeping the same number. If the number sits at a level available to the new site (for example, customer or intermediate node), then no additional step is required.

If the number sits in the inventory in the old site (the site the user is moved from), you’ll need to move the number in the inventory to either a shared level, such as customer, or to the new site, before running the onboarding step above.