Initial Setup of User Variables

One of the more annoying things about EPM Planning is the initial setup of User Variables. These variables are incredibly useful for forms and rules but can be a bit of a pain for new users. Until the new user goes into their User Preferences and selects User Variables, they will not be able to open any forms with the variables or run rules with the variables. A while back on another project, a colleague came up with a way to ease the pain for new users. He created a Groovy script that would do the initial setup.

I remembered this cool solution the other day when I was getting ready to introduce a group of new users to EPM Planning. I was putting together instructions for manually setting up all the variables and decided that it was time to use the Groovy way instead.

The first thing to do is create a basic form from which to launch the Groovy script. The only purpose of the form is to launch the rule, so it does not have to be complicated.

The POV has all the dimensions except for what is put in row and column. Select a member for each that all users have security access to.
The row dimension can be any member, I chose account and used a member that all users have access to.
Like the row, the column dimension can be any member as long as it is one that all users have access to.

Additionally, I added some instructions to the form.

Save the form, we will come back to it once we create the Groovy script.

From Calculation Manager, create a new rule as a Groovy script.

Create a string variable for the username.

Next is to map the User Variable with a default value. This will apply to any user except for a named user as noted with identifier 3.
We are including an extra mapping here to assign a different cost centre variable value for one user. This is not necessary, but we wanted to show it as an option. You could design the script to assign variables by specific users.

An important thing to point out with the mapping is that the left side of the mapping must use the system name of the variable and not the artifact label. For example, the out-of-box (OOB) variable for entity is “OEP_Entity”. Within the User Variable configuration, it displays as “Entity”, but the system name is “OEP_Entity”.

Next, we create string variables for the mapping.

The first line checks if the logged in user is one of the named users from item 3 above. If not, it uses the mapping for default user.
A println is added to list the variables being assigned.

Now we are ready to convert the mapping string to an object type and update the logged in users’ variables.

Converts userVarString entry back to Map object type.
Finishes the assignment of the mappings to the User Variables in EPM
A println to summarize the User Variable members.

There are certainly more details and explanations behind the Groovy coding, but I am trying to keep it simple.

Now let’s go back to the form we first created. Open the form to edit and attach the new rule. Enable the rule to Run After Save.

With the form created, we also want to make it easy for the users to find upon their first login to EPM. To do this, we are going to create a separate navigation flow card to add on the home page.

The card is on the home page and when selected, the form opens.

To test that the process is working as expected, we will clear several of the User Variables on our test user.

We return to the Initial Setup form and click Save.

Now back to the User Preferences and we see that the variables are populated with the members from the Groovy rule.

Lastly, we can check the Job Details to view the println messages we placed in the rule.

This process is very basic and will work for a lot of situations. It can be enhanced to have multiple Groovy rules based on the different user groups, that way each group would be prepopulated with the User Variables relevant to their needs. If you have multiple navigation flows, you could have different Initial Setup cards assigned based on the different Groovy rules.

As always, happy EPM’ng!

P.S. Many thanks to Kevin Whalen for creating the original script.

Here’s the full script for easy copying.

//Initial setup of User Variables
//Created: Mar 2023

String userName = operation.user.getName(); //get username for logged in user
println userName

/*** Set user variables based on username or default ****/
Map userVarMap = [
    1: [username:'default', 
    		'Cost Centre-COGs CCs':'ALT_Shipping', 
            'Cost Centre-Corp CC':'CC_09030', 
            'Entity-Corp Entity':'Corporate FPnA', 
            'Cost Centre-Cost Centre':'CC_09001', 
            'Cost Centre-OCOS CCs':'ALT_Other OCOS', 
            'Currency-OEP_Currency':'USD', 
            'Entity-OEP_Entity':'E_0103', 
            'Currency-OEP_Reporting Currency':'USD_Reporting', 
            'Scenario-OEP_Scenario':'OEP_Rolling Forecast',
			'Version-OEP_Version':'OEP_Working',
            'Years-OEP_Years':'FY22', 
            'Account-OFS_Expense Account':'WF_Operating Costs', 
            'Product Line-Product Line':'PL_SPF Default', 
            'Cost Centre-SGA Expense':'CC_09000' 
            ],
    2: [username:'plewis@interrel.com', 
			'Cost Centre-COGs CCs':'ALT_Maintenance']
]

String userVarString = userVarMap.find { it.value.username == userName }?.value // find a single entry for logged in user
	if (userVarString == null) {
		userVarString = userVarMap.find { it.value.username == 'default' }?.value // find default entry if user not found
    }

println "User Variables for $userVarString"

Map userMap=[:]
    userMap += userVarString.replaceAll('\\{|\\}', '').split(',').collectEntries { entry ->
        def pair = entry.split('=')
        [(pair.first().trim()): pair.last().trim()]
       } // convert userVarString entry back to Map object type

for (i in userMap) {
	if(i.key == 'username')
    continue
    String mapKey = i.key.toString()
    def dimPair = mapKey.split('-')
    def dimName = dimPair.first().trim()
    def userVar = dimPair.last().trim()
    String userVarValue = i.value.toString()

	Dimension appDim = operation.application.getDimension(dimName)
	UserVariable appUserVar = operation.application.getUserVariable(userVar)
    Member appUserVarMember = appDim.getMember(userVarValue)
    String status = operation.application.setUserVariableValue(appUserVar,appUserVarMember)
    
    println "User Variable set as Dimension: $dimName, User Variable: $userVar, User Variable Value: $userVarValue"
}