View source for Java Code Samples

<noinclude>__NUMBEREDHEADINGS__
__TOC__</noinclude>
===About the Code Samples===
These samples assume basic familiarity with the use of the platform's Java APIs. In many cases, it is also helpful to be conversant with the platform's System Objects.
<br>''Learn more:''
:* [[Getting Started with the Java API]]
:* [[Java Debugging Tips]]
:* [[System Objects]]
:* [[Java API]] (reference)

===Class Template===
{{:Java Class Template}}

===Error Handling in Java Code===
{{:Java Error Handling}}

===Add a Task to a Record===
This example uses the <tt>addRecord</tt> API to create a new Task associated for the current record.

:<syntaxhighlight lang="java" enclose="div">
import com.platform.api.Functions;
import com.platform.api.Parameters;
import java.util.*;

public class RecordAdditions
{
   public void addTask(Parameters p) throws Exception
   {      
       String objectID = p.get("object_id");
       String recordID = p.get("id"); 

       String subject = "New Task Record";
       String description = "This task needs to be accomplished.";
       String relatedTo = objectID + ":" + recordID; //ex: "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
       Result r = Functions.addRecord("tasks", taskParams);

       // Check the result here. 
       // On success, Result.getCode() returns zero (0)
       // On failure, it returns -1
   }
}
</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:'' [[Java API:Field Type Reference|Field Type Reference]] }}

===Batch Update of Related Record Owners===
This example assumes that some collection of records is divided into "batches", and that each batch has a single owner. A Batch object contains header records, and each record in the collection has a lookup to the Batch object - which makes them ''related records''.

The goal is to update all of the Related records when there is a change to the Batch record. In this case, the idea is to change the owner of all Related records whenever the Batch record is assigned to a new owner.

The solution is to create a Java method that does the updates, and invoke it only when the owner field changes in the Batch record.

====Defining the Class====
Here's a template for the class. It assumes that:
:* The name of the batch object is "Batch_Controls"
:* The name of the object with the related records is "Related_Details"
:* The name of the [[Lookup]] field in that object is <tt>lookup_field</tt>

(Note that object and field ''names'' are somewhat different from the ''display labels'' that appear on screen. In particular, note that spaces are replaced by underscores.)

:<syntaxhighlight lang="java" enclose="div">
package com.platform.yourCompany.yourPackage;

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

public class BatchProcessing
{
  /**
   * Process records related to the current record.
   */
  public void updateRelatedRecords(Parameters p) throws Exception
  {
    try { 
       // Object names. (The internal names, not the display labels.)
       String batchObject = "Batch_Controls";  // Not used. Just for clarity.
       String relatedObject = "Related_Details";

       // Get the owner of the current batch record
       //String objectID = p.get("object_id"); // Expected to be the Batch_Controls object
       String batchRecord = p.get("id");
       String batchName = p.get("some_value_that_identifies_the_batch");
       String batchOwner = p.get("owner_id");

       // Search for Related records
       Result searchResult =
          Functions.searchRecords(relatedObject , "id",  // Return record ID from search
             "lookup_field equals '" +batchRecord+ "'"); // lookup_field equals '9999999'
       int searchCode = searchResult.getCode();
       if (searchCode < 0) {
          String msg = "Error searching for Related records";
          log(msg + ":\n" + searchResult.getMessage());
          Functions.throwError(msg);                    
       } else if (searchCode == 0) {
          log("No related records found for "+batchName);
       } else {
          // Records were found (searchCode equals the number)
          ParametersIterator pit = searchResult.getIterator();
          while(pit.hasNext())
          {
             // Get the record ID, for use when updating
             Parameters relatedParams = pit.next();            
             String relatedRecordID = relatedParams.get("id");

             // Specify the field to update
             Parameters params = Functions.getParametersInstance();
             params.add("owner_id", batchOwner);

             // Update related record owner. (Functions.updateRecord() could 
             // also be used, but this method has an option to send an email.)
             Result updateResult = Functions.changeOwnerShipInfo(
                relatedObject, relatedRecordID, batchOwner, false); 
                //Set last param to true to send new owner a notification msg.
             int resultCode = updateResult.getCode();
             if (resultCode < 0) {
                // Some error happened.
                String msg = "Update failed";
                log(msg + ":\n" + updateResult.getMessage()); // Log the details
                Functions.throwError(msg + ".");        // Abort and display error
             }
          } //while
       }  //else
    } catch (Exception e) {
       // Catch surprises and report them.
       String msg = "Unexpected exception";
       log(msg + ":\n" + e.getMessage() );
       Functions.throwError(msg);      
    }
  } // method
  
  public void log(String msg) throws Exception {
    // Put the message in the log.
    Logger.info(msg, "BatchProcessing");
  }
       
