Getting Started with the Java API

Get started with the Java API and learn how to use Support Classes, Objects and Calls in the example presented here.

Learn more: Java API

Use these examples as a step-by-step tutorial to learn these basic skills:

1. Create an Account Record and a Contact Record
2. Update Records with this process:

   • Search for the Account and Contact Records in the database
   • Relate the Account Record to the Contact Record
   • Update the Contact Record with New Data

3. Create a Task to Send an Email Message and assign it to a User (task owner)
4. Send an Email Message to the Contact, then Mark the Task as Completed

Be sure to use a Plain Text Editor to manipulate the code.

For detailed descriptions of classes, objects and calls, see Java API

For a cut-and-paste version of all the code described in these step-by-step examples, see: Java API Sample

Add an Account Record

To add record using Java API, follow these steps:

1. Set up a Parameters Object
2. Call addRecord to add a new record
3. Check the result by calling methods in an instance of a Result object

Set up a Parameters Object

Data is passed to the platform using a Parameters object. The Parameters object holds key-value pairs, where each key corresponds to a field name and each value corresponds to a field value in the database. Set the key-value pairs and then pass the Parameters object as an argument when the record is added.

To set up a Parameters Object, create an instance of Parameters to hold the key-value pairs for the record by calling getParametersInstance. This instance is named addAccountParams:

Parameters addAccountParams = Functions.getParametersInstance();

To see the fields that are defined in an object:

1. Open a web browser and Login to the platform
2. Click Designer > Objects > {object} > Fields
3. View the field list

Add the key-value pairs for the database fields to addAccountParams by calling Parameters.add:

addAccountParams.add("name","Hello World Account");
addAccountParams.add("number","0000001");
addAccountParams.add("city", "Orlando");
addAccountParams.add("country", "United States");
addAccountParams.add("county", "Marine County");
addAccountParams.add("phone", "222-222-2222");
addAccountParams.add("website", "www.helloworldaccount.com");

Call addRecord

To add a new record, call addRecord and pass it an object identifier and the addAccountParams object. The values you added to addAccountParams are written to the account record in the database.

Result accountAddResult = Functions.addRecord("ACCOUNT", addAccountParams);

Like addRecord, many of the Java API record handling calls have an objectID parameter the object is specified ("ACCOUNT" in this example). In the objectID parameter, specify the Object Type Identifier.

Check the Result

The addRecord code (as well as several other Java API calls) returns an instance of the Result class. It is possible to check member variables in the Result object by calling its methods. For example, the code below makes a Java API debug utility call, making a nested call to Result.getMessage which returns a string indicating whether the call succeeded.

Functions.debug("Result of addRecord for Account:" + accountAddResult.getMessage());

The string specified in the debug call is written to the debug log.

To view the Debug Log:

Click Settings > Administration > Global Resources > Debug Log

When the code runs, use the Debug Log to troubleshoot problems during development. Many other debug calls are included in these code samples.

Debug Example for addRecord

This example checks the return code of addRecord by calling Result.getCode, and takes some action, based on the return code:

• Return codes:

• less then zero (<0); the call is not successful
• greater than or equal to zero (>= 0); successful

If the call is not successful, make a Java API throwError call, otherwise make a Result.getID call and continue

if(accountAddResult.getCode() < 0)
    String msg = "Function: Add Account";
    Functions.debug(msg + ":\n" + accountAddResult.getMessage());  // Log details
    Functions.throwError(msg + ".");                     // Error dialog
else
    return accountAddResult.getID();

Add a Contact Record

Following the same process (as adding an Account record), now add a Contact Record:

• Set up a Parameters Object
• Create an instance of Parameters by calling getParametersInstance
• Check the Result

Parameters addContactParams = Functions.getParametersInstance();

Then set the key-value pairs in the Parameters instance:

addContactParams.add("first_name", "John");
addContactParams.add("last_name", "Smith");
addContactParams.add("description", "Contact for Hello World added.");
addContactParams.add("email", "mia@financio.com");
addContactParams.add("flag_primary_contact", "true");
addContactParams.add("street", "12345 Lake st");

Call addRecord, specifying "CONTACT" as the object identifier and passing the Parameters object you set up above.

Result contactAddResult = Functions.addRecord("CONTACT", addContactParams);

Make a nested call to Result.getMessage to write to the debug log:

Functions.debug("Result of addRecord for Contact - John Smith:" + contactAddResult.getMessage());

Check the return code by calling Result.getCode:

if(contactAddResult.getCode() < 0)
    String msg = "Getting Started: Add John Smith";
    Functions.debug(msg + ":\n" + contactAddResult.getMessage());  // Log details
    Functions.throwError(msg + ".");                     // Error dialog
