Merge Client Setup
Learn how merge client works and find answers to commonly asked questions.
Written by Jessica Fleming
Updated at September 18th, 2024
Table of Contents
Overview
The Merge Client process merges two duplicate client records by first updating all transactional records associated with the Source Client ID to the Target Client ID. The Merge Client process will then set the active status of the Source Client to ‘D’ or Deleted. After the Merge Client process is complete, the Source Client record should no longer have information associated to it. All transactional records can now be found under the Target Client record. To find more information about how to add and manage merge records, please see the Merging Duplicate Clients article.
| Please Note: If any transactional records are created or edited on the Source Client record during the Merge Process, the merge will loop back through to merge the still active records with the Target Client ID. |
Process Flow
.png)
About Merge Client
Merge Status
A merge client record will cycle through the following merge status' depending on which part of the process the merge record is in.
- Unmerged (A) - This means that the Merge Setup record has been created, but the merge has not yet been scheduled.
- Added to Merge Queue (P) - This means that the Merge Setup record has been created & scheduled but the Merge has not yet begun.
- In Process (I) - This means that the asynchronous task has begun the Merge for this Merge Setup record.
- Error (E) - This means that the Merge Client process began but ran into an error with the batch of records
- Merged (M) - This means that the Merge Client process has been successful and completed the merge.
System Properties
System properties can be found within Global Administration > System Administration > System Properties
- ClientMerge-BatchSize - Sets the value for the number of merge records to be included in each batch for Merge. It is recommended that this number stays at or below 10 for optimal performance.
| Note: In larger implementations, the batch size may need to be reduced. This can be changed at any time by an administrator. |
- ClientMerge-GracePeriodInMins - Set the value for the grace period between when a Merge Record is added to the Queue and begins processing. This grace period is defined by the user allows downtime between creating the merge and the merge beginning to make any necessary changes.
User Permissions
User permissions for Merge Client can be found within User Management > Edit/Add New User > Tool Access Permissions > Feature Access
- Merge All Clients - Allows the user to merge any clients in the system.
- Merge Organization Clients - Allows the client to merge clients owned by the organization currently signed in under, if the user has been granted allowed to merge client in user organizations.
- Data Export, Data Import & Elevated API - Allows the user to edit or modify the scheduled tasks
Hourly Merge Settings
The hourly Merge task can be found within Global Administration > Batch Processes > Scheduled Tasks > Hourly Client Merge Cleanup > Edit
-
By default, the updated Merge Client process will run on an hourly basis from the hours of 6pm CT to 6am CT. These hours have been selected to avoid performance impacts during peak business hours.
-
Users may update the hourly merge settings by modifying the Excluded Hours on the Edit task form. Users may add additional excluded hours, or modify the existing hours selected. Any rows with a checkmark are hours that are excluding the Hourly Client Merge Cleanup task from running. To allow the Hourly Client Merge Cleanup task to run, remove the exclusion from the applicable rows.
| Note: Modifying the hourly merge settings is possible, but may negatively impact the async worker and performance during peak business hours as the Merge procedure will be sequenced amongst reports, exports, and other items that are dependent on the async worker. |
Validations
There are several validation checks built into the Merge Client procedure. Below are the warning messages a user may receive and what to do.
Warning/Error: One of the users, <user name>, that scheduled a merge does not have access to merge clients that aren't owned by the organization that owns the Client. You will need to remove these pending merge(s) and schedule again.
Reasoning: Users are required to have special permissions to be able to complete the merge process to protect client level data from being erroneously merged. The Merge Client forms in ClientTrack have several layers of security and access restrictions to ensure that security. If a user is able to access a Merge Client form without having the correct user permissions, the Merge Client form may be missing the necessary access restrictions.
Next Steps: Please review the user permissions of the User to determine if they have the Merge All Clients and/or Merge Organization Clients checked. If users don't have these checked, the user should not be able to access the form. Please ensure the form used is either a baseline form, or a configured form with the correct access restrictions.
Warning/Error: The same source client is set to merge multiple times. Please review the merge records and remove the duplicate.
Reasoning: When a source client is set as a Source Client in multiple records, the merge client process would need to map the transaction records to more than one target client. This cannot happen because after the merge is complete, the source client is set to ‘D’/Deleted, so the second merge record would have no transactional records to merge into the second target client.
Next Steps: Users should check the merge records on the Merge Client History form (FormID 1402) to determine where the same source client is set to merge multiple times.
Warning/Error: Record(s) cannot be added to the Merge Queue because the Source Client is part of another merge record that is still in the Merge Queue.
Reasoning: If a client is identified as a Target in one merge record, but a Source Client in another merge record, the system would be attempting to merge into the Target Client at the same time it's trying to delete the Source Client. In this situation, the merge process would miss records for merge and may delete the Source Client before the second merge is completed.
Next Steps: Users should review the merge records to determine where the Source Client is also listed as a Target Client for another merge record using the Merge Client History form (FormID 1402)
Warning/Error: A Target Client in the batch is not active.
Reasoning: If a target client is ‘D’/Deleted, then any of the Source Clients' active services, enrollments, referrals, etc. would be associated with a ‘D’/Delete client. This means end users would lose access to manage those active transaction records.
Next Steps: Review the batch of merge records on the Merge Client History form (FormID 1402) for the Target Client who is set to ‘D’/Deleted. Update the Merge Record to an active Target Client, or restore the deleted Target Client and re-add the merge record to the Merge Queue.
Frequently Asked Questions (F.A.Q.)
What is different about the new Merge Process?
- The process is now completely asynchronous and runs via an hourly task by the async worker. This process can no longer be scheduled or run on demand.
- Merge language has been updated to clarify Source and Target Clients.
- Additional validation checks have been added
- Additional Merge Status' have been added to clarify where the Merge is in the process
What do each of the Merge Status' mean?
- Unmerged (A) - This means that the Merge Setup record has been created, but the merge has not yet been scheduled.
- Added to Merge Queue (P) - This means that the Merge Setup record has been created & scheduled but the Merge has not yet begun.
- In Process (I) - This means that the asynchronous task has begun the Merge for this Merge Setup record.
- Error (E) - This means that the Merge Client process began but ran into an error with the batch of records
- Merged (M) - This means that the Merge Client process has been successful and completed the merge.
We use the baseline Merge Client forms & process, what should we do to use the updated Merge Process?
If your implementation uses the baseline Merge Client forms (FormID's 1402, 1403, & 3636), you will not need to do anything. The new baseline procedure & status' will be deployed on August 13, 2024 to all environments.
We use a custom Merge Client form & process, what should we do to use the updated Merge Process?
If your implementation uses a custom Merge Client form or links to the Merge Client process from a different location, users will need to either revert back to the baseline forms or update the button to use the updated procedure (merge_Clients). The deprecated merge client procedure will display an error message after the August 13 deployment that instructs users to return to the baseline Merge Client forms & procedures.
What about my existing clients slated for merge?
Administrators should refrain from scheduling any new merges beginning in the morning of August 13, 2024, lasting until the deployment has completed.
How often will the Merge Client process run?
The updated Merge Client process will run on an hourly basis from the hours of 6pm CT to 6am CT. To avoid performance impacts during peak business hours, the asynchronous task will not run from 6am CT to 6pm CT. If users need to modify the exclusionary hours, please review the Exclusionary Hours section above.
How many clients can be merged at one time?
Eccovia recommends keeping the total clients merged at one time at or below 10 for optimal performance. In implementations with large numbers of clients and service records, users may need to lower the number of clients merged at one time. There is a new system property that will allow Client Admins, Eccovia Admins, and/or ClientTrack Support to modify the Client Merge Batch Size.
What happens if my Merge Client process shows a status of ‘Error’?
If the merge process encounters an issue while merging a batch of clients, the entire batch of clients will receive an Merge Status of 'E' / Error. Users should navigate to the Merge Client history form (FormID 1402), select the Merge Status of Error, and add the clients back to the Merge Queue.
Can I add a merge record, created by a team member, to the Merge Queue?
No, only merge records created with your UserID can add the merge records to the merge queue. This is a security measure to ensure consistency from beginning to end of the merge process.
Are there situations in which a user shouldn't merge a duplicate client?
If the clients have different transaction restriction options, Restrict to Org versus Share Intake Globally. These clients should be carefully reviewed because merging the two records will change one of their transaction restrictions & may unintentionally restrict or share the clients' transactional records.
Two clients have been identified as a potential duplicate but they're not the same person. How do I get them to stop showing up on the Merge Multiple Duplicate Clients form?
Users can select Ignore ‘This is not the same person’ on the Merge Multiple Duplicate Clients form. By selecting Ignore, the clients will not appear as potential duplicates, and will instead appear on the Ignored Duplicates form (FormID ). If a user needs to restore the ignored client records, they may ‘Delete’ the ignored duplicate record. The client records will then appear on the Merge Multiple Duplicate Clients form (FormID 3636) and be eligible for merge again.
