Introduction

This 20-minute tutorial shows you how to create a Groovy script to work with Planning metadata, in this case, moving a member from one parent to another. The script includes RTPs to prompt users for input. You'll also learn how to create a right-click action menu with a menu item to call the script, and how to associate the action menu with a data form.

Background

The EPM object model in Groovy gives you tools to design interactive ways for users to work with metadata, such as adding new members, renaming existing members, moving members under new parents, updating other metadata properties, and so on. Including run time prompts, or RTPs, in your Groovy scripts lets you prompt users for relevant values during these operations.

The EPM object model provides utility methods to perform the following tasks:

  • Retrieve the object representations for the various types of RTPs such as Member, Members, DateAsNumber, Member Range, and so on
  • Validate RTP values and veto the rule execution if the provided values are not valid

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.

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.

Loading Planning Calculation Variables

In this section, you upload calculation variables from an XML file for use in the Groovy script.

  1. Right-click the link for HP4_Plan2_Variables.xml, and save the file to your local drive.
  2. From the Home page, navigate to Rules (under Create and Manage) to open Calculation Manager. In the System View, expand EPM Cloud > HP4. Right-click Plan2 and select Import.
  3. Under File Import Details, browse to select HP4_Plan2_Variables.xml from your local drive.
  4. Under Location Details, make the following selections:
    • Application Type: EPM Cloud
    • Application: HP4
    • Cube: Plan2
  5. Under Import Options, select Override Existing Objects.
    6. Import Variables
  6. Click Import. Review the import results (they may say Inserted or Update), and then click OK.
    7. Import Results
  7. Click Cancel to close the Import dialog box.

Creating a Groovy Script to Move Dimension Members

In this section, you implement a Groovy script to move an employee from one parent to another. We'll work with the predefined ManageEmployees form, which has been set up to capture employee information such as their Grade, Salary, Bonus, Phone, Email, Address, and Reporting Manager.

Manage Employees
  1. In Calculation Manager, create a rule named Groovy Move Employee for the Plan2 cube.
    2. New Rule
  2. In the Rule Editor, change the Designer option to Edit Script and set the Script Type to Groovy Script.
    3. Rule Editor Options
  3. Copy this script and paste it into the editor:
    4. /*RTPS: {Employee} {NewParent}*/  1 
def employee = rtps.Employee.member  2
def newParent = rtps.NewParent.member  3
employee.dimension.saveMember(["Member" : employee.name, "Parent" : newParent.name] 
	as Map‹String, Object›) 4

    Description Define all the run time prompts used by this rule on the first line.

    Description Get the Member object for the employee specified by the Employee run time prompt. The code rtps.Employee returns a RtpValue object for the Employee run time prompt, whereas rtps.Employee.member instructs the RtpValue object to return a Member object, which is what is required here.

    Description Get the Member object for the new parent specified by the NewParent run time prompt. The code rtps.NewParent returns a RtpValue object for the NewParent run time prompt, whereas rtps.NewParent.member instructs the RtpValue object to return a Member object, which is what is required here.

    Description Save the employee under the new parent. The code employee.dimension instructs the employee Member to return its Dimension object. So the full statement employee.dimension.saveMember() instructs the Dimension object to save the member with the specified property values, in this case the new parent.

    Note:

    This is a privileged method and will throw an exception if called by a user that does not have administrator privileges.
  4. On the toolbar, click Save (Save) to save the script.
  5. Click Validate and Deploy (Validate and Deploy). Enter RTP values for validation purposes, then click OK:
    • Employee: "Employee 3"
    • NewParent: "Employee 1"

    Note:

    During this step, the rule is not executed; however, you must enter valid members for the validation process to succeed.
  6. Click OK when prompted, then close Calculation Manager.

Creating Planning action menus to run Groovy scripts

In this section, you create an action menu called Manage Employees, with a right-click action menu item that runs the Groovy script.

  1. From the Home page, navigate to Action Menus (located under Create and Manage) and create an action menu named Manage Employees.
    2. Create Manage Employees Action Menu
  2. Edit the Manage Employees action menu and add a child menu item named Move Employee. Enter or select the following options to define the menu item:
    Option Field Value to Enter or Select
    Menu Item Move Employee
    Label Move Employee
    Type Business Rule
    Required Parameters Employee
    Cube Plan2
    Business Rule Groovy Move Employee
    3. Completed Move Employee Menu Item
  3. Click Save, then click OK to save the menu item. Finally, click Save again to save the action menu.
    4. Completed Manage Employees Action Menu

Associating Planning Action Menus with Forms and Testing Groovy Scripts

In this step, you associate the action menu with the ManageEmployees form and test your script.

  1. Navigate to Forms (located under Create and Manage) and edit the ManageEmployees form.
    2. Edit Manage Employees Form
  2. On the Other Options tab, add the Manage Employees context menu to the Selected Menus list.
    3. Add the Manage Employees Context Menu
  3. Click Finish to save changes to the form.
  4. Close the Form Manager and return to the Home page.
  5. Click Data to display the list of data entry forms, then click ManageEmployees to open the Manage Employees form.
    6. List of Data Entry Forms
  6. To test the Groovy script, move Employee 3 to be a child of Employee 1:
    1. Right-click Employee 3 to display the context menu, and select Move Employee.
    2. Verify that "Employee 3" is selected for the Select Employee prompt.
    3. For the Employee New Parent prompt, enter "Part Time Employees".
    4. Click Launch.

    7. Upon successful completion, Employee 3 is moved to the Part Time Employees parent.

    Completed Move of Employee 3

  7. Now, reverse the move:
    1. Right-click Employee 3, and select Move Employee.
    2. Verify that "Employee 3" is selected for the Select Employee prompt.
    3. For the Employee New Parent prompt, enter "Full Time Employees".
    4. Click Launch.

    Employee 3 is moved back to the Full Time Employees parent.

    Reversed Move of Employee 3

    Note:

    After executing this rule, you need to perform a cube refresh so that aggregations properly reflect the new hierarchies.

Next Tutorial

Adding Dimension Members with Groovy