How Siebel CRM Desktop Synchronizes Data

This chapter describes how Siebel CRM Desktop synchronizes data. It includes the following topics:

How Siebel CRM Desktop Synchronizes Data Between the Client and the Siebel Server

This topic describes how Siebel CRM Desktop synchronizes data between the client and the Siebel Server. It includes the following topics:

How Siebel CRM Desktop Synchronizes Data During the Initial Synchronization

An initial synchronization is a type of synchronization that occurs in the following situations:

Immediately after the user installs Siebel CRM Desktop.
If you deploy a metadata change to the user that includes a change to the data schema.
If the options in the login dialog box change. For example, the user name changes or the URL of the Siebel Server changes.

The purpose of the initial synchronization is to initialize the IBM Notes data storage with the Siebel CRM data that is available to the user. Siebel CRM Desktop downloads files in the customization package to IBM Notes the first time the user synchronizes metadata with the Siebel Server. This metadata includes the following information:

Definition data for Siebel CRM Desktop, such as synchronization rules, object definitions, and so on
Siebel CRM data for Siebel CRM Desktop, such as accounts, opportunities, and so on

Siebel CRM Desktop does the following work during the initial synchronization:

Establishes a synchronization session with the Siebel Server through the Web service interface.
Directs the Web Service Connector in IBM Notes to call the DownloadMetadataFiles method of the PIM Client Metadata Service business service that resides on the Siebel Server.
To broker requests through the EAI Siebel Adapter, Siebel CRM Desktop uses the business services that the Web services references. It uses the EAI Siebel Adapter business service to process the SiebelMessage payload in the requests.
Directs the PIM Client Metadata Service on the Siebel Server to get the login ID of the user from the session, and then identifies the responsibility that the user uses, the customization package that the responsibility references, and if the package is active. For more information, see Relationships Between Users, Responsibilities, Customization Packages, and Metadata Files.
If the customization package is published and valid, then Siebel CRM Desktop queries all metadata files of that package and creates a Siebel message. It does the following work:
- Sets the containsFiles argument to true.
- Enters the relevant data in the packageId, responsibilityId, and hashValue arguments.
- Applies the downloaded package for IBM Notes.
- Downloads Siebel CRM data.
  For more information, see How Siebel CRM Desktop Synchronizes Siebel CRM Data.
- Logs out of the synchronization session that it established in Step 1.

For more information, see How Siebel CRM Desktop Handles Synchronization Errors.

How Siebel CRM Desktop Synchronizes Data During an Incremental Synchronization

An incremental synchronization is a synchronization session that occurs any time after the initial synchronization. To determine the differences that exist in the data that is available to the user, Siebel CRM Desktop compares data in the IBM Notes data storage to data in the Siebel database. It then does the following work:

Inserts, updates, or deletes data on the Siebel Server according to changes that occurred in IBM Notes since the prior synchronization
Inserts, updates, or deletes data in IBM Notes according to changes that occurred on the Siebel Server since the prior synchronization

Siebel CRM Desktop does this work for each difference until it synchronizes all data that resides in the IBM Notes data storage with data in the Siebel database. In all situations, the user works with data locally in IBM Notes and Siebel CRM Desktop sends these changes to the Siebel Server during an incremental synchronization, but not at the same time that it makes the change in IBM Notes. Depending on the frequency of the process, a change might not appear on the server immediately.

Siebel CRM Desktop does the following work to complete an incremental synchronization:

Connects to the Siebel Server to establish a synchronization session.
Authenticates the user.
Passes the values of the packageId and responsibilityId arguments that it caches in IBM Notes to the Siebel Server. Siebel CRM Desktop cached these values during the prior synchronization. It does this to avoid expensive iterative operations through all responsibilities and customization packages every time it calls the Web service.
Receives a reply from the Siebel Server. This reply indicates if new metadata is available for the user.
If new metadata is available, then Siebel CRM Desktop does the following work:
- Determines if the customization package changed.
- If the package changed, then it downloads the new package to a temporary folder in IBM Notes.
- If the package is not changed, then it proceeds to Step 11.
Determines if the currently applied package is compatible with the downloaded package and then does one of the following:
- If the package is compatible, then Siebel CRM Desktop synchronizes the current data to the Siebel Server.
- If the package is not compatible, then Siebel CRM Desktop stops the synchronization and the user changes are lost. The data modified in the old package is not appropriate for the current version of Siebel CRM Desktop.
For more information, see How Siebel CRM Desktop Determines Compatibility.
Determines if the currently applied package is compatible with the current version of Siebel CRM Desktop. If the package is not compatible, then Siebel CRM Desktop does not apply the downloaded package, it displays a product incompatibility error message, and then exits this process.
For more information, see How Siebel CRM Desktop Determines Compatibility.
If the package is compatible, then Siebel CRM Desktop determines if the object structure in the downloaded package changed.
If the object structure did not change, then it applies the new package and proceeds to Step 11.
If the object structure changed, then it displays a dialog box that asks the user to do one of the following:
- Reinstall the object structure. Siebel CRM Desktop does the following:
  - Removes the old custom folders.
  - Removes the old data.
  - Installs the new package.
  - Displays the second part of the First Run Assistant. This part allows the user to set synchronization filters and make other settings that set up Siebel CRM Desktop to use the new customization package.
  - Starts a synchronization session after the user specifies these filters and other settings.
- Do not reinstall the object structure. Siebel CRM Desktop does not install the new customization package. The next time the user attempts to synchronize, it displays the same dialog box that asks the user to reinstall the object structure.
If the customization packages are identical, then Siebel CRM Desktop does the following work:
1. Sends a reply that indicates that it is not necessary to download the customization package because the package that resides on the Siebel Server is the same as the package that resides in IBM Notes.
2. Exits this process.
Identifies the differences that exist between the data in IBM Notes and the data on the Siebel Server. To do this, it compares the change key values for all records that are available to the user in IBM Notes to the change key values that reside on the Siebel Server. The change key includes the record Id and the last time the server updated the record in the Siebel database. The value for the record Id resides in the ROW_ID column of the data table and the value for the time resides in the DB_LAST_UPD column of the data table. Depending on the differences, Siebel CRM Desktop changes the values in a data set to make sure the data between IBM Notes and the server is synchronized. For example, if Siebel CRM Desktop detects a new record during synchronization:
- On the Siebel Server, then it creates a corresponding record in IBM Notes.
- In IBM Notes, then it creates a corresponding record on the Siebel Server.
If the user changes synchronization filters, then Siebel CRM Desktop removes the Siebel CRM data that falls outside of the filters from IBM Notes. It does this during synchronization. A referenced record might remain in IBM Notes. For example, assume an account references a contact and this account does not match a filter. Siebel CRM Desktop continues to synchronize this account but makes it read-only in IBM Notes. It synchronizes the account details but it does not synchronize any account relationships that exist to other records.
Downloads Siebel CRM data.
For more information, see How Siebel CRM Desktop Synchronizes Siebel CRM Data.
The user can now view the newly downloaded data.
Logs out of the synchronization session that it established in Step 1.

How Siebel CRM Desktop Handles Changes to Login Credentials

If the user name or the server URL changes, then Siebel CRM Desktop reinitializes the data structure. It does this to remove any personal user data that might exist and to allow the user to synchronize data. Before Siebel CRM Desktop begins the reinitialization, it displays a warning to the user that any data that is not synchronized might be lost. If the user agrees to proceed, then the following occurs:

Siebel CRM Desktop removes the current customization.
The user logs in with new credentials.
Siebel CRM Desktop downloads the package from the Siebel Server and then starts the First Run Assistant.

How Siebel CRM Desktop Synchronizes Siebel CRM Data

Siebel CRM Desktop does the following work to synchronize Siebel CRM data, such as opportunities and accounts:

Calculates the number of records for each type of record, such as opportunities or accounts.
Gets the values of the change keys for all synchronization objects that are enabled, such as opportunities or accounts. For example, the record ID and the last updated date in the Siebel database.
Compares the set of IDs and timestamps in IBM Notes to the set of IDs and timestamps on the Siebel Server to do the following:
- Identify differences that exist between the data sets for inserts, updates, and deletes.
- Identify conflicts and create a log entry in the synchronization conflict list for any conflicts.
For each difference, Siebel CRM Desktop does one of the following operations in IBM Notes or on the Siebel Server:
- Siebel insert. Query the Siebel database to get the details of the new record and then insert the appropriate item in IBM Notes.
- Siebel update. Query the Siebel database to get the details of the updated record and then update the appropriate item in IBM Notes. Note that a Siebel update overwrites all fields in the corresponding IBM Notes item, not just the updated fields.
- Siebel delete. Delete the appropriate item in IBM Notes.
- IBM Notes insert. Use the user key that is defined in the metadata to query the Siebel database and then do one of the following:
  - If it does not find a match, then it inserts the appropriate record in the Siebel database and then queries the Siebel database to get the record ID and timestamp.
  - If it does find a match, then it returns a synchronization issue, which is an error that occurs during synchronization.
- IBM Notes update. Use the user key that is defined in the metadata to query the Siebel database, and then do one of the following:
  - If it does not find an update for the modification number of the record, then it updates the appropriate record in the Siebel database and then queries the Siebel database to get the record Id and updated timestamp.
  - If it does find an update for the modification number, then it returns a synchronization issue. Note that this handling is different than in the situation where Siebel CRM Desktop changes the same record in the Siebel database or when it compares IDs and timestamps. In this situation, Siebel CRM Desktop makes the change in the Siebel database during the actual update operation.
IBM Notes delete. Delete the appropriate record in the Siebel database.
If a conflict occurs, then Siebel CRM Desktop does the following work:
1. Updates the synchronization issues and conflicts log on the client.
2. Prompts the user to choose the changes to keep in each of the following situations:
  - Update the record in IBM Notes and on the Siebel Server.
  - Update the record in one data set and delete the record in the other data set.
Repeats Step 4 for each additional Siebel CRM data object that requires synchronization.

How Siebel CRM Desktop Manages Synchronization Duration

Several factors determine the duration of a synchronization, such as the amount of data that is available to the user, network bandwidth, server performance, client performance, and so on. To shorten this duration, you or the user can do the following:

You can modify the application configuration. For more information, see Controlling Synchronization.
The user can adjust settings through the synchronization filter dialog box. For more information, see How Filters Reduce the Data That Siebel CRM Desktop Synchronizes.

The duration of an incremental synchronization session is typically shorter than for an initial synchronization because Siebel CRM Desktop downloads all objects during an initial synchronization but during an incremental synchronization it only downloads the objects that changed since the last synchronization.

Situations Where Siebel CRM Desktop Reinstalls the Data Structure

Siebel CRM Desktop reinstalls the data structure in any of the following situations:

The package update for the user involves a data schema change.
The user logs in as a different user.
There is a problem with the data structure. For example, assume the user deletes the Opportunities folder and then removes this deletion from the Deleted Items folder. If the user restarts IBM Notes, then Siebel CRM Desktop does the following:
- Informs the user that a problem with the data structure exists.
- Removes the data structure.
- Installs a new data structure.

If Siebel CRM Desktop must reinstall the data structure, then it does the following work:

Removes all Siebel CRM data, such as accounts, opportunities, shared contacts, and activities.
Removes every shared calendar entry and To Do item that originates in Siebel CRM. Each shared calendar entry and To Do item that originates in IBM Notes remain in IBM Notes.
Removes the custom data structure that it previously deployed to IBM Notes data storage. For example, to remove all custom folders in the user mailbox.
Installs the new data structure.

To reenter the appropriate Siebel CRM data in the IBM Notes data storage, the user must manually start a new, initial synchronization session.

The Customization Package Changed

