[Index]

Model: data/DataSync

Data Sync

The data of the various devices can be updated on VOSS-4-UC, or also directly on the device. Therefore, it is necessary to periodically synchronize cached VOSS-4-UC data with the data on devices.

Consider an example: when an instance of a Unified CM is added to the system, its data is imported and cached. However, when instances are added, updated or removed from the Unified CM, the cached data in VOSS-4-UC becomes out of sync with data on the device.

If data is deleted from Unified CM before it is deleted from VOSS-4-UC, the error "The specified resource could not be found" is displayed. This means the resource is out of sync and VOSS-4-UC may need to re-sync with Unified CM to delete or update it.

The Data Sync feature provides a means to dynamically synchronize cached VOSS-4-UC data with data on devices. The data sync instance is associated with the connection parameters of a device type in VOSS-4-UC.

Supported devices include:

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.

Refer to the Best Practices Guide chapter on Data Sync for additional considerations when managing your data syncs.

Key Settings for Data Sync

A number of key settings that are available for data sync:

Note

The Quick Import option is not recommended in most cases, but should only be used for the sync of device/cuc/ImportUser. However, initially there is an exception to the performance improvement of a quick import sync with device/cuc/User:

When quick import is turned on on a sync which has previously run without it, dependent, non-Import User model types use the LIST response data to compare with the resource data which was originally saved using the GET response data. The data sync detects a change and a resource save is initiated for each instance. In the case of device/cuc/User, this means that dependent import API calls are made, which result in a long sync time.

Once it has completed, however, subsequent quick import syncs should show an improvement over non-quick import syncs, but when changing back to a non-quick import sync, the same effect would likely be observed.

Data Sync Types

Data synchronization is available with the following functionality:

A quick import option is available to fetch only summary data that is contained in a list operation response and not the data for all instances/fields.

For all the syncs in general, the VOSS-4-UC system builds up the lists of entities from both VOSS-4-UC and the device (for example Unified CM) for comparison. The field that is used for this comparison is the key for the device entity, which is typically the unique identifier for the record in the device we that are syncing with. For example, for Unified CM, the identifier is the pkid which is the internal Unified CM database id.

In the case of subscribers, a sync will build up the list of device/cucm/Users in VOSS-4-UC and then request from the Unified CM the lists of users it currently has for the comparison. The differences in the lists are then handled according to each sync type.

Details of the sync types are listed below:

Note

Bear in mind that with the above keys list sync logic, in the case of a reversion of the Unified CM to restores/inactive partitions, the relevant pkids might be different in the end state than they were at the last time VOSS-4-UC was in sync with Unified CM before the restore - especially if there was a lot of testing in between.

What this means practically is that there could for example be a user with the same username in both VOSS-4-UC and Unified CM, but if that user's pkid in Unified CM is now different to the one that VOSS-4-UC holds from previous syncs or interactions, then the users will be seen as different even though the usernames are the same.

Synchronous and Asynchronous Data Sync

A Data Sync is by default set to be asynchronous, in other words other tasks can be carried out while the sync is in progress. However, it 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, in other words 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.

Full Sync

A full pull sync, when runs, empties the changes from the data collection as they don't need to be processed by the Change Notification Sync. Use the disabled operations and the model type list of the full sync to filter the changes to remove. If a model instance filter is included, no changes are removed.

Enable a Scheduled Data Sync

By default, when a Cisco Unified Communications Manager or Cisco Unity Connection device is set up in VOSS-4-UC, a full data sync instance is created to perform the initial sync of all data from the device. A Change Notification Sync type also gets created in the Data Sync page. In addition, a Schedule is created to execute that data sync every 14 days, but is disabled by default. We recommend running the full data sync manually only when necessary. However, if a regularly scheduled sync is desired, the schedule can be enabled as follows:

Procedure

  1. Log in as provider administrator.

  2. Choose Administration Tools > Scheduling.

  3. Choose the schedule instance that matches this naming convention:

    HcsSync-<ip_address>-<device_name>-SCHED. For example:

    HcsSync-192.0.2.24-CUCM01-SCHED

  4. Select the Active check box.

  5. Click the Multiple Executions tab, and update the interval, if desired.

  6. Click Save.

The full data sync executes immediately, and executes again according to the schedule.

Perform Publisher Actions

You can always manually run the default data sync when there have been updates to Cisco Unified Communications Manager or Cisco Unity Connection devices that need to be synced into VOSS-4-UC.

Note

Manual run of the change notification sync is not supported.

Procedure

  1. Log in as provider or reseller administrator.
  2. Choose Device Management > Advanced > Perform Publisher Actions.
  3. From the Action drop-down, choose Import.
  4. From the App Type drop-down, choose CUCM Device or CUC Device.
  5. From the Available Clusters list, choose the device and click Select.
  6. Click Save.

