Java API:Record Handling

Java API:Record Handling

From LongJump Support Wiki

Java API:Record Handling
Jump to: navigation, search

__NUMBEREDHEADINGS__The Record Handling Java APIs provide the ability to get, add, update, delete and search for Custom Objects (including some that are part of the platform).

Contents

1. Identifying Objects and Records

Many of the Java API record handling calls require an <object> element identifier.

To find the object type identifier for an object:

  1. Click Designer > Objects > {object}
  2. The Object Name is displayed at the top of the page.
    (To see the object ID, click the section-expansion (triangle) icon next to it. File:Sections-expand.gif)

File:notepad.png

Note: The Object Name is typically used as the identifier, because it is human-readable for both Built-in or CRM objects and Custom Objects. Object ID can be used, as well, but it is only human-readable for Built-in or CRM objects.

When a record is added to the database, the platform assigns it a unique record identifier. The value of a record identifier is opaque and you normally do not care about it.

However, several Java API calls take a recordID parameter. Find a record identifier by requesting the record_id field with the searchRecords call.

2. Special System Objects

These object IDs can be used to access system objects that store administrative information:

Object Name Reference
ACCESSPROFILE Access Profiles
APPLICATION_ACCESS Application Access

3. Atomic Operations

Operations initiated by Java API calls are atomic. In other words, they are transaction safe: Either all of the work is done or none of the work is done. For example, if you add a record which fires a Data Policy, then all operations triggered by that Data Policy must succeed for the add to occur. If any error occurs, the record is not added.

Similarly, if there is a cascade of Data Policies or multiple operations in a Data Policy, then none of the operations take effect, unless all are successful.

3.1 addRecord

Add a new record to an object.

Syntax

Result result = Functions.addRecord(String objectName, Parameters params);

Parameters

objectNameThe Object to add the record to.
params
  • The field-value pairs for the object you are adding.
  • Turn off data policies that might otherwise fire as a result of this action:
params.add(PLATFORM.PARAMS.RECORD.DO_NOT_EXEC_DATA_POLICY,"1");
  • Pass file parameters in the current request to any subsequent API calls made in a data policy defined on this object:
params.add(PLATFORM.PARAMS.RECORD.ENABLE_MULTIPART,"1");
Return
Result object

File:notepad.png

Note: The Result object contains the record ID for the new record. Use Result.getID() to retrieve it.

3.1.1 Example #1: Add a Record to the Account Class

This example creates an instance of Parameters and adds name-value pairs to it. The code then calls addRecord, assigning the returned value to an instance of Result and calling Result.getCode() to assign the error code to a variable which is then conditionally checked to determine the code to execute. If the call was not successful, the code calls throwError to display an error dialog.

Parameters params = Functions.getParametersInstance();
params.add("name", "Acme Solutions");
params.add("number", "GRG2323339");
Result result = Functions.addRecord("ACCOUNT", params);
int resultCode = result.getCode();
if(resultCode < 0)
{
    // Some error happened.
    String msg = "Account could not be added";
    Functions.debug(msg + ":\n" + result.getMessage());  // Log details
    Functions.throwError(msg + ".");                     // Error dialog
}
else
{
    // Take other actions on successful addition
    // of the account
}

3.1.2 Example #2: Add a Record with a Multi Object Lookup field

This example add a record to an object that contains a Multi Object Lookup, where:

  • Books is an object that contains a MultiObject Lookup field
  • libraryBook is a Multi Object Lookup field that points to a particular book and the library it came from
  • 9978946545 is the ID the library object that contains the book.
    (Object ID must be specified. Object name will not work.)
  • 767645492 is the record ID of the book in that library
Parameters params = Functions.getParametersInstance();
params.add("title", "A Good Book");
params.add("libraryBook", "9978946545:767645492");
                  //  {object_id}:{record_id}
Result result = Functions.addRecord("Books", params);
int resultCode = result.getCode();
if(resultCode < 0)
{
    // Some error happened.
    String msg = "Book record could not be added";
    Functions.debug(msg + ":\n" + result.getMessage());  // Log details
    Functions.throwError(msg + ".");                     // Error dialog
}
else
{
    // Successful add. Take other actions, as needed.
}


3.2 updateRecord

Syntax
Result result = Functions.updateRecord(String objectName, String recordID, Parameters params);

Parameters

