1. Aptify Support
  2. Installing & Administering Aptify
  3. Administering Aptify
  4. Managing Embedded Database Objects

Managing Embedded Database Objects

Avatar
Madhuri Dange

This topic describes Aptify's Embedded Database Object (EDO) technology. EDO is a technology introduced in Aptify 4.0 that provides an abstraction layer to improve normalized form of application data models while maintaining simplicity at a programmatic and reporting level.

This topic contains the following sub-topics:

Creating Embedded Objects

Embedded objects present fields from a related entity as if those fields were a part of the current entity. From a user perspective, all of the fields on the form appear to be stored in the same service when they may actually represent fields from other services.

An organization may want to use embedded links to provide a centralized user form for entering a variety of fields, while storing related information in separate entities. Also, developers will find that working with embedded links will reduce code complexity; Aptify creates an embedded Generic Entity (GE) object within the current entity that simplifies set and get operations on records in linked entities. See Understanding the Embedded Object Model for more information on developer benefits.

Embedded objects are also suitable for modeling "Is-A" types of relationships. For example, a passenger car "is a" vehicle, and a commercial truck is also a vehicle. In this case, a common "vehicles" entity can be embedded into a Cars entity and a Trucks entity.

Consider the following example that illustrates one possible use of an embedded link:

An organization wants to create an application to track the characteristics of various types of vehicles, including passenger cars and commercial trucks. To normalize the data, the organization determines that it wants a separate "Vehicles" service that stores general information common to all vehicles, such as Make, Model, Color, Year, and engine specifications.

In addition, the organization needs a "Passenger Vehicles" service to track passenger cars (and the characteristics unique to these vehicles, such as number of passengers and number of doors) and a "Commercial Vehicles" service to track commercial trucks (and the characteristics unique to these vehicles, such as hauling capacity).

Both the Passenger Vehicles service and the Commercial Vehicles service will have an embedded link to the common Vehicles service. The fields from the Vehicles service will appear as if they are part of the other two services.

The figures in the Creating Non-Shared Embedded Objects instructions illustrate this Vehicles example.

This section contains the following topics:

Important Notes Concerning Embedded Objects

  • An embedded link requires careful design to ensure that all embedded virtual fields have the appropriate settings.
  • You must examine the security permissions for the entities involved in the embedded link. In general, all users who have read/write access to the entity also need read/write access to the embedded entity. Regardless of how you configure the security settings, keep in mind that users need access to the embedded entity to function correctly.
  • When a user opens a new container entity's form and enters information in all of the required fields, including the required embedded link fields, the system creates a new container record and a new embedded link record when the record is saved.
  • If the embedded link field is required, then a user will need to specify all required fields in the embedded entity in order to save the container record (that is, the record that includes the embedded link).
    • For example, if VehicleID is required, then a user needs to specify a value for all of the required fields in the Vehicles entity. 
  • If the embedded link field is not required, the user can save a container record without specifying a value for any of the embedded fields. However, if the user specifies a value for one or more embedded fields (or changes the default value of one or more embedded fields), then the user must specify a value for all of the embedded entity's required fields in order to save the container record.
    • For example, if VehicleID is not required, then a user can save a Passenger Vehicles record without specifying any of the required Vehicle's fields. However, if a user enters a value for any of the Vehicle's fields, the user must complete all of the required Vehicle's fields to save the record. 
  • After configuring a linked field as Embedded and then saving the entity, you cannot later change the linked field to Standard. If you want to change an embedded link to a standard link, you can delete the embedded link and then add a new field for the standard link.
  • If In Place Editing is enabled for the container entity, a user can edit Virtual Fields from an embedded entity in views of the container entity's records just as if those fields existed as In Table fields within the container entity.
  • A user should not create new records from directly within the embedded entity. The user will be unable to link these records to records in a container entity.
  • If an embedded record is already linked to one or more container records, changes made directly to the embedded record are reflected within the container record(s).
  • For non-shared links, each record in an embedded entity has one "owner" record in a container entity.
    • Once an embedded record is linked to its owner, you cannot link an existing embedded entity record to another container entity record.
    • When a user opens an existing container record and modifies one or more embedded link fields, the system automatically updates the embedded entity's record.
    • If a user deletes a container record, the corresponding embedded record is also deleted. 
  • For shared links, each record in an embedded entity has one "owner" record in a container entity and may have one or more non-owner records.
    • When a user deletes a shared embedded object's owner record, the corresponding embedded record is not deleted, since it may still be linked to other records. Instead, Aptify removes the OwnerRecordID (it is reset to -1) and locks the record (sets the Locked bit).
    • See Designing and Creating Shared Embedded Objects for more information.

Creating Non-Shared Embedded Objects