else
    return contactAddResult.getID();

Update Records

To update a record, complete these steps:

• Search for the Account and Contact Records
• Check the Result
• Process the Returned Records
• Relate the Account Record to the Contact Record

In this example, the Contact record that was created in the Add a Contact Recordexample is updated by associating it to the Account record created in the Add an Account Record example.

Search for the Account and Contact Records

Follow these general steps to search for records:

1. Call searchRecords
2. Check the result
3. Process the returned records

First, create a variable to hold the record identifier.

String contactRecID = null;

When a record is added database, the platform assigns it a unique record identifier. The value of a record identifier is opaque and is of no interest to the typical user. However, several Java API calls use the recordID parameter.

To get a record identifier, request the record_id field when making a searchRecords call. Find more information about arguments in searchRecords.

This example calls searchRecords for the CONTACT object. In order, the parameters to searchRecords in this example are:

• name of the object
• names of the fields to retrieve which includes record_id
• filter string (in this case, the filter string specifies that last_name contains "Smith" (the same as for the contact record previously created)

Result contactSearchResult = Functions.searchRecords("CONTACT", 
"record_id,first_name,last_name,email", "last_name contains 'Smith'");

Check the Result

The result code for searchRecords works a little differently than for addRecord.

Debug Example for searchRecords

This example checks the return code by calling Result.getCode, and takes some action, based on the return code:

• Return codes:

• less then zero (<0); the call is not successful
• equal to zero (=0); no records found
• greater than zero (> 0); successful and the value of the return code is the number of records returned

This code sample assigns the result code to a variable, which then defines the following action:

• If not successful, an error dialog is displayed
• If the code is zero, then a message is written to the debug log
• If successful, then the code is the number of records returned

int contactSearchCode = contactSearchResult.getCode();

if(contactSearchCode < 0)
{
    String msg = "Error searching CONTACT object";
    Functions.debug(msg + ":\n" + contactSearchResult.getMessage());  // Log details
    Functions.throwError(msg + ".");                     // Error dialog
}
else if(contactSearchCode == 0)
{
    Functions.debug("Contact:No records found using the search function in CONTACT.");
}
else
{
    // If the code "falls through" here, it means records were returned 
    // that need to be processed; use the value of the return code in 
    // the next section ...
}

Process the Returned Records

In earlier examples, the Parameters object was shown to hold name-value pairs for fields for when the addRecord call is made.

The searchRecords call uses the Parameters object, but in a different way - the searchRecords call returns the set of fields that were requested for each record that matches the search criteria as an array of Parameters objects.

To process each Parameters object in the search results, create an instance of ParametersIterator and then specify ParametersIterator.hasNext as the expression of a while loop.

The example resumes with the code "falling through" when checking the result code for searchRecords, meaning that the result code is greater than zero, which is the number of records returned.

The following code sample will:

• Create an instance of ParametersIterator by calling Result.getIterator
• Set up a while loop with ParametersIterator.hasNext as the expression to evaluate at each iteration; Within the while loop, the code will:

• Create an instance of Parameters by calling ParametersIterator.next
• Call Parameters.get, specifying record_id as the parameter to get the value of the record identifier field which is assigned to a variable named contactRecordId
• Make a Java API getRecord call with these parameters:

• Object identifier
• List of fields to get
• The record identifier which is contactRecordId in this case

• Make a nested call to Result.getParameters to get the value of the first_name field; Checks if it is equal to "John". If so, the contactRecordId is assigned to the variable named contactRecID and the code breaks out of the loop; The contactRecID variable is used later when calling updateRecord, addTask, and sendEmailUsingTemplate

{
   // "Falling through" here means records were returned
   Functions.debug("Search for John Smith: Number of records found using 
       search function in Contact:" + contactSearchCode );
   ParametersIterator contactIterator = contactSearchResult.getIterator();
   while(contactIterator.hasNext())
    {
      Parameters contactParams = contactIterator.next();
      String contactRecordId = contactParams.get("record_id");  
      Result getContactRecordResult = Functions.getRecord("CONTACT", 
         first_name,last_name,flag_primary_contact,description", contactRecordId);
      String firstName = (getContactRecordResult.getParameters()).get("first_name");
      Functions.debug("Result from getRecord:\n" + getContactRecordResult.getMessage());
      Functions.debug("Return code from getRecord:" + getContactRecordResult.getCode());
      Functions.debug("First name retrieved : " + firstName);   
      if(firstName.equals("John"))
        {
           contactRecID = contactRecordId; 
           break;
        }
    }
}

Relate the Account Record to the Contact Record

As objects are manipulated in the platform (added, updated, deleted), associations between objects must be maintained.

For example, when a Contact is created, it must be related to an Account:

• In the platform user interface, objects are related using the Lookup field as described in Relating Objects Using Lookups
• In the Java API, objects are related in code by searching for an object and then using a field value that identifies the object to set a field in a related object

Define the Relationship between Objects In this example, the code searches for an Account and then uses the Account Number to set a field in the contact. When relating a record in the Account object to a record in the Contact object, these three key-value pairs are required to define the relationship:

• reference_type
• related_to_id
• related_to_name

The following code searches for an account where the name field contains the text string "Hello". The Account record is created in Add an Account Record. The code follows the same model for a Update Records: call searchRecords, check the result code, and loop to process the returned records.

The following code sample:

• Sets up a while loop with ParametersIterator.hasNext as the expression to evaluate at each iteration. Within the while loop, the code creates two instances of Parameters:

• The first instance is created by calling getParametersInstance and is named updateContactParams; This instance is used to update the contact record later
• The second instance is created by calling ParametersIterator.next and is called accountParams

• Calls accountParams.get, specifying record_id as the parameter to get the value of the record identifier field, which is assigned to a variable named accountRecordId.
• Makes a Java API getRecord call using accountRecordId as a parameter
• Makes a nested call to Result.getParameters to get the value of the name field
• Checks if the name is equal to "Hello World"; If it is, the code adds some name-value pairs to updateContactParams
• Assigns the accountRecordId retrieved in the previous account search to related_to_id (This is how record identifiers are used to relate one object to another in the Java API)
• Makes an updateRecord call, specifying contactRecID and updateContactParams as parameters, which updated the Contact record.
• Checks the result in the final lines of code in the same way that previous examples did.

Result accountSearchResult = searchRecords ("ACCOUNT", "record_id,name,number,primary_contact_id",
    "name contains 'Hello'");
int accountResultCode = accountSearchResult.getCode();
Functions.debug(" Account:Result message for search ALL Account Records is " + accountSearchResult.getMessage());
Functions.debug(" Account:Result code for search ALL Record is " + accountResultCode);
if(accountResultCode < 0)
{
    String msg = "Account could not be retrieved";
    Functions.debug(msg + ":\n" + accountSearchResult.getMessage());  // Log details
    Functions.throwError(msg + ".");                     // Error dialog
}
else if(accountResultCode == 0)
{
    Functions.debug("Account:No records found using the search function in ACCOUNT.");
}
else
{
    Functions.debug("Search for Hello World: Number of records found using search function in Account:" +
         accountResultCode);
    ParametersIterator accountIterator = accountSearchResult.getIterator();
    while(accountIterator.hasNext())
    {
        Parameters updateContactParams = Functions.getParametersInstance();
        Parameters accountParams = accountIterator.next();
        String accountRecordId = accountParams.get("record_id");	      
        Result getAccountRecordResult = Functions.getRecord("ACCOUNT", "name,description", accountRecordId);
        String accountName = (getAccountRecordResult.getParameters()).get("name");
        Functions.debug("Result from getRecord on ACCOUNT:\n" + getAccountRecordResult.getMessage());
        Functions.debug("Return code from getRecord on ACCOUNT:" + getAccountRecordResult.getCode());
        if(accountName.equals("Hello World")) 
        {
            Functions.debug("Account record ID:" + accountRecordId);
            updateContactParams.add("description", "Updating Contact");
            updateContactParams.add("reference_type", "Account");
            updateContactParams.add("related_to_id", accountRecordId);
            updateContactParams.add("related_to_name", accountName);
            Functions.debug("Updating contact record with id:" + contactRecID);
            Result contactUpdateResult = Functions.updateRecord("CONTACT", contactRecID, updateContactParams);
            if(contactUpdateResult.getCode() == 0) 
            {
               Functions.debug("Account:Contact of the Account record updated successfully\n" +
                   contactUpdateResult.getMessage());
            }
            else
            {
                String msg = "Error updating contact";
                Functions.debug(msg + ":\n" + contactUpdateResult.getMessage());  // Log details
                Functions.throwError(msg + ".");                     // Error dialog
            }  
        }           
    }
}

Create a Task Record

This section shows how to add a task and associate it to the previously created contact record.

Set Up a Parameters Object

As with the records created earlier, the code starts by creating an instance of Parameters and then assigning key-value pairs to it.

The following code sample will:

• Set up Parameters; Note that the contact_id and reference_id keys are set to the contactRecID that was retrieved in the Search for the Account and Contact Records section, which associates the task with that contact

String taskRecordID = null;
Functions.debug("Testing addTask");
Parameters addTaskParams = Functions.getParametersInstance();
addTaskParams.add("action_type", "Email");

//Set the frequency for this task to be every day
addTaskParams.add("calendar_frequency", "1");

//Set the calendar type to be day
addTaskParams.add("calendar_type", "5");
addTaskParams.add("contact_id", contactRecID );
addTaskParams.add("date_created", new Date());
addTaskParams.add("description", "Send email to set up an appointment to discuss the invoice.");
addTaskParams.add("notify_complete", "In Progress");
addTaskParams.add("percentage_complete", "10");
addTaskParams.add("priority", "High");

//Associate this task to a record that already exists so it will be displayed in open activities
//Add this task to a contact (associate the task to the contact record
//by setting the reference ID and the reference type)
addTaskParams.add("reference_id", contactRecID );
addTaskParams.add("reference_type", "CONTACT");
addTaskParams.add("status", "In Progress");
addTaskParams.add("subject", "Hello World - Invoice discussion:" + new Date());
addTaskParams.add("repeat_flag", "true");
addTaskParams.add("reminder_duration", "24");

The following code sample shows the call to addTask. In order, the parameters are:

• Subject of the task
• Date of the task
• Owner of the task which is set by making a nested call to getEnv which is a Java API utility call
• Parameters object

Result addTaskResult = Functions.addTask("CONTACT : Task for - " + contactRecID,
    new Date(), Functions.getEnv(ENV.USER.ID), addTaskParams);
Functions.debug("Result of addTask" + addTaskResult.getMessage());
if(addTaskResult.getCode() != -1)
{ 
    taskRecordID = addTaskResult.getID();
    Functions.debug("Added task using addTask - ID : " + taskRecordID);
}
else
{
    String msg = "Error adding Task";
    Functions.debug(msg + ":\n" + addTaskResult.getMessage());  // Log details
    Functions.throwError(msg + ".");                     // Error dialog
}

Check the Result

Like other Java API calls such as addRecord and searchRecords, addTask returns a Result object whose methods can be called to check the result of the call. If addTask does not succeed, Result.getCode returns -1.

Send an Email Message

This section shows how to send an email message to a contact.

The following code sample will:

• Get the record for the contactRecID (the contact named "John Smith")

Find more information about arguments in sendEmailUsingTemplate

Result getContactRecordResult = Functions.getRecord("CONTACT", "first_name,last_name,email", 
    contactRecID);
Functions.debug("Sending Email to contact of Hello World Account..with email address:" +
    (getContactRecordResult.getParameters()).get("email"));

The following code sample calls sendEmailUsingTemplate. In order, the parameters are:

• Related object identifier
• Identifier of the related record which is contactRecID that was retrieved previously
• To list which is set by making a nested call to Parameters.get to get the email address of the contact that was just retrieved
• Cc list which is set by making a nested call to Parameters.get to get the email address of the contact that was just retrieved
• Description (a text string)
• Identifier of a print template. This template is evaluated at run time, its template variables substituted, and then sent as the body of the message
• List of print template identifiers to send as attachments (not used in this example)
• List of document identifiers in your documents folder to send as attachments (not used in this example)

Result sendEmailResult = Functions.sendEmailUsingTemplate("CONTACT", contactRecID,
                                                (getContactRecordResult.getParameters()).get("email"),
                                                (getContactRecordResult.getParameters()).get("email"),
                                                "Sending Email to Hello World's Primary Contact - John Smith",
                                                "1869974057twn1678149854", "", ""); 
Functions.debug("Done with sending mail from Hello World account's Contact John Smith");
if(sendEmailResult.getCode() != 0)
{   
    Functions.debug("Error in sending email!" + sendEmailResult.getMessage()); 
}
else
{
    Functions.debug("Success on sendEmail, check inbox : " + sendEmailResult.getMessage());
    //If email was sent successfully update the task to end the task
    Parameters updateTaskParams = Functions.getParametersInstance();
    updateTaskParams.add("subject", "Email sent");
    updateTaskParams.add("end_flag", 1);
    updateTaskParams.add("status", "Completed");
    updateTaskParams.add("due_date", new Date()); 
    Result updateTaskResult = Functions.updateTask(taskRecordID, addTaskParams); 
    Functions.debug("Updated task using updateTaskResult - " + taskRecordID + " : " + updateTaskResult.getMessage());
}

Like other Java API calls such as addRecord and searchRecords, sendEmailUsingTemplate returns a Result object whose methods you can call to check the result of the call. When sendEmailUsingTemplate succeeds, Result.getCode returns zero (0).

Mark the Task as Completed

In this example, when the call to sendEmailUsingTemplate succeeds, the code creates an instance of Parameters and adds field-value pairs to it. Then the code calls updateTask specifying taskRecordID and the Parameters object as parameters. This updates the task that was added earlier, setting its status field to "completed".

Java API Sample

Complex Java Code Data Policy Sample