AgileApps Support Wiki Pre Release

getRecord

From AgileApps Support Wiki

Get a record, with specified fields.

Syntax
Result result = Functions.getRecord(String objectName, String fields, String recordID 
                  {, Parameters params} );
Parameters
objectName
An Object Identifier
fields
The fields to retrieve.
  • A comma-separated list of field names (Use the REST API:field Resource to get a complete list of fields.)
  • The asterisk ("*") wildcard specifies all fields.
  • For related-record fields in a Composite Object, specify the alias of the related object and the field name, where the alias is defined in the Object Relationships:
alias[.alias...].* or alias[.alias...].field
When fetched, an alias becomes a virtual "field" that contains an array of records from the related object, where each record contains the specified field(s).
  • alias.* specifies all fields in the aliased object.
recordID
A Record Id.
params
An optional com.platform.api.Parameters object. Use it to specify the Retrieve Record Permissions Parameter, in order to find out if the user has update or delete permissions on the record.
Return
Result object. If the return code is greater than zero, use the getParameters() method to get a Parameters object with the record's fields. (See the Java Code Samples for multiple examples of the getRecord API.)
For a Composite Object relationship, the relationship alias becomes a "field" in the Parameters object. That field contains an ArrayList of embedded Parameters objects, one for each related record.
Composite Record Example
This example assumes that a relationship has been established between Cases and a Contacts object, where Contact records have an email field and a Lookup to Cases. With that relationship, multiple contacts can be associated with a case. (In this example, the name of the alias relationship is assumed to be "contacts", matching the name of the object.)
// Get the status field and two composite fields for a specified case record.
// Composite fields are identified as <alias>.<field1>, <alias>.<field2>, etc.
// The returned structure contains an array of Parameters for the "alias", where
// each Parameters item contains the fields from a related Contact.
recordID = ...;
Result result = Functions.getRecord("cases", "status,contacts.name,contacts.email", recordID);
if (result != null && result.getCode() == 1)
{
   Parameters params = result.getParameters();
   if (params != null)      
   {
       // Get the case status
       String caseStatus = params.get("status");
       
       // The "contacts" field contains the array of Parameters for associated Contacts.
       // Each entry in the array contains the fields for one record.
       // Here we get just the first entry from the array. (Loop to get them all.)
       ArrayList caseContacts = (ArrayList)params.getObject("contacts");
       HashMap contactParams = (HashMap)caseContacts.get(0); // Get first entry
       String name = (String)contactParams.get("name");      // Get the fields
       String email = (String)contactParams.get("email");  
    }
}