objectName
The identifier of the object
recordID
The identifier of the record to update.
  • Use the searchRecords API to retrieve the record ID
  • An error is returned if the record is not found.
params
  • The field-value pairs for the object.
  • Turn off data policies that might otherwise fire as a result of this action:
params.add(PLATFORM.PARAMS.RECORD.DO_NOT_EXEC_DATA_POLICY,"1");
  • Pass file parameters in the current request to any subsequent API calls made in a data policy defined on this object:
params.add(PLATFORM.PARAMS.RECORD.ENABLE_MULTIPART,"1");

Return

Result object

3.2.1 Example #1: Update an Account Record

This example creates an instance of Parameters and adds name-values pairs to it. The code then calls updateRecord, assigning the returned value to an instance of Result and calling Result.getCode() to assign the error code to a variable which is then conditionally checked to determine the code to execute. If the call was not successful, the code calls throwError to display an error dialog.

Parameters params = Functions.getParametersInstance();
String accountID = "";
// Some logic to populate accountID variable.
params.add("name", "Acme Solutions");
params.add("number", "GRG2323339");
Result result = Functions.updateRecord("ACCOUNT", accountID, params);
int resultCode = result.getCode();
if(resultCode < 0)
{
    // Some error happened.
    String msg = "Account could not be updated";
    Functions.debug(msg + ":\n" + result.getMessage());  // Log details
    Functions.throwError(msg + ".");                     // Error dialog
}
else
{
    // Take other actions after successful addition of the account.
}

3.2.2 Example #2: Update a "Related To" Field in an Opportunity Record

This example gets needed details to update the Opportunity object's Related To field. In order to update opportunity object's Related to field to be Account or Prospect, you need to use both of these fields: related_to_id and related_to_type

//Retrieve the record ID of the ACCOUNT that you want to relate to the current opportunity
String accountID = "";

//Use requestParams to retrieve the record_id of the Opportunity record to update
String opportunityID = "";

//Create an instance of the Paramters object to hold the key-value pairs to update the record with
Parameters oppParams = Functions.getParametersInstance();

oppParams.add("related_to_id", accountID);
oppParams.add("related_to_type", "ACCOUNT");  
Result opportunityUpdateResult = Functions.updateRecord("OPPORTUNITY_v2", opportunityID, oppParams);
Functions.debug("Result from opportunity update: " + opportunityUpdateResult.getMessage());

3.2.3 Example #3: Update a Record with a Multi Object Lookup field

This example uses the same fields and record IDs as those shown when adding a record with a multiobject lookup field.

Parameters params = Functions.getParametersInstance();
String bookID = "117645552"
params.add("title", "Another Good Book");
params.add("libraryBook", "9978946545:767645492");
                      //  {object_id}:{record_id}
Result result = Functions.updateRecord("Books", bookID, params);
int resultCode = result.getCode();
if(resultCode < 0)
{
    // Some error happened.
    String msg = "Book record could not be updated";
    Functions.debug(msg + ":\n" + result.getMessage());  // Log details
    Functions.throwError(msg + ".");                     // Error dialog
}
else
{
    // Successful update. Take other actions, as needed.
}


3.3 getRecord

Get a record, with specified fields.

Syntax
Result result = Functions.getRecord(String objectName, String fields, String recordID
                  {, Parameters params} );
Parameters
objectName
An Object Identifier
fields
The fields to retrieve.
  • A comma-separated list of field names
  • The asterisk ("*") wildcard specifies all fields
(Use the REST API:field Resource to get a complete list of fields.)
  • Field lists for database views need to specify the object's alias, as well as the field name.
recordID
A Record Id.
params
An optional com.platform.api.Parameters object. Use it to specify the Retrieve Record Permissions Parameter, in order to find out if the user has update or delete permissions on the record.
Return
Result object. If the return code is greater than zero, use the getParameters() method to get a Parameters object with the record's fields.
Deprecated Field
  • workflow_owner - It is still present and can be used for updates, but it no longer contains any data when returned. Use this resource, instead: getWFOwners.

3.3.1 Example: Retrieve a Key

This example calls getRecord, assigning the returned value to an instance of Result and calling Result.getCode to assign the error code to a variable which is then conditionally checked to determine the code to execute. If the call was not successful, the code calls throwError to display an error dialog. If the call was successful, the code creates an instance of Parameters from which it then extracts the city key.