This topic describes how to create an embedded link within an entity. The entity whose fields will be embedded is referred to as the embedded entity. The entity whose form will display the embedded fields is referred to as the container entity.

For illustrative purposes, the screen shots that accompany these instructions illustrate how to embed fields from a Vehicles entity (the embedded entity) on a Passenger Vehicles form (the container entity).

Follow these steps to create a non-shared embedded link:

  1. Plan out the design of your container entity (or entities) and the embedded entity.
    • This includes identifying the list of fields that will be associated with each entity, the security settings for each entity, and how the entities will link together. 
  2. Create an Entities record for the embedded entity, including its fields. See Creating a New Entity for instructions.
    • The following figure illustrates the standard Vehicles form. These are the fields that will be added to the Passenger Vehicles form using an embedded link.  

      Form for Entity to Embed
  3. Create the first container entity, if it does not already exist. Again, see Creating a New Entity for details.
    • For this step, complete the top area of the Entities form, add security settings, and add entity fields (except for the embedded link).
    • Keep in mind that the security settings on the embedded entity and the container entity should meet the design requirements that you identified in Step 1. 
  4. Open a new Fields record for the embedded link.
  5. Enter a Name for the embedded link.
    • Aptify's standard naming convention for linked fields is the name of the linked entity (in its singular form) and the linked entity field. For example, the name of a field linked to the Vehicles entity's ID field would be VehicleID.
    • The Display Name fills in automatically when you specify a name. 
  6. Select the embedded entity from the Linked Entity drop-down list.
  7. Select ID from the Linked Field drop-down list.
  8. Select Embedded from the Link Type drop-down list. Leave Mode set to None. 
    Embedded Link Fields Record 
  9. Configure the embedded link's Is Required behavior.
    • If you want to require a user to specify a value for all of the required fields in the embedded entity, leave the Is Required option selected under the Validation tab.
    • If you want to allow users to save the container record without specifying all of the required embedded fields, clear the Is Required option on the Validation tab and select the Allow Null option on the General tab.
      • This creates a foreign key that supports null values for records where the embedded link is not required. 
    • In the Passenger Vehicles example, the designer would specify the VehicleID field as required since an organization would not want a user to save a Passenger Vehicles record without specifying the relevant vehicle information. 
  10. Click OK to save and close the Fields record.
    • You do not want to enable the field's Show In Find or Default In View options since you want the link to be transparent to users.
    • The Aptify Entity Virtual Fields wizard appears automatically when you close an embedded link's Fields record. 
  11. Use the wizard to create a virtual field for each of fields in the embedded entity that you want to display on the container entity's form.
    • Select the Create check box for each field you want to embed in the container entity. At a minimum, you must create a virtual field for each of the required fields in the embedded entity, except for ID. (Do not create a virtual field for the embedded entity's ID field.)
    • The Create check box is automatically selected for all required fields. In figure below, the ManufacturerID and Model fields are required fields in the Vehicles entity.
      Creating Virtual Fields for Embedded Links 
    • If you want the field to appear in views of the container entity by default, select the check box in the corresponding Default In View box.
    • Enter the name of the field in the Virtual Field column. The name cannot contain spaces or dashes. Aptify recommends the following naming convention: [Singular form of embedded entity name]ID_[Field Name]. For example, the Model virtual field in the figure below is VehicleID_Model.
      Configure Fields to Embed On Form
    • Enter the name that will appear as this field's caption on the container entity's form and in views of the container entity. Typically, this will be the field's name with appropriate spacing (such as, Engine Type).
    • Enter a Description for one or more virtual fields, if desired. 
  12. Click OK to create the virtual fields.
    • Note that if the embedded link is not required, the virtual field's Join Type is Optional. If the embedded link is required, the virtual field's Join Type is Required. If you subsequently change the embedded link's Is Required field, the Join Type values for the related virtual fields update automatically when you save the entity. See Join Type.
    • A Virtual Field inherits the SQL Data Type of the Fields record it is linked to.
    • If applicable, a Virtual Field inherits the Values record and Default Value setting of the Fields record it is linked to. (Note that while the values appear in the drop-down list for the embedded field on a top-level form, the Values tab on the Virtual Field remains blank though.) 
      Virtual Fields Added to Container Entity
  13. If you want one or more of the virtual fields to appear on a tab other than General on the generated form, open the applicable Fields record and enter the tab name in the Category field.
  14. Add any additional fields to the container entity and configure the other entity settings as needed.
  15. Save and close the Entities record.
  16. Open the container entity's generated form.
    • The embedded virtual fields appear as fields on the container form. See Important Notes Concerning Embedded Objects for information on how to use forms that include embedded links.
      Form with Embedded Fields
  17. Repeat steps 3 to 16 to create additional container entities, as needed.

Designing and Creating Shared Embedded Objects

Aptify's embedded object technology fully supports the concept of sharing objects between multiple records of different types and includes logic for determining the circumstances under which a record's embedded link should be updated.

This topic describes the requirements for creating an embedded object that can be shared by multiple records and covers the following sub-topics:

Creating a Shared Embedded Link

This topic provides instructions for creating a shared embedded link and its supported relationship types. See About the Shared Embedded Terminology and About the Aptify Address Management Logic for more information on shared embedded links and the supported relationship types.

Aptify recommends that you carefully plan out the design for your shared embedded object before you begin to modify the system. Among other things, you need to identify the list of fields contained in each entity, determine the security settings for each entity, and map out how the various entities will interact with the embedded object and with each other. 

This section covers the following topics:

Configuring a Shared Embedded Entity

Follow these steps to create a shared embedded entity:

  1. Create an Entities record for the embedded entity. See Creating a New Entity for instructions.
  2. Add all necessary data fields to the new entity.
  3. Add the following three fields to support the shared embedded object functionality:
    • OwnerEntity (nvarchar(100)): This field is used to identify the entity name for the record that "owns" a particular embedded record.
    • OwnerRecordID (int or bigint): This field is used to identify the record in the OwnerEntity that created a particular embedded record.
    • Locked (bit): This field is used to indicate whether or not an embedded record may be updated. When set to 1, the embedded record has a static relationship with one or more container records and cannot be updated. 
  4. Complete the configuration of the embedded entity.
  5. Save and close the Entities record.

Configuring Owner Embedded Links

Follow these steps to configure the owner entity for a shared embedded link:

  1. Create a new Entities record or open an existing record that you intend to modify. See Creating a New Entity for instructions.
    • For this step, complete the top area of the Entities form, add security settings, and add entity fields (except for the embedded link).
    • Keep in mind that the security settings on the embedded entity and the container entity should meet the design requirements that you identified previously. 
  2. Open a new Fields record for the embedded link.
  3. Enter a Name for the embedded link.
    • Aptify's standard naming convention for linked fields is the name of the linked entity (in its singular form) and the linked entity field. For example, the name of a field linked to the Addresses entity's ID field would be AddressID.
    • The Display Name fills in automatically when you specify a Name. 
  4. Select the embedded entity from the Linked Entity drop-down list.
  5. Select ID from the Linked Field drop-down list.
  6. Select Embedded from the Link Type drop-down list and press the Tab key.
    • The Mode field appears. 
  7. Set Mode to Dynamic.
    • The Dynamic Sharing tab appears. 
  8. Click the Dynamic Sharing tab.  
    Dynamic Embedded Link Field 
  9. In the Dynamic Flowdown Proc field, specify the stored procedure that defines the update logic for non-owner links that may share the owner's embedded record.
    • This field links to the Database Objects service.
    • You can use the stored procedure linked to the Companies entity's AddressID field or the Organizations entity's AddressID field as samples when writing your own stored procedures. 
  10. Add the non-owner fields referenced in the Dynamic Flowdown Proc procedure to the Dynamic Sharing Relationship sub-type area.
    • For each sub-type record, enter the following information:
      • Related Entity: Enter the name of the entity that can share this owner's embedded record.
      • Related Entity Field: Enter the name of the field in the Related Entity that links to the same embedded entity as the owner.
      • Dynamic Flowdown Filter: This field is reserved for future use. 
    • For example, a company's Addresses record may be shared by the Persons entity's AddressID field. 
  11. Click the Validation tab and configure the embedded link's Is Required behavior.
    • If you want to require a user to specify a value for all of the required fields in the embedded entity, leave the Is Required box checked under the Validation tab.
    • If you want to allow users to save the container record without specifying all of the required embedded fields, clear the Is Required option on the Validation tab and select the Allow Null option on the General tab. 
  12. Click OK to save and close the Fields record.
    • You do not want to enable the field's Show In Find or Default In View options since you want the link to be transparent to users.
    • The Aptify Entity Virtual Fields wizard appears automatically when you close an embedded link's Fields record. 
  13. Use the wizard to create a virtual field for each of fields in the embedded entity that you want to display on the container entity's form.
    • Select the Create check box for each field you want to embed in the container entity. At a minimum, you must create a virtual field for each of the required fields in the embedded entity, except for ID. (Do not create a virtual field for the embedded entity's ID field.) 
      Creating -irtual Fields for Shared Embedded Links 
    • If you want the field to appear in views of the container entity by default, select the check box in the corresponding Default In View box.
    • Enter the name of the field in the Virtual Field column. The name cannot contain spaces or dashes. Aptify recommends the following naming convention: [Singular form of embedded entity name]ID_[Field Name]. For example, AddressID_PostalCode.
    • Enter the name that will appear as this field's caption on the container entity's form and in views of the container entity. Typically, this will be the field's name with appropriate spacing (such as, Postal Code).
    • Enter a Description for one or more virtual fields, if desired. 
  14. Click OK to create the virtual fields.
    • Note that if the embedded link is not required, the virtual field's Join Type is Optional. If the embedded link is required, the virtual field's Join Type is Required. If you subsequently change the embedded link's Is Required field, the Join Types for the related virtual fields update automatically when you save the entity. See Join Type.
    • A Virtual Field inherits the SQL Data Type of the Fields record it is linked to.
    • If applicable, a Virtual Field inherits the Values record and Default Value setting of the Fields record it is linked to. (Note that while the values appear in the drop-down list for the embedded field on a top-level form, the Values tab on the Virtual Field remains blank though.) 
  15. If you want one or more of the virtual fields to appear on a tab other than General on the generated form, open the applicable Fields record and enter the tab name in the Category field. 
  16. Save and close the Entities record.
 

Configuring Non-Owner Dynamic Links

Follow these steps to configure entities that will have a non-owner, dynamic relationship to the owner entity in your shared embedded model:

  1. Create a new Entities record or open an existing record that you intend to modify. See Creating a New Entity for instructions.
    • For this step, complete the top area of the Entities form, add security settings, and add entity fields (except for the embedded link).
    • Keep in mind that the security settings on the embedded entity and the container entity should meet the design requirements that you identified previously. 
  2. Open a new Fields record for the embedded link.
  3. Enter a Name for the embedded link.
    • Aptify's standard naming convention for linked fields is the name of the linked entity (in its singular form) and the linked entity field. For example, the name of a field linked to the Addresses entity's ID field would be AddressID.
    • The Display Name fills in automatically when you specify a Name. 
  4. Select the embedded entity from the Linked Entity drop-down list.
  5. Select ID from the Linked Field drop-down list.
  6. Select Embedded from the Link Type drop-down list and press the Tab key.
    • The Mode field appears. 
  7. Set Mode to Dynamic.
    • The Dynamic Sharing tab appears. Leave the Dynamic Sharing tab blank. 
  8. Click the Validation tab and configure the embedded link's Is Required behavior.
    • If you want to require a user to specify a value for all of the required fields in the embedded entity (assuming that the user does not complete a field that would initiate a shared embedded flow-down), leave the Is Required option selected under the Validation tab.
    • If you want to allow users to save the container record without specifying all of the required embedded fields (again, assuming that the user does not complete a field that would initiate a shared embedded flow-down), clear the Is Required option on the Validation tab and select the Allow Null option on the General tab. 
  9. Click OK to save and close the Fields record.
    • You do not want to enable the field's Show In Find or Default In View options since you want the link to be transparent to users.
    • The Aptify Entity Virtual Fields wizard appears automatically when you close an embedded link's Fields record. 
  10. Use the wizard to create a virtual field for each of fields in the embedded entity that you want to display on the container entity's form. Make additional modifications to any of these virtual fields as necessary after you have used the wizard to create them.
  11. If not already in place, add the entity object plug-in to the entity's Plug-Ins tab.
    • The initial embedded link flow-down to this non-owner record (such as the address flow-down from a company to a person) is controlled by logic that needs to be added to the non-owner entity's entity object.
    • A developer writes code that specifies this flow-down logic (either adding it to an existing entity object or creating one for the entity if one does not already exist) and then adds the object to the Aptify Object Repository.
    • See Adding Plug-Ins to an Entity for more information. 
  12. Save and close the Entities record.
  13. Close and reopen the Aptify client.
  14. Test your shared embedded object implementation.

Configuring Non-Owner Static Links

Follow these steps to configure entities that will have a non-owner, static relationship to the shared embedded record:

  1. Create a new Entities record or open an existing record that you intend to modify. See Creating a New Entity for instructions.
    • For this step, complete the top area of the Entities form, add security settings, and add entity fields (except for the embedded link).
    • Keep in mind that the security settings on the embedded entity and the container entity should meet the design requirements that you identified previously. 
  2. Open a new Fields record for the embedded link.
  3. Enter a Name for the embedded link.
    • Aptify's standard naming convention for linked fields is the name of the linked entity (in its singular form) and the linked entity field. For example, the name of a field linked to the Addresses entity's ID field would be AddressID.
    • The Display Name fills in automatically when you specify a Name. 
  4. Select the embedded entity from the Linked Entity drop-down list.
  5. Select ID from the Linked Field drop-down list.
  6. Select Embedded from the Link Type drop-down list and press the Tab key.
    • The Mode field appears. 
  7. Set Mode to Static.
  8. Click the Validation tab and configure the embedded link's Is Required behavior.
    • If you want to require a user to specify a value for all of the required fields in the embedded entity (assuming that the user does not complete a field that would initiate a shared embedded flow-down), leave the Is Required option selected under the Validation tab.
    • If you want to allow users to save the container record without specifying all of the required embedded fields (again, assuming that the user does not complete a field that would initiate a shared embedded flow-down), clear the Is Required option on the Validation tab and select the Allow Null option on the General tab. 
  9. Click OK to save and close the Fields record.
    • You do not want to enable the field's Show In Find or Default In View options since you want the link to be transparent to users.
    • The Aptify Entity Virtual Fields wizard appears automatically when you close an embedded link's Fields record. 
  10. Use the wizard to create a virtual field for each of fields in the embedded entity that you want to display on the container entity's form. Make additional modifications to any of these virtual fields as necessary after you have used the wizard to create them.
  11. If not already in place, add the entity object plug-in to the entity's Plug-Ins tab.
    • The initial embedded link flow-down to this non-owner record (such as the address flow-down from a company to a person) is controlled by logic that needs to be added to the non-owner entity's entity object.
    • A developer writes code that specifies this flow-down logic (either adding it to an existing entity object or creating one for the entity if one does not already exist) and then adds the object to the Aptify Object Repository.
    • See Adding Plug-Ins to an Entity for more information. 
  12. Save and close the Entities record.
  13. Close and reopen the Aptify Desktop client.
  14. Test your shared embedded object implementation.
    • When a record in this entity is linked to a shared embedded object, the system should lock the embedded record automatically (by setting the Locked field to 1).

About the Shared Embedded Terminology

In the Shared Embedded model, there are four roles that can be defined:

About the Embedded Entity Role

This is the entity that is embedded in one or more container entities via an embedded link field. From a designer perspective, creating an embedded entity is the same as creating an entity, except you need to add three fields to support the sharing functionality:

  • OwnerEntity (nvarchar(100)): This field identifies the entity name for the record that "owns" a particular embedded record. For example, for a company's address, that Addresses record has Companies as its OwnerEntity.
  • OwnerRecordID (int or bigint): This field identifies the record in the OwnerEntity that "owns" a particular embedded record. For a company's address, this is the ID of the particular Companies record that owns an Addresses record.
  • Locked (bit): This field indicates whether or not an embedded record may be updated. When set to 1, the embedded record has a static relationship with one or more container records.  

    Shared Embedded Fields in Addresses Entity

About the Shared Embedded Owner Role

Each embedded record that is shared has an owner. This is the record from which a user initially creates the shared record. For example, an address that is shared among a company and the people at that company is owned by the company. For that particular Addresses record, the OwnerEntity would be "Companies" and the -OwnerRecordID would be the ID of the top-level company's record. The embedded link field for the Owner entity defines the sharing and update logic for all of the other container records that share the same embedded record.

The embedded link field for the owner entity has the following settings, as illustrated in the figure below, which shows the AddressID field in the Companies entity:

  • Linked Entity: The name of the embedded entity.
  • Linked Entity Field: Typically, the ID field in the embedded entity.
  • Link Type: Embedded
  • Mode: Dynamic. This setting adds a Dynamic Sharing tab to the Fields record.
  • Dynamic Flowdown Proc: This link box specifies the stored procedure which defines the logic for updating the dynamic non-owner shared links specified in the Dynamic Sharing sub-type -listing.
    • A developer needs to write a stored procedure and add it as a Database Objects record. This stored procedure should define how updates made to the embedded record at the owner level are propagated to other dynamic non-owner links. See the stored procedures that are linked to the Companies entity's AddressID field and the Organizations entity's AddressID field for examples.
    • This stored procedure does not establish the sharing relationship between an owner and non-owner container records, it only maintains the relationship and performs updates as needed. To perform the initial flow-down (for example, to associate a company's address when you add a company to a Persons form), you typically specify this logic in an entity plug-in object for the non-owner entity.

       Embedded Link Owner Field

  • Dynamic Sharing Relationships Sub-Type: This sub-type control stores the list of entities and their embedded links that can share an embedded record with this owner entity as a non-owner. Each sub-type record stores the Related Entity name, the Related Entity Field (this is the embedded link in the Related Entity that links to the shared embedded object), and a Dynamic Flowdown Filter (which you can use to filter the set of records to which this shared embedded object relationship applies). For the Companies entity's AddressID field, one type of non-owner records is updated dynamically (the specific update logic is stored in the Dynamic Flowdown stored procedure):
    • Persons/AddressID: This corresponds to the business address for Persons who are associated with the company.

       Dynamic Sharing Relationships Record

About the Dynamic Shared Embedded Non-Owner Role

Like the Dynamic Shared Embedded Non-Owner link, this type of link also identifies a non-owner entity for a shared embedded link. However, once linked, a static non-owner locks the embedded record to prevent future updates. If a user subsequently modifies the embedded record data at the owner level, Aptify automatically creates a clone of the original record, links it to the owner, updates the dynamic non-owner links to use the new record, and then modifies the record as necessary. The static record retains its link to the original, unchanged embedded record.

In Aptify, an Order's Bill To and Ship To addresses use static embedded links to a Person's address. At the time an order is created, the Person's address (which is typically owned by the Person's corresponding Company) automatically flows down to the Orders record via logic in the Orders entity object. However, if a Company's address subsequently changes (which would change the Person's address), it would not be appropriate to carry this change over to the Order's Bill To and Ship To addresses. An address change would affect future orders, but it should not affect those that occurred in the past.

The embedded link field for a static non-owner entity has the following settings, as illustrated in the figure below, which shows the ShipToAddressID field in the Orders entity:

  • Linked Entity: The name of the embedded entity.
  • Linked Entity Field: Typically, the ID field in the embedded entity.
  • Link Type: Embedded
  • Mode: Static 

     Static Shared Embedded Link
  • Non-Owner Entity Object: A developer specifies the initial flow-down logic to link the non-owner to the shared embedded record in an entity plug-in object for the non-owner entity. See Adding Plug-Ins to an Entity for details.

About the Static Shared Embedded Non-Owner Role

Like the Dynamic Shared Embedded Non-Owner link, this type of link also identifies a non-owner entity for a shared embedded link. However, once linked, a static non-owner locks the embedded record to prevent future updates. If a user subsequently modifies the embedded record data at the owner level, Aptify automatically creates a clone of the original record, links it to the owner, updates the dynamic non-owner links to use the new record, and then modifies the record as necessary. The static record retains its link to the original, unchanged embedded record.

In Aptify, an Order's Bill To and Ship To addresses use static embedded links to a Person's address. At the time an order is created, the Person's address (which is typically owned by the Person's corresponding Company) automatically flows down to the Orders record via logic in the Orders entity object. However, if a Company's address subsequently changes (which would change the Person's address), it would not be appropriate to carry this change over to the Order's Bill To and Ship To addresses. An address change would affect future orders, but it should not affect those that occurred in the past.

