Documentation
Tutorials
Form messages Widget Lifecycle

Namespace

data

mx.data

Retrieve and manipulate MxObjects.

Methods

# static action(args)

Executes a Microflow. Note that this method is not supported in offline apps.

The params.params.applyto parameter indicates which objects are passed to the Microflow as input.

Name Description
none don’t pass any objects to the Microflow
selection pass the objects with the given GUIDs
set pass the objects matching the given XPath query
Parameters:
Name Type Description
args Object
params.actionname string

name of the Microflow to invoke
params.applyto "none" | "set" | "selection"

to what to apply the Microflow
params.guids Array.<GUID>

the GUIDs to apply the Microflow to
params.xpath string

The root entity for an XPath query. The Microflow will be applied to the matching objects.
params.constraints string

the constraints for the xpath parameter
params.sort mx.data~SortSpec

sorting of XPath query results before feeding them to the Microflow
context mendix/lib/MxContext

the context for the Microflow
ags.origin mxui/lib/form/_FormBase

the page on which instructions returned by the server ('close form' in particular) can be executed
args.async boolean

whether the Microflow should be executed asynchronously. Note that the result of an asynchronous microflow is not returned.
args.callback mx.data~ActionSuccessCallback

function to handle the result when successful
args.error mx.data~ActionErrorCallback

function to handle errors
args.onValidation mx.data~ActionValidationCallback

function to handle validation feedback
Examples

Calling a simple Microflow, not expecting any entities

mx.data.action({
    params: {
        actionname: "MyFirstModule.PetCat"
    },
    origin: this.mxform,
    callback: function(obj) {
        // no MxObject expected
        alert("Just petted the cat a little");
    },
    error: function(error) {
        alert(error.message);
    },
    onValidation: function(validations) {
        alert("There were " + validation.length + " validation errors");
    }
});

Calling a Microflow expecting a list of entities, using an XPath query

mx.data.action({
    params: {
        applyto: "set",
        actionname: "MyFirstModule.GetFavoriteFood",
        xpath: "//MyFirstModule.Cat",
        constraints: "[id=281530811285515 or id=281530811285506]"
    },
    origin: this.mxform,
    callback: function(obj) {
        // expect single MxObject
        alert(obj.get("manufacturer"));
    },
    error: function(error) {
        alert(error.message);
    }
});

Performing the same request, but now using a list of `GUIDs`

mx.data.action({
    params: {
        applyto: "selection"
        actionname: "MyFirstModule.GetFavoriteFood",
        guids: [ "281530811285515", "281530811285506"]
    },
    origin: this.mxform,
    callback: function(obj) {
        // expect single MxObject
        alert(obj.get("manufacturer"));
    },
    error: function(error) {
        alert(error.message);
    }
});

Showing a progress bar while calling a microflow

var progressId = window.mx.ui.showProgress("Progress msg", true);
mx.data.action({
    params: {
        actionname: "MyFirstModule.PetCat"
    },
    origin: this.mxform,
    callback: function(obj) {
        // no MxObject expected
        alert("Just petted the cat a little");
        window.mx.ui.hideProgress(progressId);
    },
    error: function(error) {
        alert(error.message);
        window.mx.ui.hideProgress(progressId);
    },
    onValidation: function(validations) {
        alert("There were " + validation.length + " validation errors");
    }
});

# static callNanoflow(params)

Executes a Nanoflow.

Parameters:
Name Type Description
params Object
nanoflow Object

Nanoflow definition to execute, this value is exported to the property defined in the custom widget. This value may change, so it should not be tampered.
context mendix/lib/MxContext

the context for the Nanoflow
origin mxui/lib/form/_FormBase

the page on which instructions ('close form' in particular) can be executed
callback mx.data~ActionSuccessCallback

function to handle the result when successful
error mx.data~ActionErrorCallback

function to handle errors
Example

Calling a simple Nanoflow

mx.data.callNanoflow({
    nanoflow: this.propertyWithNanoflow,
    origin: this.mxform,
    context: this.mxcontext,
    callback: function(result) {
        alert("Nanoflow completed with result " + result);
    },
    error: function(error) {
        alert(error.message);
    }
});

# static commit(args, scope)

Commits an MxObject.

When there are changes, these will automatically be sent to the Runtime.

Parameters:
Name Type Description
args Object
mxobj mendix/lib/MxObject

MxObject to save changes for
mxobjs Array.<mendix/lib/MxObject>

MxObjects to save changes for
callback mx.data~CommitSuccessCallback

function to handle the result when successful
error mx.data~CommitErrorCallback

function to handle errors
onValidation mx.data~CommitValidationCallback

function to handle validation feedback
scope Object

scope in which the error and callback handler are invoked
Example
mx.data.commit({
    mxobj: obj,
    callback: function() {
        console.log("Object committed");
    },
    error: function(e) {
        console.error("Could not commit object:", e);
    }
});

# static create(args, scope)

Creates an MxObject.

Parameters:
Name Type Description
args Object
entity string

entity to create an instance of
callback mx.data~CreateSuccessCallback

function to handle the result when successful
error mx.data~CreateErrorCallback

function to handle errors
scope Object

scope in which the error and callback handler are invoked
Example
mx.data.create({
    entity: "MyFirstModule.Cat",
    callback: function(obj) {
        console.log("Object created on server");
    },
    error: function(e) {
        console.error("Could not commit object:", e);
    }
});

# static get(args, scopenullable)

Retrieves MxObjects from the Runtime (in online apps) or from the local database (in offline apps). Note that not every parameter is supported in offline apps.

Only one of the guid / guids / xpath / microflow parameters should be set.

Parameters:
Name Type Attributes Description
args Object
guid GUID

GUID of the object to retrieve
guids Array.<GUID>

GUIDS of the objects to retrieve
xpath string

XPath query to retrieve (not supported offline)
microflow string

a Microflow to fetch objects from (not supported offline)
path string

Path (reference name) to the desired object, relative to the object referenced by guid. E.g. MyFirstModule.Child_Parent.
callback mx.data~GetSuccessCallback

function to handle the result
error mx.data~GetErrorCallback <nullable>

function to handle errors
count boolean <nullable>

whether a count of the entire set should be returned
filter.attributes Array.<string> <nullable>

if provided, only the given attributes will be fetched
filter.offset number <nullable>

index from where to start in the set
filter.sort mx.data~SortSpec <nullable>

specifies how the result set should be sorted
filter.amount number <nullable>

maximum number of objects to fetch
filter.distinct boolean <nullable>

only fetch distinct objects
filter.references Object.<string, mx.data~ReferencesSpec> <nullable>

If provided, the given references, specified as keys of args.filter.references, will be pre-fetched within the same request. Pre-fetched objects will be accessible via mxobj.getChildren. Supported only for retrieval through XPath.
scope Object <nullable>

scope in which the error and callback handler are invoked
Examples
mx.data.get({
    guids: [ "123456", "456789" ],
    callback: function(objs) {
        console.log("Received " + objs.length + " MxObjects");
    }
});
mx.data.get({
    guid: "123456",
    callback: function(obj) {
        console.log("Received MxObject with GUID " + obj.getGuid());
    }
});
mx.data.get({
    xpath: "//System.User",
    callback: function(objs) {
        console.log("Received " + objs.length + " MxObjects");
    }
});
mx.data.get({
    xpath: "//System.User",
    filter: {
        sort: [["Name", "asc"]],
        offset: 0,
        amount: 10
    },
    callback: function(objs) {
        console.log("Received " + objs.length + " MxObjects");
    }
});

# static getOffline(entity, constraints, filter, callback, error)

Retrieve MxObjects from the local database. Note that this method is not supported in online apps.

Parameters:
Name Type Attributes Description
entity string

the entity of the objects to retrieve
constraints Array.<Object>

an array of constraints to filter returned records.
operator string

the operator to constrain with. One of equals, lessThan, lessThanOrEquals, greaterThan, greaterThanOrEquals, contains, and, or.
attribute string <nullable>

the attribute (or reference) to constrain on Should be omitted for and and or operators.
value string | number

an argument for the constraints's operator. Should be omitted for and and or operators.
negate boolean <nullable>

if true, return the objects not matching the constraint. Should be omitted for and and or operators.
constraints Array.<Object> <nullable>

nested constraints to combine with given operator. Should only be used with and and or operators.
filter Object

sorting and paging options additionally limiting what objects to retrieve
offset number <nullable>

index from where to start in the results
limit number <nullable>

maximum number of objects in the result
sort mx.data~SortSpec <nullable>

specifies how the result set should be sorted
callback mx.data~GetOfflineSuccessCallback

function to handle the result
error mx.data~GetOfflineErrorCallback

function to handle errors
Examples
mx.data.getOffline("MyFirstModule.Pet", [], {}, function(mxobjs, count) {
  console.log("There are " + count + " pets");
});
mx.data.getOffline("MyFirstModule.Pet", [{
  attribute: "MyFirstModule.Pet_Person",
  operator: "equals",
  value: "1234" // the guid of the owner, which is a Person entity
}], {}, function(mxobjs, count) {
  console.log("There are " + count + " pets referring to owner 1234");
});
mx.data.getOffline("MyFirstModule.Pet", [{
  operator: "or",
  constraints: [{
        attribute: "Name",
        operator: "equals",
        value: "ed"
     }, {
        attribute: "Name",
        operator: "equals",
        value: "jack"
     }]
  }], {}, function(mxobjs, count) {
  console.log("There are " + count + " pets whose name is either 'ed' or 'jack'");
});
mx.data.getOffline("MyFirstModule.Pet", [{
  attribute: "Name",
  operator: "contains",
  value: "ed"
}, {
  attribute: "Age",
  operator: "greaterThan",
  value: 2
}], {
  offset: 15,
  limit: 5,
  sort: [["Name", "asc"], ["Age", "desc"]]
}, function(mxobjs, count) {
  console.log("Pets that matched your filter: " + mxobjs.length);
  console.log("Pets that matched your query: " + count);
}, function(e) {
  console.error("Could not retrieve slice:", e);
});

# static remove(args, scope)

Removes MxObjects.

Only one of args.guid or args.guids should be set.

Parameters:
Name Type Description
args Object
guid GUID

GUID of MxObject to remove
guids Array.<GUID>

GUIDs of MxObjects to remove
callback mx.data~RemoveSuccessCallback

function to handle the result when successful
error mx.data~RemoveErrorCallback

function to handle errors
scope Object

scope in which the error and callback handler are invoked
Example
mx.data.remove({
    guid: "123456",
    callback: function() {
        console.log("Object removed");
    },
    error: function(e) {
        console.error("Could not remove object:", e);
    }
});

mx.data.remove({
    guids: [ "123456", "45678" ],
    callback: function() {
        console.log("Objects removed");
    },
    error: function(e) {
        console.log("Could not remove objects:", e);
    }
});

# static rollback(args, scope)

Rollbacks an MxObject.

Parameters:
Name Type Description
args Object
mxobj mendix/lib/MxObject

MxObject to rollback changes for
mxobjs Array.<mendix/lib/MxObject>

MxObjects to rollback changes for
callback mx.data~RollbackSuccessCallback

function to handle the result when successful
error mx.data~RollbackErrorCallback

function to handle errors
scope Object

scope in which the error and callback handler are invoked
Example
mx.data.rollback({
    mxobj: obj,
    callback: function() {
        console.log("The object was rollbacked");
    },
    error: function(e) {
        console.error("Could not rollback object:", e);
    }
});

# static saveDocument(guid, fileName, params, blob, callback, error)

Save a document file.

Parameters:
Name Type Description
guid GUID

GUID of the MxObject to associate the file with.
fileName string

file name to store the file with. If null, it will be derived from the blob parameter. For File blobs (e.g. those retrieved from an <input type='file'>) this is the name of the file, for Blob objects it is blob.
params Object

additional parameters when saving the file. These depend on the type of document to upload. For images, width and height specify the width and height of the thumbnail that will be generated for the image.
blob

Blob containing the file data.
callback mx.data~SaveDocumentSuccessCallback

success handler.
error mx.data~SaveDocumentErrorCallback

error handler.
Example
var fileBlob = document.querySelector("input[type=file]").files[0];
mx.data.saveDocument("123456", "Bunnies.jpg", { width: 180, height: 180 }, fileBlob, function() {
  // success
}, function(e) {
  console.error(e);
});

# static subscribe(args) → {mx.data~SubscribeHandle}

Registers a callback to be invoked on changes in an MxObject, an attribute of a MxObject, any changes to MxObjects of a specific entity or validations errors in a specific MxObject.

Parameters:
Name Type Attributes Description
args Object
guid GUID <nullable>

GUID to subscribe to
entity string <nullable>

entity to subscribe to
attr string <nullable>

attribute to subscribe to
val boolean <nullable>

subscribe to a validation on an MxObject
callback mx.data~SubscribeEntityCallback | mx.data~SubscribeObjectCallback | mx.data~SubscribeAttributeCallback | mx.data~SubscribeValidationCallback

function to invoke when an update is available

handle which can be passed to unsubscribe to remove the subscription

mx.data~SubscribeHandle
Examples
// Subscribe to all changes in an MxObject
var subscription = mx.data.subscribe({
    guid: "123213",
    callback: function(guid) {
        console.log("Object with guid " + guid + " changed");
    }
});

mx.data.unsubscribe(subscription);
// Subscribe to changes in a specific attribute of an MxObject
var subscription = mx.data.subscribe({
    guid: "123213",
    attr: "Name",
    callback: function(guid, attr, value) {
        console.log("Object with guid " + guid + " had its attribute " +
                    attr + " change to " + value);
    }
});

mx.data.unsubscribe(subscription);
// Subscribe to validations of an MxObject
var subscription = mx.data.subscribe({
    guid: "123213",
    val: true,
    callback: function(validations) {
        var reason = validations[0].getReasonByAttribute("MyAttribute");
        console.log("Reason for validation error on attribute MyAttribute: " + reason);
    }
});

mx.data.unsubscribe(subscription);
// Subscribe to changes in a class
var subscription = mx.data.subscribe({
    entity: "System.User",
    callback: function(entity) {
        console.log("Update on entity " + entity);
    }
});

mx.data.unsubscribe(subscription);

# static unsubscribe(handle)

Unregisters a callback registered through mx.data~subscribe.

Unregistering callbacks when they are no longer needed is important to prevent memory leaks.

Parameters:
Name Type Description
handle mx.data~SubscribeHandle

handle previously returned by a call to mx.data~subscribe
Example
// First subscribe:
var subscription = mx.data.subscribe({
    entity: "System.User",
    callback: function(entity) {
        console.log("Received update for entity " + entity);
    }
});

// And then unsubscribe:
mx.data.unsubscribe(subscription);

# static update(args)

Calls listeners to changes in a MxObject, an attribute of a MxObject or any changes to MxObjects of a entity.

Parameters:
Name Type Description
args Object
guid GUID

GUID to invoke the update for
entity string

entity to invoke the update for
attr string

attribute to invoke the update for
callback mx.data~UpdateCallback

function to be called after all invocations have been done
Examples
// Trigger object subscriptions
mx.data.update({
    guid: "123213"
});
// Trigger attribute subscriptions
mx.data.update({
    guid: "123213",
    attr: "Name"
});
// Trigger entity subscriptions
mx.data.update({
    entity: "System.User",
});

# inner ActionSuccessCallback(value)

Success callback for mx.data.action

Parameters:
Name Type Description
value mendix/lib/MxObject | Array.<mendix/lib/MxObject> | boolean | number | string

# inner CommitSuccessCallback(args, scopeopt)

Success callback for mx.data.commit

Parameters:
Name Type Attributes Description
args object
scope object | null <optional>

# inner CreateSuccessCallback(created)

Success callback for mx.data.create

Parameters:
Name Type Description
created mendix/lib/MxObject

object

# inner GetOfflineSuccessCallback(objs, count)

Success callback for mx.data.getOffline

Parameters:
Name Type Description
objs Array.<mendix/lib/MxObject>

the requested objects
count number

the total number of matching objects before filtering

# inner GetSuccessCallback(objs, extra)

Success callback for mx.data.get

Parameters:
Name Type Description
objs mendix/lib/MxObject | Array.<mendix/lib/MxObject>

either a single MxObject or an array of `MxObjects, depending on the original request.
extra
count number

when a count was requested, the total number of matching objects before filtering

# inner RemoveSuccessCallback(args)

Success callback for mx.data.remove

Parameters:
Name Type Description
args object

# inner RollbackSuccessCallback(args, scopeopt)

Success callback for mx.data.rollback

Parameters:
Name Type Attributes Description
args object
scope object | null <optional>

# inner SaveDocumentSuccessCallback(guid, fileName, params, blob, callback, error)

Success callback for mx.data.saveDocument

Parameters:
Name Type Description
guid GUID
fileName string | null
params UploadDocumentParams
blob Blob
callback function
error function

# inner SubscribeEntityCallback(entity) → {Unsubscribable}

Callback to register for entity changes

Parameters:
Name Type Description
entity string
Unsubscribable

# inner ValidateSuccessCallback(mxobjs, callback, error)

Success callback for mx.data.validate

Parameters:
Name Type Description
mxobjs Array
callback function
error function

Type Definitions

# ActionErrorCallback(errornullable)

Error callback for mx.data.action

Parameters:
Name Type Attributes Description
error Error <nullable>

error describing the failure of the request

# ActionSuccessCallback(value)

Success callback for mx.data.action

Parameters:
Name Type Description
value mendix/lib/MxObject | Array.<mendix/lib/MxObject> | boolean | number | string

# ActionValidationCallback(validations)

Validation callback for mx.data.action

Parameters:
Name Type Description
validations Array.<mendix/lib/ObjectValidation>

validations received for the request

# CommitErrorCallback(error)

Error callback for mx.data.commit

Parameters:
Name Type Description
error Error

Error describing the failure of the request.

# CommitSuccessCallback()

Success callback for mx.data.commit

# CommitValidationCallback(validations)

Validation callback for mx.data.commit

Parameters:
Name Type Description
validations Array.<mendix/lib/ObjectValidation>

validations received for the request

# CreateErrorCallback(error)

Error callback for mx.data.create

Parameters:
Name Type Description
error Error

error describing the failure of the request

# CreateSuccessCallback(created)

Success callback for mx.data.create

Parameters:
Name Type Description
created mendix/lib/MxObject

object

# GetErrorCallback(error)

Error callback for mx.data.get

Parameters:
Name Type Description
error Error

error describing the failure of the request

# GetOfflineErrorCallback(error)

Error callback for mx.data.getOffline

Parameters:
Name Type Description
error Error

error describing the failure of the request

# GetOfflineSuccessCallback(objs, count)

Success callback for mx.data.getOffline

Parameters:
Name Type Description
objs Array.<mendix/lib/MxObject>

the requested objects
count number

the total number of matching objects before filtering

# GetSuccessCallback(objs, extra)

Success callback for mx.data.get

Parameters:
Name Type Description
objs mendix/lib/MxObject | Array.<mendix/lib/MxObject>

either a single MxObject or an array of `MxObjects, depending on the original request.
extra
count number

when a count was requested, the total number of matching objects before filtering
Object

# ReferencesSpec

Specifies how objects associated with the requested one must be fetched.

Properties:
Name Type Attributes Description
attributes Array.<string> <nullable>

if provided, only the given attributes of an objects will be fetched
amount number <nullable>

maximum number of objects to fetch
sort mx.data~SortSpec <nullable>

specifies how the result set should be sorted

# RemoveErrorCallback(error)

Error callback for mx.data.remove

Parameters:
Name Type Description
error Error

error describing the failure of the request

# RemoveSuccessCallback()

Success callback for mx.data.remove

# RollbackErrorCallback(error)

Error callback for mx.data.rollback

Parameters:
Name Type Description
error Error

error describing the failure of the request

# RollbackSuccessCallback()

Success callback for mx.data.rollback

# SaveDocumentErrorCallback(error)

Error callback for mx.data.rollback

Parameters:
Name Type Description
error Error

error describing the failure

# SaveDocumentSuccessCallback()

Success callback for mx.data.saveDocument

Array.<Array.<string>>

# SortSpec

Specifies how the result set must be sorted.

Consists of ordered pairs of an attribute name and a string "asc" or "desc".

Example
[ [ "LastName", "asc" ], [ "FirstName", "asc" ] ]

# SubscribeAttributeCallback(guid, attribute, value)

Callback to register for attribute changes

Parameters:
Name Type Description
guid GUID

GUID of the changed object
attribute string

attribute that was changed
value *

new value of the attribute

# SubscribeEntityCallback(entity)

Callback to register for entity changes

Parameters:
Name Type Description
entity string

# SubscribeHandle

Handle to a subscription

# SubscribeObjectCallback(`GUID`)

Callback to register for object changes

Parameters:
Name Type Description
`GUID` GUID

of the changed object.

# SubscribeValidationCallback(validations)

Callback to register for object validations

Parameters:
Name Type Description
validations Array.<mendix/lib/ObjectValidation>

validations for the object

# UpdateCallback()

Callback called after invocations by mx.data~update are done

# ValidateErrorCallback(error)

Error callback for mx.data.validate

Parameters:
Name Type Description
error Error

Error describing the failure of the request.

# ValidateSuccessCallback()

Success callback for mx.data.validate