Java API:Utility

These Utility Java APIs perform general-purpose operations.

debug

DEPRECATED:
This function has been deprecated. Developers are encouraged to use the Logger utility class, instead.
Learn more: Debug Log.

Logs a debug message at the "INFO" severity level.

Learn more:

View debug messages in the Debug Log
Change the recording level for messages in Developer Configuration

Parameters: obj - An object or a String.

Syntax

void = Functions.debug(Object obj);
void = Functions.debug(String message);

Return None

Example: This example calls debug after calling updateRecord to log the result code. The code also calls debug to log the message if the result code is less than zero (0).

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();
Functions.debug(" Result code is " + resultCode);

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 on successful addition of the account.
}

exec

DEPRECATED: Functions have been deprecated. Rather than using the exec method, put your code into a method in a Java Class, and call that code directly. (For the moment, it is still possible to invoke existing functions, although it is no longer possible to create new ones. At some future date, however, support for functions will be dropped entirely, at which point all existing functions will need to be converted.)

Functions.exec(String functionName, Parameters params)

Description: Executes a function: functionName with params as input . Note that this params object is visible in functionName as requestParams.

Within a called function, the Parameters object can be accessed using the requestParams object.

Syntax

Functions.exec(String functionName, Parameters params)

Return: The return value is defined by the function

Example

This example calls a calculate_estimated_profit function which returns the profit as 30% of the specified revenue.

float revenue = params.getFloat("revenue", 0.0);
Parameters params = Functions.getParametersInstance();
params.add("revenue", revenue);
float profit = Functions.exec("calculate_estimated_profit", params);

getEnv

getEnv(String key)

Description: Gets the environment variable value for the key

Syntax

String = Functions.getEnv(String variable)

Environment Variable Constants

The following constants can be used as keys to access the environment variables:

Key	Variable
ENV.USER.ID	Logged in user's ID
ENV.USER.USER_NAME	Logged in user's username
ENV.USER.FULL_NAME	Logged in user's full name
ENV.USER.COMPANY_NAME	Logged in user's company name
ENV.USER.EMAIL	Logged in user's email
ENV.USER.TENANT_ID	The ID of the tenant the user is logged in to
ENV.USER.TIME_ZONE	Logged in user's timezone

ENV.COMMUNITY.TENANT.ID	The community tenant ID

ENV.MSP.ID	The ID of the MSP for this tenant. Blank if the current tenant is not under an MSP.

ENV.SESSION.ID	ID of the logged in user's session

ENV.ISV.RECAPTCHA_PUBLIC_KEY	Key used when verifying that the system is interacting with a person. Learn more: recaptcha.

Return

The value of the environment variable as a String.

Example: This example calls getEnv to get the current user's identifier.

String userID = Functions.getEnv(ENV.USER.ID);

getLoggedInUserInfo

Functions.getLoggedInUserInfo()
Description: Retrieves information about a Logged in User

In addition to the fields are listed in REST API:user Resource, this API returns the following:

Name	Type	Attribute	Description	Additional Information
locale	Object	Read Only	Identifies the user's language and country code	java.util.Locale

Syntax

Map<String,Object> Functions.getLoggedInUserInfo()

Return

Map containing user information

Example

Map user = Functions.getLoggedInUserInfo();
Functions.debug(user);
Functions.debug(user.get("last_name"));

getTimezonesUtility

Functions.getTimezonesUtility()

Description

Retrieves the list of time zones

Syntax

MMap Functions.getTimezonesUtility()

Return

Map

Example

Retrieve a list of all timezones

Learn more: Time Zone Codes

Functions.debug("Retrieve time zone list");
Map<String, TimeZoneBean> timezoneCollection = Functions.getTimezonesUtility() 
for(Map.Entry e : timezoneCollection.entrySet())
{
TimeZoneBean tz = e.getValue();
Functions.debug("code: "+ tz.getId() + "; value: "+ tz.getJavaValue() + "; user friendly value: "+ tz.getUserFriendlyValue());
}

getTimezoneUtility

Functions.getTimezoneUtility(String timezoneId)

Description

Retrieves a time zone, based on a provided id

Syntax

Map Functions.getTimezoneUtility(String timezoneId)

Where timezoneId is a Time Zone Code

Return

TimeZoneBean

Example: Retrieve the time zone for timezoneId = 80

