Documentation

Class

MxObject

MxObject()

An instance of an entity in the domain model of the current session.

It provides methods for accessing and modifying attributes.

Instances of MxObject should seldom be instantiated manually. They are the result of calls into mx.data (mx-api/data in the new API) such as mx.data.get (for example retrieveByEntity in the new API) or mx.data.create (create in the new API).

Constructor

# new MxObject()

Classes

MxObject

Methods

# addReference(attr, guid) → {boolean}

If attr is a reference attribute, sets it to the given object. If attr is a reference set attribute, adds the given object to it.

Parameters:
Name Type Description
attr string

The reference attribute. Can refer to either a reference or reference set attribute.
guid GUID

GUID of the object to add to the reference

true if successful, false otherwise

boolean
Example
mxobj.addReference("MyFirstModule.Ent_RefEnt", "12345");

# addReferences(attr, guids) → {boolean}

Add an object to a reference set attribute.

Parameters:
Name Type Description
attr string

the reference set attribute
guids Array.<GUID>

GUIDs of the objects to add to the reference

true if successful, false otherwise

boolean
Example
mxobj.addReferences("MyFirstModule.Ent_RefEnt", ["12345", "12346"]);

# fetch(path, callback, error)

Gets an object or value of an attribute, through a path from this object.

The result is passed to a callback and depends on the requested path:

| Path resolves to | Result |------------------------------------------------------------------------------------- | attribute | value of the attribute | object reference | GUID of the object | object reference set | array of GUIDs with the objects | entity | array of GUIDs for a reference set, MxObject otherwise

If no path is given, the result is set to the object itself. A reference set can only be the last reference in the path.

Parameters:
Name Type Description
path string

path from the object to the desired object or attribute
callback MxObject~FetchCallback

called when fetching is done
error MxObject~FetchErrorCallback

function to handle errors
Examples

Retrieving an attribute value from an object is essentially a callback version of mx.data.get (for example `retrieveByGuids` in the new API): 

mxobj.fetch("Name", function(value) {
    alert("Person's name is " + value);
});

Retrieving an object through a reference:

mxobj.fetch("MyFirstModule.Friend/MyFirstModule.Person", function(value) {
    alert("Name of person's friend is " + value.get("Name"));
});

When retrieving an object through a reference set, the result will be an Array:

mxobj.fetch("MyFirstModule.Owns/MyFirstModule.Pet", function(value) {
    alert("Person owns the following pets: " + value);
});

Retrieving an attribute through several references:

mxobj.fetch("MyFirstModule.Friend/MyFirstModule.Person/" +
            "MyFirstModule.Father/MyFirstModule.Person/" +
            "Age", function(value) {
    alert("Name of the father of this person's friend is " + value);
});

# get(attr) → {string|number|external:Big|boolean}

Returns the value of an attribute.

Parameters:
Name Type Description
attr string

attribute whose value to return

value of the specified attribute. The return type depends on the type of the attribute as follows:

Attribute type Javascript type Javascript value
Integer, Long, Decimal external:Big instance containing the number
Autonumber string string representation of the number
DateTime number timestamp of the date
Enum string value of the enumeration
String string
Boolean boolean
Reference string referenced object GUID as a string
ReferenceSet Array<string> referenced object GUIDs as strings

Empty values are always returned as the empty string ("").

string | number | external:Big | boolean
Examples
mxobj.get("IsActive");   // true
mxobj.get("Name");       // "John Doe"
numericValue = mxobj.get("LoginCount");
numericValue instanceof Big // true
numericValue.toString()     // "315"

# getAttributes()

Convenience function

See:
  • MxMetaObject#getAttributes
Example
mxobject.getAttributes(); // ["Name", "Age"];

# getChildren(attr) → {Array.<MxObject>}

Retrieves the MxObjects referenced by a reference attribute, if these objects were retrieved together with the current one using mx.data.get's args.filter.references (for example retrieveByGuids with params.filter.references in the new API).

Otherwise returns an empty array, including the case when the reference has been modified since retrieval. When trying to retrieve a non-reference attribute this way, an exception is thrown. Passing a reference that contains multiple associations also throws an exception.

Parameters:
Name Type Description
attr string

attribute whose referenced objects to return

MxObjects referenced by the given reference attribute

Array.<MxObject>

# getEntity() → {string}

Gets the entity name.

the entity name

string
Example
mxobject.getEntity(); // "System.User"

# getGuid()

Returns the GUID of this MxObject.

Example
mxobj.getGuid(); // "1234567890131"

# getOriginalReferences(attr) → {Array.<GUID>}

