During the tracking of the object, the add-in also writes information to the OutlookSyncCache.sdf client-side database file, which is located in the user’s roaming appdata folder (C:\Users\<user>\AppData\Roaming\Microsoft\MSCRM\Client). The OutlookSyncCache contains several tables including the OutlookSyncTable and the idMappingTable.
The OutlookSyncTable can be thought of as a queue that holds the change requests between synchronization cycles for any changes made on the client to synchronized records. Then, when the sync process occurs, this table is updated to contain the record data for changes that occurred in CRM in between the synchronization cycle. The columns found in the OutlookSyncTable include:
In the circumstance of performing a manual track, a row is first inserted into the OutlookSyncTable with a Priority of 1 for the CRM record create request, which is processed immediately by the add-in. This is in contrast to how updates to existing tracked items are handled, which will have a different priority. These items are instead processed during the next synchronization cycle. The full behavior of the background synchronization process will be discussed in a future blog.
The idMappingTable acts as a pointer table for the OutlookSyncTable to correlate the unique Outlook entry ID to the unique CRM ID during the synchronization process. In other words, this table can be thought of as an index which tells the add-in where it needs to look in the user’s mailbox to find the actual Outlook object that is linked to a corresponding CRM record. Each row in this table is not fully populated until the CRMID is returned from the initial create request.
The columns contained in the idMappingTable are as follows:
After the create response is received, the add-in then insert a row into the idMappingTable to correlate the Outlook item’s EntryId to the CRM record id.
As discussed above, the track process begins with an SDK Create request from the client. The SDK Create message can be captured in a server side platform trace, and will appear with the following message for a contact:
MessageProcessor start processing message:'Create' for entity:'contact'
When the server receives this request, the platform will perform a series of validations before the request is fulfilled and a response is generated. This includes:
When an Outlook object is manually tracked, several user-defined fields are created in the Outlook object to complete the track process. The fields that are introduced may include:
These custom fields are used by the add-in for the following tasks, among others:
It is important to note that manual modification of these fields do not necessarily impact the record in CRM. For example, even though it would be possible to set the crmLinkState property to 0, this would not “untrack” the record and cause the item to be deleted in CRM. Instead, the CRM add-in would no longer view the record as "tracked" from within Outlook, even though synchronization would still occur with the item. Likewise, if the crmid property is changed to an invalid value, the “Show in CRM” button would no longer work correctly, as the add-in uses the value of this property to construct the URL back to the related CRM record.
Should these fields be altered, they can be corrected during the synchronization process if the same item has changed on the server. If the item has not been changed on the server, these fields will remain in a “broken” state and may not allow the add-in to perform necessary functions on the item, especially if the CRMID field has been changed. The reason for this behavior is that the add-in will not retrieve the corrected state of the record from the server if no changes have been made to the object in the application since the last synchronized time. As a result, manual manipulation of these fields can have unintended consequences and is not recommended.
For example, one issue that we see in support from time to time is when these fields are modified or dropped by 3rd party applications, such as smartphones that synchronize with the user’s mailbox. If these fields are modified or deleted, the mail server may create a duplicate (untracked) item in Outlook, or may alter the properties of the existing object in such a way that the item’s ribbon contextual buttons do not work as expected.
Often the User Defined fields can be used to help troubleshoot the synchronization status of an item. To view the user-defined fields, enable the Developer feature in Outlook:
Note: These instructions are for Outlook 2010
Afterwards, the user defined fields for a tracked item can be viewed by completing these steps:
Hi Aaron, thank you for these two posts. They are great! Do have anything on the synchronization process for tracking emails? One of our clients is experiencing inconsistent behavior with their synchronization and understanding what happens behind the scenes would really help us out.
Never mind, I just found your email Tracking series :) Thanks again.