searchRecords
Search and retrieve the records for an object.
Syntax
- <syntaxhighlight lang="java" enclose="div">
Result result; result = Functions.searchRecords (String objectOrView, String fields, String criteria
{, Parameters params} );
result = Functions.searchRecords (String objectOrView, String fields, String criteria,
String sortBy, String sortOrder,
String sortBy2, String sortOrder2,
int offset, int numberOfRows {, Parameters params} );
</syntaxhighlight>
Parameters
- objectOrView
- The object name, object identifier, or Database View id.
- fields
- The fields to retrieve.
- A comma-separated list of field names (Use the REST API:field Resource to get a complete list of fields.)
- The asterisk ("*") wildcard specifies all fields.
- For related-record fields in a Composite Object, specify the alias of the related object and the field name, where the alias is defined in the Object Relationships:
- alias[.alias...].* or alias[.alias...].field
- When fetched, an alias becomes a virtual "field" that contains an array of records from the related object, where each record contains the specified field(s).
- 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.
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.
Learn More
Examples
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.
- <syntaxhighlight lang="java5" enclose="div">
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"; Logger.info(msg + ":\n" + result.getMessage(), "Accounts"); // Log details Functions.throwError(msg + "."); // Error message
} 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
}
} </syntaxhighlight>
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.
- <syntaxhighlight lang="java5" enclose="div">
// 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"; Logger.info(msg + ":\n" + result.getMessage(), "Accounts"); // Log details Functions.throwError(msg + "."); // Error message
} 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.
}
} </syntaxhighlight>
Example: Multi-Page Search
This search retrieves 5,000 records at a time, with each set of records in a separate "page".
- <syntaxhighlight lang="java5" enclose="div">
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";
Logger.info(msg + ":\n" + result.getMessage(), "Accounts"); // Log details
Functions.throwError(msg + "."); // Error message
}
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");
Logger.info(recordId, "Accounts");
}
}
} </syntaxhighlight>
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
- <syntaxhighlight lang="java5" enclose="div">
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"; Logger.info(msg + ":\n" + result.getMessage(), "Accounts"); // Log details Functions.throwError(msg + "."); // Error message
} 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
}
} </syntaxhighlight>
- Learn more: Audit Log Fields
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 become available for use as a tab in the application. - 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.
- <syntaxhighlight lang="java" enclose="div">
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";
Logger.info(msg + ":\n" + result.getMessage(), "Search"); // Log details
Functions.throwError(msg + "."); // Error message
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() ) {
Logger.info(""+key, "Search");
}
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
Logger.info("Order #" + num + " for " + company, "Search");
}
//Result code is the #of records found.
return ""+resultCode;
}
}
@TestMethod
public void runSearchOrders() throws Exception {
String record_count = searchOrders();
RunTest.assertEquals(record_count, "6");
}
} </syntaxhighlight>