Line in The Sand For Exchange and IBM Notes Sync Policies

  • Updated

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 emails) 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 presents unique Riva challenges that should be planned to ensure minimal disruption of the 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 Transaction 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 anymore 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 send 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 into 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.

    ResolutionContact the Riva Success Team.

  • SCENARIO 5: A mailbox migration has been 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 (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:

Custom Option Key

Example of Value

Explanation

Sync.Crm.MinStartDate.Appointment

2024-01-01

Date format: YYYY-MM-DD.

This key is used to ignore any appointments in the CRM before the specified date. This key is looking specifically at the "Sync Start Date" of the calendar item.

Sync.Crm.MinStartDate.ForCreates 2024-01-01

Date format: YYYY-MM-DD.

This key is used to ignore any appointment created in the CRM before the specified start date. This key is looking specifically at the "Sync Start Date" of the calendar item when the item is being created.  The ultimate goal is to block updates and deletes on older appointments but still allow creations.

Sync.Crm.MinStartDate.Custom* 2024-01-01

Date format: YYYY-MM-DD.

This key is used to ignore any custom calendar item created in Exchange or Notes before the specified start date. This key is looking specifically at the "Sync Start Date" of the calendar item when it is being created. The ultimate goal is to block updates and deletes on older appointments, but still allow creations.

Note: Replace the asterisk (*) with the custom module's number.
Example: Sync.Crm.MinStartDate.Custom1

Sync.Crm.MinStartDate 2024-01-01

Date format: YYYY-MM-DD.

This key is used to ignore ALL calendar module created (including custom modules) in Exchange or Notes before the specified start date. This key is looking specifically at the "Sync Start Date" of the calendar item when it is being created. The ultimate goal is to block updates and deletes on older appointments but still allow creations.
 

Sync.Ex.MinStartDate.Calendar

2024-01-01

Date format: YYYY-MM-DD.

This key is used to ignore any appointments in Exchange or Notes before the specified date. This key is looking specifically at the "Sync Start Date" of the calendar item.

Sync.Ex.MinStartDate.ForCreates 2024-01-01

Date format: YYYY-MM-DD.

This key is used to ignore any appointment created in Exchange or Notes before the specified start date. This key is looking specifically at the "Sync Start Date" of the calendar item when it is being created. The ultimate goal is to block updates and deletes on older appointments but still allow creations.

 

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:

Custom Option Key

Example of Value

Explanation

Sync.Crm.MaxAgeDays

30

0

Date format: number.  If the value is "0", the filter is disabled.

This key is used to ignore any appointments in the CRM before today and past the maximum number of days. It assumes that today's date is the MinStartDate and the number specified is the number of days into the future. This allows for a "rolling MinStartDate" with a maximum number of days. The polled results are based on the user's CRM time zone (not UTC).

Sync.Crm.MaxAgeDays.ForCreates

30

0

Date format: number. If the value is "0", the filter is disabled.

This key is used to ignore any appointment created in the CRM before today and past the maximum number of days. It assumes that today's date is the MinStartDate and the number specified is the number of days into the future. This allows for a "rolling MinStartDate" with a maximum number of days. The ultimate goal is to block updates and deletes on older appointments but still allow creations. The polled results are based on the user's CRM time zone (not UTC).

Sync.Ex.MaxAgeDays

30

0

Date format: number.  If the value is "0", the filter is disabled.

This key is used to ignore any appointments in Exchange or Notes before today and past the maximum number of days. It assumes that today's date is the MinStartDate and the number specified is the number of days into the future.  This allows for a "rolling MinStartDate" with a maximum number of days.

Sync.Ex.MaxAgeDays.ForCreates

30

0

Date format: number.  If the value is "0", the filter is disabled.

This key is used to ignore any appointment created in Exchange or Notes before today and past the maximum number of days. It assumes that today's date is the MinStartDate and the number specified is the number of days into the future.  This allows for a "rolling MinStartDate" with a maximum number of days. The ultimate goal is to block updates and deletes on older appointments but still allow creations.

 

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 created 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 created 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 sync only appointments going forward for a certain date.

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

Custom Option Key

Example of Value

Explanation

Sync.Ex.SyncStartTimeOverride.[module]

Sync.Ex.SyncStartTimeOverride.Calendar
Sync.Ex.SyncStartTimeOverride.Phone_Call

2024-01-01

Date format: YYYY-MM-DD.

Works against the "MOD" date of the calendar item.

This advanced option overrides the default "Sync Start Time" in the policy. Only appointments modified after this date in Exchange or Notes will be synced to the CRM.

Sync.Crm.SyncStartTimeOverride.[module]

Sync.Crm.SyncStartTimeOverride.Appointment
Sync.Crm.SyncStartTimeOverride.Phone_Call

2024-01-01

Date format: YYYY-MM-DD.

Works against the "MOD" date of the calendar item.

This advanced option overrides the default "Sync Start Time" in the policy. Only appointments modified after this date in the CRM will be synced to Exchange or Notes.

Sync.Crm.FirstSyncDateTimeOverride.[module]

Sync.Crm.FirstSyncDateTimeOverride.Appointment
Sync.Crm.FirstSyncDateTimeOverride.Phone_Call

2024-01-01

Date format: YYYY-MM-DD.

Works against the "CREATE" date of the calendar item.

This advanced option overrides the default "Sync Start Time" in the policy. Only appointments created on or after this date in the CRM will be synced to Exchange or Notes.

Sync.Ex.FirstSyncDateTimeOverride.[module]

Sync.Ex.FirstSyncDateTimeOverride.Appointment
Sync.Ex.FirstSyncDateTimeOverride.Phone_Call

2024-01-01

Date format is YYYY-MM-DD.

Works against the "CREATE" date of the calendar item.

This advanced option overrides the default "Sync Start Time" in the policy.  Only appointments created on or after this date in Exchange or Notes will be synced to the CRM.

Sync.Crm.ShouldFirstPollUseDate.[module]

Sync.Crm.ShouldFirstPollUseDate.Appointment
Sync.Crm.ShouldFirstPollUseDate.Phone_Call

True or False

If this advanced option is set to false, the initial sync will use the "Modified Date" instead of the "Start Date"

 

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 an 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.

Custom Option Key

Value

Explanation

Sync.Crm.FirstSyncExistingItemOption.Calendar

SyncToCrm

This option prevents "Lost & Found" for calendar items when performing a first-time sync from CRM to Exchange or IBM Notes. Riva will leave pre-categorized calendar items in the primary calendar. Users need to be advised that Riva will no longer sync calendar items scheduled to start before the MinStartDate.

NOTE: Since we are preventing the Lost and Found from happening, any appointment modified after the "Sync Start Date" specified above will be duplicated in the CRM.

 

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.

    NameTab.png

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

    lookup.png

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

    metadatakb1221.png

  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: 

UserLineInTheSand.png

Was this article helpful?

/