The embedded link field for a static non-owner entity has the following settings, as illustrated in the figure below, which shows the ShipToAddressID field in the Orders entity:

  • Linked Entity: The name of the embedded entity.
  • Linked Entity Field: Typically, the ID field in the embedded entity.
  • Link Type: Embedded
  • Mode: Static 

     Static Shared Embedded Link
  • Non-Owner Entity Object: A developer specifies the initial flow-down logic to link the non-owner to the shared embedded record in an entity plug-in object for the non-owner entity. See Adding Plug-Ins to an Entity for details.

About the Aptify Address Management Logic

This section describes how Aptify uses Shared Embedded Objects to manage addresses across Companies, Persons, and Orders. In this implementation, the Embedded Entity is Addresses, the Shared Embedded Owner is Companies, the Dynamic Shared Embedded Non-Owner is Persons, and the Static Shared Embedded Non-Owner is Orders.

The following steps outline Aptify's addressing implementation:

  1. A user creates a new top-level company (Companies ID 1) and specifies a Street Address.
    • A new record is added to the Companies entity.
    • Aptify creates a new Addresses record for the specified address (Addresses ID 1). The Companies record is the Addresses record's owner in the shared embedded model. The Companies entity's AddressID field has the settings described in About the Shared Embedded Owner Role and shown in the figure below. The Addresses record has the following embedded field values:
      • OwnerEntity: Companies
      • OwnerRecordID: The ID of the new Companies record.
      • Locked: 0
    • The following figure illustrates the relationship between these records. 

      Owner Company and Its Address
  2. A user creates a new Persons record and specifies Companies ID 1 as the Company (Persons ID 1). The company's Street Address automatically flows down to the person's Business Address.
    • The logic contained in the Persons entity's entity object automatically associates the Persons record's AddressID with the same AddressID from the specified Companies record (Addresses ID 1).
    • Addresses ID 1's Owner remains Companies ID 1. Persons ID 1 is a dynamic non-owner to Addresses ID 1.
    • The Persons entity's AddressID field has the settings described in About the Dynamic Shared Embedded Non-Owner Role and shown in in the figure below.

      Company to Person Flowdown
  3. A user creates a second new Persons record and specifies Companies ID 1 as the Company (Persons ID 2). The company's Street Address automatically flows down to the person's Business Address. But in this case, the user specifies a different Business Address for the person.
    • Modifying the address on the Persons record breaks the shared embedded link between the Companies record and the Persons record.
    • Aptify creates a new Addresses record for the Person's specified address (Addresses ID 2) and specifies the Persons record as the Addresses record's owner.

      Person with Different Address Specified
  4. A user creates a new Companies record and specifies Companies ID 1 as the Parent company (Companies ID 2). The parent company’s Street Address does not automatically flows down to the new subsidiary company’s Street Address so a user enters the subsidiary’s address as appropriate.
  5. A user creates a third new Persons record and specifies Companies ID 2 as the Company (Persons ID 3). The company’s Street Address automatically flows down to the person’s Business Address.

    Subsidiary Company With a Person
  6. A user modifies the Street Address for Companies ID 1.
    • The changes the user specified are saved in Addresses ID 1.
    • These changes are automatically applied to Persons ID 1, since this person shares a link to the same Addresses record.
    • No changes are made to Persons ID 2's address since it linked to a different Addresses record.
  7. A user creates and saves an order for Persons ID 1 (Orders ID 1).
    • The logic contained in the Orders entity's entity plug-in object automatically associates the Orders record's ShipToAddressID and BillToAddressID with the same AddressID from the specified Persons record (which happens to be owned by the associated Companies record, Addresses ID 1).
    • The Orders entity's ShipToAddressID and BillToAddressID fields have the settings described in About the Static Shared Embedded Non-Owner Role and shown in the figure below.
    • Since the Orders entity is a Static link, Addresses ID 1 becomes Locked to prevent any further modification to that Addresses record. Note that Companies ID 1 and Persons ID 1 remain linked to Addresses ID 1

      . Static Record Locks Embedded Record
  8. Companies ID 1 moves and its Street Address changes. A user opens the Companies ID 1 record and modifies the Street Address.
    • Since Addresses ID 1 has been locked by Orders ID 1, Aptify creates a new Addresses record to store the company's updated Street Address and links Companies ID 1 and Persons ID 1 to this new address (Addresses ID 3).
    • The Owner Record for Addresses ID 1 changes from Companies ID 1 to Companies ID -1, which reflects the fact that Companies ID 1 is no longer the owner of this record. An ID of -1 indicates a blank value.
    • Orders ID 1 remains linked to Addresses ID 1.
    • Addresses ID 1's owner entity remains Companies, even though Companies ID 1 is no longer linked to it.
    • Persons ID 2 remains linked to Addresses ID 2, since it is was unlinked from the company's address at an earlier point.

      Updates Generate New Records When Locked