Retrieves the original MxObjects referenced by a reference or reference set attribute.

Parameters:
Name Type Description
attr string

reference attribute whose original referenced objects to return

GUIDs of the original referenced objects

Array.<GUID>
Example
mxobj.getReferences("MyFirstModule.Ref");            // [ "12345", "12346" ]
mxobj.set("MyFirstModule.Ref", [ "12347" ]);         // [ "12347" ]
mxobj.getReferences("MyFirstModule.Ref");            // [ "12347" ]
mxobj.getOriginalReferences("MyFirstModule.Ref");    // [ "12345", "12346" ]

# getOriginalValue(attr) → {string|number|external:Big|boolean}

Returns the original, last committed, value of an attribute.

Parameters:
Name Type Description
attr string

attribute whose value to return
See:
  • MxObject#get for an overview of how the return value depends on the attribute's type.

original value of the specified attribute.

string | number | external:Big | boolean
Example
mxobj.get("Name");               // "Fred"
mxobj.set("Name", "Henry");
mxobj.get("Name");               // "Henry"
mxobj.getOriginalValue("Name")   // "Fred"

# getReference(reference) → {string}

Retrieves the GUID of the object referenced by a reference attribute. When trying to retrieve a non-reference or reference set attribute this way, an exception is thrown.

Parameters:
Name Type Description
reference string

attribute whose referenced object to return

GUID of the MxObject referenced by the given reference attribute

string
Example
// Get GUID of object over association MyFirstModule.Ref.
refs = mxobj.getReference("MyFirstModule.Ref"); // "12345"

# getReferenceAttributes()

Convenience function

See:
  • MxMetaObject#getReferenceAttributes
Example
mxobject.getReferenceAttributes(); // [ "Mod.Person_Parent",
                                   //   "Mod.Person_Company" ]

# getReferences(attr) → {Array.<GUID>}

Retrieves the MxObjects referenced by a reference or reference set attribute.

Parameters:
Name Type Description
attr string

reference attribute whose referenced objects to return

GUIDs of the references objects

Array.<GUID>
Example
// Get GUIDs of objects over association MyFirstModule.Ref.
mxobj.getReferences("MyFirstModule.Ref");    // [ "12345", "12346" ]

# getSelectorEntity(attr)

Convenience function

Parameters:
Name Type Description
attr Attribute
See:
  • MxMetaObject#getSelectorEntity
Example
mxobject.getSelectorEntity("Order_OrderLine"); // "CRM.OrderLine"

# getSubEntities()

Convenience function

See:
  • MxMetaObject#getSubEntities
Example
mxobject.getSubEntities(); // [ "MyModule.EntityA", "MyModule.EntityB" ]

# getSuperEntities()

Convenience function

See:
  • MxMetaObject#getSuperEntities
Example
mxobject.getSuperEntities(); // [ "MyModule.EntityC",
                             //   "MyModule.EntityD",
                             //   "System.User" ]

# hasChanges() → {boolean}

Checks an MxObject for changes.

true if this MxObject has changes, false otherwise

boolean
Examples
mx.data.get({
    guid: "12345",
    callback: function(obj) {
        // Object is fresh from the runtime; next line prints 'false'.
        console.log(obj.hasChanges());

        obj.set("Name", "foo");

        // Object has a changed attribute; next line prints 'true'.
        console.log(obj.hasChanges());
    }
});
const objects = await retrieveByGuids({ guids: ["12345"] });
const obj = objects[0];
// Object is fresh from the runtime; next line prints 'false'.
console.log(obj.hasChanges());

obj.set("Name", "foo");

// Object has a changed attribute; next line prints 'true'.
 console.log(obj.hasChanges());

# hasSubEntities()

Convenience function

See:
  • MxMetaObject#hasSubEntities
Example
mxobject.getSubEntities(); // [ "MyModule.EntityA", "MyModule.EntityB" ]

# hasSuperEntities()

Convenience function

See:
  • MxMetaObject#hasSuperEntities
Example
if (mxobject.hasSuperEntities()) {
    alert("This object inherits from another Entity");
} else {
    alert("This object does not inherit from another Entity");
}

# inheritsFrom(className)

Convenience function

Parameters:
Name Type Description
className Entity
See:
  • MxMetaObject#inheritsFrom
Example
if (mxobject.inheritsFrom("System.User")) {
    alert("This object inherits from System.User");
} else {
    alert("This object does not inherit from System.User");
}

# isA(classname)

Convenience function

Parameters:
Name Type Description
classname Entity
See:
  • MxMetaObject#isA
