Difference between revisions of "Getting Started with the Java API"

From AgileApps Support Wiki
imported>Aeric
imported>Aeric
Line 171: Line 171:
</syntaxhighlight>
</syntaxhighlight>


{{Note|Since a Task can be attached to a record in any object, <tt>related_to</tt> is a [[Multi Object Lookup]] field. It's data value therefore contains both an object identifier and the record identifier, separated by a colon.<br>''Learn more:'' [[Field Types in the Java API]] }}
{{Note|Since a Task can be attached to a record in any object, <tt>related_to</tt> is a [[Multi Object Lookup]] field. It's data value therefore contains both an object identifier and the record identifier, separated by a colon.<br>''Learn more:'' [[Java API:Field Type Reference|Field Type Reference]] }}


===Update Records===
===Update Records===

Revision as of 01:04, 3 August 2013

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:
  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:

<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 GearIcon.png > 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 GearIcon.png > GearIcon.png > 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

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

Add a Task Record

This example uses the addRecord API to create a new Task associated with an existing case.

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

import com.platform.api.Functions; import com.platform.api.Parameters; import java.util.*;

public class AddTask {

  public void add(Parameters p) throws Exception
  {      
      String subject = "New Task Record";
      String description = "This task needs to be accomplished.";
      String relatedTo = "cases:99999999";
      // Create the Task parameters
      Parameters taskParams = Functions.getParametersInstance();
      taskParams.add("subject", subject);
      taskParams.add("description", description);
      taskParams.add("related_to", relatedTo);
      taskParams.add("due_date", new Date() );
         // Add other fields like owner_id, as required     
     
      // Add the Task Record
      Result r = Functions.addRecord("tasks", taskParams);
      // Check the result here. 
      // On success, Result.getCode() returns zero (0)
      // On failure, it returns -1
  }

} </syntaxhighlight>

Notepad.png

Note: Since a Task can be attached to a record in any object, related_to is a Multi Object Lookup field. It's data value therefore contains both an object identifier and the record identifier, separated by a colon.
Learn more: Field Type Reference

Update Records

To update a record, complete these steps:

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.

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

String contactRecID = null; </syntaxhighlight>

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)
<syntaxhighlight lang="java" enclose="div">

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

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
<syntaxhighlight lang="java" enclose="div">

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

} </syntaxhighlight>

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, and sendEmailUsingTemplate
<syntaxhighlight lang="java" enclose="div">

{

  // "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;
     }
  }

} </syntaxhighlight>

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.
<syntaxhighlight lang="java" enclose="div">

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
           }  
       }           
   }

} </syntaxhighlight>

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

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

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

</syntaxhighlight>

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)
<syntaxhighlight lang="java" enclose="div">

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

} </syntaxhighlight>

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