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 replaced with what was configured in the template

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).

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.