Developing Duplicate Check Objects

An important aspect of maintaining data integrity is to identify duplicate records before they are added into the system. Aptify provides a mechanism that checks for possible duplicates when users save new records. This helps avoid a situation where the same person, item, or event has multiple records within the system.

However, since what may be considered as a duplicate will vary from entity-to-entity and from organization-to-organization, a developer must write a duplicate check plug-in object for each entity for which the organization wants to enable this feature.

This topic includes the following sub-topics, which provide information about Aptify's duplicate checking procedure and describe how to write a new duplicate check plug-in object:

• Writing a Duplicate Check Plug-In Object
• Adding a Duplicate Check Plug-In Object to an Entities Record

Writing a Duplicate Check Plug-In Object

To write a duplicate check object in Aptify, a developer writes code that implements the IAptifyDuplicateCheck interface to define the criteria for absolute and/or potential matches. IAptifyDuplicateCheck is an interface in the Aptify.Framework.BusinessLogic.GenericEntity namespace (see the Aptify Software Development Kit (SDK) for more information on this interface).

Also, the code typically references a stored procedure that contains the match logic. As described in Use Stored Procedures to Retrieve Database Values, Aptify recommends that developers use stored procedures where possible rather than include SQL statements directly within a plug-in object's code.

The IApifyDuplicateCheck interface has two members that serve the following purposes:

• CheckForDuplicates Method: This method is responsible for checking for duplicate records against the data in the pending record within the current GE. Aptify recommends that you use a parameterized data table to provide input values for a stored procedure that contains the matching logic. Based on the data table created by the stored procedure's execution, the method then returns a duplicate check result (None, Potential, or Exact) and the set of Duplicate record IDs.
• DuplicateMessageObject Property: This property identifies the object that corresponds to the duplicate message dialog to display when the CheckForDuplicate method has identified one or more duplicate record matches. To use the standard message box provided by Aptify (whose functionality and appearance is described in Enabling the Duplicate Record Check for a Service), this property should return Nothing. See About the Sample Application Duplicate Check Objects for an example.

This topic contains the following sub-topics:

• About the Sample Application Duplicate Check Objects
• Bypassing the Duplicate Check Process
• Creating a Dupe Check Class

Bypassing the Duplicate Check Process

Aptify provides the ability to bypass the duplicate check process or override the return value of the Generic Entity's CheckForDuplicates method. To implement this functionality, Aptify supports the following optional flags, specified by temporary fields:

• _xBypassDuplicateCheck: This temporary field is used to bypass the duplicate check process and supports the following values:
  • If this temporary field exists and has non-zero value, the duplicate check will not be executed and the result will be returned.
  • If the field doesn't exist or is any other value than 1, the standard duplicate check will occur.
    
    
• _xOverrideCheckForDuplicatesResult: This temporary field is used to override the return value of the duplicate check process.
  • If this temporary field exists and has a value of 2 or FalseOnPotentialMatch, the CheckForDuplicates method will return False when one or more Potential matches exist. All other results will not be changed from the standard logic.
  • If the temporary field exists and has a value of 1 or AlwaysTrue, the CheckForDuplicates method will return True, regardless of the duplicate check result.
  • If the temporary field exists with a zero value or AlwaysFalse, the CheckForDuplicates will return False, regardless of the duplicate check result.
  • If the temporary field doesn't exist, the CheckForDuplicates method will return the standard duplicate check result. Note that when this temporary field exists, DisplayDuplicateMessage will not be called since the field is providing a value that cannot be overridden by the user.

Creating a Dupe Check Class

The following steps provide an overview of how to write a duplicate check object for Aptify:

If using the template provided by Aptify for this project, configure the template as described in Loading the Sample Code and Templates, rename the project and class as necessary, and skip to Step 9

1. Open a new Class Library project in Visual Studio.
2. Configure the Properties for the project.
   • When assigning an assembly name for this object, use this format: [EntityName]DupeCheck (remove spaces in the entity name). For example: VehicleModelsDupeCheck (or SampleVehicleModelsDupeCheck, as shown below).
   • Specify a root namespace for your project. For example: Aptify.SampleApplication.MotorLoaner, as shown below.
     
     