Functions.debug("Retrieve time zone 80);
TimeZoneBean tz = Functions.getTimezoneUtility("80");
Functions.debug("code: "+ tz.getId() + "; value: "+ tz.getJavaValue() + "; user friendly value: "+ tz.getUserFriendlyValue());

getParametersInstance

Functions.getParametersInstance()

Description: Gets an instance of the Parameters class; Returns an instance of the Parameters class

Syntax

Parameters = Functions.getParametersInstance()

Return: Parameters object

Example: This example creates an instance of Parameters, adds name-value pairs to it, and calls addRecord, passing the Parameters object as an argument.

Parameters params = Functions.getParametersInstance();
params.add("name", "Acme Solutions");
params.add("number", "GRG2323339");
Result result = Functions.addRecord("ACCOUNT", params);

showMessage

Functions.showMessage(String key [, String[] args])

Description

Displays the message in the UI, irrespective of any database insertions or updates (without interrupting the program flow)
Translates the token and displays the Custom Label in the selected language

Element

Display Type

Description

key

string

Created from category name, followed by '.' and token name

Syntax

#categoryname.tokenname

args

string

Optional

Declares an array of Strings in Java (or Arguments)

If arguments are passed, the call expects a token
If no arguments are passed, the message alone is displayed

Syntax

void Functions.showMessage(String key [, String[] args]);

If no arguments are needed (for example, for a label in the #custom category), use:

Functions.showMessage("#custom.label",null)

Return

Returns the localized message configured on the key in the Translation Workbench
If no key is configured in the translation workbench, then the passed key is returned

sleep

Functions.sleep(long milliseconds)
Description: Pauses the current process for the specified number of milliseconds.

Syntax

void Functions.sleep(long milliseconds);

Throws

InterruptedException if the process was awakened by the JVM (or terminated) before the specified wake-up time.

setTargetPage

setTargetPage(String URL)
Description: Performs the action of clicking a link in the UI; Sets the target page, URL is the relative path

Syntax

void setTargetPage(String URL)

Return: None

Example

This code causes the Setup page (s=641) to be displayed.

 setTargetPage("Service?t=641&top_tab=none");

throwError

Functions.throwError(key [, String[] args])

Description

Ends execution and throws an error with the specified message
Supports Language Translation via Translation Workbench
Translates the token and displays the translated message in the selected language

Element

Display Type

Description

key

string

Created from category name, followed by '.' and token name

Syntax

#categoryname.tokenname

String [] args

string

Optional

Declares an array of Strings in Java (or Arguments)

If arguments are passed, the call expects a token
If no arguments are passed, the message alone is displayed

Syntax

void = Functions.throwError(String key [, String[] args])</pre>

If no arguments are needed (for example, for a label in the #custom category), use:

Functions.throwError("#custom.label",null)

Return

Returns the message configured on the key in the Translation Workbench
If no key is configured in the translation workbench, then the passed key is returned

Example: This example checks a parameter passed to it to see if it is equal to "Acme". If it is, the code calls throwError to display an error message saying that the account cannot be "Acme".

if(requestParams.get("name").equals("Acme"))
{
    // message "Account cannot be Acme" will be shown to the user in the UI.
    Functions.throwError("Account cannot be Acme");
}
else
{
    // Normal business logic.
}

To include new lines in the message, specify <br>:

Functions.throwError(“Include <br> for <br> newline”);

translateToken

The translateToken API accesses a Custom Label (a message) defined in the Translation Workbench.

Syntax

String result = Functions.translateToken(String key) 
String result = Functions.translateToken(String key, String [] args)

Parameters

key: The category and token (index key) for the message to retrieve, in the form: "#category.token_name".
args: An array of string-arguments to be substituted into the message, in the locations defined by the message format.

Returns: A string containing the selected message in the user's currently active language, with specified arguments substituted.

Example

In this example, go_msg is a Custom Label in the Translation Workbench created in the "custom" category, where the translation in the user's current language is "It's a {1} day for a {2}." Supplying the arguments then allows for variations on the message.

String [] args = {"nice", "walk"};
String msg = Functions.translateToken("#custom.go_msg", args));
    // ==> "It's a nice day for a walk."

Search

where to start

learn more

Tools

Personal tools

Java API:Utility

Contents

debug

exec

getEnv

getLoggedInUserInfo

getTimezonesUtility

getTimezoneUtility

getParametersInstance

showMessage

sleep

setTargetPage

throwError

translateToken