  public void debug(String msg) throws Exception { 
    // For interactive debugging. Displays in a popup
    // or at top of user's page, depending on context.
    Functions.showMessage(msg);
    log(msg);
  }
} // end class
</syntaxhighlight>

====Creating the Update Rule====
The next step is create an event Rule that runs only when the <tt>owner_id</tt> field changes in a Batch record:

# '''[[File:GearIcon.png]] > Objects > Batch > Business Rules'''
# '''Event Rules, On Batch (record): Owner Changed'''
# '''[New Rule]'''
# Action: Invoke the Java method, <tt>updateRelatedRecords()</tt>

====Learn more====
:* [[Rules#Execution Criteria]]
:* [[REST API:exec Resource]]

===Manage Files===
Files can be added to a specific field in a record, or added to the list of attachments.

====Add a File to a Record====
If a record contains a field of type <tt>File</tt>, use this code to add file content to that field. 

For example, here we are adding an image for a book's cover. We assume that image was retrieved as a byte-array using a [[Web Service]] or an [[HttpConnection]]. The byte array is then passed to the method below, which converts it to an encoded string and stores it in the platform.

:<syntaxhighlight lang="java" enclose="div">
import com.platform.api.*;
import com.platform.beans.*;
import com.platform.api.utility.*;  // Encoding class

public class RecordAdditions 
{
   /**
    * Add a byte[] of document/image content to a record in the Books object
    */
   public void addBookCover(byte[] bytes) throws Exception
   {
      Base64Codec base64 = new Base64Codec();
      String encodedString = base64.encodeToString(bytes); 
      PlatformFileBean file = new PlatformFileBean("cover image", encodedString); 

      // Add the file to a new record in the Books object, in the "bookCover" field
      Parameters params = Functions.getParametersInstance();
      params.add("bookCover", file);
      Result result = Functions.addRecord("Books", params); 

      // Alternatively, update an existing record in the Books object
      // (Here the record ID is hardcoded. Generally, it would be passed as a parameter.)
      //String recordID = "76799333"; 
      //Result result = Functions.updateRecord("Books", recordID, params);
   }
}
</syntaxhighlight>

====Add and Access Record Attachments====

===== Generate an Attachment =====
{{:Code:Generate an Attachment}}

=====Add an External Attachment=====
Use this code to add an image, document, or file to a record as an attachment. As before, the byte array is presumed to have come from a [[Web Service]] or [[HttpConnection]]:
:<syntaxhighlight lang="java" enclose="div">
package com.platform.yourCompany.yourApplication;

import com.platform.api.*;
import com.platform.beans.*;
import com.platform.api.utility.*;  // Encoding class

public class RecordAdditions 
{
   /**
    * Add a byte[] of document/image content to the current record as an attachment.
    */
   public void addAttachment(Parameters p, String fileName, byte[] bytes) throws Exception
   {
      // Get the ID of the current record
      String objectID = p.get("object_id");
      String recordID = p.get("id"); 
      String relatedTo = objectID + ":" + recordID; //ex: "cases:99999999"

      Base64Codec base64 = new Base64Codec();
      String encodedString = base64.encodeToString(bytes); 
      PlatformFileBean file = new PlatformFileBean(fileName, encodedString); 

      // Add the file as an attachment to the current record
      Parameters params = Functions.getParametersInstance();
      params.add("title", fileName);
      params.add("file_field", file);
      params.add("related_to", relatedTo);
      Result result = Functions.addRecord("attachments", params); 
   }

   /**
    * Test the addAttachment() method. Invoke this method from a Rule 
    * and inspect the results in the GUI. (This method can be executed
    * from a Rule, because it has the required signature.)
    */
   public void addAttachmentTest(Parameters p) throws Exception
   {
      String fileName = "testfile.txt";
      String fileContent = "This is a test file.";
      byte[] bytes = fileContent.getBytes();
      addAttachment(p, fileName, bytes);
   }
}
</syntaxhighlight>

=====Process Attachments=====
Use this method to process attachments for the current record:
:<syntaxhighlight lang="java" enclose="div">
   /**
    * Process the current record's attachments. To test this method, invoke
    * it from an update Rule and inspect the Debug Log.
    */
   public void processAttachments(Parameters p) throws Exception
   {
      // Get the ID of the current record
      String objectID = p.get("object_id");
      String recordID = p.get("id");
      String relatedTo = objectID + ":" + recordID;     //ex: "cases:99999999"

      Result searchResult = 
          Functions.searchRecords("attachments", "*",   //all fields
               "related_to equals '" +relatedTo+ "'");  //related_to equals 'cases:9999999'
      int searchCode = searchResult.getCode();
      if (searchCode < 0)
      {
         String msg = "Error searching Attachments";
         Logger.info(msg + ":\n" + searchResult.getMessage(), "Search");
         Functions.throwError(msg);                     
      }
      else if (searchCode == 0)
      {
         Logger.info("No attachments found for "+relatedTo, "Search");
      }
      else
      {
         // Records were found (searchCode equals the number)
         Logger.info(searchCode+ " attachments found for " + relatedTo, "Search");
         ParametersIterator pit = searchResult.getIterator();
         while(pit.hasNext())
         {
            // Log the search result. Optionally test for a specific record.
            Parameters attachParams = pit.next();             
            String title = attachParams.get("title");
            Logger.info("Attachment title: "+title, "Search");
            if (title.equals("...test for a specific attachment...")) {
               // Operate on a specific attachment here
               break;
            }

            // Work with the search result. 
            // Here, we assume it is text and put it into the log/
            PlatformFileBean file = attachParams.getPlatformFileBean("file_field");
            String encodedContent = file.getEncodedFileContent();
            byte[] bytes = base64.decode(encodedContent); 
            String text = new String(bytes);
            Logger.info("Attachment data: " + text, "Search");
            // ...
         }
      }
   }
</syntaxhighlight>

=== Set Case Status According to Related Tasks ===
This code sample sets the Case state to Resolved or Pending, depending on the status of its related Tasks. Comments in the code explain its behavior. The expectation is that code is invoked by a Rule that is triggered when a Task's status changes.
 
:<syntaxhighlight lang="java" enclose="div">
package com.platform.acme.demo.TaskProcessing;

import com.platform.api.*;
import static com.platform.api.Functions.*;

public class TaskProcessing
{
  public void log(String msg) throws Exception {
    // Put the message in the log.
    Logger.info(msg, "TaskProcessing");
  }
       
  public void debug(String msg) throws Exception {
    // Display message in a popup or at top of page, depending on context, and log it.
    Functions.showMessage(msg);
    log(msg);
  }

  /*
   * Call this code whenever a task changes status.
   *   - In the Tasks object, create an Event Rule that runs when a record is updated
   *   - Run the Rule when this expression is true: ISCHANGED(status)
   * Mark the case the task is attached to as "Resolved" if all tasks are completed.
   * Mark it "Pending" if all uncompleted tasks are pending (i.e. waiting on someone else).
   * NOTES: 
   *  1. This code assumes that "Waiting" has been added to the list of "Case Task Status" values
   *  2. Only processes that have started generate tasks, so all relevant processes should
   *     be launched manually or by rule before any tasks are completed. Otherwise, the case
   *     status may be prematurely set to "Resolved".
   */
  public void setCaseStatus(Parameters input_params) throws Exception
  {
    try {
      // Global Picklist "Case Status" defines the values for cases.
      String caseNew = "1";
      String caseOpen = "2";
      String casePending = "3";
      String caseResolved = "4";
      String caseClosed = "5";
      String caseReopened = "6";
      
      // Global Picklist "Case Task Status" defines the values for tasks.
      String taskOpen = "1";
      String taskCompleted = "2"; 
      String taskApproved = "3";
      String taskRejected = "4";
      String taskWaiting = "5";

      // Default case status depends on the current task status.
      String taskID = input_params.get("id");
      String taskStatus = input_params.get("status");
      String caseFlag = "";
      if (taskStatus == taskCompleted) { 
         caseFlag = caseResolved;
      } else if (taskStatus == taskWaiting) {
         caseFlag = casePending;
      } else {
         // TODO: If case status is currently Resolved or Closed, it should change to Reopened.
         //       (We ignore that scenario here. Fix it in production.)
         return;
      }
           
      // Format of the related_to field is object_id:record_id
      String relatedCase = input_params.get("related_to");
      String caseObject = relatedCase.substring(0, relatedCase.indexOf(":"));
      String caseID = relatedCase.substring(relatedCase.indexOf(":")+1, relatedCase.length());
         //debug("Case Obj: "+ caseObject +", ID: "+ caseID +",  Task: "+ taskID);

      // Get all task records related to the same case. Return the status field for each record.
      Result result = Functions.searchRecords("tasks","status,id","related_to = '"+relatedCase+"'");
      int resultCode = result.getCode();
      if (result.getCode() < 0) {
         // Display message to user and add an entry to debug log.
         String msg = "Task search failed. Code="+result.getCode();
         log(msg);
         Functions.throwError(msg + "\n" + result.getMessage() );      
      }  
      
      // Search returned a list of tasks. Examine each of them.
      ParametersIterator iterator = result.getIterator();
      while (iterator.hasNext())
      {
         Parameters params = iterator.next();
         if (taskID == params.get("id")) continue;
            // The input record is included in the search results. Ignore it. 

         String status = params.get("status");
         if ( status.equals(taskOpen) ) 
         {
            // If there is an open task, case status does not change.
            caseFlag = "";
            break;
         }
         else if ( status.equals(taskWaiting) )
         {
            // If all remaining tasks are completed or waiting, 
            // this setting will stand.
            caseFlag == casePending;               
         }
         else
         {
            // Ignore completed/approved/rejected tasks.           
            continue;
         }
      }
      
      if (caseFlag != "")
      {
         // All tasks are either waiting or completed. 
         // Set the case status accordingly
         Parameters fcn_params = Functions.getParametersInstance();
         fcn_params.add("status", caseFlag);
         Functions.updateRecord(caseObject, caseID, fcn_params);
      }
      
    } catch (Exception e) {
       // Catch surprises, display a popup, and put them in the log.
       String msg = "Unexpected exception";
       log(msg + ":\n" + e.getMessage() );
       Functions.throwError(msg + " - see debug log");      
    }
  }
}
</syntaxhighlight>

===Add and Access Notes===
When you add a Task or Attachment, an entry is added to the record history. But when you add a Private Note, you add it directly to the History object. There, the <tt>category</tt> field (value ="29") distinguishes Private Notes from other entries in the history, including email messages and other activities.

To add a Private Note to the history, therefore, you must be sure to set that field value. Similarly, it must be part of the search criteria when retrieving history records, to eliminate all but the Private Note records in that object.

''Learn more:'' [[System Objects#Adding and Accessing Related System Object Records|Adding and Accessing Related System Object Records]]

====Add a Note====
This example adds a note with special handling instructions to a claim record. In this scenario, there is a Rule that is triggered by adding a record when certain conditions are met (for example, when the record pertains to a particular customer, or when a particular flag has been set). The Rule then invokes the method defined here.

To add the note, a record is added to the History object. The record is identified as a Private Note and set up so it references the appropriate Claim.
:<syntaxhighlight lang="java" enclose="div">
import com.platform.api.*;
import java.util.*;

public class RecordAdditions
{
   public void addNote(Parameters p) throws Exception
   {      
      // Get the ID of the current record
      String objectID = p.get("object_id");
      String recordID = p.get("id");

      // Formulate the Lookup-target for the note.
      // (A note can be added to a record in any object. So the Lookup target
      //  is a combination of an object identifier and a record identifier.)
      String relatedTo = objectID + ":" + recordID; //ex: "cases:99999999"

      // HTML tags can be included in the text
      String noteText = "<b>Special handling instructions:</b><br>...notes...";

      // Create the Note parameters
      Parameters noteParams = Functions.getParametersInstance();
      noteParams.add("description", noteText);
      noteParams.add("related_to", relatedTo);
      noteParams.add("category", "29");
      
      // Add the Note
      // result code is zero on success, -1 on failure
      Result r = Functions.addRecord("history", noteParams);
      if (r.getCode() < 0) {
         // Display message to user, add an entry to debug log, and
         // roll back the current transaction (no changes are committed).
         Functions.throwError("Failed:\n  " + r.getMessage() );      
      }        
   } 
}
</syntaxhighlight>

'''Notes:'''
:* The string "29" specifies a Private Note. The values are defined in a global picklist.<br>To see the full list, go to '''[[File:GearIcon.png]] > Customization > Global Picklists > History Category'''.

:* HTML tags included in the note text are interpreted when displayed. So this:
:::<tt><nowiki><b>Special handling instructions:</b><br>...notes...</nowiki></tt>
:: displays like this:
:::'''Special handling instructions:'''<br>...notes....

====Access Notes====
For Tasks and Attachments, you search the appropriate object looking for records that have a <tt>related_to</tt> value equal to the ID of the record you're interested in. To access notes, you search the History object, and you add one additional filter to restrict to the search to records who have the value "29" in the record's <tt>category</tt> field. That's the value that identifies the record as a Private Note, rather than an email or the recording of some action that was taken on the record. (To see the list of possible values, go to '''[[File:GearIcon.png]] > Global Picklists > History Category'''.)

:<syntaxhighlight lang="java" enclose="div">
   /**
    * Process the notes attached to the current record. To test this
    * method, invoke it from an update Rule and inspect the Debug Log.
    */
   public void processNotes(Parameters p) throws Exception
   {
      // Get the ID of the current record
      String objectID = p.get("object_id");
      String recordID = p.get("id");
      String relatedTo = objectID + ":" + recordID;     //ex: "cases:99999999"

      Result searchResult = 
          Functions.searchRecords("history", "*",   //all fields
              "related_to equals '" +relatedTo+ "' AND category='29'");  
             //related_to equals 'cases:9999999' AND category = '29'
      int searchCode = searchResult.getCode();
      if (searchCode < 0)
      {
         String msg = "Error searching History";
         Logger.info(msg + ":\n" + searchResult.getMessage(), "Search");
         Functions.throwError(msg);                     
      }
      else if (searchCode == 0)
      {
         Logger.info("No notes found for "+relatedTo, "Search");
      }
      else
      {
         // Records were found (searchCode equals the number)
         Logger.info(searchCode+ " notes found for " + relatedTo, "Search");
         ParametersIterator pit = searchResult.getIterator();
         while(pit.hasNext())
         {
            // Log the results. Do other processing as needed
            Parameters noteParams = pit.next();
            String text = noteParams.get("description");
            Logger.info("Note: " + text, "Search");
            if (text.contains("...test for a specific note...")) {
               // Operate on a specific note here
               break;
            }
         }
      }
   }
</syntaxhighlight>

===Send an Email Message===

Start by getting an email address. Here, we'll get it from the record for a Contact with a known ID ("John Smith"):
:<syntaxhighlight lang="java" enclose="div">
Result getContactRecordResult = Functions.getRecord("CONTACT",
    "first_name,last_name,email", contactRecID);
Logger.info("Sending Email to contact of Hello World Account..with email address:"
                +(getContactRecordResult.getParameters()).get("email"), "SendMail");
</syntaxhighlight>

Then use the [[sendEmailUsingTemplate]] API to send a message to that person. In order, the parameters are:
:* Related object identifier 
:* Identifier of the related record which is <tt>contactRecID</tt> that was retrieved previously
:* To list which is set by making a nested call to <tt>Parameters.get</tt> to get the email address of the contact that was just retrieved
:* Cc list which is set by making a nested call to <tt>Parameters.get</tt> to get the email address of the contact that was just retrieved
:* Description (a text string)
:* Identifier of an [[Email Template]]. The template is evaluated at run time, and values are substituted for template variables. The result becomes the body of the message.
:* List of [[Document Templates]] identifiers to send as attachments (not used in this example).
:::'''Note:'''<br>Do not choose a template based on a JSP page for use as an attachment.<br>''Learn more:'' [[JSP Attachment Deprecation]] 

:* 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", "", ""); 
Logger.info("Done sending mail from Hello World account's Contact John Smith", 
            "SendMail");
if(sendEmailResult.getCode() != 0)
{   
    Logger.info("Error in sending email!" + sendEmailResult.getMessage(), 
                "SendMail"); 
}
else
{
    Logger.info("Success on sendEmail, check inbox : " + sendEmailResult.getMessage(), 
                "SendMail");
}
</syntaxhighlight>

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

===Get the Name of an Object===
This small routine is useful for general-purpose code that could be running on a variety of objects. Given the object's ID, it returns the singular version of the object name. It's used later, in the sample code that sends notification messages when a record has been updated.

:<syntaxhighlight lang="java" enclose="div">
   /*
    * Get singular object name.<br>
    * (Does not work for User and Team objects.)
    *
    * @param objectID The object's identifier, as passed in the incoming Parameters
    *                 passed to a method called from the platform.
    */
   public String objectName(String objectID) throws Exception
   {
      try {
         CustomObjectMetaDataBean mdb = Functions.getObjectMetaData(objectID);
         // For plural object name, use getDisplayTitle().
         // (Note the mispelling of "singular" in the API.)
         return mdb.getSingluarDisplayTitle();
      }
      catch (Exception e) {
         String msg = e.getMessage() + "\n methodName(): "+e.getClass().getName();
         Functions.throwError(msg);
         return "";  // Required to keep the compiler happy
      }
   }
</syntaxhighlight>

===Invoke Web Services Programmatically===
These examples show:
:* How to invoke a Web Service from Java Code
:* How to call that code from a JSP page
:* How to add a button to a form, and invoke that code (or any other) when the button is clicked.

====Invoke a Web Service from Java Code====
This code sample invokes a Web Service directly from a Java class. The Web Service used in this example is one of the platform's REST APIs. In this case, it's the API to [[REST API:record Resource#Retrieve a Record|get a record]]. That API is called as though it is an external service, using the same techniques you will employ for any services you connect to.

In this case:
:* The method is invoked by a process, macro, or Rule that is attached to some record. 
:* We assume that the record contains an <tt>orderNum</tt> field that identifies an existing order.
:* The Web Service is used to retrieve the order date and invoice number for that order.
:* In the examples that follow, the orderNum is entered into a record form.
:* If the orderNum is "1" or "2", we return test values, turning the class into a "mock stub" for the proxy. For "3", we assume that an error occurred, and return no data.
:* We assume that the service address is http://orders.com/order, and that the number of the order to retrieve is passed as part of the URL: http://orders.com/order/{orderNum}. That strategy keeps the sample code simple.
:* The structure of the returned data looks like this:
::<syntaxhighlight lang="xml" enclose="div">
<ORDER>
    <ORDERNUM>...</ORDERNUM>
    <ORDERDATE>...</ORDERDATE>
    <INVOICENUMBER>...</INVOICENUMBER>
</ORDER>
</syntaxhighlight>
:* We assume that the Java <tt>orders</tt> package contains the order-processing classes.
:* In that package, we create a class called <tt>WebServiceProxy</tt>, to manage connections to the external service. 
:* That class defines the <tt>getOrderDetails</tt> method, which uses the platform's [[HttpConnection Class]] to connect to the external service.
:* The returned data structure is parsed using Java's <tt>XPathFactory</tt>.

;Invoking the Service:
The method defined in this class invokes the web service:
:<syntaxhighlight lang="java" enclose="div">
package com.platform.yourCompany.orders;

import com.platform.api.*;
import java.util.*;
import java.io.StringReader;
import javax.xml.xpath.*;
import org.xml.sax.*;

import static com.platform.api.Functions.*;

public class WebServiceProxy
{
  public static final String WS_URL = "http://orders.com/order/";  
  /*----------------------------
    Output from the external Web Service:
    <ORDER>
        <ORDERNUM>...</ORDERNUM>
        <ORDERDATE>...</ORDERDATE>
        <INVOICENUMBER>...</INVOICENUMBER>
    </ORDER>
   -----------------------------*/

  //Define paths used for parsing
  public static final String ORDERDATE_ELEMENT = "ORDER/ORDERDATE";
  public static final String INVOICENUMBER_ELEMENT = "/ORDER/INVOICENUMBER";

  public Map getOrderDetails(Map params) throws Exception
  {
     Map<String,String> order = new HashMap<String,String>();

     String orderNum = (String) params.get("orderNum");
     if(orderNum != null && orderNum != "" )
     {
        /** Return test values **/
        if (orderNum.equals("1")) {
           order.put("orderDate", "11 Jan 2011");
           order.put("invoiceNumber", "1111111111");
           return order;
        } else if (orderNum.equals("2")) {
           order.put("orderDate", "22 Feb 2022");
           order.put("invoiceNumber", "2222222222");
           return order;
        } else if (orderNum.equals("3")) {
           // On error, return an empty data set
          return order;
        }

        /** Execute the Web Service **/
        String orderDate = "";
        String invoiceNumber = "";
      
        HttpConnection con = 
           new HttpConnection(CONSTANTS.HTTP.METHOD.GET, WS_URL+orderNum);
        int code= con.execute(); 
        String response = con.getResponse();
        try
        {
           // Parse the response to retrieve order date and invoice#.
           XPathFactory factory = XPathFactory.newInstance();
           XPath xPath = factory.newXPath();
           
           orderDate = xPath.evaluate(
             ORDERDATE_ELEMENT, 
             new InputSource(new StringReader(response))
             );
           invoiceNumber = xPath.evaluate(
             INVOICENUMBER_ELEMENT,
             new InputSource(new StringReader(response))
             ); 
           
           order.put("orderDate", orderDate);
           order.put("invoiceNumber", invoiceNumber);
        }
        catch(XPathExpressionException xpe) 
        {
           Logger.info(xpe.getCause(), "HttpConnection");
           showMessage("Parse of Web Service data failed. Check debug log.");
        }
     }
     return order;                         
  }     
}
</syntaxhighlight>

====Invoke a Web Service from a JSP Page====
This JSP page displays a simple form that uses the Web Service Proxy defined above. When the user clicks '''[Search]''', retrieved data is displayed:
: [[File:WebServiceJspFormExample.png]]

'''Notes:'''
:* JavaScript embedded in the page uses the platform's [[REST API:exec Resource|REST exec API]] to invoke the <tt>getOrderDetails()</tt> method.

:* The Input XML sent to that method looks like this:
::<syntaxhighlight lang="xml" enclose="div">
<platform>
   <execClass>
      <clazz>com.platform.yourCompany.orders.WebServiceProxy</clazz>
      <method>getOrderDetails</method>
      <orderNum>...</orderNum>
   </execClass>
</platform>
</syntaxhighlight>

:* The jQuery .ajax method is used to make the REST request and to process the returned data.

:* The structure of the returned data is defined by the platform's [[REST API:exec Resource|REST exec API]]. (It's in {{^JSON}} format, at the request of the AJAX call). The part of the structure we are concerned with here looks like this:
::<syntaxhighlight lang="xml" enclose="div">
{"platform": {
  "execClass": {
    ...
    "orderNum": "..."
    "orderDate": "...",
    "invoiceNumber": "...",
  },
  ...
}}
</syntaxhighlight>

;JSP Page:
:<syntaxhighlight lang="xml" enclose="div">
<!--User enters record-selection data and clicks [Search].-->
<table>
   <tr>
      <td> Order#: </td> 
      <td><input type="text" id="orderNum" name="orderNum" size=10/></td>
      <td><input type="button" id="submit" name="submit" value="Search"/></td>
   </tr>
</table>
<br></br><br></br>

<!--Returned data appears here. (With no borders, table starts out invisible.) -->
<table id="result">
</table>

<!--This script attaches an anonymous function to the form button.
    The function invokes the method in the WebServiceProxy class. -->
<script type="text/javascript">
  $("#submit").click( function(){

    var orderNum= $('#orderNum').val();
    var inputXML = "<platform><execClass>"
                 + "<clazz>com.platform.yourCompany.orders.WebServiceProxy</clazz>"
                 + "<method>getOrderDetails</method>"
                 + "<orderNum>" + orderNum + "</orderNum>"
                 + "</execClass></platform>"; 

   try {
    /* jQuery AJAX call to invoke REST API and process returned data */
    $.ajax({
      type: 'POST',
      url: '/networking/rest/class/operation/exec',
      contentType: 'application/xml',
      Accept:'application/json',
      data: inputXML,  
      dataType: 'json',
      success: function(data) {
        /* Clear the results table. (jQuery method that removes */
        /* element content, but not the element or its attributes.) */
        $('#result').empty();  
     
        /* Size the table and make it visible */
        $('#result').attr('border', '1');
        $('#result').attr('style', 'width:300px');
        
        var orderNum = data.platform.execClass.orderNum;
        if (orderNum) {
          var orderDate = data.platform.execClass.orderDate;
          var invoice = data.platform.execClass.invoiceNumber;

          /* Add header rows and table data */
          $('#result').append(
            '<tr><td>Order# </td>'
           +'<td>Order Date</td>'
           +'<td>Invoice Number</td></tr>'
          );
          $('#result').append(
            '<tr><td>'+orderNum+'</td>'
           +'<td>'+orderDate+'</td>'
           +'<td>'+invoice+'</td></tr>'
          );     	
        } else {
          /* Call succeeded, but returned no data */
          $('#result').append('<tr><td>No data found for that order.</td></tr>');
        }
      } /* End of success function */

    }); /*End of ajax call*/

   } catch (e) {
     // JavaScript errors aren't recorded in the debug log.
     // Make sure we see them.
     alert(e);
   };

  }); /* End of processing function */          
</script>
</syntaxhighlight>

====Invoke a Web Service from a Form Button====
For information about invoking a web service from a form button, see the tech community article [https://tech.forums.softwareag.com/t/invoke-web-services-using-form-script/237544 Invoking a Web Service Using Form Script].

===Search and Update===
To update a record, this example follows these steps:
:*[[#Search for Account and Contact Records|Search for Account and Contact Records]]
:*[[#Check the Result|Check the Result]]
:*[[#Process the Returned Records|Process the Returned Records]]
:*[[#Relate the Account Record to the Contact Record|Relate the Account Record to the Contact Record]]

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

====Search for Account and Contact Records====
Follow these general steps to search for records:
# Call <tt>searchRecords</tt>
# Check the result
# 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 <tt>recordID</tt> parameter. 

To get a record identifier, request the <tt>record_id</tt> field when making a [[#searchRecords|<tt>searchRecords</tt>]] call. Find more information about arguments in <tt>[[searchRecords]]</tt>.

This example calls <tt>searchRecords</tt> for the CONTACT object. In order, the parameters to <tt>searchRecords</tt> in this example are:
:* name of the object
:* names of the fields to retrieve which includes <tt>record_id</tt>
:* filter string (in this case, the filter string specifies that <tt>last_name</tt> 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>

''Learn more:'' [[JAVA API:Filter Expressions in JAVA APIs]]

=====Check the Result=====

The result code for <tt>searchRecords</tt> works a little differently than for <tt>addRecord</tt>. 

'''Debug Example for <tt>searchRecords</tt>'''

This example checks the return code by calling <tt>Result.getCode</tt>, 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";
    Logger.info(msg + ":\n" + contactSearchResult.getMessage(), "Search");
    Functions.throwError(msg + ".");                     
}
else if(contactSearchCode == 0)
{
    Logger.info("Contact:No records found using the search function in CONTACT.",
                "Search");
}
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 <tt>Parameters</tt> object was shown to hold name-value pairs for fields for when the <tt>addRecord</tt> call is made. 

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

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

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

The following code sample:
:* Creates an instance of <tt>ParametersIterator</tt> by calling <tt>Result.getIterator</tt>
:* Sets up a <tt>while</tt> loop with <tt>ParametersIterator.hasNext</tt> as the expression to evaluate at each iteration; Within the <tt>while</tt> loop, the code will:
::* Creates an instance of <tt>Parameters</tt> by calling <tt>ParametersIterator.next</tt>
::* Calls <tt>Parameters.get</tt>, specifying <tt>record_id</tt> as the parameter to get the value of the record identifier field which is assigned to a variable named <tt>contactRecordId</tt>
::* Makes a Java API <tt>getRecord</tt> call with these parameters:
:::* Object identifier
:::* List of fields to get
:::* The record identifier which is <tt>contactRecordId</tt> in this case
::* Makes a nested call to <tt>Result.getParameters</tt> to get the value of the <tt>first_name</tt> field; Checks  if it is equal to "John". If so, the <tt>contactRecordId</tt> is assigned to the variable named <tt>contactRecID</tt> and the code breaks out of the loop; The <tt>contactRecID</tt> variable is used later when calling <tt>[[updateRecord]]</tt>, and <tt>[[sendEmailUsingTemplate]]</tt>

:<syntaxhighlight lang="java" enclose="div">
{
   // "Falling through" here means records were returned
   Logger.info("Search for John Smith: Number of records found using 
       search function in Contact:" + contactSearchCode, "Search");
   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");
      Logger.info("Result from getRecord:\n" + getContactRecordResult.getMessage(),
                      "Search");
      Logger.info("Return code from getRecord:" + getContactRecordResult.getCode(),
                      "Search");
      Logger.info("First name retrieved : " + firstName, "Search");
      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: 
:*<tt>reference_type</tt>
:*<tt>related_to_id</tt>
:*<tt>related_to_name</tt>

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

The following code sample:
:*Sets up a <tt>while</tt> loop with <tt>ParametersIterator.hasNext</tt> as the expression to evaluate at each iteration. Within the <tt>while</tt> loop, the code creates two instances of <tt>Parameters</tt>:
::* The first instance is created by calling <tt>getParametersInstance</tt> and is named <tt>updateContactParams</tt>; This instance is used to update the contact record later
::* The second instance is created by calling <tt>ParametersIterator.next</tt> and is called <tt>accountParams</tt>
:*Calls <tt>accountParams.get</tt>, specifying <tt>record_id</tt> as the parameter to get the value of the record identifier field, which is assigned to a variable named <tt>accountRecordId</tt>.
:*Makes a Java API <tt>getRecord</tt> call using <tt>accountRecordId</tt> as a parameter
:*Makes a nested call to <tt>Result.getParameters</tt> to get the value of the <tt>name</tt> field
:*Checks if the name is equal to "Hello World"; If it is, the code adds some name-value pairs to <tt>updateContactParams</tt>
:*Assigns the <tt>accountRecordId</tt> retrieved in the previous account search to <tt>related_to_id</tt> (This is how record identifiers are used to relate one object to another in the Java API)
:*Makes an <tt>updateRecord</tt> call, specifying <tt>contactRecID</tt> and <tt>updateContactParams</tt> 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();
Logger.info(" Account:Result message for search ALL Account Records is "
            + accountSearchResult.getMessage(), "Search");
Logger.info(" Account:Result code for search ALL Record is " + accountResultCode,
            "Search");
if(accountResultCode < 0)
{
    String msg = "Account could not be retrieved";
    Logger.info(msg + ":\n" + accountSearchResult.getMessage(), "Search");
    Functions.throwError(msg + ".");
}
else if(accountResultCode == 0)
{
    Logger.info("Account:No records found using the search function in ACCOUNT.", 
                "Search");
}
else
{
    Logger.info(
      "Search for Hello World: Number of records found using search function in Account:"
      + accountResultCode, "Search");
    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");
        Logger.info("Result from getRecord on ACCOUNT:\n" 
                    + getAccountRecordResult.getMessage(), "Search");
        Logger.info("Return code from getRecord on ACCOUNT:" 
                   + getAccountRecordResult.getCode(), "Search");
        if(accountName.equals("Hello World")) 
        {
            Logger.info("Account record ID:" + accountRecordId, "Update");
            updateContactParams.add("description", "Updating Contact");
            updateContactParams.add("reference_type", "Account");
            updateContactParams.add("related_to_id", accountRecordId);
            updateContactParams.add("related_to_name", accountName);
            Logger.info("Updating contact record with id:" + contactRecID, "Update");
            Result contactUpdateResult = 
                Functions.updateRecord("CONTACT", contactRecID, updateContactParams);
            if(contactUpdateResult.getCode() == 0) 
            {
               Logger.info("Account:Contact of the Account record updated successfully\n"
                   + contactUpdateResult.getMessage(), "Update");
            }
            else
            {
                String msg = "Error updating contact";
                Logger.info(msg + ":\n" + contactUpdateResult.getMessage(), "Update");
                Functions.throwError(msg + ".");
            }  
        }           
    }
}
</syntaxhighlight>

===Send Notification Messages to Followers===
{{:HowTo:Send Notification Messages to Followers}}
<noinclude>

[[Category:Java API|1]]
</noinclude>