If you have a comment on this topic, contact Aptify Documentation. If you want to return to the Aptify Community Site, please click here.

Get An Embedded GE Object

Owned by admin (Deactivated)
Last updated: Feb 09, 2015
3 min read

When a field is a Linked Field with Link Type Embedded, you can (and should) pull the embedded GE Object straight out of the field instead of loading it as a separate GE. 

This How-To assumes you have already gone through the steps in Get A GE Object and are coding inside of a callback to Aptify.framework.genericEntity.getEntityObject(). It continues that example, assuming you have already defined personGE.

Step-by-step guide

  1. Know the name of the embedded field.

  2. Optional: if the embedded field's name is passed to you or otherwise not hard-coded, it's wise to check that the field is, indeed, an embedded one. For this you also need to have the metadata of the entity on which the field is defined.

    This step assumes you have already gone through the steps in Get Entity-Level Metadata and have named the entity metadata object entityMd.

    Check If A Field Has Link Type Embedded
    if (entityMd) {
	var fieldMd = entityMd.fields.findByName(embeddedFieldName);
    if (fieldMd && fieldMd.linkType.toLowerCase() == "embedded") {
		// Now you know it's really a field with Link Type embedded. Proceed to Step 3.
    } else if (fieldMd) {
		// Field metadata exists but Link Type is wrong, throw an informative exception
    	throw "The " + embeddedFieldName 
              + " field must have a Link Type of Embedded, but it is " 
              + fieldMd.linkType + ".";
    } else {
		// No field metadata found, throw an informative exception
        throw "The " + embeddedFieldName 
              + " field could not be found on the " 
              + entityMd.name + " entity.";
    }
} else {
	// No entity metadata found, throw an informative exception
	throw "Could not find entity metadata.";
}

  3. If the embedded object has already been loaded, you can call getEmbeddedObject() on the main GE Object, passing the field name. If it has not, you must call loadEmbeddedObject() instead. Best practice is to use this structure if you are not absolutely certain getEmbeddedObject() will work:

    Get the Embedded GE Object
    // If using Step 2, this code would go in the branch where the check for 
// Link Type == "embedded" was successful
var addressGE = personGE.getEmbeddedObject("AddressID");
if (addressGE) {
	// The embedded object already exists, do whatever you like to it
} else {
	// The embedded object needs to be loaded, which is an asynchronous operation
    personGE.loadEmbeddedObject("AddressID", function (embeddedGE) {
		addressGE = embeddedGE;
		// The embedded object now exists, so do whatever you like to it
	});
}

    Note that getEmbeddedObject() is synchronous, while loadEmbeddedObject() is asynchronous.

    Notice that you want to do the same thing whether or not you have to get at the embeddedGE asynchronously? This is an excellent place to encapsulate that thing in a function so you can avoid duplicating code across the synchronous and asynchronous branches.

Copyright © 2014-2017 Aptify - Confidential and Proprietary