3. Click the References tab in the Properties page and add a reference to the following Aptify objects:
   • AptifyApplication
   • AptifyAttributeManagement
   • AptifyExceptionManagement
   • AptifyGenericDataServices
   • AptifyGenericEntityBase

   • IAptifyDataServices

     References to the following Microsoft Objects should already exist in the project: System, System.Data, and System.Xml. You can find the Aptify objects in your Aptify Windows application's C:\Program Files\Aptify 5.5 directory.

4. Open the class file.
5. Add Option Explicit On and Option Strict On at the top of the class file (as described in Use Option Explicit and Option Strict.
6. Import the following namespaces into the class:
   • Aptify.Framework.BusinessLogic.GenericEntity
   • Aptify.Framework.DataServices
   • Aptify.Framework.Application 
7. Define the name for your class (typically this is Public Class [Object Name]).
8. Add Implements IAptifyDuplicateCheck below the class name to specify that this class will implement that interface to create a duplicate check object.
   
   
9. Write a function to implement the CheckForDuplicate method for your object.
   • As described previously, Aptify recommends that you write a stored procedure to check for matching records and add this stored procedure to the database. The stored procedure should receive its input parameters from your CheckForDuplicate function.
   • See About the Sample Application Duplicate Check Objects, the sample application source code, and Use Stored Procedures to Retrieve Database Values for more information and examples.
10. If you are planning to use the standard Duplicate Check dialog box, configure the DuplicateMessageObject Property to Return Nothing.
    • See the sample applicable source code for examples.
11. Build, test, and sign the assembly. See Best Practices When Writing Code for Aptify for details.
    • See Adding a Duplicate Check Plug-In Object to an Entities Record for instructions on how to add the object to the Aptify system.

Adding a Duplicate Check Plug-In Object to an Entities Record

After you have built the duplicate check object's assembly file, you need to add it to Aptify as a plug-in. Follow these steps:

1. If you not done so already, add the stored procedure you wrote for the duplicate check object to Aptify by creating a Database Objects record within Aptify.
   • See Creating Database Objects for information on the Database Objects service.
   • When you add a new Database Objects record to Aptify, the system automatically creates the database object in SQL Server. 
2. Open the entity's record in the Entities service. (This is the entity for which you created the dupe check plug-in.)
3. Click the entity's DB Objects tab and add the Database Objects record for the stored procedure you wrote for the dupe check object.
   • Following this practice ensures that all objects required for the entity to function correctly are referenced within the Entities record. Also, when you use the Entity Packer to pack an entity, the wizard automatically includes any Database Objects referenced on this tab as part of the pack file.
   • In the example below, since the Vehicle Models dupe check object uses the spCheckForVehicleModelMatch stored procedure, this stored procedure has been added to the entity's DB Objects tab. (Note that the Usage field is for informational purposes only and is not required.)
     
     
4. Click the Plug-Ins tab.
5. Open a new Plug Ins sub-type record.
   • If the entity has an existing Entity plug-in and your new object inherits from that plug-in, open the existing Entity Plug Ins record. 
6. Select Duplicate Check from the Plug In Type drop-down list.
7. Click the Object Repository icon in the Object Name field to open the Select Object Repository Object dialog.  
   
   
8. Browse to the Object Package for your organization where you want to store the entity object (see Best Practices When Configuring Object Repository Objects for information on recommended naming and storing conventions).
9. Double-click the .NET Assembly (Private Deployment) Object Type.
   
   
10. Click the New button and browse to the location of the entity object's file.
11. Select the object you just added and click OK to return to the Plug In form. (The Object Name field is automatically populated with the Object Package.Object Name of the object you selected, as shown below.)
    
    
12. Enter the object's .NET assembly name in the Assembly Name field.
13. Enter the object's class name in the Class Name field.
    
    
14. Click OK.
15. Save and Close the Entities record.
16. Close and reopen the Aptify client.
17. Test the duplicate check object by attempting to save an absolute or partial match to an existing record (based on the match criteria you defined in the stored procedure).