String accountID = "";
// Some logic to populate accountID variable.
Result result = Functions.getRecord("ACCOUNT","city,country",accountID);
int resultCode = result.getCode();
if(resultCode != 1)
{
    // Some error happened.
    String msg = "Account could not be retrieved";
    Functions.debug(msg + ":\n" + result.getMessage());  // Log details
    Functions.throwError(msg + ".");                     // Error dialog
}
else
{
  //Records retrieved successfully
  Parameters resultParameters = result.getParameters();
  String city = resultParameters.get("city");
  // Other code according to your business logic.
}

3.3.2 Example:Access File Data

When a field points to a file, the PlatformFileBean parameter is used to retrieve the file's contents:
Result result = Functions.getRecord( {objectName}, "fieldName,..." , {record_Id} );
Parameters resultParameters = result.getParameters();
PlatformFileBean file= resultParameters.getPlatformFileBean("fieldName");
String content = file.getEncodedFileContent();
Learn more: See the PlatformFileBean javadocs for a complete list of methods.

3.3.3 Example: Access an Audit Log

Audit Logs can be searched using the getRecord and searchRecord APIs
Learn more: Audit Log Fields
How it Works
Provide an audit log recordID to get a single record and retrieve a list of audit log fields.
Syntax
public static Result Functions.getRecord(String objectId, String fields, String recordId)
objectId
log
fields
record_id, ownerid, type, operation, object_singular_name, date_created, description, type_code
recordId
audit log record Id
Return
Result object
Audit Log Example Based on recordID
Result result = Functions.getRecord("log","record_id,type,operation,"+
"object,description","656");

int resultCode = result.getCode();

if(resultCode != 1)
{
    // Some error happened.
    String msg = "Log could not be retrieved";
    Functions.debug(msg + ":\n" + result.getMessage());  // Log details
    Functions.throwError(msg + ".");                     // Error dialog
}
else
{
  //Records retrieved successfully
    Parameters params = result.getParameters();
    String desc= params.get("description");
    String type= params.get("type");
    String obj = params.get("object");
    String record_id = params.get("record_id");
    String operation = params.get("operation");                  

    // Take action according to your business logic
   
}
Learn more: Audit Log Fields

3.4 getRecordCount

Gets a count of records in an Object that match specified filtering criteria.

Syntax
int count = Functions.getRecordCount(String objectName, String criteria);
Parameters
objectName
The object name or identifier
criteria
A filter expression that specifies records to select.
Returns
An integer containing a count of records that match the selection criteria.

3.5 changeOwnerShipInfo

Change the owner of a record.

Requirements

To perform this operation, you must either:

File:notepad.png

Note: When adding a record with the addRecord method, it is only necessary to specify the owner in the requestParams:
  requestParams.add("owner_id", "new user id");

Syntax
Result result;
result = Functions.changeOwnerShipInfo(String objectName, String recordId,
                                       String ownerId [, Boolean notifyEmail] );
Parameters
objectName - The object name or identifier
recordId - The record identifier
ownerId - User ID of the new owner.
notifyEmail- An optional parameter. Set to true to send the new owner an email notification.
Returns
Result object
Throws
Exception


3.6 deleteRecord

Delete a record.

Syntax

Result result = Functions.deleteRecord(String objectName, String recordID);
Result result = Functions.deleteRecord(String objectName, String recordID, Parameters params);

Parameters

objectName
The object name or identifier
recordID
The identifier of the record to delete.
params
  • Data policy override parameter:
params.add(PLATFORM.PARAMS.RECORD.DO_NOT_EXEC_DATA_POLICY,"1");
Return
Result object
Example
This example calls deleteRecord, assigning the returned value to an instance of Result and calling Result.getCode to assign the error code to a variable which is then conditionally checked to determine the code to execute. If the call was not successful, the code calls throwError to display an error dialog.
String accountID = "";
// Some logic to populate accountID variable.
Result result = Functions.deleteRecord("ACCOUNT", accountID);
int resultCode = result.getCode();
if(resultCode < 0)
{
    // Some error happened.
    String msg = "Account could not be deleted";
    Functions.debug(msg + ":\n" + result.getMessage());  // Log details
    Functions.throwError(msg + ".");                     // Error dialog
}
else
{
    // Take other actions on successful addition
    // of the account.
}


