6 User Maintenance

User administration is the process by which administrators add or delete authorized system users, create or delete user groups, and edit user profiles. These tasks are performed through completion wizards on the User Administration tab.

The following procedures are discussed in this chapter:

Adding a User

Adding a User Group
Deleting a User
Deleting a User Group
Editing a User

These procedures can be performed through the RPAS Fusion Client by accessing the User Administration task in the Administration activity in the taskflow (Figure 6-1).

In addition, the usermgr utility is also described in this chapter. This utility allows you to manage users and users groups through a command line interface. For more information, see "Managing Users Using usermgr".

Once users and user groups are set up, access permissions to workbook templates and measures within workbooks can be assigned through Security Administration. Security Administration also supports modification of the label, default workbook template, and Admin status associated with individual users.

Note:

Users must be set up in the directory for the external authorization provider as well. The users must also exist here to define access to and within each RPAS solution.

User Administration Activity

To access the User Administration workbooks:

In the taskflow, click the Expand icon next to Administration. The Administration panel appears.
In the Administration panel, select User Administration for the solution you want to work on. The steps within the User Administration task appear.

Figure 6-1 User Administration

Adding a User

To add a user:

Under User Administration, click the Create New Workbook icon next to Add User. A Workbook Wizard window appears.
In the Workbook Wizard window, enter relevant information in the following fields:
- User name: Type the user name that the user uses for logging on.
  
  Note:
  Each user name must begin with a letter and contain only alphanumeric characters and underscores. It cannot have spaces. User names are case sensitive.
