.. _data-sync: Introduction to data sync --------------------------- .. _18.1.2|DOC-225: .. _21.3-PB3|EKB-12810: .. _21.4-PB1|EKB-14443: .. _21.4-PB4|EKB-16845: .. _24.1-PB1|EKB-21084: .. _24.2-PB2|VOSS-1493: .. _25.2|VOSS-1445: .. tip:: :ref:`use-action-search-to-navigate-automate` Overview ............ Data syncs can be performed from within VOSS or directly on a device. For this reason, cached VOSS data should be periodically synced with data on devices. Examples: * When an instance of a Cisco UCM is added to the system, its data is imported and cached. * When instances are added, updated, or deleted from the Cisco UCM, the cached data in VOSS becomes out of sync with data on the device. * When deleting data from Cisco UCM before deleting it from VOSS, the system displays the following error: "The specified resource could not be found" This means the resource is out of sync, and VOSS may need to re-sync with Cisco UCM in order to delete it or update it. VOSS data syncs allow you to dynamically synchronize cached VOSS data with data on devices. The data sync instance is associated with the connection parameters of a device type in VOSS. Supported devices include: * Cisco Unified CM (Cisco UCM) * Cisco Unity Connection (CUC) * LDAP * Webex * MSTeamsOnline (Microsoft Teams) * MSGraph Individual add, update, and delete operations carried out by a data sync instance can be disabled on the user interface. If no operation is selected, the default behavior is maintained. For Microsoft deployments, it is recommended that you enable *Prevent Duplicate Numbers* in the Global Settings to force the system to fail transactions involving workflow steps that create a copy of a number that already exists in VOSS, for example, when creating a number range or when syncing in users. For details, see: * .. raw:: latex Prevent duplicate numbers in the Core Feature Guide .. raw:: html Prevent duplicate numbers * .. raw:: latex Global Settings (Number Inventory tab/panel) in the Core Feature Guide .. raw:: html Global Settings (Number Inventory tab/panel) .. rubric:: Related topics * .. raw:: latex Sync overview in the Best Practices Guide .. raw:: html Sync overview * .. raw:: latex Data sync types in the Core Feature Guide .. raw:: html Data sync types * .. raw:: latex Model instance filters in the Core Feature Guide .. raw:: html Model instance filters * .. raw:: latex Prevent duplicate numbers in the Core Feature Guide .. raw:: html Prevent duplicate numbers Data sync settings ................... To view the summary list of configured data syncs in VOSS, go to the **Data Sync** page. The list view displays basic details for each available data sync, including a number of summary attributes that provide additional details about the data sync. .. image:: /src/images/admin-tools-data-sync.png To view data sync settings, click on a data sync in the list to open the configuration page. .. image:: /src/images/admin-tools-data-sync-config.png | The table describes a number of key settings that are available for data syncs: .. tabularcolumns:: |p{4cm}|p{11cm}| +------------------------+-------------------------------------------------------------------------------------+ | Settings | Description | +========================+=====================================================================================+ | Model Type lists | Define the entities to pull in a given sync. For example: | | | | | | * Only pull in ``device/cucm/User`` records from CUCM. | +------------------------+-------------------------------------------------------------------------------------+ | Model Instance filters | Limit a sync to a subset of entities in a sync. For example: | | | | | | * Pull in users with a primary extension starting with *1*. | | | | | | A system-level administrator will need to expose this setting in the Admin Portal. | | | | | | * The **Purge Unmatched Records** option can be enabled to purge all VOSS | | | data that does not match the active filters during sync. This allows for a | | | maintenance free scheduled sync that will keep the cache records in line with the | | | filter. | +------------------------+-------------------------------------------------------------------------------------+ | Disabled Operations | Choose which operations are enabled for a sync (Add/Update/Remove). | | | | | | * Update requires more effort to run because this typically involves a GET API call | | | for each record, which must then be compared to VOSS data. | | | * Add/Remove can be determined from the initial list API calls. | | | | | | To save time on the sync, you may wish to disable *Update* if you only require | | | Add/Delete. | | | | | | From the list view of **Data Sync** entries, these fields are also available as | | | columns (summary attributes) and can for example be used to filter the list of data | | | syncs by the operations. | | | | | | .. important:: | | | | | | *Remove* is disabled by default if you've selected a model instance filter for | | | the sync. You'll need to enable *Remove* if you intend for the sync to purge | | | (remove) cache records that are excluded in the model instance filter. | | | | | | If you're upgrading to 21.4-PB4 from an earlier version of VOSS, a | | | migration script disables *Remove* for any syncs that have a model instance | | | filter applied. This is to prevent the sync from unexpectedly removing a large | | | number of records after the upgrade. | +------------------------+-------------------------------------------------------------------------------------+ | Quick Import | Uses the list API responses to update the VOSS cache, and won't perform | | | individual GET calls for each entity for the update. | | | | | | Recommended when the list response contains all values for the entity, or where | | | only the key settings must be updated. | | | | | | Removing individual GETs speeds up the sync, since VOSS is not waiting for the | | | API responses when there are a many entities to update. This is useful if the list | | | and GET responses are required, or if you only need the summary data from the list | | | view. | | | | | | This setting is disabled by default for syncs related to `device/spark/user` syncs | | | (`SyncSparkUsers` and `SyncSpark`). | | | | | | This setting is *enabled* by default for syncs related to `data/MSGraph` syncs | | | (Syncs Microsoft License data from Microsoft Graph). | +------------------------+-------------------------------------------------------------------------------------+ .. note:: *Quick Imports* can improve sync performance but must be used with extreme caution to avoid unintended changes. Typically, Quick Import is recommended only for Microsoft-related data syncs (MSOperatorConnect, MSGraph, MSTeamsOnline, MSExchangeOnline) and for Webex App/Teams-related syncs that do not include the Webex App/Teams user (device/Spark/user). The default Full Sync instance provided for CUC also does not have **Quick Import** enabled. Synchronous and asynchronous data sync ....................................... By default, a data sync is asynchronous; that is, other tasks can be carried out while the sync is in progress. However, a data sync can be set to be synchronous so that a workflow step can, for example, wait for the sync process to complete. Asynchronous imports initiated by a data sync are standalone transactions; that is, they aren't child transactions of the data sync execute transaction. Synchronous imports initiated by a data sync are children of the data sync execute transaction. .. note:: By default, syncs related to `data/MSGraph` syncs (Syncs Microsoft License data from Microsoft Graph) are *synchronous*.