Understanding the Embedded Object Model

This section provides a high-level overview of Embedded Database Object (EDO) technology and why it is important to the Aptify Framework.

It covers the following topics:

About the Problem Leading to EDO

In many business applications there are situations where tables of data contain common repeating patterns of information that are not best managed if stored redundantly in each table. A good example of this is address information. There are many business cases that result in logical data models, including address information in entity designs. For example, address information is logically associated with Organizations, Employees, Persons, Companies, Orders, Subscriptions, and more.

In Aptify 3.x and prior versions, this information was maintained separately in each table in order to simplify the development and report-writing aspects of the data model. Added normalization in a data model usually comes at a cost in the area of reporting ease of use, performance for queries, and programmatic complexity when working with the data model. On the other hand, added normalization generally will improve transactional performance due to smaller table sizes and more efficient data storage patterns.

One of the design goals for the Aptify 4.x and 5.x framework technologies was to enable application developers, including the developers of Aptify's own CRM and Membership suite, to pursue a more normalized data model while at the same time maintaining the ease of programmatic and reporting access that has been enjoyed in all prior versions of the technology. For example, consider the following scenario:

In an application, a developer chooses to create a normalized Address table which will be used in all areas of a system that need to store Address data, including a Customer table and an Orders table.

A simplified version of the schema might look something like this:

Simplified Schema
The challenge to the developer is that all transactions that relate to a Customers or Orders record in the above model would require managing records in both the Customers/Orders table as well as one or more records in the Addresses table. In addition, it is critical that the transaction management around these multiple inserts/updates be managed properly so that an update to a customer profile happens in its entirety as part of a commit.

In addition, report writers must join in multiple tables for common report writing requirements, such as to create simple rosters or label reports on a Customers record. This complexity is particularly problematic for many of the report writers who do not have substantial database experience and fit the description of a power-user more than a database administrator or programmer.

About the Optional Embedded Objects

There are cases when a foreign key relationship is established as an optional relationship between records. For example, a company may or may not have a Billing Address that is different from its primary address. In those types of scenarios, an embedded object may or may not exist for a given foreign key in the Generic Entity (GE) object model.

The GE object model optimizes the loading of embedded objects when a containing object is first loaded. For example, if a Company GE object is loaded up, only the Company GE object itself is loaded into memory initially. The virtual fields associated with the CompanyGE are available for read access without needing to access the embedded GE object since those values are carried in the Company GE itself as virtual fields.

The embedded GE is loaded up only if a change is being made to an embedded object, or if a user's code directly requests the underlying embedded object through the Dot syntax method or direct embedded object access. This approach is completely transparent to developers that are using the GE but is important to be aware of since it improves performance of the GE object loading and saving by a considerable margin.