During synchronization, Siebel CRM Desktop determines if the customization package for the user who is currently logged in changed in such a way that it must reinstall the data structure. The following changes in the data structure of the customization package can cause this situation:

An object is added to or deleted from the mapping scheme.
A field is added to an existing object or an existing field is modified.

If the customization package changed, and if Siebel CRM Desktop must reinstall the data structure, then it displays a prompt that is similar to the following:

A new configuration is available. Are you ready to download and apply it? Selecting 
"Yes" will remove your current data, re-install the data structure, and download the 
data again.

The Customization Package Changed But the Data Structure Has Not Changed

If Siebel CRM Desktop determines during synchronization that the customization package for the user who is currently logged in has changed in such a way that there is no change to the data structure, then it downloads and installs the new package and informs this user about this download. A modification to a security rule is an example of where the package changed but the data structure has not changed. In this situation, Siebel CRM Desktop does not start a new, initial synchronization.

How Siebel CRM Desktop Prevents Data Loss if the User Deletes Customization Package Files

Siebel CRM Desktop prevents data loss if the user deletes customization package files differently depending on if IBM Notes is open:

IBM Notes is open. The user cannot delete any customization package files. For example, if the user attempts to use Windows Explorer to delete files from the following directory in Windows 7, then Windows Explorer does not allow the deletion:
```
C:\Users\user\AppData\Roaming\Oracle\CRM Desktop for IBM Notes\Profile\Data
```

IBM Notes is not open. The user can use Windows Explorer to delete customization package files. However, if the user subsequently starts IBM Notes, then Siebel CRM Desktop restores the customization package files from local storage. For more information about this local storage, see How Siebel CRM Desktop Stores Siebel CRM Data.

How Connectivity Failures Affect Synchronization

An internet or network connectivity failure that occurs during synchronization can interrupt the synchronization. An interruption does not cause data loss or corruption. Synchronization can proceed from the last step that Siebel CRM Desktop ran successfully before the interruption.

Factors That Determine the Data That Siebel CRM Desktop Synchronizes

A Siebel user can typically access only a subset of data that is available in the Siebel database. This topic describes that factors that determine the data that a user can access. How you configure Siebel CRM Desktop determines many aspects of the data that it synchronizes. For example:

Synchronization objects that are configured
Internal filters that are applied
View modes that are configured on each object
Security and other configuration that exists on the Siebel Server

You specify this configuration before you deploy Siebel CRM Desktop to your users. The user can choose presets for a predefined filter and specify personal filters in the First Run Assistant. The internal filters and server application metadata configuration restricts access to some data, and the user filters apply a second layer of filtering. Siebel CRM Desktop applies these filters during initial synchronization and incremental synchronization.

How Filters Reduce the Data That Siebel CRM Desktop Synchronizes

The following figure illustrates how the number of Siebel CRM records that are available in the client reduces as these records encounter each set of filters.

Explanation of Callouts

The following filters reduce the data that Siebel CRM Desktop synchronizes:

Siebel visibility filters. Visibility rules that are configured in the Siebel Repository and that the Siebel Server applies affects data access. Siebel CRM Desktop integrates with the Siebel Server through the Web service interface, so security, search specifications, and other logic that is configured at the integration or business object layer limits the data that Siebel CRM Desktop synchronizes to the client. The user interface configuration does not affect the results of queries or other operations that Siebel CRM Desktop performs.
Master filters. Internal synchronization filters that an administrator sets. They identify the Siebel CRM data that Siebel CRM Desktop synchronizes to the client. Search specifications on the Siebel Server and security settings in the Siebel Repository establish the first level of filtering. A set of filters that reside on the client can also restrict the data that Siebel CRM Desktop downloads to the client.
Preset and user filters. An administrator can create preset filters in the customization package and then specify the filter that Siebel CRM Desktop applies as the default filter. The user can use this default filter or choose another preset filter. The user can do this in the First Run Assistant during installation or later in the Filter Records Tab of the Synchronization Control Panel. To create a preset filter, the user can modify an existing preset filter. The user can apply different saved presets at different times, depending on the filter requirement. Siebel CRM Desktop uses these filters and the application configuration to identify the data to synchronize.
Depending on relationships in the data, Siebel CRM Desktop might synchronize an object that the Filter Records Tab disables for synchronization. For example, if the opportunity object is enabled but the account object is not enabled, then it still downloads any account data that the opportunity references. This download is required to make sure the data is complete. Also, Siebel CRM Desktop might still upload changes that the user makes in the client to the Siebel Server even if an object or synchronization filter is disabled. For example, if the user disables the account object and then creates an account in IBM Notes, then it uploads the account to the Siebel Server. For more information, see the following topics:
- Customizing How the First Run Assistant Performs the Initial Synchronization
- Controlling Synchronization Filters