3.7 Retrieve Record Permissions Parameter

When retrieving or searching for records, it is sometimes useful to find out if the user has update or delete permissions. (For example, to determine whether or not to display a button for the purpose.)

To do that, you specify the PLATFORM.PARAMS.RECORD.RETRIEVE_RECORD_PERMISSIONS parameter, with a value of "1".

For example:

recordId = ...;
com.platform.api.Parameters params = Functions.getParametersInstance();
params.add("PLATFORM.PARAMS.RECORD.RETRIEVE_RECORD_PERMISSIONS" ,"1");
Result result = getRecord("profile", "id,profileName", recordId, params);

When specified, and when the field list contains the id field (needed to do an update or delete), a RecordPermissions bean containing the relevant permissions is returned in the Result object:

Parameters resultParameters = result.getParameters();
RecordBean.RecordPermissions permissions =  
   (RecordBean.RecordPermissions)resultParameters.getObject("PLATFORM.PARAMS.RECORD.RECORD_PERMISSIONS");

if (permissions != null)
{
   Functions.debug("Update=" + permissions.getUpdatePermission());
   Functions.debug("Delete=" + permissions.getDeletePermission());
}

3.8 searchRecords

Search and retrieve the records for an object.

3.8.1 Syntax

Result result;
result = Functions.searchRecords (String objectName, String fields, String criteria
                                    {, Parameters params} );

result = Functions.searchRecords (String objectName, String fields, String criteria,
                                  String sortBy, String sortOrder,
                                  String sortBy2, String sortOrder2,
                                  int offset, int numberOfRows {, Parameters params} );

3.8.2 Parameters

objectName
The object name or identifier.
fields
The fields to retrieve.
  • A comma-separated list of field names
  • The asterisk ("*") wildcard specifies all fields
(Use the REST API:field Resource to get a complete list of fields.)
  • Field lists for database views need to specify the object's alias, as well as the field name.
criteria
A filter expression that specifies records to select.
sortBy
Sort the search results on the specified field.
sortOrder
Specify if the sort order is ascending ("asc") or descending ("desc"). Not case sensitive. The default is ascending.
sortBy2
Do a secondary sort on the specified field.
sortOrder2
Specify if the sort order on the second level is ascending ("asc") or descending ("desc"). Not case sensitive. The default is ascending.
offset
The maximum number of records that you can retrieve in a single call to searchRecords is 5,000. If you need to retrieve more than 5,000 records, you must set up a loop where you do paging by incrementing the offset parameter.
For example, if you need to retrieve 25,000 records, you need to set the offset parameter to zero (0) and the numberOfRows parameter to 5,000 on the first pass to get records 1-5000. Then, on the second pass, you set offset to 1 to get records 5001-10,000, and so on. In other words, you multiply offset by numberOfRows and add one to determine the number of the first record retrieved at each pass.
numberOfRows
The maximum number of records to return
params
An optional com.platform.api.Parameters object. Use it to specify the Retrieve Record Permissions Parameter, in order to find out if the user has update or delete permissions on the records.

3.8.3 Returns

Result object. If the return code is greater than zero, use the Result_Class#getIterator method to cycle through the list of Parameters objects it contains, one per record.

3.8.4 Learn More

3.8.5 Examples

3.8.5.1 Example: Basic Search

This example calls searchRecords with three parameters, assigning the returned value to an instance of Result and calling Result.getCode to assign the error code to a variable which is then conditionally checked to determine the code to execute.

If the search was not successful, the code calls throwError to display an error dialog.
If the search was successful and returned records, the code creates an instance of ParametersIterator. In a while loop, the code calls ParametersIterator.next to get an instance of Parameters from which it then extracts the name and number keys.
String accountID = "";
// Some logic to populate accountID variable.
Result result = Functions.searchRecords("ACCOUNT", "record_id,name,number",
    "name contains 'Acme'");
int resultCode = result.getCode();
if (resultCode < 0)
{
    // Some error happened.
    String msg = "Account could not be retrieved";
    Functions.debug(msg + ":\n" + result.getMessage());  // Log details
    Functions.throwError(msg + ".");                     // Error dialog
}
else if (resultCode == 0)
{
   // No records found. Take action according to your business logic
}
else
{
  //Records retrieved successfully
  ParametersIterator iterator = result.getIterator();
  while(iterator.hasNext())
  {
    Parameters params = iterator.next();
    String accountID = params.get("record_id");
    String accountName = params.get("name");
    String number = params.get("number");
    // Take action according to your business logic
  }
}
3.8.5.2 Example: Sorted Search

