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 getFileUrl(params) → {string}

Gets the URL pointing to the most recent version of a stored file for the given MxObject.

The returned URL can be used to download or display the file.

Parameters:
Name Type Attributes Default Description
params Object

The parameters for retrieving the file URL.
object MxObject

The MxObject containing the file, should be an instance or generalization of System.FileDocument or System.Image.
fileName string <optional>

A custom name for the file, when retrieved by the URL.
thumbnail boolean <optional>
 false

Whether to retrieve a thumbnail version of the file.

A URL that can be used to access the file.

string
Examples
// Get URL for a file
const url = getFileUrl({ object: mxobj });
// Get URL for a file with a custom name
const url = getFileUrl({
  object: mxobj,
  fileName: "report.pdf"
});

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