Documentation

Module

mx-api/data

Methods

# static commit(params) → {Promise.<void>}

Commits an MxObject.

Any changes in the provided objects will be automatically sent to the Runtime.

Parameters:
Name Type Description
params Object

The parameters for committing MxObjects.
objects Array.<MxObject>

An array of MxObjects to commit.

A promise that resolves when the MxObject is successfully committed, or rejects with an error.

Promise.<void>
Example
// Commit multiple objects to the Runtime.
await commit({ objects: [obj1, obj2] });

# static create(params) → {Promise.<MxObject>}

Creates an MxObject.

Parameters:
Name Type Description
params Object

The parameters for creating an MxObject.
entity Entity

The name of the entity to create the MxObject for.

A promise that resolves with an instance of MxObject when successfully created, or rejects with an error.

Promise.<MxObject>
Example
// Create a new MxObject for the "MyFirstModule.Cat" entity.
const cat = await create({ entity: "MyFirstModule.Cat" });

# static remove(params) → {Promise.<void>}

Removes MxObjects.

Parameters:
Name Type Description
params Object

The parameters for removing MxObjects
guids Array.<GUID>

GUIDs of MxObjects to remove.

A promise that resolves when the MxObject is successfully removed, or rejects with an error.

Promise.<void>
Example
// Removes MxObjects by their `GUIDs`
await remove({guids: [ "123456", "45678" ]});

# static retrieveByEntity(params) → {Promise.<Array.<MxObject>>}

Retrieves MxObjects by entity from the Runtime (in online apps) or from the local database (in offline apps).

Parameters:
Name Type Attributes Description
params Object

The parameters for retrieving MxObjects.
entity string

The name of the entity to retrieve.
queryFilter QueryFilter <optional>

A query used to filter returned records in the local database. Only supported in offline apps.
filter Filter <optional>

An optional filter for sorting, limiting, or paginating the results.

A promise that resolves with an array of MxObject instances when successfully retrieved, or rejects with an error.

Promise.<Array.<MxObject>>
Examples
// Retrieve all pets of the "MyFirstModule.Pet" entity.
const pets = await retrieveByEntity({ entity: "MyFirstModule.Pet" });
// Retrieve pets with pagination and sorting applied.
const pets = await retrieveByEntity({
  entity: "MyFirstModule.Pet",
  filter: {
    offset: 15,
    limit: 5,
    sort: [["Name", "asc"], ["Age", "desc"]]
  }
});
// Retrieve pets with specific constraints on attributes. (offline only)
const pets = await retrieveByEntity({
  entity: "MyFirstModule.Pet",
  queryFilter: {
      type: "function",
      name: "and",
      parameters: [
        {
          type: "function",
          name: "contains",
          parameters: [
            {
              type: "attribute",
              attribute: "Name",
              attributeType: "String"
            },
            {
              type: "value",
              value: "ed"
            },
          ]
        },
        {
          type: "function",
          name: ">",
          parameters: [
            {
              type: "attribute",
              attribute: "Age",
              attributeType: "Integer"
            },
            {
              type: "value",
              value: 2
            }
          ]
        }
      ]
    }
 });
// Retrieve pets owned by a specific person with filtering and pagination. (offline only)
const pet = await retrieveByEntity({
    entity: "MyFirstModule.Pet",
    queryFilter: {
      type: "function",
      name: "=",
      parameters: [
        {
          type: "association",
          associationPath: "MyFirstModule.Pet_Person",
          associationType: "Reference"
        },
        {
          type: "value",
          value: "4785074604081430",
          isGuid: true
        }
      ]
    },
    filter: {
        offset: 15,
        limit: 5,
        sort: [["Name", "asc"], ["Age", "desc"]]
      }
});

# static retrieveByGuids(params) → {Promise.<Array.<MxObject>>}

Retrieves MxObjects by GUIDs from the Runtime (in online apps) or from the local database (in offline apps).

Parameters:
Name Type Description
params Object

The parameters for retrieving MxObjects by GUIDs.
guids Array.<GUID>

An array of GUIDs to retrieve the MxObjects for.

A promise that resolves with an array of MxObject instances when successfully retrieved, or rejects with an error.

Promise.<Array.<MxObject>>
Example
// Retrieve MxObjects by GUIDs.
const objects = await retrieveByGuids({ guids: ["123456", "111111"] });

# static retrieveByPath(params) → {Promise.<Array.<MxObject>>}

Retrieves MxObjects by path from the Runtime (in online apps) or from the local database (in offline apps).

Parameters:
Name Type Attributes Default Description
params Object
path string

Path (reference name) to the desired object, relative to the object referenced by GUID. E.g. MyFirstModule.Parent_Child.
guid GUID

// GUID of the starting entity
entity Entity

// The target entity
direction AssociationDirection <optional>
 "reverse"

A promise that resolves with an array of MxObject instances when successfully retrieved, or rejects with an error.

Promise.<Array.<MxObject>>
Example
const parent = await retrieveByPath({path: "MyFirstModule.Parent_Child", guid: "123456", entity: "MyFirstModule.Parent"})

# static retrieveByXPath(params) → {Promise.<Array.<MxObject>>}

Retrieves MxObjects by XPath from the Runtime.

Note: This method is not supported in offline apps.

Parameters:
Name Type Attributes Default Description
params Object

The parameters for retrieving MxObjects.
xpath string

The XPath query to execute.
filter Filter <optional>

An optional filter for sorting, limiting, or paginating the results.
returnCount boolean <optional>
 false

Whether to return the count of objects instead of the objects themselves.

A promise that resolves with an array of MxObject instances when successfully retrieved, or rejects with an error.

Promise.<Array.<MxObject>>
Examples
// Retrieve all users of the "System.User" entity.
const users = await retrieveByXPath({ xpath: "//System.User" });
// Retrieve users with pagination and sorting applied.
const users = await retrieveByXPath({
  xpath: "//System.User",
  filter: {
    offset: 15,
    limit: 5,
    sort: [["Name", "asc"], ["Age", "desc"]]
  }
});

# static rollback(params) → {Promise.<void>}

Rolls back MxObjects.

Parameters:
Name Type Description
params Object

The parameters for rolling back MxObjects.
objects Array.<MxObject>

MxObjects to remove

A promise that resolves when the MxObject is rolled back successfully, or rejects with an error.

Promise.<void>
Example
// Rolls back objects 'obj1' and 'obj2'
await rollback({objects: [ obj1, obj2 ]});

# static subscribe(scope, params) → {Unsubscribable}

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
scope
params 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 SubscribeEntityCallback | SubscribeObjectCallback | SubscribeAttributeCallback | SubscribeValidationCallback

Function to invoke when an update is available.

handle which can be passed to unsubscribe to remove the subscription

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

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

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

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

unsubscribe(subscription);

# static unsubscribe(handle)

Unregisters a callback registered through subscribe.

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

Parameters:
Name Type Description
handle Unsubscribable

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

// And then unsubscribe:
unsubscribe(subscription);

# static update(params) → {Promise.<void>}

Triggers listeners for changes in a MxObject, an attribute of an MxObject, or for all MxObjects of a specific entity.

Parameters:
Name Type Attributes Description
params Object

The parameters defining the scope of the update.
guid GUID <optional>

The GUID of the MxObject to invoke the update for. If provided with attr, triggers updates for the specific attribute.
entity string <optional>

The name of the entity to invoke updates for. Cannot be combined with guid or attr.
attr string <optional>

The attribute of the MxObject to invoke the update for. Must be used in combination with guid.

A promise that resolves when the update is successfully triggered, or rejects with an error if the operation fails.

Promise.<void>
Examples
// Trigger object subscriptions
await update({
    guid: "123213"
});
// Trigger attribute subscriptions
await update({
    guid: "123213",
    attr: "Name"
});
// Trigger entity subscriptions
await update({
    entity: "System.User"
});

Type Definitions

# 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

# 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.<ObjectValidation>

validations for the object
Unsubscribable

# Unsubscribable

Invoke to unsubscribe from entity changes.

Properties:
Name Type Description
unsubscribe function

A function to unsubscribe from the entity.