This example calls searchRecords with nine parameters, assigning the returned value to an instance of Result and calling Result.getCode to assign the error code to a variable which is then conditionally checked to determine the code to execute:

  • If the search was not successful, the code calls throwError to display an error dialog.
  • If the search was successful and returned records, the code creates an instance of ParametersIterator. In a while loop, the code calls ParametersIterator.next method to get an instance of Parameters from which it then extracts the name and number keys.
// Next searchRecords call will sort the results, first by city
// (ascending) and then by number (descending). It will return
// first 200 records matching the criteria.

Result result = Functions.searchRecords("ACCOUNT", "record_id,city,name,number",
"name contains 'California'", "city", "asc", "number", "desc", 0, 200);
int resultCode = result.getCode();
if(resultCode < 0)
{
    // Some error happened.
    String msg = "Account could not be retrieved";
    Functions.debug(msg + ":\n" + result.getMessage());  // Log details
    Functions.throwError(msg + ".");                     // Error dialog
}
else if(resultCode == 0)
{
  // No records found
  // Take action according to your business logic
}
else
{
   //Records retrieved successfully
   ParametersIterator iterator = result.getIterator();
   while(iterator.hasNext())
   {
      Parameters params = iterator.next();
      String accountID = params.get("record_id");
      String accountName = params.get("name");
      String number = params.get("number");
      // Take action according to your business logic.
   }
}
3.8.5.3 Example: Multi-Page Search

This search retrieves 5,000 records at a time, with each set of records in a separate "page".

int i;
int numberOfRecords;
int numberOfPages;
int max_records_per_page = 5000;

//Ensure use of same criteria to do the search and to get the record count
String criteria = "";

String objectName = "ACCOUNT";
String fields = "record_id,name";
String sortBy = "";
String sortOrder = "";
String sortBy2 = "";
String sortOrder2 = "";

numberOfRecords = Functions.getRecordCount(objectName, criteria);
numberOfPages = numberOfRecords / max_records_per_page;
if (numberOfRecords % max_records_per_page > 0) {
  // If the modulus operator says the division left a remainder,
  // then do one more fetch for the remaining records.
  numberOfPages++;
}

for(i=0; i < numberOfPages; i++)
{
    Result result = Functions.searchRecords (
        objectName, fields, criteria,
        sortBy, sortOrder, sortBy2, sortOrder2,
        i, max_records_per_page);
    int resultCode = result.getCode();
    if (resultCode < 0)
    {
        // Some error happened.
        String msg = "Account could not be retrieved";
        Functions.debug(msg + ":\n" + result.getMessage());  // Log details
        Functions.throwError(msg + ".");                     // Error dialog
    }
    else if (resultCode == 0)
    {
        // No records found. Take action according to your business logic
    }
    else
    {
        // Records retrieved successfully
        ParametersIterator iterator = result.getIterator();
        while(iterator.hasNext())
        {
            params = iterator.next();
            String recordId = params.get("record_id");
            Functions.debug(recordId);
        }
    }
}
3.8.5.4 Example: Searching Audit Logs
Audit Logs can be searched using the getRecord and searchRecord APIs
Learn more: Audit Log Fields
How it Works
Provide search criteria to search multiple audit log records and retrieve a list of audit log fields. The getRecord and searchRecords APIs are used in actions that Invoke a Java Method.
Syntax
public static Result Functions.searchRecords(String objectId, String fields, String criteria)
objectId
log
fields
record_id, ownerid, type, operation, object, date_created, description, type_code
recordId
Audit log record Id
Return
Result object
Audit Log Example Based on Filtering Criteria
Result result = Functions.searchRecords("log", "record_id,type,operation,"+
"object,description", "(record_id starts with'65') and (description contains 'audit')");

int resultCode = result.getCode();

