Getting Started with AJAX API

DEPRECATED: The AJAX APIs are deprecated. They continue to work, for backward compatibility, but they are not being extended or enhanced. (Web pages should use AJAX and REST to carry on a conversation with the server, rather than the deprecated AJAX APIs.)

This topic is a tutorial for the AJAX API where you will learn:

• How to get related data for one record from another object in the On Change Event Script for a field.
• How to set a form field based on related object data in the Lookup Post-Selection Event Script for a field.

In both cases, the script code contains JavaScript and makes calls to the AJAX API.

For cut-and-paste code samples, see Code Samples

On Change Event Script

This example uses the standard Benefits object in the Employee Manager application, adding these two custom fields:

• Employee ID
• Social Security Number

These two fields correspond to the same-named fields in the Employees object in Employee Manager. This example assumes that you have already added these custom fields to Benefits.

At runtime, when a user enters an employee ID in Benefits and tabs out of the field, script code takes the employee ID and searches for the corresponding record in Employees, retrieving the employee's name and social security number. The retrieved values are used to set the corresponding fields in the Benefits tab.

You enter scripting by following the instructions in Field Scripting.

The following explains the JavaScript code line by line for the on change event for this example. You can find the complete code in On Change Event Script Example.

Before you make an AJAX API call, you must pass the session identifier to the platform:

AjaxInfo.setServerId('{$AppSessionID}');

By calling setServerId and specifying $AppSessionID, you are asking to use the credentials of the current logged in user.

In the HTML document object model (DOM), the current form is named mainForm. The line of code below gets a reference to the current form in the variable named form:

var form = document.mainForm;

Later in the code, form is used to refer to fields in the form.

The LongJump.Record object is used to send data to and receive data from the platform. The LongJump.Record object holds properties in key-value pairs. To create a LongJump.Record object, instantiate it with the new operator:

var record = new LongJump.Record();

To set up the search, you must assign some key-value pairs to the instance of LongJump.Record, First, set the object that you want to search for. You can find the identifier of an object by checking the the Object Id field when you select Designer > Objects > {object} > Properties. In this example, "1555611998oit1617201617" identifies the Employees object.

record.set('object','1555611998oit1617201617');

Next, you set the list of fields to retrieve from the record. For this example, we want the first name, last name, and social security number (security_id_):

record.set('field_list',"first_name,last_name,security_id_");

Finally, you need to set the filter property which specifies a search criteria in a filter expression. This example specifies that the employee_id field in the Employees object must match the value of the current employee_id field in the form:

record.set('filter', "employee_id equals'" + form.employee_id.value + "'");

Once the instance of LongJump.Record is set up, you can call searchRecords:

var result = AjaxAPI.searchRecords(record);

The searchRecords call returns an instance of LongJump.Record which is called result in this example. The status property of the first element of result contains "ERROR" when the search does not retrieve any records. If records were retieved, then the status property of the first element contains "RECORD". So, the code first handles the error condition by displaying an error dialog:

if(result[0].getStatus() != 'RECORD')
{
    alert("Enter a valid 'Employee ID'");
}

If the flow gets this far, it means that a record was successfully retrieved. In this case, the first element of the result varaible contains the fields that were requested. In the lines below, the code:

• Concatenates the first and last name in result and puts the value in the employee_name form field
• Puts the social security number in result in the social_security_number form field

else
{
    form.employee_name.value = result[0].get("first_name") + " " + result[0].get("last_name");
    form.social_security_number.value = result[0].get("security_id_");
}

Note that in this example searchRecords returned only one set of fields. However, it is possible for searchRecords to return multiple sets of fields.

Lookup Post-Selection Event Script

DEPRECATED: The AJAX APIs are deprecated. They continue to work, for backward compatibility, but they are not being extended or enhanced. (Web pages should use AJAX and REST to carry on a conversation with the server, rather than the deprecated AJAX APIs.)

For information on this deprecated functionality, see the version 8.0 platform docs:
https://agileappscloud.info/lj80/index.php?title=Getting_Started_with_AJAX_API