Getting Started with the Java API

About the Java API

The Java APIs are used when writing custom Classes that can be invoked from Rules.

The examples on the remainder of this page take you through the process of working with Java API, step by step.

Considerations

• The Java 6 syntax and feature set are supported in custom classes.
• When pasting code into the online editor, make sure it comes from a plain text editor.

Learn More:

• Java Code Samples - an initial class template and advanced, ready-to-copy code samples
• Java Debugging Tips - for help debugging your application
• Java API - for detailed descriptions of the classes, objects and API calls used in these examples
• Localization#Java Programming - learn how to take into account localization of data for users

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 learn more about the parameters passed to a Java method, see the Standard Parameters.)

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

Logger.info("Result of addRecord for Account:" + accountAddResult.getMessage(), "Add");

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

To view the Debug Log:

Click > Customization > Developer 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";
    Logger.info(msg + ":\n" + accountAddResult.getMessage(), "Add"); // Log details
    Functions.throwError(msg + ".");                                 // Error message
else
    return accountAddResult.getID();

Add a Contact Record

Here, you following the same process as adding an Account record to 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:

Logger.info("Result of addRecord for Contact - John Smith:"
          + contactAddResult.getMessage(), "Add");

Check the return code by calling Result.getCode:

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

Update a Record

This code updates a record.

public void changeRecordValue(Parameters p) throws Exception
{
   try {
      String objectID = p.get("object_id");
      String recordID = p.get("id");  
      
      // Specify the parameters to modify. (Only specified params are changed.)
      Parameters params = Functions.getParametersInstance();
      params.add("field_name", "new_value");

      // Result.getCode() >= 0 on success, -1 on failure
      Result r = Functions.updateRecord(objectID, recordID, params);
      if (r.getCode() < 0) {
         Functions.throwError("Update failed\n" + r.getMessage() );      
      }  
   } catch (Exception e) {
      Functions.throwError( e.getMessage() );      
   }
}

Change Record Ownership

This code changes a record's owner. Note that it does not reassign any tasks that may be attached to the record. (Additional code would be required to do that.)

public void changeOwner(Parameters p) throws Exception
{
   try {
      String objectID = p.get("object_id");
      String recordID = p.get("id");  
      String newOwner = "..ID of owner with desired team..";
      boolean notifyNewOwner = true;

      // Result.getCode() >= 0 on success, -1 on failure
      Result r = Functions.changeOwnerShipInfo(
         objectID, recordID, newOwner, notifyNewOwner);
      if (r.getCode() < 0) {
         Functions.throwError("Update failed\n" + r.getMessage() );      
      }  
   } catch (Exception e) {
      Functions.throwError( e.getMessage() );      
   }
}