AgileApps Support Wiki Pre Release

Parameters Class

From AgileApps Support Wiki

The Parameters class is a set of key-value pairs that holds a list of fields and their values:

  • You add key-value pairs to a Parameters object to pass values to Java API calls as input parameters. Each Java API call knows how to extract the key-value pairs and use the field values.
  • You extract key-value pairs that the Java API calls return.

You can see the fields defined for an object by selecting GearIcon.png > Customization > Objects > {object} > Fields.

Instantiating

You cannot instantiate a Parameters object with the new operator. Instead, you make the getParametersInstance utility call in the Java API: 

Parameters p = Functions.getParametersInstance();

You can also get an instance of a Parameters object by calling getParameters in the Result object.

Example

As an example, in the account object, there is a field called name that holds the name of an organization. Follow these steps to set the name field and add a new account record:

  1. Create an instance of the Parameters object
  2. Add the name field to it, setting the value (such as "Acme Solutions")
  3. Pass the Parameters object to the addRecord call

The code for this example is: 

Parameters account = Functions.getParametersInstance();
account.add("name", "Acme Solutions");
String accountName = account.get("name"); 
Result result = Functions.addRecord("ACCOUNT", account);

Methods

The Parameters object has following methods which you can use to manipulate the set of key-value pairs.

add

Adds a key-value pair to the object.

Signature of the Method 

void add(String key, Object value)
Example
This example the creates an instance of Parameters and then adds a key-value pair to it. As is frequently the case, it uses a string for the value, as well as the key.
Parameters params = Functions.getParametersInstance();
params.add("name", "Acme Solutions");

get

Gets the value of the given key.

You must make sure the string is valid. No error is returned if you try to get an invalid string.

Signature of the Method 

String get(String key)
Example
This example creates an instance of Parameters, adds a key-value pair to it, and then calls get to assign that value to a variable.
Parameters params = Functions.getParametersInstance();
params.add("name", "Acme Solutions");
String accountName = params.get("name");

getDate

Gets a date value for the given key.

The returned value maps to java.util.Date.

For the first signature, this method throws a Java Exception if a date cannot be formed from the given key's value. For the second signature, this call returns defaultValue if a date cannot be formed.

Method Signature 

Date getDate(String key)
Date getDate(String key, Date defaultValue)
Example #1 - Get a Date
Use the getDate() method to retrieve a value in 'Date' format from the Parameters object.

This example assigns the result of a getRecord call to an instance of Parameters and then calls getDate with one parameter to assign the value to a variable.

If the following code is run from a data policy on any object, you can use requestParams to retrieve the record ID of the record and object ID of the object
String recordID = requestParams.get("record_id"); 
Result result = Functions.getRecord(requestParams.get("object_id"), "record_id,date_created", recordID);
Logger.info("Record retrieved in function using getRecord:"
            + result.getMessage(), "Parameters");
Date d = (result.getParameters()).getDate("date_created");
Example #2 - Get an Existing or Default Date
This example assigns the result of a getRecord call to an instance of Parameters. The code then calls getDate with two parameters to assign the value to a variable; if a date value cannot be formed, the current date is assigned. The following code can be used in scenarios when we want to retrieve date field even if it is not populated. Assigns a default value of current Date.
String recordID = requestParams.get("record_id"); 
Result result = Functions.getRecord(requestParams.get("object_id"), "record_id,date_created", recordID);
Logger.info("Record retrieved in function using getRecord: "
           + result.getMessage(), "Parameters");

Parameters params = result.getParameters();
Date accountCreationDate = params.getDate("date_created", new Date());
// If the date_created field is not null or blank, returns 
// the date value, otherwise returns the current date.

getBoolean

Gets a Boolean value for a given key. If the value is equal to "1" or "true" or Boolean True, this call returns "true", otherwise it returns "false".

Signature of the Method 

boolean getBoolean(String key)
Example
This example assigns the result of a getRecord call to an instance of Parameters. The code then calls getBoolean to assign a property called do_not_call to a variable called do_not_call which is then conditonally tested to determine the code to execute.
// Some code to populate accountID
String accountID = "";
//If the following code is being used on a data policy from Account object,
//you can retrieve the ID of the account record using requestParams
String accountID = requestParams.get("record_id"); 
Result recordRetrieved = Functions.getRecord(requestParams.get("object_id"),
    "record_id,date_created,do_not_call", accountID);
Logger.info("Record retrieved in function using getRecord:" 
           + recordRetrieved.getMessage(), "Parameters");
boolean doNotCall = (recordRetrieved.getParameters()).getBoolean("do_not_call");
if(doNotCall)
{
    // Code here will specify what to do when doNotCall is true
}
else
{
    // Code here will specify what to do when 
    // doNotCall is false (in other words, when it is OK to call)
}

getInteger

Gets an integer value for the given key.

For the first signature, this method throws a Java Exception if an integer cannot be formed from the given key's value. For the second signature, this call returns defaultValue if an integer cannot be formed.

Signature of the Method 

int getInteger(String key)

int getInteger(String key, int defaultValue)
Example
This example assigns the result of a getRecord call to an instance of Parameters and then calls getInteger with one parameter to assign the value to a variable.
String accountID = "";
// Assuming the following code is being called from a policy on Account object
accountID = requestParams.get("record_id");
Result recordRetrieved = Functions.getRecord("ACCOUNT", "record_id,employees", accountID);
Logger.info("Record retrieved in function using getRecord:" 
           + recordRetrieved.getMessage(), "Parameters");
