Line in the Sand for Exchange and IBM Notes Sync Policies

Riva sometimes reports sync errors related to identification numbers being mismatched or missing. This article discusses some of those circumstances and explains how Riva can be reconfigured to restore data sync.

What Is All the Fuss About

CRMs and email systems save items (like messages, appointments, and email) into databases as unique records. Each record is assigned a unique ID, which is normally a long character string that is not visible to users. Those IDs are referred to by different titles (GlobalID, itemID, crmID, folderID, etc.). Riva uses those IDs to locate items that need to be created, modified, or deleted.

Riva maintains transaction records for data that has been synchronized for each user. Those transaction records

• record a relationship between the Object ID of the Exchange item (contact, appointment, task, or email) and the Object ID of the corresponding CRM item
• record the GlobalID of each Exchange calendar items Riva synced
• record the FolderID of the Exchange folder in the user's mailbox where items are stored (specifically the Contact folder, primary calendar folder, task folder, Inbox, Sent Items folder, and the entire Riva created folder structure used for manual email sync
• record the GUID of the user mailboxes that Riva is syncing
• record the date-time stamp when the item was last created, updated, or deleted and then synced by Riva

Any significant Exchange system change can impact the Riva transaction records and how Riva will behave. Each of the above scenarios present unique Riva challenges that should be planned to ensure minimal disruption of Riva sync service for users. If Riva cannot find the applicable item or folder ID when attempting to sync, Riva will normally report an error and stop syncing the user.

How Are ID Issues Resolved?

Typically, when Riva detects challenges with mismatched IDs, Riva needs to be reconfigured to run a first time sync.

What happens when Riva syncs replacement data from the CRM

When Riva performs a first time sync for each user, Riva always checks the user mailbox to see if any items are categorized with the category name that is configured in the sync policy. If it finds categorized items, it assumes that Riva or some other sync process has synced those Exchange items with corresponding items in the CRM; and Riva moves those items to "Lost & Found" containers in the mailbox. Specifically:

• Contacts and leads are moved to a "Lost & Found" contacts folder, and a fresh copy of every CRM contact and lead is created in the designated CRM sync contact folder.

• Task items are moved to a "Lost & Found" task list, and a fresh copy of every CRM task item is synced to the user's primary task list from their Salesforce task list.

• Email residing in Riva drop folders (for example, "\<Category Name>\- Create New Email") are moved to a "Lost & Found" folder.

• Calendar items are moved to a "Lost & Found" child calendar, and a fresh copy of every CRM calendar item is synced to the user's primary Exchange calendar.

Note: On the first sync, Riva uses the "StartDate" for appointments and not the "ModifiedDate". After the first sync, Riva will use the "ModifiedDate".
 

Challenges with Lost & Found Calendar Items

When Riva moves previously categorized calendar items to the "Lost & Found" child calendar, the original calendar items are moved. Riva creates a "copy" of the calendar item in the primary calendar. Here are two problem scenarios:

• Recurring Series - A user creates a recurring series appointment or meeting in Exchange or Notes. Riva normally syncs those to the CRM and creates a set of single appointments or meetings in the CRM. Riva syncs the calendar items, not the rule set. If you look at those calendar items in the CRM, they do not appear as a recurring series. When a first time sync is performed to fix ID mismatch errors, the original series is moved to "Lost & Found". The user loses the ability to manage the original recurring series in Exchange.

• Meetings - A user creates a meeting (an appointment with multiple attendees) in Exchange or Notes, and Riva syncs that to the CRM as a meeting with the attendee list. When a first time sync is performed to fix ID mismatch errors, the original meeting (with acceptance tracking) is moved to "Lost & Found". Riva syncs an appointment into Exchange or Notes that has an attendee list but not the acceptance tracking info. If the user updates the new copy of the meeting, Exchange or Notes sends a new meeting invitation to the attendees. Each attendee's calendar ends up with two meetings for the same meeting.

To overcome such challenges, a "Line in the Sand" procedure and a clean-up process can be implemented.

What Is a "Line in the Sand"

