AJAX API Toolkit

AJAX API toolkit represents a single JavaScript class in single file. This file is already included in Platform pages to facilitate calling AJAX API functions. Simply declare the class and call functions in an on-page script as shown in the example below.

Note: This is an advanced feature that does require an understanding of JavaScript and the use of JavaScript classes.

Picklist Sample

Example of calling a list of customers to display on a page in a picklist:

<script>
var callback = function(responseText) {
    // eval() converts the json return into a JavaScript object
    var CUSTOMER = eval(responseText);

    // sort the array of results into alphabetical order by NAME
    CUSTOMER.sort((function(index){
          return function(a, b){
             return (a[index] === b[index] ? 0 : (a[index] < b[index] ? -1 : 1));
          };
          })('NAME')); // NAME is the sort by field name

    // options variable to receive picklist values
    var options = '<option>-- Select Customer --</option>';

    // add an option element for each customer record
    for(var i=0;i<CUSTOMER.length;i++){
         options += '<option value="' + CUSTOMER[i].NAME + '">' + CUSTOMER[i].NAME + '</option>';
    }

    // load options in the 'pick_customer' element
    document.getElementById('pick_customer').innerHTML = options;
}
var s = new API_Session();
s.ip_read("CUSTOMER", "NAME", "", "json", "", callback);
</script>

<select name="select" size="1" id="pick_customer"></select>

In the above script:

  1. The 'callback' variable is set to the function you want performed on the data you intend to return.
  2. The read call is made on the 'CUSTOMER' object, requesting the 'NAME' field in 'json' format.
  3. The select field provides a display point in the HTML.

GL Balance Sample

The following sample returns a table the GL Balance by Location for the account specified in the code. It assumes you have a current reporting period named like "Month Ended April 2014".

<style>
    #scriptSection fieldset {
        padding: 30px;
        border: 1px solid #EEEEEE;
    }

    #scriptSection fieldset legend {
        font-weight: bold;
        padding-left: 20px;
        padding-right: 20px;
    }

    #scriptSection fieldset table td, #scriptSection fieldset table th {
        border-left: 1px solid #EEEEEE;
        padding-left: 20px;
        padding-right: 20px;
    }

    #scriptSection fieldset table th {
        border-bottom: 1px solid #EEEEEE;
    }

    #scriptSection fieldset table tr:hover td {
        background-color: #fEf98D;
    }
</style>
<div id="scriptSection">
<fieldset>
    <legend>Current Petty Cash Balance</legend>
    <div id="arGLBalanceHolder">
        <table>
            <thead>
            <tr>
                <td>Loading ...</td>
            </tr>
            </thead>
        </table>
    </div>
</fieldset>

<script>
    jq(document).ready(function(){

        // fetch and display the gl account balance
        var monthNames = [ "January", "February", "March", "April", "May", "June",
            "July", "August", "September", "October", "November", "December" ];
        var d = new Date();
        var month = monthNames[d.getMonth()];
        var year = d.getFullYear();
        var reportingPeriod = 'Month Ended ' + month + ' ' + year;
        var account = 1010;
        var api = new API_Session();

        var callback = function(data) {
            var holder = jq('div#arGLBalanceHolder');
            data = eval(data);
            if ( data.length == 0 ) {
                holder.html('No data');
                return;
            }
            var tableContent = '<thead><tr><th>Account</th><th>Location</th><th>Amount</th></tr></thead><tbody>';
            for ( var r = 0; r < data.length; r++ ) {
                tableContent += '<tr>';
                tableContent += '<td>' + data[r].ACCOUNTNO + '--' + data[r].ACCOUNTTITLE + '</td>';
                tableContent += '<td>' + data[r].LOCATIONID + '</td>';
                tableContent += '<td>' + Number(data[r].ENDBAL).toFixed(2) + '</td>';
                tableContent += '</tr>';
            }
            tableContent += '</tbody>';
            holder.html('<table>' + tableContent + '</table></br><p>(For ' + reportingPeriod + ')</p>');
        };

        api.ip_readByQuery(
                'glaccountbalance',
                'ACCOUNTNO,ACCOUNTTITLE,ENDBAL,LOCATIONID',
                "period = '" + reportingPeriod + "' AND accountno = '" + account + "'",
                10,
                'json',
                callback
        );
    });
</script>
</div>

Pick List of Purchasing Transaction Types

<script>
    var callback = function(responseText) {
        var xml = responseText,
                xmlDoc = jq.parseXML(xml),
                $xml = jq(xmlDoc);
        var select = jq('#pick_potransaction');

        $xml.find("type[typename='PODOCUMENT']").each(function() {
            var value = jq(this).text();
            if (value !== 'Purchasing Document') {
                select.append("<option value='" + value + "'>" + value + "</option>");
            }
        });

    }
    var s = new API_Session();
    s.ip_inspect("*", "1", callback); //returned as XML not JSON
