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.
IMPORTANT WARNING: The files contained in the transaction folders are specially formatted data files and must not be opened with a text editor or office application. Doing so may corrupt those files and cause sync issues. Work in the Riva\Transactions folder structure must only be performed by Riva personnel or under their supervision. Do not move or delete any transaction files or folders unless advised to do so by Riva personnel.
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
Any significant email system or CRM system change can impact the Riva transaction records and how the sync is done. Examples:
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 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 188.8.131.5211 and 184.108.40.20612, the sync policy transaction folders are created in a new format for the transactionID and the corresponding folder name.
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 firstname.lastname@example.org.
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.
IMPORTANT WARNING: The files contained in the user transaction folder are specially formatted data files and must not be opened with a text editor or office application. Doing so may corrupt those files and cause sync issues.
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:
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 are maintained in the Riva\Transactions\Global\Default\[VendorCrmName] folder.
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.
Duplicating a sync policy is performed in the Riva Manager application and results in the following actions:
Deleting a sync policy is done in the Riva Manager application and results in the following actions:
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.
Article ID: 1493
Last updated: 06 Sep, 2017