The expression "Line in the Sand" refers to setting a cut-off date for calendar items so that the syncing of those items does not occur before a defined date. This is designed to reduce the amount of data syncing from the CRM to the email platform when a "New Sync" occurs.

Sometimes when Riva is syncing user data, the Exchange or Notes calendar can become corrupt or something happens to the mailbox where a reinitialization is required on the Calendar module.

Item mismatch conditions: Riva maintains Transactions metadata for each data item that has been synced and maps unique IDs between corresponding CRM and email items. For example, Riva maintains a map of the Exchange or Notes appointment itemID and the corresponding crmID for calendar items. This enables Riva to keep track of what has been modified and whether to update that item in the CRM or the email platform.

FolderID mismatch conditions: Sometimes, something happens in the email system that changes the FolderID of the primary calendar. When that occurs, Riva reports a folder mismatch between what it previously recorded and what it discovers when attempting to sync calendar data. A reinitialization is required to remap the FolderID for the calendar.

However, sometimes the mapping to the Calendar module can become corrupt, which causes a new ID to be assigned to the Calendar folder in Exchange or IBM notes. As a result, Riva cannot map items any more to the Calendar module, and a reinitialization is required to remap these items.

When Riva remaps the IDs, it performs a "first time sync" of calendar items from the CRM to Exchange or IBM Notes. This results in the loss of the Exchange or IBM Notes format of calendar items. This is important because the format of Exchange or IBM Notes items (appointments that originate in Exchange or IBM Notes) allows you to sent updates to attendees or request new times and allows the organizer to schedule new times, etc.

When Riva does its "first time sync", it cannot reproduce the Exchange or IBM Notes format of the appointment. It creates the appointment with no organizer and attaches the attendees as contacts on the appointment. Therefore, you could not send any updates or have the appointment linked to other people's Exchange or IBM notes appointments.

This is where the "Line in the Sand" comes in to play, allowing you to retain the Exchange or IBM Notes formats of appointments and allowing you to set a cut-off date for appointments that no longer need syncing. This reduces the amount of data that Riva needs to sync on the first cycle.

The purpose of the Line in the Sand is to preserve the Exchange or IBM Notes format of appointments.

Typical Scenario and configuration setup:

• Choose your "Min Start Dates" so that Riva ignores those calendar items before the specified date.
• Choose your "Sync Start Time Override" so that Riva overrides the calendar "Sync Start Date" and syncs appointments only going forward from that date.
• Choose whether or not you want to keep the Exchange or IBM Notes formats of the calendar items.

Line in the Sand Scenarios

Some reasons you might need the Line in the Sand:

• SCENARIO 1: FolderID mismatch conditions. The CRM Service Monitor reports an error that reads

  [XA] Previous folder ID does not match current folder ID. A reinitialization is required (An error that occurs when something happens to the mailbox). 

  Sometimes, something happens in the email system that changes the FolderID of the primary calendar. When that occurs, Riva reports a folder mismatch between what it previously recorded and what it discovers when attempting to sync calendar data. A reinitialization is required to remap the FolderID for the calendar.

  Resolution: This requires a "Line in the Sand" on just the calendar module.

• SCENARIO 2: A reinitialization is needed to correct some other underlying issue.

  Riva reports item ID mismatch errors or is unable to locate itemIDs of items that it is trying to sync from the CRM to the email system. There is no defined cause of this, but it is pronounced and prevents accurate syncing of data for that user.

  Resolution: This requires a "Line in the Sand" for the affected modules (or the entire mailbox).

• SCENARIO 3: Adjusting calendar Sync Start Dates

  The "Line in the Sand" custom option keys can be used for setting sync start date filters for calendar items that no longer need to be synced.

  Resolution: Apply option keys to adjust the Sync Start Date for calendar sync to meet the new requirements.

• SCENARIO 4: CRM data and users are moved to a different Vendor CRM or the Salesforce organization is upgraded to a different edition (for example, from Professional to Enterprise or Unlimited).

  When a customer switches to a different vendor CRM solution (or upgrades Salesforce), the crmIDs change and no longer match the Riva transaction metadata records.

  Resolution: Contact the Riva Success Team.

