Understand How Riva Maintains Transaction Records

Audience: Project Team Leads and Riva Administrators.

The purpose of this article is to provide a basic understanding of the Riva transaction records that are maintained for users assigned to a sync policy. Transaction records are used to maintain the validity of transactions so that duplicate information is not created in the user's CRM account or email mailbox.

Contents:

• What is all the fuss about;
• The Transaction folder structure;
• Types of transaction records:
  • User transaction records,
  • Global transaction records,
  • Common transaction records;
• What happens when a sync policy is duplicated;
• What happens when a sync policy is deleted.

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; for example, GlobalID, itemID, crmID, or folderID. In Riva, those IDs are used to locate items that need to be created, modified, or deleted.

Riva transaction records are maintained for data that has been synced for each user. Those transaction records

• record a relationship between the Object ID of the mailbox item (contact, appointment, task, or email) and the Object ID of the corresponding CRM item;
• record the GlobalID of each email-system meeting item that has synced;
• record the FolderID of the folder in the user's mailbox where items reside (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 synced by Riva; and
• record the date-time stamp when the item was last created, updated, or deleted and then synced by Riva.

Any significant email system or CRM system change can impact the Riva transaction records and how the sync is done. Examples:

• Changing domain names in email addresses,
• Migrating mailboxes from on-premises servers to hosted email services, or
• Changing CRM vendors.

Whenever an email system or CRM system change results in the modification (in that system) of the unique IDs of previously synced items, unique challenges arise. Such email or CRM system changes should be planned to ensure minimal disruption of the Riva sync service for users. If the applicable item or folder ID cannot be found when the sync is attempted, the system normally reports an error and stops syncing the user.

The Transaction folder structure

The system maintains a transaction folder structure that contains the transaction data files:

Transaction folders are related to sync policies and are named to match the transactionID value in the sync policy file.

Starting with Riva 2.4.40.23911 and 2.4.41.23912, the sync policy transaction folders are created in a new format for the transactionID and the corresponding folder name.

Types of Transaction Records

There are three types of transaction records:

• user,
• global, and
• common.

User transaction records

When a user is added to a sync policy and is synced for the first time, the system accesses the Lookup folder and creates in it a unique user folder that matches the user's email address or the user's EntityName that is used in the sync policy file. For example, the GORDON.WELLING$RIVADEMO$ONMICROSOFT$COM folder matches the EntityName of gordon.welling@rivademo.onmicrosoft.com.

Each user transaction folder contains a set of .metadata files that store the records of the transactions for that module. For example, AddressBooks.metadata stores the records of the contacts synced for that user between the CRM and the email mailbox. The metadata-journal files store a temporary copy of the items that were synced during the previous sync poll. The entity.settings file contains information about the user entity, including the next scheduled sync date/time and the type of sync to perform.

Because user transaction records are created and stored against the sync policy transaction folder, a common challenge occurs when a Riva administrator removes a user from one sync policy and adds it to a different sync policy. The system considers the user that was added to the second sync policy as a new user, because it does not detect that the user has a transaction folder in another sync policy transaction folder. When a sync poll starts for the user in the second sync policy, it does not find transaction records for that user, it assumes that it is a new user, and it performs a first time sync to create a set of transaction folders. The unhappy result for the user is that the system moves all previously synced items to "Lost & Found" folders and syncs fresh copies of items into the primary locations.

To prevent such unhappy scenarios, it is important to understand two things:

• The location of user transaction folders and
• That to transfer a user between sync policies, the user's transaction folder has to be moved from the original sync policy transaction folder to the second sync policy transaction folder.

In this example, Riva administrators would move the GORDON.WELLING$RIVADEMO$ONMICROSOFT$COM folder from the \551416422\Lookup folder to the \ee4af307-daaf-443a-966f-58e2464a4f02\Lookup folder. For detailed instructions, see How to move users to a duplicated sync policy.

Global transaction records

Global transaction records are maintained in the Riva\Transactions\Global\Default\[VendorCrmName] folder.

• If users are syncing meetings (appointments with multiple invitees), global.metadata and global.metadata-journal files are created to record the meeting globalIDs.
• If two or more sync policies connect to the same vendor CRM, syncDestinations.metadata and syncDestinations.metadata-journal files are created to record which sync policy is syncing which user entity.

Common transaction folders

If multiple sync policies will be created and users will be added by using different distribution groups, we recommend implementing a common transaction folder structure. To have that structure configured for you, contact the Riva Success Team.

Common transaction records are maintained in the Riva\Transactions\Common folder.

In some scenarios, using common transactions files can make it easier to move users between policies. For more information, contact the Riva Success Team.

What Happens When a Sync Policy is Duplicated

Duplicating a sync policy is performed in the Riva Manager application and results in the following actions:

• A new disabled sync policy object is created in the Riva Manager application. It contains the same user list and all of the policy option settings as the original source sync policy.
• A new sync policy file is created. It uses a new transactionID.
• A corresponding sync policy transaction folder is created:

  • Starting with Riva 2.4.40.23911 and Riva 2.4.41.23912, an empty sync policy transaction folder is created.
    
    

  • In Riva 2.4.39 or earlier, a new sync policy transaction folder is created. It includes a Lookup folder that contains a user transaction folder for every user in the user list on the General page of the policy. Every user transaction folder contains a new Entity.settings file but no other files until the duplicate sync policy is enabled and the first Riva sync poll takes place.
    
    
    
    No user transaction metadata files are copied from the source sync policy to the duplicate sync policy. It is critical that the final steps for creating a duplicate sync policy be followed to prevent the unintentional sync of previously synced users.

What Happens When a Sync Policy is Deleted

Deleting a sync policy is done in the Riva Manager application and results in the following actions:

• The sync policy object is removed from the Policies view in the Riva Manager application.
• Only the .policy file is removed from the Riva\Configuration folder. The .policy.backup file is not removed.
• The sync policy transaction folder is left in place.

As long as the .policy.backup file and the corresponding sync policy transaction folder still exist, it is possible to recover from an accidental removal of a sync policy.