int employees = (recordRetrieved.getParameters()).getInteger("employees");
Example
This example assigns the result of a getRecord call to an instance of Parameters. The code then calls getInteger with two parameters to assign the value to a variable; if an integer value cannot be formed, 10 is assigned.
String accountID = "";
// Assuming the following code is being called from a policy on Account object
accountID = requestParams.get("record_id");
Result recordRetrieved = Functions.getRecord("ACCOUNT", "record_id,employees", accountID);
Logger.info("Record retrieved in function using getRecord:" 
           + recordRetrieved.getMessage(), "Parameters");
int employees = (recordRetrieved.getParameters()).getInteger("employees", 10);
// This will return 10 employees if value of employees
// is null or blank.

getFloat

Gets a float value for the given key.

For the first signature, this method throws a Java exception if a float cannot be formed from the given key's value. For the second signature, this call returns defaultValue if a float cannot be formed.

Signature of the Method 

float getFloat(String key)

float getFloat(String key, float defaultValue)
Example
This example assigns the result of a getRecord call to an instance of Parameters and then calls getFloat with one parameter to assign the value to a variable.
String accountID = "";
String objectID = "";
// Let us assume the following code is being used in a data policy related to ACCOUNT
//You can use requestParams object to retrieve the record ID and object ID
accountID = requestParams.get("record_id");
objectID = requestParams.get("object_id");
Result recordRetrieved = Functions.getRecord("ACCOUNT","record_id,revenue,date_created", accountID);
Logger.info("Result from getRecord!\nMessage:" + recordRetrieved.getMessage()
          + "\nCode:" + recordRetrieved.getCode(), "Parameters");
if(recordRetrieved.getCode() == 1)
{
   // This will return the revenue as 0
   // if the value of employees is null or blank
   Float totalRevenue = (recordRetrieved.getParameters()).getFloat("revenue"); 
}
Example
The following example show how to assign default values when you try to retrieve a float value using getFloat()

This example assigns the result of a getRecord call to an instance of Parameters. The code then calls getFloat with two parameters to assign the value to a variable; if a float value cannot be formed, 0.0 is assigned. 

String accountID = "";
String objectID = "";
// Let us assume the following code is being used in a data policy related to ACCOUNT
//You can use requestParams object to retrieve the record ID and object ID
accountID = requestParams.get("record_id");
objectID = requestParams.get("object_id");
Result recordRetrieved = Functions.getRecord("ACCOUNT","record_id,revenue,date_created", accountID);
Logger.info("Result from getRecord!\nMessage:" + recordRetrieved.getMessage()
          + "\nCode:" + recordRetrieved.getCode(), "Parameters");
if(recordRetrieved.getCode() == 1)
{
   // This will return the revenue as 0
   // if the value of employees is null or blank
   Float totalRevenue = ((recordRetrieved.getParameters()).getFloat(("revenue"), 0.0f)); 
}

remove

Removes a key-value pair for the given key.

Signature of the Method 

void remove(String key)
Example
This example creates an instance of Parameters, adds a key-value pair to it, and then removes that key-value pair.
Parameters myAccount = Functions.getParametersInstance();
myAccount.add("name", "Acme Solutions");
myAccount.remove("name");

clear

Removes all key-value pairs.

Signature of the Method 

void clear()
Example
This example creates an instance of Parameters, adds key-value pairs to it, and then removes all the key-value pairs.
Parameters params = Functions.getParametersInstance();
params.add("name", "Acme Solutions");
params.add("number", "60000");
params.clear();

size

Returns the size of the Parameters object.

Signature of the Method 

int size()
Example
This example creates an instance of Parameters and adds two key-value pairs to it. The code then assigns the result of calling size to a variable called sizeOfParameters; at this point sizeOfParameters contains 2. Next, the code calls remove to delete one of the name-value pairs and assigns the result of calling size to sizeOfParameters; at this point sizeOfParameters contains 1.
Parameters myAccount = Functions.getParametersInstance();
myAccount.add("name", "Acme Solutions");
myAccount.add("number", "Acme Solutions");
int sizeOfParameters = myAccount.size();
// sizeOfParameters variable is now 2 

myAccount.remove("name");
sizeOfParameters = myAccount.size();
// sizeOfParameters variable is now 1

getObject

Returns an Object of the value for the given string. Used to retrieve the record being imported as a string array.

Signature of the Method 

Object getObject(String key)
Example
//Retrieve the row that will be imported
//The String array returned will contain all the values in the row as its various elements
String[] accountArray = (String[])requestParams.getObject("record");
//Retrieve the element
String name = accountArray[0];
//Check the value of the column
//Add the check based on your criteria
if (name.equals("Acme"))
{
   //Use throwError API so as to report the error 
   //The record that did not meet the criteria
   //Will not be imported   
    String msg = "Ignoring record:" + name;
    Logger.info(msg, "Parameters");  // Log it
    Functions.throwError(msg);       // Report it to user
}
else
{
   //Add you custom code here to proceed further 
   Logger.info("Value of record in csv:" + name, "Parameters");
}
Retrieved from "https://agileappscloud.info/aadev-src/index.php?title=Parameters_Class&oldid=1832"