- User label: Type a label that describes the user (for example, the user's full name). This identifying label appears in various locations throughout the application. For example, labels appear on the File - Open dialog box to identify the owner of a given workbook and on some views to specify which user performed a task.
- Default group: Select the user group to which the user belongs.
- Other groups: If a user belongs to more than one group, select the additional groups from the list in the Other groups field.
Note:
Passwords are not used by the Fusion Client. The password is defined and managed by your external authentication provider.

If the user should have Admin status, check the Administrator box.

Note:

Administrator privilege enables users to access the Save Format option on the View menu, which creates new system-wide default styles for workbook templates.

Administrative users have special privileges and the read-only status may not apply to them.

If you are not sure whether a user should be granted this ability, you can modify the Admin status later in the Users view (in the User and Template Administration workbook).

Note:

Granting users Admin status gives them access to all workbook templates, but it does not automatically give them access to all workbooks.

Select the Lock user account check box to temporarily disable the user's account.
Click Finish to add the new user to the database.

Workbook template and measure access rights can now be assigned to the user. To do this, access the Security Administration workbook. For more information, see "Accessing Security Administration".

Adding a User Group

User groups provide an intermediate level of security to workbooks that were created and saved by specific users. When new users are assigned to the system, they must be assigned to existing user groups. User groups should consist of individuals with similar job functions or responsibilities. In the Oracle Retail Predictive Planning Suite, the user group corresponds to the user's planning role.

To add a user group:

Under User Administration, click the Create New Workbook icon next to Add User Group. A Workbook Wizard window appears.
In the Workbook Wizard window, enter relevant information in the following fields:
- In the Group Name field, type a name for the group.
  
  Note:
  Each group name must begin with a letter and contain only alphanumeric characters and underscores. It cannot have spaces. User group names are case sensitive.
- In the Group Label field, type a descriptive label for the group. This label is displayed when referring to the group throughout RPAS.
Click Finish to add the user group to the database.

Deleting a User

If a user profile is no longer needed, it should be deleted from the system in order to maintain system security.

To delete a user:

Under User Administration, click the Create New Workbook icon next to Delete User. A Workbook Wizard window appears.
The Workbook Wizard window appears and displays the user names and labels for all users. Select the name of the user to delete.
Click Finish to delete the user from the system.

Deleting a User Group

If a user group no longer exists, the group should be deleted from the system as soon as possible to maintain system security.

Caution:

Before you can delete a user group, all users must be removed from the group. For each user in the group, you must either delete the user or change the default user group assignment for the user.

To delete a user group:

Under User Administration, click the Create New Workbook icon next to Delete User Group. A Workbook Wizard window appears.
In the Workbook Wizard window, select the user group you want to delete.
Click Finish to delete the user group from the system.

Editing a User

To edit a user's profile:

Under User Administration, click the Create New Workbook icon next to Edit User. A Workbook Wizard window appears.
The Workbook Wizard window appears, displaying the user names and labels for all users. Select the user you want to edit and click Next.
Make the necessary changes to the user's profile. You can change anything except the User name. For more information on the fields, see "Adding a User".
Click Finish to save the changes.

Managing Users Using usermgr

Use the usermgr utility to add and remove users and groups, copy user and group information to other domains, edit user and group information, and convert that information from XML files to database files and vice versa.

With the usermgr utility, you can create both user and administrator accounts using the -addGroup command. This allows you to add many accounts at once.

To create users and groups, you must create a database file called users.db, which contains user and group information. Once you have created and imported the users.db file into RPAS, it contains all user, administrator, and group information. This file is an encrypted binary file that you cannot edit.

To edit any account information, you must convert the database file to an XML file using the -convertDbToXml command. This creates an editable XML file that contains all the information in the user.db file. Again, this is to ensure the security and safety of the account information. Once you edit the XML file with the changes you need to make, you must convert it back to a database file in order to import it into RPAS. To convert it, use the -convertXmlToDb command.

Once the users.db file is created, it can be shared across multiple domains. To automatically import the user, administrator, and group information every time a domain is created, place the users.db file in the rpasInstall input directory of the domain.

usermgr Usage

usermgr -d domainPath -add [userName] -label [label] -group [groupName] {-admin}
usermgr -d domainPath -addGroup [groupName] -label [label]
usermgr -d domainPath -remove [userName]
usermgr -d domainPath -removeLabel [label]
usermgr -d domainPath -removeGroup [groupName]
usermgr -d domainPath -list  
usermgr -d domainPath -listHashAlgs
usermgr -d domainPath -showHashSettings
usermgr -d domainPath -hashAlg [algorithmid]
usermgr -d domainPath -hashIter [iterations]
usermgr -d domainPath -forcePasswordChange {true|false} [-user username]
usermgr -d domainPath -changePassword [username]
usermgr -d domainPath -lock [userName]
usermgr -d domainPath -unlock [userName]           
usermgr -d domainPath -print -user [userName]
usermgr -d domainPath -print -group [groupName]
usermgr -d domainPath -importXml [path]
usermgr -d domainPath -exportXml [path]
usermgr -d domainPath -importDb {-replace}
usermgr -d domainPath -exportDb [path]
usermgr -convertXmlToDb -src [pathToXml] -dest [pathToDb]
usermgr -convertDbToXml -src [pathToDb] -dest [pathToXml]

Note:

-convertDbToXml, -convertXmlToDb, and -listHashAlgs do not require a domain.

Table 6-1 provides descriptions of the arguments used by the usermgr utility.

Table 6-1 Arguments Used by the usermgr Utility

Argument	Description
-d domainPath	Specifies the path to a domain to add, remove, or get information about a user.
-add userName	Adds a user with a specified name. Use the other arguments specified in the usage to add those attributes for that user. If -noPassword is specified, then this user can only be logged in via the Fusion Client. Otherwise, this command will prompt for a temporary password for use with the Classic Client only
-label label	Specifies the label of the user or group to add to the domain. Use this argument with -add and -addGroup.
-group grp	Specifies the user group of the user to add to the domain.
-admin	Specifies that the user to add to the domain has administrative rights.
-addGroup groupName	Adds a group with a specified name. Use -label to specify the label for the group.
-remove userName	Removes the user with the specified name from the domain.
-removeLabel label	Removes all users with this label.
-removeGroup groupName	Removes a group with this groupName.
-list	Lists all the users registered to the specified domain.
-listHashAlgs	Lists the different hashing algorithms supported in this release. The list will show an integer id, the details of the algorithm, and a status field indicating whether the algorithm has been deprecated 'X' or is the default '*'. This option is only used with the Classic Client.
-showHashSettings	Shows the selected hashing algorithm and the selectednumber of hash iterations. This option is only used with the Classic Client.
-hashAlg	The given algorithm ID parameter defines the algorithm to use for new users or users whom update their password. Use the string 'default' to always chose the default algorithm. This option is only used with the Classic Client.
-hashIter	The given iterations parameter is used to set the number of iterations the hash algorithm will used for new users or users whom update their password. This option is only used with the Classic Client.
-forcePasswordChange	The given boolean parameter either 'true' or 'false' determine the setting of the password must change variable. If 'true' then the next login will request the password to be updated. If the optional -user parameter is provided the effect of this value will only affect that user. This option is only used with the Classic Client.
-changePassword	For the given user application will prompt for the new password. This option is only used with the Classic Client.
-print	Use this argument to print the specified user or group information.
-user username	Specifies the user name in the specified domain to print. This argument is only applicable to the -print option.
-group groupname	Specifies the group in the specified domain name to print. This argument is only applicable to the -print option.
-importDb	Imports the database. The database must be located in the domain's input directory. The database is time stamped and moved to the processed directory upon successful completion. Existing user are skipped unless -replace is used.
-replace	Updates existing users when you are using -importDb. The user label, the groups that user belongs to, the admin status, and the account lock status are updated. Password information is not affected by the update.
`-lock` userName	Locks the specified user. This prevents the user from logging into the domain.
`-unlock` userName	Unlocks the specified user. This allows the user to log into the domain.
-importXml path	Add or update users from 'users.xml' placed in the input directory of the domain. By default, existing users are ignored. However, if the -replace option is selected, their information (excluding password) are replaced. If -noPassword is used, then any new users added can only log in via the Fusion Client. Otherwise, this command will prompt for temporary passwords for admin and non-admin users.
-exportXml path	Creates an XML file that contains all users and groups in the selected domain. Passwords and password histories are not exported.
-importDb path	Add or update users from 'users.db' placed in the input directory of the domain. By default, existing users are ignored. However, if the -replace option is selected, their information (excluding password) are replaced.
-exportDb path	Creates a database that contains all users and groups in the selected domain. This prompts you for new temporary passwords for admin and user accounts.
-convertDbToXml	Converts a user database to a user XML file. Passwords are not included in the conversion.
-convertXmlToDb	Converts a user XML file to a user database. This prompts you for temporary passwords for admin and user accounts.
-src path	Specifies the source file that is used in the arguments -convertDbToXml and -convertXmlToDb.
-dest path	Specifies the destination file that is used in the arguments -convertDbToXml and -convertXmlToDb.

Note:

The arguments userName and groupName must conform to the standards for position names in RPAS. They may contain only the characters a-z, A-z, 0-9, _, &, $ or %. User and group names cannot begin with an underscore. Any supplied upper case letters will be converted to lower case by the application. User and group names cannot be an empty string.

XML Schema

The XML schema contains information for all groups and users that are imported into the domain. Since this file can be edited, it does not contain any password information. Each group and user contains an XML attribute with the group or user name as well as the following inner tags:

Table 6-2 XML Schema

Outer Tag	Inner Tag	Description
GROUP	LABEL	The group's label.
USER	LABEL	The user's label.
USER	DFLT_GRP	The user's default group.
USER	OTHER_GRPS	A comma-separated list that contains all other groups that the user is associated with.
USER	ADMIN	If this value contains T, this user is an admin.
USER	LOCKED	If this value contains T, the user is locked when the file is imported.

Note:

All XML tags must be in all caps.

Additionally, the schema for users.xml has been updated. The 14.0 version of usermgr will accept either schema, but only outputs the new version.

Here is a sample users.xml file.

<?xml version=”1.0” ?>
<VERSION>1.0</VERSION>
<USER_LIST version="2.0">
<GROUPS>
             <GROUP NAME=”grp1”>
          <LABEL>Administrators</LABEL>
     </GROUP>
     <GROUP NAME=”grp1”>
          <LABEL>Group 1</LABEL>
     <?GROUP>
     <GROUP NAME=”grp2”>
          <LABEL>Group 2</LABEL>
     </GROUP>
     <GROUP NAME=”grp3”>
          <LABEL>Group 3</LABEL>
     </GROUP>
</GROUPS>
<USERS>
     <USER NAME=”adm1”>
          <LABEL>admin 1</LABEL>
          <DFLT_GRP>adms</DFLT_GRP>
          <ADMIN>T</ADMIN>
     </USER>
     <USER NAME>=”adm2”>
          <LABEL>admin 2</LABEL>
          <DFLT_GRP>adms</DFLT_GRP>
          <ADMIN>T</ADMIN>
          <LOCKED>T</LOCKED>
     </USER>
     <USER NAME=”usr1”>
          <LABEL>user_1</LABEL>
          <DFLT_GRP>grp1</DFLT_GRP>
          <OTHER_GRPS>grp2</OTHER_GRPS>
     </USER>
     <USER NAME=”usr2”>
          <LABEL>user_2</LABEL>
          <DFLT_GRP>grp2</DFLT_GRP>
          <OTHER_GRPS>grp1,grp3</OTHER_GRPS>
     </USER>
     <USER NAME=”usr3”>
          <LABEL>user_3</LABEL>
          <DFLT_GRP>grp1</DFLT_GRP>
          <OTHER_GRPS>grp1</OTHER_GRPS>
     </USER>
</USERS>
</USER_LIST>

Use Cases

Here is a list of common use cases for the XML and database files.

Exporting from an Existing Domain

You can export from an existing domain using -exportDb or -exportXml. Exporting is useful for sharing users with another domain or for creating backups.

Use -exportXml if you need to edit the users or groups. This can be used when you are making bulk updates that apply to many users or groups. Once you have made changes to the file, you must convert it back to a database by using -convertXmlToDb and then import the updated file using -importDb -replace.

Use -exportDb if you do not need to edit the users or groups. This method produces a binary file that is ready for import.

Importing into a Domain

You can import existing users.db by using -importDb. Importing is useful for bulk insertion or updates of users and groups.

By default, existing users and groups are skipped. However, if -replace is used, existing users are updated with the following information: user label, groups that the users belong to, admin status, and account lock status. Group labels are updated for existing groups.

Password information for existing users is not affected by the update. New users receive temporary passwords that are stored in users.db.

Note that new users may not be created if the following conditions exist:

A group already exists with the user name.
The user's default group does not exist.

New groups are skipped if the following conditions exist:

A user already exists with the group name.

Note:

If a users.db is placed inside the rpasInstall input folder, the users within that file are automatically imported upon domain creation.

Converting Between XML and Database

Since only users.xml can be edited and only users.db can be imported, it is necessary to convert between the two formats when you need to edit and import users and groups. For example, if you are creating users for the first time, you must first create an XML file for those users. Then you must convert that XML file to a database file using -convertXmlToDb in order import the file. If you have an existing users.db that you need to edit, convert it to xml using -convertDbToXml.

When converting from an XML to a database file, the following validation rules apply:

The file must be a properly formatted XML file; otherwise, the operation fails.
Groups and users without a NAME attribute are skipped.
Duplicate groups and users are skipped. Duplicate groups and users are those that share the same NAME attribute as an existing group or user within the same XML file. For instance, a new group called Sales cannot be created if a user or group named Sales already exists.
Users without a DFLT_GRP field are skipped.

Note:

If a user or group is skipped, a warning is logged. Since warnings are not included in the default log level, you should run this utility with warnings visible.