if(resultCode < 0)
{
    // Some error happened.
    String msg = "Error during search";
    Functions.debug(msg + ":\n" + result.getMessage());  // Log details
    Functions.throwError(msg + ".");                     // Error dialog
}
else if(resultCode == 0)
{
   // No records found. Take action according
   Functions.throwError("No results returned from search");
}
else
{
  //Records retrieved successfully
  ParametersIterator iterator = result.getIterator();
  while(iterator.hasNext())
  {
    Parameters params = iterator.next();
    String desc= params.get("description");
    String type= params.get("type");
    String obj = params.get("object");
    String record_id = params.get("record_id");
    String operation = params.get("operation");                  
 
    // Take action according to your business logic
  }
}
Learn more: Audit Log Fields
3.8.5.5 Example: Search Test

This example does a number of things:

  • It defines a search method on the Orders object.
  • It creates a test method to run that search, taking advantage of the [RunTests] button to execute the method.
    Learn more: Unit Test Framework
  • It gets all fields in searchRecords and getRecord, using the "*" wildcard.
  • It enumerates the names of the fields that are returned, putting them into the Debug Log.
    Note: Enumerating things in a JSP Page would produce a nicer result, without much additional effort. That page could then be named as a Web Tab, which would be available in the Workspace.
  • In addition data contained in an Order record, it uses the Java getRecord API and the data in the related_to_Customer lookup field to get data from the related Customer record.
    Note: The Java API Composite Object getRecord method could also be used to specify the customer name as a field to retrieve. But the "wildcard" specifier could not be used for field names, in that case.
package com.platform.demo.test;

import com.platform.api.*;

public class SearchTest
{
  public String searchOrders() throws Exception {
 
    Result result = Functions.searchRecords("Order", "*", "");
       //Toss the exception, if one occurs
   
    int resultCode = result.getCode();
    if (resultCode < 0)
    {
        // Some error happened.
        String msg = "Error during search";
        Functions.debug(msg + ":\n" + result.getMessage());  // Log details
        Functions.throwError(msg + ".");                     // Error dialog
        return("");
    }
    else if(resultCode == 0)
    {
        // No records found. Take action accordingly
        Functions.throwError("No results returned from search");
        return("");
    }
    else
    {
        //Records retrieved successfully
        ParametersIterator iterator = result.getIterator();
        boolean first_time = true;
        while(iterator.hasNext())
        {
            Parameters params = iterator.next();
            String num= params.get("order_number");
       
            // List the fields present in the params object
            if (first_time) {
                for (Object key : params.keySet() ) {
                   Functions.debug(""+key);
                }
                first_time = false;
            }
                   
            // Use the Lookup value in related_to_Customer to get customer info
            String customerID = params.get("related_to_Customer");
            Result customer =
                Functions.getRecord("Customer", "*", customerID);
            String company = customer.getParameters().get("customer_name");
       
            // Echo order info
            Functions.debug("Order #" +  num + " for " + company);      
        }        
        //Result code is the #of records found.
        return ""+resultCode;
    }
  }  
 
  @TestMethod
  public void runSearchOrders() throws Exception {
     String record_count = searchOrders();
     RunTest.assertEquals(record_count, "6");
  }
 
}


3.9 execSQL

Execute a SQL query.

3.9.1 Syntax

Result result = Functions.execSQL(String query);

3.9.2 Parameters

query
The SQL query to execute.
Learn more: SQL Syntax

3.9.3 Returns

Result object. If the return code is greater than zero, use the Result_Class#getIterator method to cycle through the list of Parameters objects it contains, one per record.

3.9.4 Sample Code

This sample retrieves a value from the most recent record that matches the specified criteria:

try {
   String latest_value;
   String sql =
      "SELECT some_field FROM MyObject " +
      "WHERE another_field = '" + someValue + "' " +
      "ORDER BY date_created DESC " +            
      "LIMIT 1";
   Result result = Functions.execSQL(sql);
   int resultCode = result.getCode();
   if (resultCode < 0)
   {
      // Error occurred
      String msg = "Sample: Error during SQL search";
      Functions.debug("Sample:\n" + result.getMessage());
   }
   else if (resultCode > 0)
   {
      // A record was found. (Otherwise, resultCode == 0)                    
      ParametersIterator it = result.getIterator();
      Parameters params = it.next();  // Use a loop if Limit > 1      
      latest_value = params.get("some_field");
      Functions.debug("Sample: latest value = " + latest_value);        
   }
} catch (Exception e) {
   String msg = "Sample: Exception during SQL search";
   Functions.debug("Sample:\n" + e.getMessage());        
}

3.9.5 Sample App

