Saturday, May 26, 2012

Assigning bulk users to groups in - using command line utility

In my previous post I discussed the steps to assign multiple users to groups in one go using the Life Cycle Management available under shared services. Being an administrator, I would still like to have some automated way to avoid performing all these steps every time I need to assign users. It eventually led to writing this post.

Step 4 : Migration definition XML
We need to perform the first three steps defined in the previous post, but this will be a one time activity to export group information and obtain the folder structure at 'Base path' (I will come to defining base path later in this post). While performing step 4 for the first time, save the migration definition before launching it. This file gets downloaded as an XML file and the contents of the same are as shown below.

The file has a tag <Options> which defines the operation to be performed during the import. It has the same value which we choose during the 'Import Operation Type'  - Create/Update, Create, Update, Delete.

We will be creating two such files and save them as 'ImportCreate' and 'ImportDelete' to signify the operation they perform.

Life Cycle Management also comes as a command line utility to initiate LCM. This utility is placed under <Installation drive>:\Oracle\Middleware\user_projects\epmsystem1\bin. This utility can be executed from any command line interface in Windows (Utility.bat) or Unix (Utility.sh). The documentation for the same is available on Oracle website.
The syntax for executing the utility is:
Utility.bat <migration definition XML> -b <base path>

Migration definition XML : The XML file saved during the Migration definition XML step
Base Path: The file system path where all exports & imports are stored. The utility provides the ability to move the exported folder to any other location and define that path as base path. Make sure the new path does not have spaces or special characters in its name.

Let us first try removing few users from the group 'GrpCtrl'. We enter 'E001', 'E002' in the 'Groups.csv' and execute the utility. Moreover we move the GroupExport folder and the xml files to C:\ to provide an easy file location.

Utility.bat C:\ImportDelete.xml -b C:\

On executing the utility with a fresh xml file, the utility asks for user name and password.

One thing to observe is that the ImportDelete.xml gets updated with this username and encrypted password which was initially not present in the file.

Lets check the group properties. We find E001 and E002 are no longer part of GrpCtrl.

Now lets add few users to a different group 'GrpEast'. We enter 'E004', 'E006' in the 'Groups.csv' and execute the utility.

Utility.bat C:\ImportCreate.xml -b C:\

On checking the properties, we see the users get added to 'GrpEast' while they still exist to be part of 'GrpCtrl'.

Its done !!! 
We can further automate this process by saving this command as a .bat file and pass the XML as parameter to perform desired operation. Let me know your comments.

Monday, May 21, 2012

Assigning bulk users to groups in

During every implementation of Oracle EPM system, administrators come across the task to assign a long list of users to corresponding Hyperion groups. It is a pretty easy job if we have a handful of users, but one of the cumbersome tasks if the the list is long. 

Celvin described creating users in bulk in his blog post, so I am not going to reiterate the same. This post is more of an extension to it, where we need to assign users from a directory to groups.

In this post, we will discuss a method to assign multiple users to corresponding groups in one go.

Step 1: Assign a 'TestUser' to any of the existing groups

Step 2: Use LCM to export group definition
Navigate to shared services and expand 'Application Groups'. Further expand 'Foundation' and select 'Shared Services'. This opens a list of artifacts on the right. Select 'Groups' and click on 'Define Migration'.

It opens the 'Migration Wizard'. We need to define migration to export groups information to file. In the 'Source Option' leaving the 'Native Group Filter' value as * (asterisk) means we need to export information about all groups. If we desire to export information about single group, we can provide group name.

Select 'Next'. Provide a folder name where group information will get stored. This folder gets created at the following location 
<Installation drive>:\Oracle\Middleware\user_projects\epmsystem1\import_export\<username>@<DirectoryName>\<folder name>

 Select 'Next' and confirm summary.

On summary page 'Execute Migration' to export information.

Click 'Launch Migration Status Report' to check the status as completed.

Navigate to the folder location <Installation drive>:\Oracle\Middleware\user_projects\epmsystem1\import_export\<username>@<DirectoryName>\<folder name> . In this case, we used 'admin' user to export group details, thus the path is C:\Oracle\Middleware\user_projects\epmsystem1\import_export\admin@Native Directory\GroupExport. Within this folder we have sub folders as shown below

Step 3: Update file to add users
Navigate to 'Native Directory' and find a file name 'Groups.csv'. Rather than opening the file in excel (default double click), open the file in a textpad editor. The file looks as shown below. The upper section with section header #group contains definition of the groups while lower section with section header #group_children contains a list of users and the groups to which they are assigned. As we had only the TestUser assigned to the group GrpCtrl, we see one record for the same.

We need to deal with the lower section of the file. Since we need not modify any information about the groups, we can get rid of the upper section. The new file would look as shown below. Please Note: Always keep a backup copy of the file before making any changes. 

Lets add the list of new users and the corresponding group to which we want to assign them. All we need to update are three fields - id, user_id, user_provider. Everything else can be left blank. In this case, since I do not have any external active directory configured in my shared services, I will be using users created in Native Directory. If the users exist in external directory, we need to provide the external directory name in user_provider column and the users will be picked up from external directory. This is how the file will look like after update. We are assigning user E001 to E006 to group GrpCtrl. Make sure you do not change the name or location of the file.

Lets check how many users does GrpCtrl have before we run the update with this new file. It contains only 'TestUser' which we added manually to export group details.

Step 4: Using LCM to assign users to groups
To upload the new users to the group, open shared services and expand the 'File System' folder in the left menu. We will find an item created with the same name which we provided as folder name as our target to export migration. Select this folder. In this case, the folder name we provided was 'GroupExport', so we select it to open artifacts on the right.

Select 'Groups' and click on 'Define Migration' from bottom. It will launch the migration wizard. The source is the file system with the folder. Click 'Next' to move to next screen.

The destination is 'Foundation Shared Services'. Click 'Next'.

Select the import operation type. There are four options - Create/Update , Create, Update, Delete. We need to take care how we select the options - Create and Update. Create performs the operation of adding the users while Update performs the operation of addition and deletion. It add the users present in the groups.csv and deletes which are not present.

Confirm the source and destination. Click 'Execute Migration'.

Click 'Launch Migration Status Report' and check the status as completed.

On checking the group 'GrpCtrl', we find the new users 'E001' to 'E006' gets added to the group while 'TestUser' gets removed since we selected the option 'Create/Update' and 'TestUser' was not present in the groups.csv

This completes the process of assigning users to groups in one go. In coming posts, I will be discussing the process to automate the same.