Controlling a Data Sync with a Model Type List

Using a Model Type List (MTL), you can control the types of data that are synced into VOSS-4-UC from Cisco Unified Communications Manager or Cisco Unity Connection devices. Controlling the types of data that are synced can greatly improve sync performance. The MTL is a list of device models associated with the device type, for example, Phone and Line device models that are associated with the Unified CM device.

These are the possible types of Model Type Lists:

A data sync created with an empty Model Type List attribute results in the subsequent import(s) synchronizing all device models for the corresponding device.

Here's an example of an include MTL:

A data sync using this MTL will sync all Media Resource Group, Media Resource Lists, Music on Hold servers and audio sources, and Media Termination Points. No other data will be synced from Unified CM.

It is recommended to define MTLs for sets of data that are being modified on the device directly, particularly Unified CM because this is where the bulk of the configuration data for each customer resides. By defining MTLs that target specific data sets rather than doing a full sync, the performance of VOSS-4-UC can be maintained with better response times and quicker transaction execution. Some Unified CM device models to avoid unless needed are Users, Phones, and Lines, as there may be large numbers of these in the Unified CM and result in a lengthy data sync operation.

Data sync overhead can be further reduced if you want to sync only new and deleted instances of the device model and not updates to existing instances. This can be done by unchecking the Refresh Existing (Changed) Data check box on the Data Sync configuration page. This check box controls whether existing device model instances are updated in VOSS-4-UC in addition to importing new instances and removing deleted instances. If checked, all device model instances must be synced and examined. If unchecked, only new and deleted instances need to be imported and the data sync will run considerably faster.

Create a Targeted Model Type List

If you manage data on Cisco Unified Communications Manager (Unified CM) or Cisco Unity Connection directly on a regular basis, perhaps for configuration that is not orchestrated from VOSS-4-UC, such as media resources, it is recommended to create a Model Type List and Data Sync specifically targeting the data items you are managing. This ensures each data sync is highly optimized for the data being changed on Unified CM directly and minimizing the load on VOSS-4-UC. To create a targeted Model Type List:

Procedure

  1. Log in as Provider level admin or higher.

  2. Select Administration Tools > Model Type List.

  3. Click Add.

  4. Specify the name of the Model Type List.

    It is recommended to use a naming convention that makes it easy to identity the MTL in a list view, such as Unified CM Media Resources.

  5. From the List Type drop-down, choose the list type:

  6. Add Model Types to the list of device models that are to be included or excluded according to the List Type selected.

    See View List of Device Models for information on how to see a list of available Unified CM and Cisco Unity Connection device models.

  7. Click Save.

View List of Device Models

Use this procedure to see the device models available to use in Model Type Lists for custom data syncs from Cisco Unified Communications Manager or Cisco Unity Connection.

Procedure

  1. Log in as entadmin.
  2. Click the ? on the menu bar to open Online Help.
  3. Select Model API.
  4. Select Device/Cuc or Device/Cucm. All the applicable device models are listed for the selected device.

What to Do Next

When including the device model in a Model Type List, use the format: device/<device_type>/<device_model>. For example, device/cucm/BillingServer.

Create a Custom Data Sync

Create a custom data sync to use a targeted Model Type List.

Procedure

  1. Log in as provider admin or higher.

  2. Choose Administration Tools > Data Sync.

  3. Click Add.

  4. Enter the name of the Data Sync in the Name field.

    It is recommend to use a naming convention that makes it easy to identify the data syncs in the list view, such as C1Pull-CUCM01-DS where C1 is the customer name, Pull is the data sync type, CUCM01 is the name of the Cisco Unified Communications Manager, and DS stands for Data Sync. You could also include the type of data included in the sync, such as C1Pull-CUCM01-MediaResources-DS.

  5. From the Device Type drop-down, choose the Device Type you are syncing from.

  6. From the Sync Type drop-down, choose Pull from Device.

  7. From the Dependency Resolution drop-down, choose Default.

  8. Select the Execute Asynchronously and Refresh Existing (Changed) Data check boxes.

    Execute Asynchronously means that the sync request will return a reply before its complete when executed from the API. Refresh Existing Data means that all instances of the device models specified in the Model Type List will be updated.

  9. Select the Force Refresh of Data check box if a data update is required regardless of whether data has changed on the device. This option would for example be used if it is required that update workflows be run upon a data sync.

  10. From the Model Type List drop-down, choose the targeted Model Type List you defined earlier.

  11. Leave Synchronization Order and Model Instance Filter blank.

  12. Click + next to Device Filters to add an entry to the list.

    1. From the Attribute Name drop-down, choose host.
    2. From the Condition drop-down, choose Equals.
    3. From the Value drop-down, choose the hostname/IP address of the device.

    Note

    Workflows can be added to, and executed by a custom data sync to perform specific data sync operations.

  13. In the Workflows section, include workflows in the custom data sync if you want to perform specific data sync operations, otherwise leave the Workflows section empty. For example, if you want to move remote destinations from the Customer hierarchy level to the Site level, choose the RD_Overbuild_PWF_wrapper workflow from the Workflow drop-down.

  14. Click Save.

What to Do Next

To run the custom data sync, click the data sync from the Data Sync list and click Execute.

Unified CM Change Notification Feature Alerts

The Unified CM Change Notification Feature (CNF) is enabled to display alerts. You don't have to configure the change notification feature alerts manually in the VOSS-4-UC. The administrator gets the alerts when something goes wrong with the collector process.

The administrators can view the alerts at the hierarchy level they log in and all the levels below that hierarchy. For example, if an alert is raised at the customer level (sys.hcs.provider.reseller.c1), then the provider, reseller, and customer administrators can see that alert but not site administrator. A Site administrator doesn't have access to view the alert. All the administrators have read and delete permissions to the alerts.

When a change notification feature alert is raised, the Notifications indicator on the VOSS-4-UC Admin GUI shows the alert. Clicking the Notifications button shows a pop-up and a message that alerts have been raised. Clicking on the message, the users are navigated to the list of alert messages under Administration Tools > Alerts.

CNF alerts have the following distinct properties:

Note

Administrators can also filter alerts by any of the alert fields.

VOSS-4-UC displays change notification feature alerts for the following error scenarios:

The administrator reads, inspects, acts on (for example, run a full sync on the device), and then manages alerts of the Change Notification collection service. The administrator can delete the alert from the list only when the issue that raised the alert has been resolved.

Note

If the Administrators forget to remove the change notification feature alert after resolving it, the alert will still be shown when they log in to VOSS-4-UC. We strongly recommend removing the alert after resolving it.

Alert Field Descriptions

Field Description
ID * The unique ID of the alert.
Code * The code of the alert.
Category * The category of the alert.
Severity The severity of the alert.
Message The message describing the alert.
Count The number of times this alert has occurred.
Latest Alert The last time this alert occurred.

Data Sync Blacklisted Attributes

Administrators with permissions to access the Global instance of the settings in the data/Settings model, can create a list of device attributes that will not trigger any update workflows that may have been defined to execute during the data sync. These attributes are here called "blacklisted" attributes.

The reason for blacklisted attributes is that while data sync operations can have a performance impact, some data sync attribute changes do not require data sync workflows to be carried out.

A number of blacklisted attributes have been added by default:

Note however that the local device cache will still be updated with the updated attribute data. No update workflows will be run, though. The transaction logs will indicate the updated device cache, but the transactions for blacklisted attributes instances will show as:

"Device changes on blacklisted attributes only. Updating cache, skipping workflows."

Note

After release 19.3.2 or applying patch EKB-4362-19.2.1_patch, the previously blacklisted LDAP attributes are no longer imported during LDAP syncronization:

For device/ldap/user:

Provides data synchronization capabilities with devices (eg. CUCM, CUC, LDAP)

Model Details

Title Description Details
Name * The name that is given to the Data Sync instance.
  • Field Name: name
  • Type: String
Description A description for the Data Sync instance.
  • Field Name: description
  • Type: String
Device Type * The type of devices to be synchronized. Choices are based on connection parameter data models of the devices supported by the current system.
  • Field Name: device_type
  • Type: String
  • Choices: ["Active Directory", "Active Directory Hybrid", "Call Manager AXL Generic Driver", "Call Manager Control Center Services", "Cisco HCM-F", "Cisco Unified CM", "Cisco Unified Contact Center Express", "Cisco Unity Connection", "Cisco WebEx", "Exchange", "Exchange Hybrid", "Exchange Online", "LDAP", "Microsoft Online", "PowerShell", "Service Now", "SkypeForBusiness", "SkypeForBusiness Hybrid", "SkypeForBusiness Online", "Spark", "Unity Connection GUI"]
Sync Type The selected Sync Type. The Type can be Pull from Device, Push to Device, Merge with Device, or Purge Local. For Push, the system data state is the master state and the model types of the connection parameter are synchronized with it. For Pull, the model type states of the connection parameter is the master and the system model data is synchronized with these. For Merge, data synchronization takes place in both directions without overwrite of either data. For Purge Local, resources all resources that exist in the system will be deleted, although the entities in the device are not deleted - this is useful when cleaning up the system.
  • Field Name: sync_type
  • Type: String
  • Choices: ["Pull from Device", "Push to Device", "Merge with Device", "Purge Local Resources", "Change Notification Sync"]
Dependency Resolution The strategy for handling failures due to missing dependencies. Only 'Best Effort' resolution is supported. 'Best Effort' resolution attempts to brute force the synchronization as much as possible by re-iterating over failed imports until there are no errors.
  • Field Name: dependency_resolution
  • Type: String
  • Choices: ["Best Effort", "Default"]
Quick Import (Warning: Summary Data Only) Enable with caution: Indicates whether import operations will fetch full data for all instances or just use the summary data. Only use with Model types where all of the required data is in the summary data eg: device/cuc/ImportUser model.
  • Field Name: quick_import
  • Type: Boolean
Import Schema Only Indicates whether import operations will fetch schema only and no data.
  • Field Name: schema_only
  • Type: Boolean
Import Data Only Indicates whether import operations will fetch data only and no schema.
  • Field Name: no_schema
  • Type: Boolean
Execute Asynchronously Indicates whether the Data Sync must be executed Asynchronously or Synchronously. Default: True
  • Field Name: asynchronous
  • Type: Boolean
  • Default: True
Refresh Existing (Changed) Data Indicates whether the Data Sync refreshes existing data that has changed on the device.
  • Field Name: refresh_existing_data
  • Type: Boolean
Force Refresh Of Data Indicates whether a update action is executed regardless of whether the device has changed or not
  • Field Name: force_update_flag
  • Type: Boolean
Number of Changes To Process Specifies how many changes to process during a device notification.
  • Field Name: num_changes_to_process
  • Type: Integer
Disabled Operations Indicates which operations should be disabled for this Data Sync.
  • Field Name: disabled_operations
  • Type: Object
Add Disable the "add" operation.
  • Field Name: disabled_operations.add
  • Type: Boolean
Update Disable the "update" operation.
  • Field Name: disabled_operations.update
  • Type: Boolean
Remove Disable the "remove" operation.
  • Field Name: disabled_operations.remove
  • Type: Boolean
Model Type List The selected 'exclusion/inclusion' model type list that was created as a model instance of the Model Type List. See: Model Type List.
  • Field Name: model_type_list
  • Type: String
  • Target: data/ModelTypeList
  • Target attr: name
  • Format: uri
Synchronization Order The selected 'ordered' model type list that was created as a model instance of the Model Type List. This list dictates the order in which models will be synchronized. See: Model Type List.
  • Field Name: sync_order
  • Type: String
  • Target: data/ModelTypeList
  • Target attr: name
  • Format: uri
Model Instance Filter An instance of Model Instance Filter data model. This instance defines the rules for filtering out the models to be synchronized. See: Model Instance Filter.
  • Field Name: model_instance_filter
  • Type: String
  • Target: data/ModelInstanceFilter
  • Target attr: name
  • Format: uri
Device Filters A refinement on devices that the data sync applies to. These filters are optional. If they are not specified, data sync will be applied to all instances of the device type supported by this Data Sync instance. If specified, only the devices that match the given filters will be synchronized.
  • Field Name: device_filters.[n]
  • Type: Array
Attribute Name * The model attribute name to which the condition applies.
  • Field Name: device_filters.[n].attr_name
  • Type: String
  • Choices: [""]
Condition * If the Condition is Equals or Not Equals, then the Value to test the condition against. If the Condition is In or Not In, then Value is a list of values to test against.
  • Field Name: device_filters.[n].condition
  • Type: String
  • Choices: ["Equals", "Not Equals", "In", "Not In"]
Value The selected Attribute Name is tested against the Value that can also be a list of values, such as a list of host names. The Condition tests against the Value or list of values.
  • Field Name: device_filters.[n].value
  • Type: String
  • Choices: [""]
Values If the Condition is In or Not In, then the Values list the items to test the condition against.
  • Field Name: value_list.[n]
  • Type: Array
Workflows A list of workflows that is to be executed as part of data sync actions eg. when a resource is added, modified, or deleted
  • Field Name: workflows.[n]
  • Type: Array
Model Type The model type for which the workflow is to be executed.
  • Field Name: workflows.[n].model_type
  • Type: String
  • Format: uri
Operation * The operation for which the workflow is to be executed.
  • Field Name: workflows.[n].operation
  • Type: String
  • Choices: ["Add", "Update", "Delete"]
Phase * The operation phase at which the workflow is to be executed eg. Pre-Execution (before the operation is performed) or Post-Execution (after the operation is performed)
  • Field Name: workflows.[n].phase
  • Type: String
  • Choices: ["Pre Execution", "Post Execution"]
Workflow * The workflow instance that will be executed.
  • Field Name: workflows.[n].workflow
  • Type: String
  • Target: data/ProvisioningWorkflow
  • Target attr: name
  • Format: uri
Synchronous If selected the workflow will be executed synchronously, otherwise asynchronously (default).
  • Field Name: workflows.[n].synchronous
  • Type: Boolean
API reference for data/DataSync