Getting Started with the Java API

The examples on this page take through the process of working with Java API, step by step.
Note: Be sure to use a plain text editor to manipulate the code.

Learn more:

• See the Java Code Samples page for ready-to-copy code samples that do even more
• See the Java API page for detailed descriptions of the classes, objects and API calls used in these examples
• See Localization#Java Programming to 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 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:

<syntaxhighlight lang="java" enclose="div">

Parameters addAccountParams = Functions.getParametersInstance(); </syntaxhighlight>

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:

<syntaxhighlight lang="java" enclose="div">

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"); </syntaxhighlight>

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.

<syntaxhighlight lang="java" enclose="div">

Result accountAddResult = Functions.addRecord("ACCOUNT", addAccountParams); </syntaxhighlight>

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.

<syntaxhighlight lang="java" enclose="div">

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

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

<syntaxhighlight lang="java" enclose="div">

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();

</syntaxhighlight>

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

<syntaxhighlight lang="java" enclose="div">

Parameters addContactParams = Functions.getParametersInstance(); </syntaxhighlight>

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

<syntaxhighlight lang="java" enclose="div">

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"); </syntaxhighlight>

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

<syntaxhighlight lang="java" enclose="div">

Result contactAddResult = Functions.addRecord("CONTACT", addContactParams); </syntaxhighlight>

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

<syntaxhighlight lang="java" enclose="div">

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

Check the return code by calling Result.getCode:

<syntaxhighlight lang="java" enclose="div">

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();

</syntaxhighlight>