Welcome to the TechEPM blog, your go-to resource for all things Oracle Enterprise Performance Management (EPM). In today's post, we're diving into the world of Groovy scripting—a powerful tool that's transforming how administrators and developers customize Oracle Financial Consolidation and Close (FCCS) and other EPM applications like Planning, Profitability and Cost Management (PCMCS), and Enterprise Data Management (EDMCS). Whether you're an EPM admin looking to streamline workflows or a developer seeking to optimize performance, Groovy offers flexibility beyond standard business rules.
Groovy is a dynamic scripting language integrated into Oracle EPM Cloud's Calculation Manager. It allows you to write custom rules that dynamically generate Essbase calculation scripts, validate data, integrate with APIs, and more. Unlike traditional fixed business rules, Groovy adapts to runtime contexts like user inputs, form data, or point-of-view (POV), making it ideal for complex, real-time scenarios in FCCS (for consolidations and close processes), Planning (for budgeting and forecasting), PCMCS (for profitability analysis), and EDMCS (for metadata management).
This post draws heavily from Oracle's official documentation, including the EPM Cloud Groovy Calculations guide, and insights from industry experts like Joe Aultman, a renowned Oracle EPM consultant known for his work on Groovy automation, and the Woman in EPM and LearnHyperion blogs, which provide practical examples and community-driven solutions. Joe Aultman has shared valuable insights in forums and podcasts, emphasizing Groovy's ability to extend EPM capabilities securely. The Woman in EPM and LearnHyperion blogs have been instrumental in providing code samples and use case inspiration. Oracle's documentation offers the technical foundation for API usage and syntax.
Below, we explore 10 practical use cases for Groovy across Oracle EPM applications, with a focus on FCCS where applicable, and clarify which applications (FCCS, Planning, PCMCS, EDMCS) each use case applies to. Each is explained in simple terms with step-by-step implementation details and code snippets adapted from these sources, ensuring EPM admins and developers can apply them effectively.
10 Use Cases for Groovy Scripting in Oracle EPM
1. Data Form Validation
Applications: FCCS, Planning, PCMCS
Groovy excels at checking user-entered data in real-time on forms, ensuring it meets business rules before saving. For example, validate journal entries in FCCS or budget thresholds in Planning to prevent errors. Credit to Woman in EPM for their detailed validation examples.<grok:render type="render_inline_citation"><argument name="citation_id">76</argument></grok:render>
Practical Usage:
- Log in to your Oracle EPM Cloud instance (FCCS, Planning, or PCMCS).
- Navigate to Application > Calculation Manager via the Navigator menu (hamburger icon > Application cluster).
- Create a new rule: Right-click your application > New > Rule. Select "Script" as the type and "Groovy" as the language.
- In the script editor, write your validation logic. Assign the rule to a form: Go to Forms > Edit the form > Business Rules tab > Add the Groovy rule (e.g., as an On Save rule).
- Deploy the rule and test on the form—users will see error messages if validation fails.
Sample Code (Validates email and phone on an employee form in Planning):
```
/RTPS: {EmployeeEmail} {EmployeePhone}/
def mbUs = messageBundle(["validation.invalidemail":"Email address is invalid: {0}", "validation.invalidphone":"Phone number is invalid: {0}"])
def mbl = messageBundleLoader(["en" : mbUs]);
validateRtp(rtps.EmployeeEmail, /^.+@.+/, mbl, "validation.invalidemail", rtps.EmployeeEmail);
validateRtp(rtps.EmployeePhone, /^\d{10}$/, mbl, "validation.invalidphone", rtps.EmployeePhone);
```
This code uses runtime prompts (RTPS) to check patterns and throws custom errors if invalid, inspired by Woman in EPM's validation patterns.<grok:render type="render_inline_citation"><argument name="citation_id">76</argument></grok:render>
2. Focused Calculations for Performance Improvement
Applications: FCCS, Planning, PCMCS
Instead of calculating the entire database, Groovy targets only edited cells or POVs, slashing runtime from minutes to seconds—crucial for large FCCS consolidations, Planning forecasts, or PCMCS cost allocations. LearnHyperion's performance optimization posts informed this approach.<grok:render type="render_inline_citation"><argument name="citation_id">79</argument></grok:render>
Practical Usage:
- In Calculation Manager, create a Groovy rule as above.
- Attach it to a form or menu: Forms > Edit Form > Business Rules > Add as a right-click menu item.
- Use DataGrid to iterate over changed cells. Deploy and run from the form—calculations will focus on dirty data only.
- Monitor performance in Jobs console (Navigator > Jobs).
Sample Code (Calculates only on edited cells in FCCS):
```
DataGrid grid = operation.grid
grid.dataCellIterator({DataCell cell -> cell.edited}).each { cell ->
// Perform calculation on cell, e.g., cell.setValue(cell.getValue() 1.1)
}
return "FIX(${grid.pov.members.collect{it.name}.join(',')}) / Calc logic / ENDFIX;"
```
This generates a dynamic FIX statement for Essbase, optimizing for changed data, as highlighted by LearnHyperion.<grok:render type="render_inline_citation"><argument name="citation_id">79</argument></grok:render>
3. Dynamic Calculation Script Generation
Applications: FCCS, Planning, PCMCS
Groovy builds Essbase calc scripts on the fly based on form context, like user-selected scenarios in Planning or account trends in FCCS. Oracle's documentation provides the syntax for dynamic scripts.<grok:render type="render_inline_citation"><argument name="citation_id">76</argument></grok:render>
Practical Usage:
- Create the rule in Calculation Manager.
- Set as an On-Demand rule: Rules > Properties > On-Demand.
- Launch from a form or task list: Tasks > Create Task List > Add Rule.
- Test by entering data and running—the script adapts dynamically.
Sample Code (Updates a global driver in Planning):
```
/RTPS: {Driver} {DriverValue}/
"""FIX("No Scenario", "No Version", "No Entity", "No Year", "BegBalance", "Local") $rtps.Driver = $rtps.DriverValue; ENDFIX;"""
```
Returns a custom calc script for execution, per Oracle's examples.<grok:render type="render_inline_citation"><argument name="citation_id">76</argument></grok:render>
4. Metadata Management (Add/Rename/Move Members)
Applications: EDMCS, FCCS, Planning
Manage dimension members dynamically, like adding employees in Planning workforce planning or renaming entities in FCCS or EDMCS. Oracle's API docs guide this process.<grok:render type="render_inline_citation"><argument name="citation_id">76</argument></grok:render>
Practical Usage:
- In Calculation Manager (for FCCS/Planning) or EDMCS scripting interface, create a pure Groovy rule (no calc script return).
- Assign to a menu: Menus > Create Menu > Add Rule (FCCS/Planning) or EDMCS workflow.
- Run from Navigator > Right-click in a form (FCCS/Planning) or EDMCS dimension view. Validate changes in Outline Editor (Application > Consolidation > Outline) or EDMCS dimension.
Sample Code (Rename and move a member in EDMCS):
```
/RTPS: {Employee} {NewName} {NewParent}/
rtps.Employee.member.dimension.saveMember(["Member" : rtps.Employee.member.name, "New Name" : rtps.NewName.enteredValue, "Parent" : rtps.NewParent.member.name] as Map<String, Object>)
```
Updates the dimension outline instantly, based on Oracle's metadata APIs.<grok:render type="render_inline_citation"><argument name="citation_id">76</argument></grok:render>
5. REST API Integration
Applications: FCCS, Planning, PCMCS, EDMCS
Call EPM REST APIs from Groovy to automate tasks, like launching jobs or integrating data across pods in FCCS, Planning, PCMCS, or EDMCS. Oracle's REST API guide is the primary source.<grok:render type="render_inline_citation"><argument name="citation_id">77</argument></grok:render>
Practical Usage:
- Ensure API access: Tools > Access Control > Assign roles.
- Create rule in Calculation Manager (FCCS/Planning/PCMCS) or EDMCS scripting.
- Run as a business rule from a dashboard or task: Dashboards > Edit > Add Rule Component.
- Check status in Jobs console.
Sample Code (Launch a data integration job in FCCS):
```
HttpResponse<String> jsonResponse = operation.application.getConnection("EPM_REST").post("/interoperability/rest/v1/applicationsnapshots")
.header("Content-Type", "application/json").body(json([name: "Backup"])).asString()
```
Triggers a snapshot via REST, as per Oracle's API examples.<grok:render type="render_inline_citation"><argument name="citation_id">77</argument></grok:render>
6. Data Export to Flat Files
Applications: FCCS, Planning, PCMCS
Export form data to CSV for reporting or auditing in FCCS close processes, Planning analysis, or PCMCS cost reporting. Woman in EPM's export examples inspired this.<grok:render type="render_inline_citation"><argument name="citation_id">78</argument></grok:render>
Practical Usage:
- Create Groovy rule in Calculation Manager.
- Attach to a menu or form save.
- Export path: Use inbox/outbox (Navigator > Inbox/Outbox).
- View exported file via Tools > Download.
Sample Code (Write to CSV in FCCS):
```
FileWriter writer = new FileWriter("/tmp/export.csv")
operation.grid.dataCellIterator().each { cell ->
writer.write("${cell.members.collect{it.name}.join(',')},${cell.data}\n")
}
writer.close()
```
Iterates grid and writes to file, adapted from Woman in EPM.<grok:render type="render_inline_citation"><argument name="citation_id">78</argument></grok:render>
7. Custom Calculations (e.g., Discounts)
Applications: FCCS, Planning, PCMCS
Perform bespoke math, like applying discounts based on volumes in Planning sales planning, FCCS adjustments, or PCMCS cost allocations. LearnHyperion's calculation posts informed this.<grok:render type="render_inline_citation"><argument name="citation_id">78</argument></grok:render>
Practical Usage:
- Rule in Calculation Manager.
- Run on form submit.
- Verify results in Smart View (connect via Excel add-in).
Sample Code (Calculate discount in Planning):
```
double discountRate = 0.1
operation.grid.dataCellIterator({it.edited}).each { cell ->
cell.setValue(cell.data (1 - discountRate))
}
```
Applies discount to edited cells, inspired by LearnHyperion.<grok:render type="render_inline_citation"><argument name="citation_id">78</argument></grok:render>
8. Launching EPM Automate Commands
Applications: FCCS, Planning, PCMCS, EDMCS
Run EPM Automate directly in Groovy for backups or imports without external scripts. Oracle's EPM Automate guide provides the syntax.<grok:render type="render_inline_citation"><argument name="citation_id">6</argument></grok:render>
Practical Usage:
- Enable in rule properties in Calculation Manager or EDMCS.
- Schedule via Tasks > Schedules.
- Monitor in Jobs.
Sample Code (Run backup in FCCS):
```
epmAutomate "backup", [name: "DailyBackup"]
```
Executes command inline, per Oracle's documentation.<grok:render type="render_inline_citation"><argument name="citation_id">6</argument></grok:render>
9. Dynamic Data Push/Smart Push
Applications: FCCS, Planning, PCMCS
Push data between cubes dynamically, like from Planning to FCCS reporting cube or PCMCS to Planning. LearnHyperion's data push examples guided this.<grok:render type="render_inline_citation"><argument name="citation_id">79</argument></grok:render>
Practical Usage:
- Define Data Map first: Application > Data Maps.
- In Groovy rule, trigger push.
- Attach to calc rule set in Calculation Manager.
Sample Code (Dynamic push in FCCS):
```
operation.application.getDataMap("PlanToReport").pushData([sourcePov: operation.grid.pov])
```
Pushes based on current POV, as per LearnHyperion.<grok:render type="render_inline_citation"><argument name="citation_id">79</argument></grok:render>
10. Error Highlighting and Warnings
Applications: FCCS, Planning, PCMCS
Highlight invalid cells or warn users during entry in forms for better UX in FCCS journals, Planning budgets, or PCMCS allocations. Woman in EPM's UX tips inspired this.<grok:render type="render_inline_citation"><argument name="citation_id">75</argument></grok:render>
Practical Usage:
- Rule as On Save or Validate in Calculation Manager.
- Use cell styling in code.
- Test on form—cells change color on errors.
Sample Code (Highlight errors in FCCS):
```
operation.grid.dataCellIterator().each { cell ->
if (cell.data < 0) cell.addValidationError(0xFF0000, "Negative values not allowed")
}
```
Colors cells red and shows message, adapted from Woman in EPM.<grok:render type="render_inline_citation"><argument name="citation_id">75</argument></grok:render>
Conclusion
Groovy scripting empowers EPM admins and developers to go beyond out-of-the-box features, making Oracle FCCS, Planning, PCMCS, and EDMCS more efficient and tailored. Special thanks to Joe Aultman for his thought leadership, Woman in EPM and LearnHyperion for their practical examples, and Oracle's documentation for technical clarity.
References
- Oracle EPM Cloud Groovy Calculation GuideOfficial Oracle documentation detailing Groovy integration, script creation, and usage examples for EPM Cloud.(Search: “Oracle EPM Cloud Groovy Calculation Guide”)
- Oracle EPM Cloud REST API GuideTechnical reference covering REST API endpoints, authentication, and sample integration calls for FCCS, Planning, PCMCS, and EDMCS.(Search: “Oracle EPM Cloud REST API Guide”)
- Oracle EPM Automate User GuideOfficial Oracle guide for using EPM Automate command-line utilities in automation and scripting.(Search: “Oracle EPM Automate User Guide”)
- Aultman, Joe – Thought Leadership and Groovy AutomationExpert articles, presentations, and discussion contributions on Groovy scripting and EPM automation.(Search: “Joe Aultman Oracle EPM Groovy”)
- Woman in EPM BlogCommunity-driven blog featuring step-by-step Groovy scripting examples, validation patterns, and real-world use cases across Oracle EPM Cloud products.(Search: “Woman in EPM Groovy scripting examples”)
- LearnHyperion BlogExpert blog offering practical Groovy code samples, troubleshooting tips, and performance optimization strategies for Oracle EPM.(Search: “LearnHyperion Groovy EPM examples”)
<!– wp:social-links –><ul class=”wp-block-social-links”><!– wp:social-link {“url”:”https://gravatar.com/hamidanthro”,”service”:”gravatar”,”rel”:”me”} /–></ul><!– /wp:social-links –>