To determine whether an embedded object has been loaded by the GE, check the AptifyDataFieldBase.EmbeddedObjectExists function. This function is used by the parent GE object to determine whether or not the Embedded GE object has been loaded. It returns True if the Embedded object has been instantiated and False otherwise. See the Aptify Software Development Kit (SDK) for more information.

The EmbeddedObjectExists function provides a valuable service since the Embedded GE object will only be loaded when it is required. If the parent GE identifies that the Embedded record has not been loaded, which means it has not been changed, no further interaction is required, and the parent GE can optimize its Validation and Save operations. Conversely, if you access the AptifyDataFieldBase.EmbeddedObject method, the system will load the Embedded GE object each time, even when it is not necessary.

About the Types of Embedded Objects

Aptify offers two implementations of Embedded Data Objects: Non-Shared and Shared.

Non-Shared Embedded Objects

A non-shared object is an embedded link that provides a one-to-one relationship between the parent record and the embedded record. For example, in Aptify, the Message Parts service has an embedded, non-shared link to the Scripts service, since a particular script corresponds to a single Message Parts record. See Creating Non-Shared Embedded Objects for information on how to create a non-shared embedded link.

Shared Embedded Objects

A shared embedded object corresponds to an embedded record that may be linked to multiple records. For example, consider the example of an application that includes a Companies entity and a Persons entity that are used to manage customers at the organizational and individual level. Companies and individuals frequently share address information. Using a normalized model such as the one described in  Understanding the Embedded Object Model, it is possible to link a company and its individuals directly to the same record in the Addresses table. This would reduce the number of records in the system and also speed up transactional performance when adding new persons to an existing company since a new record would not need to be inserted into the Addresses table. Furthermore, space requirements in the database would be reduced in this model and when an address is changed at the company level, it would automatically be reflected in all persons linked to the same physical Addresses record.

