AJAX API (v2.0)

Magentrix has a AJAX REST API wrapper that allows you to easily use REST to communicate with your Magentrix platform. In order to use the wrapper, you must include this on your page:

<aspx:IncludeStandardScript runat='server' ScriptType='REST' version='2.0' />

There are a variety of functions available to access the REST API.

Exec
Get
Query
Search
IsSuccess
Create
Edit
Upsert
Remove
Metadata

REST2.exec

The exec method allows you to execute any action available to AJAX (Has a Json Response). You must specify the Action's URL to call it. You can also specify any parameters that may be needed by the action.

There are a variety of options available:

url: URL of the action, for example: "/aspx/mypage/myaction".
data: the parameters/POST data to be passed to your action's arguments.
type: "POST" or "GET". Allows you to specify whether this will be a POST or a GET call, defaults to POST.
stateful: boolean. Determines whether or not the action should return the state of the action.
verifyOrigin: boolean. Determines whether the call should provide an anti-forgery token.
callback: function, whether the operation was successful or not, the callback is called and proper results is reported.

Here's an example of Active Class Action method:

[HttpPost]
[HandleExceptionsForJson]
public ActionResponse TestMethod(Contact contact, bool enableAsUser)
{
   if (Insert(contact) && enableAsUser) 
   {
       // Enables the contact as a portal user and sets the email as user's login name.
       PortalManager.CreatePortalUser(contact, contact.Email);
   }
   
   return Json("OK");
}

Here's an example of calling the above action using the AJAX API:

var contact = { 
  Firstname : "John", 
  Lastname : "Smith", 
  Email : "johns@testmail.com"
};

REST2.exec({ 
    url:"/aspx/test/testMethod", 
    data: { contact: contact, enableAsUser: true }, 
    callback: function(context) { 
        if (REST2.isSuccess(context)) {
            // ... context.Result == "OK"
        }
    }   
});

The "context" object is always passed to the "callback" function and is never "null". This object returns a JavaScript object that contains three fields:

Result is a variable the action has returned. This will be determined by whatever your called action returns.
Errors shows any errors that the function encountered.
HasErrors is a boolean that defines if there were any errors encountered.

REST2.isSuccess

The isSuccess method allows you to determine if your REST method was successful or not. If it successfully performs its action, it will return true. If it did not successfully perform its action, it will display any errors it encountered. It accepts a variable as an argument.

{ 
  callback:function(context) { 
    if (REST2.isSuccess(context)) {
       console.log(context);
    }
  }
}

REST2.get

The get method allows you to retrieve one record from the database. You must specify the id of the record you wish to retrieve.

REST2.get({ 
   id: "01000000000004600bo",
   callback: function(context) { 
      console.log(context); 
   }
});

REST2.query

The query method is used to query entities from the Magentrix database. You must supply a query string. In order to use the skip option, you must supply an ORDER BY in your query string. In order to learn more about Magentrix REST Query syntax please click here.

Options include:

query: string. Query string which contains SELECT, FROM, WHERE, ORDER BY and LIMIT clauses.
includes: string. Optional. Comma-separated list of Relationship Names as related entities which should be eager loaded along with the records being queried.
callback: function. A callback to access the results.

Query Format:

SELECT field1, field2, field3 FROM entityName
    [WHERE conditions] 
    [ORDER BY field direction] 
    [LIMIT n,n]

This returns a JavaScript object that contains four fields:

Count: number of records retrieved if there are no skip and take specified, otherwise the total number of records the query returns.
Errors: shows any errors that the function encountered.
HasErrors: is a boolean that defines if there were any errors encountered.
Records: is an array that contains all the records that the function retrieved.

REST2.query({
   query:'Select Id, Name FROM Contact WHERE FirstName == "John"', 
   callback : function(context) { 

      //contains the record data
      console.log(context.Count); 

   } 
});

Here's an example of querying data with pagination that returns the first five results:

REST2.query({
   query:'FROM Contact WHERE FirstName == "John" ORDER BY FirstName LIMIT 10,5', 
   callback : function(context) { 
      console.log(context.Count);
      // Loop through the records:
      $.each(context.Records, function(index, record) {
        // Your code...
      });
   } 
});

REST2.search

The Search function allows you to do a full-text search of your entities to find relevant records. By using Search, the results can be ordered by the relevancy to the search term. You are able to provide a string as the search term (e.g. "brown hair").

Options:

query (string,required): Query string which contains FIND, IN, WHERE, ORDER BY, LIMIT and SELECT clauses.
includes (string,optional): Comma-separated list of Relationship Names as related entities which should be eager loaded along with the records being queried.
fullTextEnabled (boolean,optional): Determines whether the search should perform a full-text search or standard search. Default value is "true".
callback (function,required): A callback function to access the results.

Query Format:

FIND {keywords} IN entityName 
  [WHERE conditions]
  [ORDER BY field direction] 
  [LIMIT n]
  [SELECT field1, field2, field3]

This returns a JavaScript object that contains four fields:

Count is a number that shows how many records there are of that type.
Errors show any errors that the function encountered.
HasErrors is a boolean that defines if there were any errors encountered.
Records is an array that contains all the records that the function retrieved.

REST2.search({
   query:'FIND {"john smith"} IN Contact ORDER BY Name DESC',
   callback : function(context) { 
      if (REST2.isSuccess(context)) {
         console.log(context.Records);
      }
   }
});

REST2.create

The Create function allows you to create a new record of a defined Entity type. You must supply the entity name, and the object with properties which has all required fields and meets all validation rules.

The method accepts the following setting parameters:

objectType (string, required): full name of the entity including its Entity Schema except for "standard" Schema Entities.
data (object, required): JavaScript object with properties which has all required fields and meets all validation rules.
callback (function, required): A callback function to access the results.

The method returns a JavaScript object that contains three fields:

Id: the id of the record you have just created.
HasErrors: a boolean that defines if there were any errors encountered.
Errors: shows any errors that the function encountered.

REST2.create({
   objectType: 'Contact',
   data: { FirstName: 'John', LastName: 'Smith', Email: 'john.smith@example.com' },
   callback: function(context) {
      if (REST2.isSuccess(context)) {
           var newId = context.Id;
      }
   }
});

REST2.edit

The Edit function allows you to edit an existing record. You must supply the entity name and the object with properties which has all required fields and meets all validation rules. Magentrix RESTful edit performs partial update on the Entity record and therefore only fields that a value provided for them will be updated. If you need to set the values of some fields to "null" (remove/erase their value), use the fieldsToNull parameter.

Note: The data object passed must contain the Id field and the ID value must be provided.

The method accepts the following setting parameters:

objectType (string, required): full name of the entity including its Entity Schema except for "standard" Schema Entities.
data (object, required): JavaScript object with properties which has all required fields and meets all validation rules.
callback (function, required): A callback function to access the results.
fieldsToNull (array, optional): list of field names to erase their values.

The method returns a JavaScript object that contains three fields:

Errors shows any errors that the function encountered.
HasErrors is a boolean that defines if there were any errors encountered.
Id is the id of the record you have just edited.

var contact = { 
  Id : "01000000000004600bo", 
  Description : "Tall, dark, and handsome"
};

// The below statement updates the "Description" field ONLY.
REST2.edit({
  objectType : "Contact", 
  data: contact,
  callback : function(context) {
      if (REST2.isSuccess(context)) {
          // Do something....
      }
  }
});

REST2.upsert

The Upsert function allows you to upsert (update or insert) a record. You must supply a type and a model. An ExternalId option allows you to specify by which field the method should search to find a record within the database (If not specified ID is used). If a record is found, the method will perform a partial update on the record; if no record is found, the system will create a new one. If more than one record is found, the system generates an error.

The method accepts the following setting parameters:

objectType (string, required): full name of the entity including its Entity Schema except for "standard" Schema Entities.
data (object, required): JavaScript object with properties which has all required fields and meets all validation rules.
externalId (string,optional): The field by which the system should search to find a record and determine to perform update or insert.
callback (function, required): A callback function to access the results.
fieldsToNull (array, optional): list of field names to earse their values.

Here's an example of performing an upsert by email:

var contact = { 
   Email : "Johns@testmail.com", 
   FirstName : "John", 
   Phone : "416-222-3333"
};

REST2.upsert({ 
   objectType: 'Contact', 
   data: contact,
   externalId: 'Email', 
   callback: function(context) { 
       if (REST2.isSuccess(context)) {
          // Do something....
       }
   }
});

REST2.remove

The Remove function allows you to delete a record. You must supply an id to remove it. You can choose to make the delete permanent. If you set permanent to false, the record will be sent to the recycle bin and if permanent is set to true, the record will be permanently deleted. Note that all Salesforce objects will be sent to the recycle bin, regardless of permanent settings.

The method accepts the following setting parameters:

id: ID of the record to be deleted.
permanent (boolean,option): default is false. If set to true, the record will not be moved to the Recycle Bin and will be permanently removed.
callback (function, required): A callback function to access the results.

The method returns a JavaScript object that contains three fields:

Id is the id of the record you have just deleted
HasErrors is a boolean that defines if there were any errors encountered.
Errors shows any errors that the function encountered.

Here's an example of deleting an account record:

REST2.remove({
  id : "00100000000003E0001",
  callback : function(result) { ... }
});

REST2.metadata

This API can be used to describe entities and their fields.

This method requires "objectType" which is the name of entity you want to be described.

objectType: name of the entity to describe

This method returns a JavaScript object that contains the following properties:

Here is an example of how you can call it:

REST2.metadata({
   objectType : "Account",
   callback : function(entityMetadata) {
      if (REST2.isSuccess(entityMetadata) {

        // Now you can access various properties of the entity metadatavar label = entityMetadata.Label;
        ...
        
        // You also can use a method to find entity fields and access the field metadata.var typeField = entityMetadata.findProperty("Type");
        
      }
   }
});

Table of Contents

AJAX API (v2.0)

REST2.exec

REST2.isSuccess

REST2.get

REST2.query

REST2.search

REST2.create

REST2.edit

REST2.upsert

REST2.remove

REST2.metadata