</script>

<select name="select" size="1" id="pick_potransaction"></select>

Courtesy of JMcMonegal.

Limits

The system has limits on the number of AJAX requests it will accept from a single user:

  • Aggregate: 900 requests in any 18 second period and 1800 requests in a 60 second period.
  • Parallel: 100 requests.

Limits are subject to change without notice to allow us to maintain optimal performance.

Required Methods

AJAX API Toolkit requires the following functions to establish a session:

API_Session()

This is the constructor method for establishing an API session. It uses the credentials of the current user.

Parameters:

  • controlid: Intacct control ID, optional, default = "foobar"
  • uniqueid: Enforces uniqueness on controlid, optional, default = "false"
  • dtdversion: Sets the dtd version used by the call, optional, default = "3.0"

Methods for API Functions

AJAX API Toolkit uses the following methods to make calls:

ip_create(object, fieldsArray)

Generates a create call on the API.

Parameters:

  • object: object name
  • fieldsArray: JSON array of fields: field name -> field value

ip_createXML(xmlPayload)

Generates a create API call passing XML content that you specify.

Parameters:

  • xmlPayload: XML text which may include several objects of arbitrary complexity to create

ip_delete(object, keys)

Generates a delete API call.

Parameters:

  • object: object name
  • keys: comma-separated list of keys to delete

ip_inspect(object, callback)

Generates an inspect API call on the named object.

Parameters:

  • object: object name
  • detail: 0 or 1
  • callback: JavaScript callback function. Will receive XML document returned by server as parameter.

ip_getLastRequest()

Returns last XML request sent to server. This function can be used for debugging.

ip_read(object, fields, keys, returnFormat, docparid, callback)

Generates a read API call.

Parameters:

  • object: object name
  • fields: comma-separated list of fields or *
  • keys: comma-separated list of keys to fetch
  • returnFormat: as described in API documentation
  • docparid: as described in API documentation
  • callback: JavaScript callback function. Will receive XML document returned by server as parameter.

ip_readByName(object, fields, keys, returnFormat, callback)

Generates a readByName API call.

Parameters:

  • object: object name
  • fields: comma-separated list of fields or *
  • keys: comma-separated list of keys to fetch
  • returnFormat: as described in API documentation
  • callback: JavaScript callback function. Will receive XML document returned by server as parameter.

ip_readByQuery(object, fields, query, pagesize, returnFormat, callback)

Generates a readByQuery API call.

Parameters:

  • object: object name
  • fields: comma-separated list of fields or *
  • query: query to use. See ReadByQuery() for details on query format.
  • pagesize: as described in API documentation
  • returnFormat: as described in API documentation
  • callback: JavaScript callback function. Will receive XML document returned by server as parameter.

ip_readMore(object)

Generates a readMore API call.

Parameters:

  • object: object name

ip_readRelated(object, keys, relation, fields, returnFormat, callback)

Generates a readRelated API call.

Parameters:

  • object: object name
  • keys: comma-separated list of keys to fetch
  • relation: as described in API documentation
  • fields: comma-separated list of fields or *
  • returnFormat: as described in API documentation
  • callback: JavaScript callback function. Will receive XML document returned by server as parameter.

ip_readView(view, pagesize, returnFormat, filters, callback) -- New Spring 2014

Generates a readView API call. This call usually relies on filters set in the view through the UI, but you can set additional filters to incorporate dynamic information generated through your script.

Parameters:

  • view: expressed as object#viewOriginalID.
  • pagesize: integer (optional, default 100, max 1000).
  • returnFormat: xml, cvs, or json.
  • filters: 'condition,field:operator:value,field:operator:value'. (optional, max 5 filter conditions)
  • callback: Receives the response.

Example:

var api = new API_Session();

api.ip_readView('VENDOR#43101839@10375', 20, 'json', 'AND,TOTALDUE:greater than:1000,TOTALDUE:less than:50000', callback);

ip_update(object, fieldsArray)

Generates an update API call.

Parameters:

  • object: object name
  • fieldsArray: JSON array of fields: "field name":field value

Example:

<script>

var id = '{!object.id!}';  //id of the current record of the object to update
var fmv = '{!object.test_field!}';
var s = new API_Session();

// Call API toolkit function here
var arr = {"id":id, "test_field":fmv};
s.ip_update('det_fund', arr);

</script>

ip_updateXML(xmlPayload)

Generates an update API call passing the XML you provide.

Parameters:

  • xmlPayload: XML text which may include several objects of arbitrary complexity to update

Related

You can also combine AJAX with JQuery methods (see JQuery in Page Scripts).

 

Comments

gmctall

More Examples

More examples can be found in this thread: http://developer.intacct.com/discussion/more-ajax-examples

jmote

On the last line of the ip_update example

You may want to change "det_fund" to the word "object" like you use in the variable declarations (for 'id' and 'fmv') to avoid any confusion.