While this type of data modeling is desirable in some areas of a database, it can be undesirable in others. In some applications and in some table relationships it may be necessary for a record to have exclusive ownership of an embedded object. In that case, the concept of sharing would not be used at all.

For example, in the case where a company and multiple persons linked to it are sharing an address, if an individual within the company has a unique address, it is important that the unique address of that individual be respected and not overwritten when a company's address changes. The rest of the individuals linked to the company should get the new company address automatically, but an individual that previously had a different address than the company address should retain that unique address.

This type of functionality has existed in the Aptify CRM and Membership applications in several relationship areas including Companies/Persons and Organizations/Employees. However, in prior versions of the business applications, this flow-down actually was a physical flow-down of data from the Companies record to the Persons record and from the Organizations record to the Employees record. Whenever a company's address was changed, each person linked to the company was evaluated, and if the address at the person level was the same as the old company address, a flow-down occurred.

This type of business application functionality is commonplace and desirable at a logical level. In Aptify, embedded object sharing supports this scenario, but through a much more efficient process. Rather than physically flowing down data, records can be shared and therefore automatic "flow-downs" occur since Persons and Companies that are intended to share an address are linked to the same Addresses record.

If all shared embedded object scenarios desired to have complete auto-flow-down of data, then the concept of sharing embedded objects would be a simple one to implement. All the users would need to do is link in the same embedded object primary key value into multiple "container" records. Whenever any such container record made a change to the embedded object, all other container records would automatically get the change. The problem, of course, is this is not always desired. In some cases, the desire is for the "flow" to occur only in one direction — from Company to Person, but not the other way.

Therefore, Aptify's shared embedded implementation also deals with these types of situations where an automatic record update is not desired, such as when a person has a different address than his or her company or when an order has an address specified as a Ship To destination.

Shared embedded objects eliminate the need for many custom flow-down scenarios in business application code and also can increase the efficiency of common transactions, such as changing an address of a company that might have many individuals linked to it. See Designing and Creating Shared Embedded Objects for more information on shared embedded links and their implementation.

 
 
 
Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.

Articles in this section