Introduction

This 25-minute tutorial shows you how to create a Groovy template with interactive Design Time Prompts (DTPs)

Background

Similar to working with Calculation Scripts, you can create Groovy-based script templates for reusability and maintenance purposes. Templates also enable you to add Design Time Prompts (DTPs) to create interactive wizards for your users.

Prerequisites

Cloud EPM Hands-on Tutorials may require you to import a snapshot into your Cloud EPM Enterprise Service instance. Before you can import a tutorial snapshot, you must request another Cloud EPM Enterprise Service instance or remove your current application and business process. The tutorial snapshot will not import over your existing application or business process, nor will it automatically replace or restore the application or business process you are currently working with.

Before starting this tutorial, you must:

  • Have Service Administrator access to a Cloud EPM Enterprise Service instance.
  • Upload and import this snapshot into your Planning instance. If you've previously uploaded the snapshot for another Groovy tutorial, you can continue using the same snapshot.

Note:

If you run into migration errors importing the snapshot, re-run the migration excluding the HSS-Shared Services component, as well as the Security and User Preferences artifacts in the Core component. For more information on uploading and importing snapshots, refer to the Administering Migration for Oracle Enterprise Performance Management Cloud documentation.

Tip:

The scripts you need for this tutorial are linked as text files within each section.

Creating a Groovy template to calculate employee bonuses

In this section, you'll create a Groovy template that calculates employee bonuses when an employee's salary has been updated. The template will prompt for a bonus multiplier to use during the calculation. You'll work with the predefined ManageEmployees form, which has been set up to capture employee information such as their Grade, Salary, Bonus, Phone, Email, and Reporting Manager.

Manage Employees
  1. Open Calculation Manager and create a template named GT_Calculate Employee Bonuses in the Plan2 cube.
    2. New Template
  2. In the Template Editor, change the Designer option to Edit Script and set the Script Type to Groovy Script.
    Rule Editor Options
  3. Select the Design Time Prompt tab.
  4. Click Insert Row (Insert Row) to add a DTP. Select Insert Row at End.
  5. Define the prompt with the following values:
    Option Value
    Name BonusMultiplier
    Type Integer
    Prompt it? Selected
    Mandatory? Selected
    DTP Text Enter a value between 0 and 8
    6. Create Prompt - Bonus Multiplier
  6. On the toolbar, click Insert Row (Create/Edit Wizard) to open the Template Wizard Designer.
  7. Click Add Step (Add Step). For the Name, enter Enter a Bonus Multiplier, then click OK.
    8. Template Wizard Designer with BonusMultiplier added to Selected DTPs dialogue
  8. Add the BonusMultiplier DTP to the Selected DTPs list, then click OK.
    9. Template Wizard Designer with BonusMultiplier added to Selected DTPs

    Note:

    For more complicated user input situations, you can create multiple wizard steps and choose which DTPs to present on each step.
  9. Select the Template Designer tab again. Copy this script and paste it into the editor.
    10. /*RTPS: {BonusMultiplier} */ 1
def BonusMultiplier = rtps.BonusMultiplier;
def mbUs = messageBundle(["validation.invalidbonusmultiplier":
	"Bonus multiplier must be between 0 and 8: {0}"])
def mbl = messageBundleLoader(["en" : mbUs]); 

//Validate the RTP values 2
validateRtp(rtps.BonusMultiplier, {(0..8).contains(it.enteredValue as int) }, mbl,
	"validation.invalidbonusmultiplier", rtps.BonusMultiplier);

// Capture the edited employees 3
Set employees = []  

operation.grid.dataCellIterator("Salary").each { DataCell cell ->
       if(cell.edited) {
       	employees << cell.getMemberName("Employee")
       }
    }

if(employees.size() == 0) { 4 
    println("No employee's bonus has been updated")
    return
}

// Generate the calc script to calculate bonuses for the employees 
whose salaries were edited 5
List povMemberNames = operation.grid.pov*.essbaseMbrName  
String calcScript = """  
Fix("${povMemberNames.join('", "')}", "${employees.join('", "')}")
	"Bonus" = "Salary" * (${BonusMultiplier}/100);
EndFix;"""  

println("The following calc script was executed by $operation.user.fullName: \n $calcScript")  
return calcScript.toString()

    1 Define the run time prompts and variables used by this rule.

    2 Check if the value entered for BonusMultiplier is between 0 and 8. If not, veto the operation.

    3 Use a dataCellIterator to iterator over the grid and capture the edited employees in the form.

    4 If no employees have been edited, return a message and exit the script.

    5 Generate the calculation script to calculate bonuses for edited salaries.

  10. On the toolbar, click Save (Save) to save the script.
  11. Click Validate and Deploy (Validate and Deploy).
  12. Click OK when prompted, then close Calculation Manager.

Adding templates to forms

In this section, you add your Groovy template to the ManageEmployees form so that it runs automatically when the form is saved.

  1. From the home page, navigate to Forms (located under Create and Manage) and edit the ManageEmployees form.
  2. On the Business Rules tab, associate the GT - Calculate Employee Bonuses template to be run After Save. Save the form and close the Form Manager window.
    3. Manage Employees form with Groovy template added

Testing the Groovy template

In this step, you test your template in the ManageEmployees form.

  1. From the home page, click Data to display data entry forms. Click ManageEmployees to open the form.
  2. For Employee 1, enter a salary of 40000, then click Save. The prompt to enter a bonus percent multiplier is displayed.
    3. Prompt page for entering a bonus multiplier
  3. To check the data validation, enter 9 and click Launch. The validation error message is displayed.
    4. Validation error message for entering a bonus multiplier
  4. Click OK to close the error message. Enter 5, then click Launch.
  5. The Salary information is saved, and the employee bonus is calculated as 5% of the entered salary.
    6. ManageEmployees form after calculation
  6. To see the calculation script that was generated, close the data entry form and navigate to Jobs. Notice that there are two entries in the Recent Activity list for the calculation: the completed calculation, and the error condition from entering an invalid multiplier.
    7. Recent Activity list in Jobs
  7. Click the first entry in the list, then click the Completed link to view the executed calculation script. Notice that the calculation is limited to Employee 1, the edited employee, and the entered bonus multiplier, 5, appears in the Bonus calculation.
    8. Calculation script created by the Groovy template
  8. Close the Job Details, and click on the second entry in the list. Click the Error link to view the error message. Notice that the validation error message is printed here, along with the invalid entry (9).
    9. Error message created by the Groovy template