This sample uses the execSQL operation to populate a JSP page with a list of object records.

3.9.6 Learn More

3.10 replaceTemplateVariables

Functions.replaceTemplateVariables(String text, String objectId, String recordId)
Finds and replaces Template Variables with new information

Syntax

Result result = Functions.replaceTemplateVariables(String text, String objectId, String recordId)

Parameters

text
Text string
objectID
The identifier of the object
recordID
The identifier of the record
Example
As part of a Data Policy, an action that executes Java code could contain the following lines to replace the $project.name Template Variable with a new Object Type Identifier (objectId) and Record Id (recordId).
String text = "$project.name"
String replaced_text = Functions.replaceTemplateVariables(text, "PROJECT", "123456")


4. Workflow Record Handling

4.1 processWorkflowAction

Description
Executes a Workflow Action.
Result Functions.processWorkflowAction(
    String workflowName,
    String currentStateName,
    String recordId,
    String customObjectName,
    String workflowAction,
    String workflowComments,
    String userChoiceOwner)
/*
    where:
        workflowName is the Workflow name
        currentStateName is the State name (optional)
        recordId is the Record Id
        customObjectName is the Object name or ID
        workflowAction is the Workflow action
        workflowComments contain the Workflow comments
        userChoiceOwner is the Workflow Decision Maker, User Choice (user ID)
 */
Example
/* This example initiates an action in an existing workflow.
    - In the existing workflow, a Workflow state exists: "Start"
    - An action can be taken from that state, called "Initiate"
    When the following code is invoked, the Workflow action "Initiate" is
    applied to a record in a Workflow state "Start", which is then updated
    to the new state, as defined in the workflow
 */

    Functions.debug("Initiate Workflow");
    String recordId = requestParams.get("record_id");
    Result result = Functions.processWorkflowAction(
        "expense_report_wf",
        "start",
        recordId,
        "ExpenseReport",
        "Initiate",
        "Initiate workflow",
        "f3cedfca55644c7");
    Functions.debug("Result Code and Message:"
                   +result.getCode()+":"+result.getMessage());

    Parameters priorParams = requestParams.getPriorParams();
    Functions.debug("Old workflow state:"+priorParams.get("workflow_state") );
    Functions.debug("New workflow state:"+requestParams.get("workflow_state") );


Considerations

The following permissions are checked before an Action is applied in a Workflow. If the User does not meet the specified permissions, a error is thrown.

Condition The Logged in User must be:
Record is in the Start stateRecord Owner and decision maker (as specified in the Start state decision-makers list)
Record is in any state (not Start)Workflow Owner
Note
If Unanimous Decision Making is selected, the action is taken, only if the action was not taken by this user already.


4.2 getWorkflowActionList

Retrieves a list of Workflow Actions available for a record, depending on it's Workflow State.

Syntax
Functions.getWorkflowActionList(String objectName,String recordId)
where:
  • objectName is the name or id of the object
  • recordId is the id of the record
Return
Map
Example
This example returns workflow action list for object "Invoice". A map of actions for a record in the Invoice object is returned.
Functions.debug("Retrieve workflow action list");
String recordId = requestParams.get("record_id");
Map<String,WorkflowActionBean>  wfCollection = Functions.getWorkflowActionList("Invoice", recordId);
for(Map.Entry<String,WorkflowActionBean> e : wfCollection.entrySet())
{
    WorkflowActionBean wf = e.getValue();
    Functions.debug("Action name : "+ wf.getName());
}


4.3 getWFOwners

Identify current owners of a record in a workflow.

Syntax
Functions.getWFOwners(String objectName, String recordId)
where:
Return
RecordBean containing a list of IDs and names of record owners.
Example
This example lists current owner IDs and names for an EXPENSES record, depending on where it is in the workflow path.
Functions.debug("List workflow owners");
RecordBean rb = Functions.getWFOwners("EXPENSES", (String)requestParams.get("record_id"));
List<RecordBean.WorkflowOwners.WFOwner> owners = rb.getAvailableWFOwners().getOwners();
if (owners != null)
{
    for (int indx=0; indx<owners.size(); indx++)
    {
        RecordBean.WorkflowOwners.WFOwner owner = owners.get(indx);
        debug ("id: " + owner.getId() + "; name:" + owner.getFullName() );
    }
}
Personal tools