Objects That Are Enabled for Synchronization

A set of objects that are enabled for synchronization determines the data that Siebel CRM Desktop can synchronize, depending on the configuration that Siebel CRM Desktop downloads for the user. These objects are defined in the application metadata that you deploy through the customization package that is available to the user. If the application metadata does not define an object, then Siebel CRM Desktop does not synchronize it. Application metadata also defines the field mappings that Siebel CRM Desktop uses in the synchronization. These mappings specify how Siebel CRM Desktop synchronizes objects in IBM Notes and on the Siebel Server. For more information, see Customizing Field Mapping.

How Differences Between IBM Notes and the Siebel Server Affect Synchronization

Siebel CRM Desktop downloads to IBM Notes all data that resides on the Siebel Server that is available to the user for the initial synchronization. For an incremental synchronization, the changes that occur to data in IBM Notes and on the Siebel Server play a large role in determining the data that Siebel CRM Desktop synchronizes. The following changes can occur:

Data is created, updated, or deleted in IBM Notes.
Data is created, updated, or deleted on the Siebel Server.

For more information, see How Siebel CRM Desktop Synchronizes Data During an Incremental Synchronization.

Differences in Data Access Rules

Differences in data access rules that occur from one synchronization to the next can occur for the following reasons:

The user downloaded a different customization package with a different configuration of synchronization objects, view modes, or internal synchronization filters.
The configuration of the Siebel Repository changed. This can include security logic, search specifications, or other logic in the integration or business object layers.

How Siebel CRM Desktop Handles Synchronization Duplicates and Errors

This topic describes how Siebel CRM Desktop handles synchronization duplicates and errors. It includes the following topics:

How Siebel CRM Desktop Avoids Duplicate Data

Siebel CRM Desktop includes metadata in the client and configuration in the Siebel Repository that prevents it from creating duplicate data. This configuration is in addition to the following items:

The standard user keys that reside in the Siebel database.
Data deduplication that you can deploy to prevent duplicate data. For more information, see Resolving Synchronization Conflicts.

The view mode that Siebel CRM Desktop uses for duplicate requests during synchronization for an object type. For more information, see Controlling the View Mode During Synchronization According to Object Type.

Siebel CRM Desktop uses Siebel integration objects to create the data structures that are available to synchronize with IBM Notes. These objects support the user key definition that is the first additional layer of duplicate prevention. For information about how to configure user keys for integration objects and how the EAI Siebel Adapter uses them, see Overview: Siebel Enterprise Application Integration.

Siebel CRM Desktop also supports user key configuration in the metadata for the client. If it detects the IBM Notes insert during synchronization, then it queries the synchronization object in the Siebel database with the user key to determine if any records exist that match the record that it is inserting. If it:

Does not find a match. It proceeds with the insert operation.
Finds a match. It raises a synchronization issue that prevents the insert. For more information, see Resolving Synchronization Conflicts.

How Siebel CRM Desktop Handles Synchronization Errors

If a high-level error occurs during synchronization, then the Synchronization Engine stops any further processing and displays a message to the user that describes the error. The following types of errors can occur:

System error
Resource allocation error
General storage problem
Application state malfunction
Login failure
Connectivity problem
Missing xml or js files in the customization package

If an operation failure occurs in the Synchronization Engine, then Siebel CRM Desktop creates a synchronization issue and then attempts to do this operation again during the next synchronization session. The following types of errors can occur in this situation:

Unexpected failure during an add, update, or delete operation.
If the data for an object changed since Siebel CRM Desktop queried this object during the current synchronization session, then it cannot do the update and the delete operations until the next synchronization cycle. In this situation, it creates an issue and then handles this issue in the subsequent synchronization. This synchronization creates a collision because the object changed since the last synchronization. A collision is a data integrity problem that occurs if Siebel CRM Desktop modifies the same record on the Siebel Server and in IBM Notes between synchronization sessions. For more information, see Resolving Synchronization Conflicts.

Siebel CRM Desktop logs synchronization errors in synchronization log files and in the General Log log file. It does not enable log files, by default. For more information, see Log Files You Can Use with Siebel CRM Desktop.

How Siebel CRM Desktop Handles Errors While Downloading the Customization Package

If an error occurs while Siebel CRM Desktop downloads the customization package, then it displays an error message near the taskbar. This error notifies the user that the customization package changed but Siebel CRM Desktop cannot download it because of errors. The problem might be due to the fact that the user does not possess the privilege that the Siebel Server requires to download the package. In this situation, the user must contact the system administrator to get the necessary privileges and then get the customization package again.

How Siebel CRM Desktop Determines Compatibility

This topic describes how Siebel CRM Desktop determines compatibility. For a description of the work Siebel CRM Desktop does depending on compatibility, see How Siebel CRM Desktop Synchronizes Data During an Incremental Synchronization.

How Siebel CRM Desktop Determines Product and Version Compatibility

Siebel CRM Desktop uses the following element in the info.xml file to determine product and version compatibility:

<compatibility>
  <products>versions</products>
  <schemas>versions</schemas>
</compatibility>

where:

products. Specifies product versions that are compatible with the package that Siebel CRM Desktop must install.
schemas. Specifies package versions that are compatible with the package that Siebel CRM Desktop must install. If the current package is compatible with the new package that it must install, then Siebel CRM Desktop synchronizes the local data to the Siebel Server before it applies the new package.
versions is a string that includes one or more version numbers. A dash (-) specifies a range of versions. A semi-colon (;) separates individual version numbers.

For example, the following code specifies that all product versions starting with version 3.05.15.00 through version 3.05.30.99 are compatible:

<compatibility preferred_product="3.05.30.00">
  <products>3.05.15.00-3.05.30.99</products>
  <schemas>3.04.00.00-3.05.30.99</schemas>
</compatibility>>

Siebel CRM Desktop returns a preferred version in the following situations:

The product is not compatible.
The product is compatible but the preferred version is not the same version as the current product version.

How Siebel CRM Desktop Determines Schema Compatibility

The schema subelement of the compatibility element in the info.xml file determines schema compatibility. If Siebel CRM Desktop can save the data that it creates or modifies in the old customization package, then the schema is compatible. It saves this data to the current version of the Siebel database. An example of schema incompatibility occurs if a required field in Siebel CRM does not contain a value because the old package does not require it.

How Siebel CRM Desktop Determines Object Structure Compatibility

Siebel CRM Desktop examines the object structure to determine compatibility. For example, if you create a new object type that Siebel CRM Desktop synchronizes, then it must reinstall the current folder structure and install the new folder structure with the new package. If the object structure that the new customization package defines is not different from the object structure that the old package defines, then Siebel CRM Desktop applies changes from the new customization package.

How Siebel CRM Desktop Handles Incompatible Customization Packages

If the current version of Siebel CRM Desktop is not compatible with the downloaded customization package, then Siebel CRM Desktop does not apply the package. Instead, it displays an error message that notifies the user and then adds an entry in the CRMDesktopn.log file, where n is an incremental number that uniquely identifies the log file name. It stores the error message in the most recent log file.