Writing an Entity Plug-In Object

Entity Objects that override or enhance the functionality provided by the Generic Entity should import the Aptify.Framework.BusinessLogic.GenericEntity namespace and inherit from the AptifyGenericEntity class. (See Aptify Generic Entity versus Aptify Generic Entity Base for a discussion on when to inherit from AptifyGenericEntity and when to inherit from AptifyGenericEntityBase.)

The majority of entity objects written by a developer will override the standard functionality of the following members of the AptifyGenericEntity class to supplement Aptify's standard functionality:

• Save
• Validate
• SetValue
• GetValue
• Events

In general, a developer will supplement the standard Aptify GE logic by either pre- or post-processing the logic in the GE's base functionality. The entity objects included with the sample application demonstrate how to override the Save and Validate methods to supplement the base GE functionality (as described below). See the AptifyGenericEntity class in the Aptify Software Developement Kit (SDK) for information on the other class members that can you can override.

• RentalAgreementObject Validate Method: The entity object for the Rental Agreements entity overrides the Validate method to impose additional logic to the entity field values depending on the current "state" of the Rental Agreement (for example, when in the check-out state, the check-in fields cannot be modified). See BPR19: Enforce Rental Agreement Consistency.
• RentalAgreementObject Save Method: The entity object for the Rental Agreements entity also overrides the Save method to automatically update a vehicle's status to Rented (following a check-out) or Available (following a check-in). The method also updates the vehicle's mileage for check-in operations. See BPR11: Automatically Track Vehicle Status and Mileage.
• ServiceTicketObject Save Method: The entity object for the Service Tickets entity is provided as an alternative implementation for the Vehicle Status Updater Process Flow, which automatically updates a vehicle's status to Available when a completed Service Ticket is approved and no other open tickets exist for the vehicle. Note that this entity object is not installed within the sample application (the sample application uses the process flow by default). Aptify provides the source code for this entity object so you can review how the same results can be achieved using either an entity object or a process flow.

The following steps provide an overview of how to write a new entity object for Aptify:

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]Entity (remove spaces in the entity name)For example: VehiclesEntity (or SampleRentalAgreementsEntity, 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
   • AptifyGenericEntity
   • AptifyGenericEntityBase
   • AptifyUtility

   • 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 Aptify.Framework.BusinessLogic.GenericEntity namespace and/or any other namespaces required for your object.Note: If writing an entity object for an Aptify entity that already has an existing entity object, you should import the namespace for that entity object. For example, if you creating a new entity object sub-class for the OrdersEntity object, import Aptify.Application.OrderEntry.
7. Define the name for your class (typically this is Public Class [Object Name]).
8. Add Inherits AptifyGenericEntity below the class name.Note: If writing an entity object for an Aptify entity that already has an existing entity object, you should inherit from that object rather than from AptifyGenericEntity. For example, if you creating a new entity object sub-class for the OrdersEntity object, inherit from OrdersEntity.
   
    
9. Write code to override the appropriate methods as needed.
   • Refer to the sample code for the RentalAgreementsEntity and ServiceTicketsEntity objects for examples of how to override the AptifyGenericEntity's Save and Validate methods.
   • If writing an entity object for a sub-type entity, Aptify recommends that you override the Validate method rater than the Save method. In this case, the system can notify a user with a pop-up dialog that the validation failed when he or she clicks the OK button on the sub-type form.
   • Also, when working with entity object sub-types, keep in mind that the object can access the parent GE through the Parent property.
      
10. Add any new protected and public methods and properties as needed.
    • Note that if defining new interfaces, they should be added to entity object assembly.
       
11. Build, test, and sign the assembly. See Best Practices When Writing Code for Aptify for details.
    • See Adding an Entity Plug-In Object to an Entities Record for instructions on how to add the entity object to the Aptify system.Note: If writing code to create or update sub-type records, any save operations should occur for the top-level record and not for the sub-type record directly.