How To Write Custom Java Code In Pega?

Custom Java code can be integrated into Pega applications through several standard and guardrail-compliant methods, but should only be used when Pega's native low-code features cannot achieve the desired functionality.

Using custom Java is a powerful but advanced technique that requires a deep understanding of the Pega Platform's architecture and guardrails to ensure application stability, security, and maintainability.

Here is an extensive article covering how to write and use custom Java code in Pega.

1. The Pega guardrails: When to use custom Java

Before writing any custom Java, it is crucial to understand Pega's design philosophy. Pega is a low-code platform, and its primary goal is to minimize hand-coding. The recommended approach is to use standard Pega rules and configurations, as they are easier to maintain, are automatically secured, and are more compatible with future upgrades.

Use custom Java only when absolutely necessary, for tasks such as:

• Calling external Java libraries that do not have a standard Pega connector.
• Implementing complex algorithms or data transformations that are not feasible with standard functions or data transforms.
• Accessing advanced features of the Pega Public API that are not exposed through standard rule configurations.
• Integrating with legacy systems via custom connectors.

Avoid using custom Java for:

• Simple property manipulations (use data transforms).
• Conditional logic (use when rules, decision tables, or decision trees).
• Database interactions (use Pega's data layer, connectors, and report definitions).
• User interface logic (use section rules and UI controls).

2. Methods for adding custom Java

There are two primary, guardrail-compliant ways to incorporate custom Java into a Pega application: within Activity rules and within Function rules.

Method 1: Using the Java step in an Activity rule

An Activity is an ordered sequence of steps used to automate business logic. You can add a Java step to an Activity to include inline Java code.

Steps to add a Java step:

1. Create or open an Activity rule in the appropriate class and ruleset.
2. Add a new step to the activity.
3. In the Method column for the new step, type Java and press Enter.
4. Click the gear icon to expand the Method field and reveal a text box for your code.
5. Enter your Java code into the text box. The code can reference Pega properties and standard Java libraries.

Key considerations for Java steps:

• Accessing Pega APIs: Within a Java step, you can use the tools variable to access the Pega PublicAPI, which contains methods for interacting with the clipboard, properties, and other Pega-specific functions. For example:
  • tools.findPage("pyWorkPage").putString(".Status", "Resolved-Completed");
• Fully qualified class names: You cannot use import statements in a Java step. All external Java classes must be referenced using their fully qualified name.
  • Correct:java.util.Vector x = new java.util.Vector();
  • Incorrect:Vector x = new Vector();
• Handling exceptions: Wrap your Java code in try-catch blocks to gracefully handle exceptions and set the activity's status to indicate an error.
• Iteration: Use the loop feature of the Java step to iterate over a Page List or Value List property. The currentProperty variable will reference the current element during each iteration.

Method 2: Creating a Function rule

For reusable code, custom logic should be encapsulated in a Function rule (Rule-Utility-Function) rather than being duplicated across multiple Activities.

Steps to create a Function:

1. Create a Library rule (Rule-Utility-Library). A library acts as a container or package for one or more functions and belongs to a ruleset.
2. Create a Function rule within your new Library.
3. Define the function signature:
   • Specify the Return Type (e.g., String, boolean, double).
   • Define the Input Parameters, including their names, descriptions, and data types.
4. Navigate to the Java tab and enter your custom Java code. You do not need to use the tools variable here; the PublicAPI is available directly.
5. Click Save and Compile. Pega will validate and compile your Java code, and any errors will be displayed.

**Calling a Function rule:**After a function is defined, you can call it from various Pega rules, including Activities, Data Transforms, Decision rules, and Declare Expressions. The syntax for calling a function is @(LibraryName:FunctionName)(Parameter1, Parameter2). For example: @(MyCo-Custom:CalculateBonus)(.TotalSales, .EmployeeLevel).

Method 3: Using a Function Alias

A function alias provides a user-friendly, business-oriented name and description for an underlying Java Function rule. This allows non-developers to use complex functions in rules like Decision tables, Decision trees, and Report definitions without needing to understand the underlying code.

Steps to create a Function Alias:

1. Create a Function rule as described above.
2. Create a Function Alias rule (Rule-Alias-Function) and reference your custom Java function.
3. Provide a readable name and a clear description for business users.
4. Define the Presentation template and Echo template to provide a contextual description when used in rules.

3. Best practices for writing custom Java in Pega

• Follow the Pega guardrails: Only use custom Java as a last resort. Pega's automated tools and upgrades are not compatible with un-guarded custom code.
• Encapsulate logic in Functions: Move any complex, reusable Java code into a Function rule. This improves reusability, maintainability, and version control.
• Use the PublicAPI: Always use the Pega PublicAPI to interact with the clipboard and Pega data, rather than attempting direct manipulation of the underlying Java objects. This ensures compatibility and proper session management.
• Avoid complex data types in Functions: Java Functions should primarily return primitive types (String, int, etc.) and avoid complex Java objects, which can cause issues with older versions of Pega when used in Decision rules.
• Write clean and simple code: Keep Java steps and functions as small and simple as possible. Complex logic should be broken down into smaller, more manageable methods.
• Add comments: Provide clear and comprehensive comments in your custom Java code to explain the purpose of the logic, as it is often difficult for other Pega developers to debug.
• Test thoroughly: Use Pega's unit testing features to test your Activities and Functions to ensure they work as expected under various scenarios.
• Run security checks: Always run the Rule Security Analyzer on any rule containing custom Java to check for potential security vulnerabilities like Java injection.

4. Security considerations for custom Java

Hand-coded Java poses significant security risks if not properly managed. When you add custom Java, you are responsible for mitigating potential vulnerabilities.

Security risks associated with custom Java:

• Java injection: Malicious code could be injected into your Java steps, allowing unauthorized access or execution of commands.
• Insecure data handling: Improper handling of data in custom Java could expose sensitive information or lead to data corruption.
• Bypassing Pega security: Custom code can bypass Pega's built-in security features, such as access control and validation rules.

Mitigating security risks:

• Run the Rule Security Analyzer: Use this tool to scan your custom Java code for common vulnerabilities.
• Validate all inputs: Never trust user input. Always validate and sanitize all data passed into your custom Java code to prevent injection attacks.
• Use PublicAPI methods: Rely on the Pega PublicAPI methods for secure interactions with the system instead of writing custom, low-level code.
• Restrict permissions: Apply proper access control and privileges to the rules containing custom Java to limit who can execute them.
• Perform independent security assessments: Have a security expert review and sign off on any custom Java code in your application.

5. Advanced custom Java concepts

• Virtual File Interface (VFI): When working in a Java EE application server environment, you cannot directly access the server's file system using standard java.io routines. Instead, use the Pega Virtual File Interface (VFI), which is part of the Public API, to safely interact with files.
• Calling external libraries: To call a method from an external Java library, the library's JAR file must be in the application server's classpath. You can then reference classes from that library using their fully qualified class names within your Pega Java code.
• Custom authentication activities: A specific advanced use case for custom Java is creating custom authentication activities. This requires calling methods from the PRAuthentication interface.