• SCENARIO 5: A mailbox migration has completed, and the Unique IDs have changed.

  Depending on the type of migration, email items may lose their Unique IDs, which would result in requiring a "Line in the Sand" approach. This is the last resort for a mailbox migration to maintain the original format.

Line in the Sand Procedure

Certain advanced options can be added to the policy to retain the Exchange or IBM Notes format of appointments. These keys can be applied at the policy level or user level.

We highly recommend contacting the Riva Success Team for this procedure.

For instructions on applying the advanced options, see Setting advanced options.

• Min Start Dates

• Rolling Min Start Date + Days

• Min Due Dates

• Min Create Dates

• Sync Start Time Overrides

• Prevention of Lost and Found

• Calendar Metadata deletion

• Example configuration

• Alternate Line in the Sand

Min Start Dates (Calendar)

The "Min Start Dates" specify the cut-off point for the "Line in the Sand", which means that any appointment before the date set will no longer be synced by Riva.

When to use Min Start Dates:

• When you want to retain the Exchange or IBM Notes format of calendar items and you want to ignore calendar items before a specified date. Something happened to the Calendar module.

• When you want to set a date to ignore items in the past, or prevent users from updating appointments and causing them to sync that happened in the past.

• When you want to reduce the number of Calendar items that will be synced from the CRM on the first sync.

• When the appointment format is still in the original state, and you want Riva to just ignore these items.

The advanced options can be applied at the user level or policy level. For instructions, see Setting advanced options.

Any appointments before the "Date" set below will not be synced by Riva anymore:

NOTE: Please choose the dates carefully, because Riva will ignore everything before the date you choose.
 

Rolling Min Start Start Date + Days (Calendar)

The "Min Start Dates" specify the cut-off point for the "Line in the Sand", which means that any appointment before the date set will no longer be synced by Riva.

When to use Min Start Dates:

• When you want to retain the Exchange or IBM Notes format of calendar items and you want to ignore calendar items before a specified date. Something happened to the Calendar module.

• When you want to set a date to ignore items in the past, or prevent users from updating past appointments and causing them to sync.

• When you want to reduce the number of Calendar items that will be synced from the CRM on the first sync.

• When the appointment format is still in the original state, and you want Riva to just ignore these items.

The advanced options can be applied at the user level or policy level. For instructions, see Setting advanced options.

Any appointments before today's date will not be synced by Riva anymore:

Min Due Dates (Tasks)

The "Min Due Dates" specify the cut-off point for the "Line in the Sand", which means that any task that is due before the date set will no longer be synced by Riva.

Important: This filter also ignores all tasks that do not have a defined due date.

Custom Option Key	Example of Value	Explanation
Sync.Crm.MinDueDate	2024-01-01	Date format: YYYY-MM-DD. This key is used to ignore any tasks in the CRM before the specified due date. This key is looking specifically at the "Due Date" of the task item. Riva will ignore tasks with due dates before the specified date and all tasks with no specified due date.
Sync.Ex.MinDueDate	2024-01-01	Date format: YYYY-MM-DD. This key is used to ignore any tasks in the email system before the specified due date. This key is looking specifically at the "Due Date" of the task item. Riva will ignore tasks with due dates before the specified date and all tasks with no specified due date.

Min Create Dates

Two options cause Riva to ignore items based on the "Create Date".

Custom Option Key	Example of Value	Explanation
Sync.Crm.MinCreateDate.Appointment	2024-01-01	Date format: YYYY-MM-DD. This key is used to ignore any appointments in the CRM before the specified create date. This key is looking specifically at the "Creation Date" of the calendar item.
Sync.Ex.MinCreateDate.Calendar	2024-01-01	Date format: YYYY-MM-DD. This key is used to ignore any appointments in Exchange or Notes before the specified create date. This key is looking specifically at the "Creation Date" of the calendar item.

Sync Start Time override