Example
if (mxobject.isA("System.User")) {
    alert("This object is a System.User");
} else {
    alert("This object is not a System.User");
}

# isBoolean(attr)

Convenience function

Parameters:
Name Type Description
attr Attribute
See:
  • MxMetaObject#isBoolean
Example
if (mxobject.isBoolean("Checked")) {
    alert("Attribute 'Checked' is a Boolean");
} else {
    alert("Attribute 'Checked' is not a Boolean");
}

# isDate(attr)

Convenience function

Parameters:
Name Type Description
attr Attribute
See:
  • MxMetaObject#isDate
Example
if (mxobject.isDate("DoB")) {
    alert("Attribute 'DoB' is a Date");
} else {
    alert("Attribute 'DoB' is not a Date");
}

# isEnum(attr)

Convenience function

Parameters:
Name Type Description
attr Attribute
See:
  • MxMetaObject#isEnum
Example
if (mxobject.isEnum("Colors")) {
    alert("Attribute 'Colors' is an Enumeration");
} else {
    alert("Attribute 'Colors' is not an Enumeration");
}

# isLocalizedDate(attr)

Convenience function

Parameters:
Name Type Description
attr Attribute
See:
  • MxMetaObject#isLocalizedDate
Example
if (mxobject.isLocalizedDate("DoB")) {
    alert("Attribute 'DoB' is a Localized Date");
} else {
    alert("Attribute 'DoB' is not a Localized Date");
}

# isNumeric(attr)

Convenience function

Parameters:
Name Type Description
attr Attribute
See:
  • MxMetaObject#isNumeric
Example
if (mxobject.isNumeric("Count")) {
    alert("Attribute 'Count' is numeric");
} else {
    alert("Attribute 'Count' is not numeric");
}

# isObjectReference(attr)

Convenience function

Parameters:
Name Type Description
attr Attribute
See:
  • MxMetaObject#isObjectReference
Example
if (mxobject.isObjectReference("Mother")) {
    alert("Attribute Parent is a reference");
} else {
    alert("Attribute Parent is not a reference");
}

# isObjectReferenceSet(attr)

Convenience function

Parameters:
Name Type Description
attr Attribute
See:
  • MxMetaObject#isObjectReferenceSet
Example
if (mxobject.isObjectReferenceSet("Children")) {
    alert("Attribute Children is a reference set");
} else {
    alert("Attribute Children is not a reference set");
}

# isPassword(attr)

Convenience function

Parameters:
Name Type Description
attr Attribute
See:
  • MxMetaObject#isPassword
Example
if (mxobject.isPassword("Password")) {
    alert("Attribute 'Password' is a Password");
} else {
    alert("Attribute 'Password' is not a Password");
}

# isReadonlyAttr(attr) → {boolean}

Checks whether an attribute is read-only.

Parameters:
Name Type Description
attr string

attribute for which to check

true if attr is a read-only attribute, false otherwise

boolean

# isReference(attr)

Convenience function

Parameters:
Name Type Description
attr Attribute
See:
  • MxMetaObject#isReference
Example
if (mxobject.isReference("Children")) {
    alert("Attribute Children is a reference set");
} else {
    alert("Attribute Children is not a reference set");
}

# removeReferences(attr, guids) → {boolean}

Removes references from a reference attribute.

Parameters:
Name Type Description
attr string

reference attribute to remove references from
guids Array.<GUID>

GUIDs of the objects to remove from the reference

false if an exception occurred while removing the reference, true otherwise

boolean
Example
mxobj.removeReferences("MyFirstModule.Ent_RefEnt", ["12345", "12346"]);

# set(attr, val)

Sets the value of attribute attr to the value of val.

The type of val depends on the type of attribute.

This only changes the MxObject instance in the client session. To commit the object to the backend database, see mx.data.commit (commit in the new API).

Parameters:
Name Type Description
attr string

attribute to set
val *

value to set

Error if value is invalid, use validator#validate before calling this method

Examples
mxobj.set("Name", "John Smith");
mxobj.set("IsActive", true);

# inner FetchCallback(requested)

Callback for returning data with MxObject#fetch.

Parameters:
Name Type Description
requested *

object, attribute value or an Error object when there was an error.

Type Definitions

# FetchCallback(requested)

Callback for returning data with MxObject#fetch.

Parameters:
Name Type Description
requested *

object, attribute value or an Error object when there was an error.

# FetchErrorCallback(error)

Error callback for MxObject#fetch

Parameters:
Name Type Description
error Error

error describing the failure of the request