Microsoft Sync Overview ------------------------- .. _21.4-PB1|EKB-15520: Overview .......... The VOSS Automate system interfaces and syncs with a range of Microsoft applications depending on the specific setup and use in your environment. These include: * Microsoft Entra ID/Office365 - via MS Graph API * MS Teams - via PowerShell * Exchange Online - via PowerShell .. note:: Microsoft has changed the name of Azure Active Directory to Microsoft Entra ID. There are a number of considerations to keep in mind when considering the sync setup around these applications. One consideration for all Microsoft syncs is the delete protection. The relevant macros for the Microsoft Entra ID and MS Teams syncs are: * ``PULL_SYNC_DELETE_THRESHOLD_MSTeamsOnline`` * ``PULL_SYNC_DELETE_THRESHOLD_MSGraph`` These macro settings are designed to protect against mass deletes above the configured threshold in the macro (default 10). So you can review if you want to change these values to start with (depends on churn in your environment) or adjust them later as needed based on the sync messages. For details on sync delete thresholds, also refer to: .. raw:: html Pull Sync Delete Threshold .. raw:: latex the Pull Sync Delete Threshold topic in the Advanced Configuration Guide. .. rubric:: Related Topics * .. raw:: html Introduction to Data Sync .. raw:: latex Introduction to Data Sync in the Core Feature Guide * .. raw:: latex Controlling a Data Sync with a Model Type List in the Core Feature Guide .. raw:: html Controlling a Data Sync with a Model Type List * .. raw:: html Create a Targeted Model Type List .. raw:: latex Create a Targeted Model Type List in the Core Feature Guide * .. raw:: html Model Instance Filter .. raw:: latex Model Instance Filter in the Core Feature Guide * .. raw:: html Microsoft Quick Start Guide .. raw:: latex Microsoft Quick Start Guide in the Core Feature Guide Microsoft Entra ID/Office365 .............................. This sync pulls users and licenses in from the Microsoft Entra ID instance for the tenant. This can either be the source AD or it could be synced with an on-prem AD which is the real source. A combination of sources is also possible depending on the setup. The licensing for cloud services is controlled on this user object in Microsoft Entra ID. The primary purpose of the sync with Microsoft Entra ID would be to: * Provide the user objects and details that are in the Microsoft Entra ID environment, including existing settings and licenses. * Pull in license details for the Microsoft tenant - which licenses are valid for the tenant, current available/used statistics, as well as the service plans for each License SKU. The setup of the sync and timing can depend on how much of this data is required for your environment and how often you are viewing and using the data. For instance, if you are using the Automate functionality to assign licenses to users as part of user onboarding, then the sync of users and licenses is important and needs to be timely in order to pick up new users in the system that need licenses, etc. On the other hand, if licensing is being handled outside the VOSS platform then this sync is less critical in terms of frequency. As this is a sync with basically the corporate AD, it is often best to filter down what is being synced into the system. This can be to keep the volume of users in the sync down to save load on the system, time for the sync to execute, or data security to ensure user data that is not relevant for VOSS to manage the system is not pulled in. Some common use cases for this filtering include (and sometimes a combination): * Filter users by geography - certain cities and/or countries - potentially for a limited rollout of voice services in some geographies/sites but not others. * Filter users based on O365 licensing. You can have a simple filter that only pulls in users that are licensed (with any license) or you can have a more specific filter identifying specific licenses you want to match. The "IsLicensed" field is a filterable field for MsolUser and is the easiest filter (any license); whereas building a list of license IDs and permutations is more involved, but can be useful to narrow the sync down to a specific service (for example, those with licenses related to voice services like E5, Phone System, Calling plan, etc). When contemplating this condition, consider if you are looking at managing users without a Phone System - for example, MS Exchange, MS Teams users without Phone system, etc. - in which case a specific license filter may not be appropriate. * Combination of the above - users from a certain geography with an appropriate license. These types of filters are setup via Model Instance Filters (MIFs) in the system. For more information on model instance filters and their use, see the relevant section of the documentation. The system includes some example MIFs for the scenarios outlined above. You can clone and use these MIFs and adjust as needed - including your City name(s), country name(s) or License SKU ids for instance. Before First sync '''''''''''''''''''''' If your environment has more than a few thousand users, we suggest you plan your sync strategy and not just do a full sync. You can use the guidance above to plan an approach based on the number of users you want/need to pull in and adjust the sync before you start pulling any users in. Some additional guidance includes: * You can start with a sync of Licenses only (without users) to see what licenses are in the environment and corresponding IDs and such to set up in your MIFs (if filtering by licenses). * Consider if your deployment will only include certain geographic regions and you can se tup filters for those regions (maybe even starting with a single region initially to test and finalize setup). * Then, once you have your filters in place, run the sync and you can further adjust from there as needed. MS Teams ......... This sync pulls in a wide range of elements from the MS Teams tenant to enable VOSS to provide the management of the MS Teams tenant. This includes elements like the users, resource accounts, numbers, policies, teams, and many other elements. While the sync can handle a wide range of elements, the users are typically the main focus in considering the setup of the sync. This is down to the fact that user creation and updates around capabilities related to the licensing of users in Microsoft Entra ID. For instance, a user will not appear in MS Teams at all unless they have a relevant license assigned in Microsoft Entra ID/O365. Then once that license is assigned, the users will automatically be created by Microsoft as a base user into MS Teams. So syncing those base users into VOSS Automate is the first step to then being able to enable services, assign policies, and generally manage those users in the system. .. note:: VOSS Automate syncs in all 0365 and Teams data via the default data syncs that are created when a tenant is added. No Model Type List (MTL) is applied to these default syncs, which means that VOSS Automate syncs in all supported data for the tenants, including all CSOnlineUsers, that is, both enabled and disabled users (accountEnabled=true and accountEnabled=false). Since user accounts remain in MS Teams even when licensing to MS Teams is removed from the user or the user is removed from Microsoft Entra ID/O365, syncing in all users in the default sync allows VOSS Automate to identify any numbers currently assigned to disabled subscribers. This ensures that the number inventory is accurate, and prevents assignment of duplicate numbers. In addition, the Microsoft Entra ID (M365) data syncs have *Quick Import* enabled, which improves the performance of the sync. If you wish to limit the sync to only enabled users (accountEnabled=true), you can apply a Model Instance Filter (MIF) to future syncs; that is, set up a sync with a MIF by using accountEnabled equals true as a condition. You may also consider menu filters and other configuration to separate disabled accounts from enabled accounts. As with the Microsoft Entra ID sync, again filtering might be a consideration again in setting up the MS Teams sync in your environment. As the MS Teams integration today utilizes PowerShell, there are some additional considerations for filtering and setup to ensure the syncs are optimized to be efficient and performance is acceptable. Here are some guidelines for the CsOnlineUser object sync setup: * PowerShell supports filtering on some fields. This filtering only supports the equals condition. It is most efficient to plan your filters/conditions around these fields and capabilities. This is due to the filtering happening on the Microsoft end, significantly improves the PowerShell response time and limits the amount of data being passed between the systems for processing. Syncs using these conditions will be significantly faster and consume less bandwidth. The fields that are supported by PowerShell for filtering are: * Country * UsageLocation * Department * AccountEnabled * City - this is a more of a hybrid filter - this requires filtering on the VOSS Automate end but is handled more efficiently than falling back to standard MIF implementation. So it can be used if required, but more efficient if you can stick to the fields above. If your requirements cannot be satisfied by utilizing the fields above, then you can filter on other fields on the CsOnlineUser object. This filtering is applied to the results provided by PowerShell back to the system using the PowerShell filter. So this results in the additional non-PS criteria essentially being treated as an AND criteria with the PowerShell filter. The filter is configured via the same Model Instance Filter (MIF) mechanism used for all other sync filtering. The VOSS Automate system will take the MIF and break it down to utilize in the following way: * The MIF will be checked for any criteria that uses the fields supported for PowerShell Filtering. It will build the PowerShell command and issue it using those fields as a filter. * The condition will be equals regardless of the condition set in the MIF for that field (as that is all that is supported by PowerShell). * That result is then compared against the VOSS Automate cache for users that have been added/updated/deleted. * With this resulting list of users, any further criteria from the MIF will be applied to the returned data. * conditions for these fields will be applied as configured in the MIF * this results in an AND condition between the PowerShell filter criteria and the "regular" MIF criteria. So while you can mix criteria in a MIF for less complexity and more predictable results, it is best to avoid doing that if possible. If you need to mix, then best to test this carefully for expected results. For example, consider a filter with: * filter on country (can happen in PowerShell filtering) and telephoneNumber (not in PowerShell filtering): * The first list of users from the device would be filtered based on country (PowerShell Filter) * code does the compare to see the resulting set of users that are added/updated/deleted * telephoneNumber filter is then applied. * The result of the MIF is users where country and telephone number match .. note:: Filtering by UserPrincipalName in the MIF is possible. Due to size limitations, this is implemented slightly differently in terms of capturing the list of UserPrincipalNames to filter. Some common user cases and scenarios taken individually or in combination: The criteria needs to be "equals" and multiple values can be provided - either as AND or as OR depending on the setup in the MIF. These cases can all be handled via PowerShell filtering so are the preferred use cases: * Filter users by geography - Country - pull in users from a subset of countries in the environment. * Filter users by geography - UsageLocation - similar to country to pull in users in certain UsageLocations. * Filter users by geography - city - possible but less efficient as still requires pulling all the users into VOSS then filtering by city. So best if used in conjunction with another PowerShell filter field. * Filter users by Department - pull in users assigned to certain departments. The system includes some example MIFs for these use cases that can be cloned and adjusted to meet specific needs. Some of those examples: * MSTeamsOnline-CsOnlineUser-MultipleCountry - simple MIF that provides an example of how to filter on users matching United Kingdom OR United States * MSTeamsOnline-CsOnlineUser-CountryMultipleCity - MIF that includes an example of how to filter on users matching a country and multiple cities in the country. Allowlist and Denylist considerations ...................................... For more background on allowlist and denylist data sync settings, see the Core Feature Guide topic *Allowlists and Denylists*. The system provides out-of-the-box allowlist entries for Microsoft Entra ID and Teams users to help optimize these syncs. If you need to adjust these due to specific requirements (for instance flow through provisioning requirements), then these can be adjusted. Otherwise, the out-of-the-box entries should work for most cases and will account for the fact that sync workflows for a user may not be triggered even though a change for the user was pulled in during the sync. VOSS may update these default lists from time to time during upgrades if future features/functionality require it. .. image:: /src/images/admin-menubar-new.png