The "Sync Start Time Override" provides Riva with a way of specifying a new date that will be used on the "first sync" of calendar items. Instead of using the "Sync Start Time" on the policy, Riva will use the new date specified to start the syncing of calendar items.

When to use the "Sync Start Time Override"

• When you need to perform a "Line in the Sand" to keep the format of  Exchange or IBM Notes appointments. The "Sync Start Time Override" can be used to override the sync start time in the policy and will prevent any items to not sync before this date.  

• When used with the "Min Start Dates", since those dates specify that appointments be ignored before the specified date, the "Sync Start Time Override" will prevent any items from syncing to Exchange or IBM Notes before those dates.

• If you are doing a first time sync and you want to only sync appointments going forward for a certain date.

The advanced options can be applied at the user level or policy level. See Applying advanced options.

Prevent Lost and Found  

When Riva does a first sync, it always checks for the category name in the calendar. Riva then moves all of the items from the calendar to a Lost and Found. The following advanced option is used during the first sync and prevents moving items to a Lost and Found folder.

When to prevent the Lost and Found:

• When you are doing a first time sync for the "Line in the Sand" with a ID changing on the Exchange or IBM Notes calendar.

• When used with the "Min Start Dates" and the "Sync Start Time Override", after the previous advanced options are set, Riva begins its initial sync after those dates specified. Whereas normally Riva would put these items in a Lost and Found, this advanced option prevents that from happening.

The advanced options can be applied at the user level or policy level. See Setting advanced options.

Delete calendar metadata

When Riva encounters an error with the calendar module, a Full-Reinit Delete will only do a resync. The calendar metadata must be deleted in order for the Line in the Sand to work properly:

1. Stop the service.

2. Do one of the following:

   • In Windows Explorer, navigate to the Riva installation directory, for example C:\Program Files\Riva. Navigate to the Transactions folder and then to its child folder Lookup; or

   • In the Riva Manager application, on the main menu, select Policy. Double-click the CRM policy. While holding down the CTRL key, double-click Name.

   

   The Lookup folder displays one subfolder per user. The subfolder's name uses an email format such as test$microsoft$com.

   

3. Open every user's subfolder, and delete the Calendar.metadata file.

   

4. Start the service.

Example configuration

User A reported receiving the error "[XA] Previous folder ID does not match current folder ID. A reinitialization is required."

The current "Sync Start Time" on the policy is set to 2020-01-01 or January 1st, 2020. The user wants to retain the Exchange format of the calendar items, and the current date is 2020-03-31 or March 31st, 2020. The following process takes place:

1. The user stops the service.

2. The user decides to ignore all appointments before 2020-02-01 or February 1st, 2020, and sets the following advanced options on the policy or user level:

   • Sync.Crm.MinStartDate = 2020-02-01

   • Sync.Ex.MinStartDate = 2020-02-01

   Riva will ignore any appointments or calendar items before these dates.

3. The user decides to override the "Sync Start Time" on the policy to sync only appointments modified after 2020-03-31 or March 31st, 2020. The user sets the following advanced options at the policy or user level:

   • Sync.Ex.SyncStartTimeOverride.Appointment = 2020-03-31

   • Sync.Crm.SyncStartTimeOverride.Appointment = 2020-03-31

   Anything modified after this date will be synced to the CRM and Exchange or Notes. Any appointments that currently exist in the user's calendar when modified will be duplicated in the CRM. However, the Exchange or Notes format will be retained.

4. The user applies the following advanced option to prevent the Lost and Found from happening:

   • Sync.Crm.FirstSyncExistingItemOption.Calendar = SyncToCrm

5. The user sets the option that makes the first sync based on the mod date and ensures that the SyncStartTime overrides the policy start time.

   • Sync.Crm.ShouldFirstPollUseDate.Appointment = true

6. The user deletes the metadata from the transactions folder.

7. The user starts the service.

   Riva creates new metadata files. On the first sync, Riva does not create a Lost and Found.

   On the second sync cycle, the "SyncStartTimeOverride" takes effect for the syncing of calendar items.

This is what the user's advanced options would look like in the Riva Manager application: