Migrating Role Associations for Analytics Folders

This chapter describes how to migrate the associations between roles and analytics folders using the Oracle Migration Tool On Demand client. It contains the following topics:

Role Associations for Analytics Folders

Users can store the analyses and dashboards that they create in folders. Folders can be created in a user’s personal area in Oracle CRM On Demand and in the company wide shared folders in Oracle CRM On Demand, including the Company Wide Shared Folder and the Migrated Company Wide Shared Folder. The Company Wide Shared Folder contains a predefined Dashboards folder, under which users can create subfolders for storing dashboards.

Analyses and dashboards that are stored in a user’s personal area are available only to that user. Analyses that are saved in the Company Wide Shared Folder and the Migrated Company Wide Shared Folder are available to all users by default, and dashboards that are stored in folders under the predefined Dashboards folder are available to all users by default.

However, you can limit access to the contents of subfolders in the company wide shared folders, including the subfolders in the predefined Dashboards folder, by associating roles with the subfolders. After you associate one or more roles with a folder, only users with those roles can access that folder. If no role is associated with a folder, then all users have access to the folder by default. A subfolder automatically inherits the role associations of its parent folder, but you can change the role associations for the subfolder. For more information about setting up analytics folders, see Oracle CRM On Demand Online Help.

Note: You cannot associate roles with the Dashboards subfolder under the Company Wide Shared Folder, but you can associate roles with the subfolders under the Dashboards folder.

You can use the Oracle Migration Tool On Demand client to extract and update the associations between roles and existing folders in the company wide shared folders. However, you cannot use the Oracle Migration Tool On Demand client to create analytics folders or subfolders.

The following table describes the Oracle Migration Tool On Demand client commands used with role associations for analytics folders. These commands are case sensitive.

Table Commands Used with Role Associations for Analytics Folders in Oracle Migration Tool On Demand

Command Description

Command	Description
`Read ReportFolder FolderPath`	This command extracts the details of a specified folder and its role associations. The FolderPath parameter must specify the full path for the folder, including the string for the root folder. For the folders in the Company Wide Shared Folder, the root folder is: /shared/Company Analyses For the folders in the Migrated Company Wide Shared Folder, the root folder is: /shared/Migrated Company Analyses The extracted information includes the name of the folder’s parent folder and the names of any subfolders.
`ReadAll ReportFolder`	This command extracts the details of all analytics folders and their role associations.
`Upsert ReportFolder ReportFolderXML`	This command updates or inserts role associations for an analytics folder. Note: You can use the `Upsert` command only to add role associations for existing folders, and to set the access level for the roles. You cannot use the `Upsert` command to remove role associations from folders or to create new folders or subfolders.

Read ReportFolder FolderPath

This command extracts the details of a specified folder and its role associations. The FolderPath parameter must specify the full path for the folder, including the string for the root folder. For the folders in the Company Wide Shared Folder, the root folder is:

/shared/Company Analyses

For the folders in the Migrated Company Wide Shared Folder, the root folder is:

/shared/Migrated Company Analyses

The extracted information includes the name of the folder’s parent folder and the names of any subfolders.

ReadAll ReportFolder

This command extracts the details of all analytics folders and their role associations.

Upsert ReportFolder ReportFolderXML

This command updates or inserts role associations for an analytics folder.

Note: You can use the Upsert command only to add role associations for existing folders, and to set the access level for the roles. You cannot use the Upsert command to remove role associations from folders or to create new folders or subfolders.

Privileges Required for Migrating Role Associations for Analytics Folders

The following privileges are required for the user account running the Oracle Migration Tool On Demand client commands:

For the Read and ReadAll commands: Enable Web Services Access, Manage Roles and Access, Manage Custom Reports (to extract role associations for folders containing analyses), and Manage Dashboards (to extract role associations for folders under the predefined Dashboards folder). In addition, to extract role associations for the folders in the Migrated Company Wide Shared Folder, the Access Migrated Company Wide Shared Folder privilege is required.
For the Upsert command: Enable Web Services Access, Manage Roles and Access, Manage Custom Reports (to update or insert role associations for folders containing analyses), and Manage Dashboards (to update or insert role associations for folders under the predefined Dashboards folder). In addition, to update or insert role associations for the folders in the Migrated Company Wide Shared Folder, the Access Migrated Company Wide Shared Folder privilege is required.

For information about setting and checking privileges, see Oracle CRM On Demand Online Help.

Elements and Sections in the Role Associations for Analytics XML Output File

The following table describes the elements and sections in the role associations for analytics folders XML output file.

Table Elements and Sections in the Role Associations for Analytics Folders XML File

Description	Element or Section
The <ReportFolder> section contains all of the information for a single folder and its subfolders.	<data:ReportFolder> . . . </data:ReportFolder>
<Catalog> contains the catalog version for the folder. The valid value is V3. Note: When you insert or update the role associations for a folder, you must either set the <Catalog> element to V3 or leave it empty. If you leave the element empty, then V3 is used by default.	<data:ReportFolder> <data:Catalog>V3</data:Catalog> . . . </data:ReportFolder>
<Path> contains the path for the folder.	<data:ReportFolder> . . <data:Path>/shared/Company Analyses/ Test Folder</data:Path> . . . </data:ReportFolder>
<FolderName> contains the name of the folder.	<data:ReportFolder> . . . <data:FolderName>Test Folder </data:FolderName> . . . </data:ReportFolder>
<Description> contains the description of the folder, if a description exists.	<data:ReportFolder> . . . <data:Description>This is my test folder</data:Description> . . . </data:ReportFolder>
<ParentFolder> contains the name of the parent folder. If the folder is created directly in the company wide shared folder, then the name of the parent folder is Company Analyses.	<data:ReportFolder> . . . <data:ParentFolder>Company Analyses </data:ParentFolder> . . . </data:ReportFolder>
The <ListOfSubFolders> section contains details of the subfolders under the current folder, if any exist.	<data:ReportFolder> . . . <data:ListOfSubFolders> . . . </data:ListOfSubFolders> . . . </data:ReportFolder>
The <SubFolder> section contains details of one subfolder. It includes the following elements: <Catalog> contains the catalog version for the subfolder. <Path> contains the path to the subfolder. <FolderName> contains the name of the subfolder. <Description> contains a description of the subfolder.	<data:ReportFolder> . . . <data:ListOfSubFolders> <data:SubFolder> <data:Catalog>V3</data:Catalog> <data:Path>/shared/Company Analyses/ Test Folder/Test Folder A</data:Path> <data:FolderName>Test Folder A </data:FolderName> <data:Description/> </data:SubFolder> . . . </data:ListOfSubFolders> . . . </data:ReportFolder>
The <ListOfAssociatedRoles> section contains details of the role associations for the folder.	<data:ReportFolder> . . . <data:ListOfAssociatedRoles> . . . </data:ListOfAssociatedRoles> </data:ReportFolder>
The <AssociatedRole> section contains details of a single role association, including the following: <RoleName> is the name of the role. <AccessLevel> is the level of access that is given to this role for this folder.	<data:ReportFolder> . . . <data:ListOfAssociatedRoles> <data:AssociatedRole> <data:RoleName>User Role2 </data:RoleName> <data:AccessLevel>Change/Delete </data:AccessLevel> </data:AssociatedRole> . . . </data:ListOfAssociatedRoles> </data:ReportFolder>

Migrating Role Associations for Analytics Folders

The following topics describe how to use the Oracle Migration Tool On Demand client to migrate role associations for analytics folders:

Extracting Role Associations for a Single Analytics Folder

This topic describes how to extract the role associations for a single analytics folder from the Oracle CRM On Demand server for your environment; that is, a customer test environment or production environment.

Syntax

The following is the syntax for using the Oracle Migration Tool On Demand client to extract the role associations for a single analytics folder:

migrationtool -u UserID -s ServerURL Read ReportFolder FolderPath

where:

UserID is the user sign-in ID that has the appropriate privileges to run the Oracle Migration Tool On Demand client commands.
ServerURL is the URL for the Oracle CRM On Demand server where your company resides.
FolderPath is the path for the folder for which you want to extract the role associations.

Note: The Oracle Migration Tool On Demand client requests your Oracle CRM On Demand password, which can be redirected (using the pipe command) to the client program from standard input; that is, from a file, from the command line, or from another program.

Example of Extracting Role Associations for a Single Analytics Folder

The following is an example of extracting the role associations for a single analytics folder. In this example, the folder named Test Folder A is a subfolder of the folder named Test Folder:

migrationtool -u UserID -s ServerURL Read ReportFolder "/shared/Company Analyses/Test Folder/Test Folder A"

Note: Quotation marks are always required for the folder path, because the path for the root folder (/shared/Company Analyses or /shared/Migrated Company Analyses) contains a space.

Extracting Role Associations for All Analytics Folders

This topic describes how to extract the role associations for all analytics folders from the Oracle CRM On Demand server for your environment; that is, a customer test environment or production environment.

Syntax

The following is the syntax for using the Oracle Migration Tool On Demand client to extract the role associations for all analytics folders:

migrationtool -u UserID -s ServerURL ReadAll ReportFolder

where:

UserID is the user sign-in ID that has the appropriate privileges to run the Oracle Migration Tool On Demand client commands.
ServerURL is the URL for the Oracle CRM On Demand server where your company resides.

Note: The Oracle Migration Tool On Demand client requests your Oracle CRM On Demand password, which can be redirected (using the pipe command) to the client program from standard input; that is, from a file, from the command line, or from another program.

Updating or Inserting Role Associations for Analytics Folders

This topic describes how to insert or update role associations for an analytics folder on your Oracle CRM On Demand environment (customer test environment or production).

About the Upsert Operation

The Upsert command inserts or updates role associations for analytics folders based on the following user keys:

<Path>
<Path> and <Catalog>

Note: The <Catalog> element must either be set to V3 or left empty. If you leave the <Catalog> element empty, then V3 is used by default.

Oracle CRM On Demand attempts to locate the folder specified in the input file based on the user key. If an existing folder that matches the value in the <Path> element is located, then the following happens:

If a role association that is specified in the input file already exists for that folder, and if the access level that is specified for the role in the input file is different from the existing access level for the role, then the role association is updated. Otherwise, the existing role association is left unchanged.
If a role association that is specified in the input file does not already exist for the folder, then the role association is inserted for the folder.
Any existing role associations for the folder that are not specified in the input file are left unchanged.

Syntax

The following is the syntax for using the Oracle Migration Tool On Demand client to insert or update role associations for an analytics folder:

migrationtool -u UserID -s ServerURL Upsert ReportFolder ReportFolderXML

where:

UserID is the user sign-in ID that has the appropriate privileges to run the Oracle Migration Tool On Demand client commands.
ServerURL is the URL for the Oracle CRM On Demand server where your company resides.
ReportFolderXML is the fully qualified path name of the XML file containing the role associations for the analytics folder, for example:
```
C:\My Files\Test Folder.xml
```
If the fully qualified path name contains any spaces, then it must be enclosed with quotation marks, for example:
```
migrationtool -u UserID -s ServerURL Upsert ReportFolder "C:\My Files\Test Folder.xml"
```

Note: The Oracle Migration Tool On Demand client requests your Oracle CRM On Demand password, which can be redirected (using the pipe command) to the client program from standard input; that is, from a file, from the command line, or from another program.

Example of Updating or Inserting Role Associations for an Analytics Folder

The following is an example of updating or inserting role associations for an analytics folder in your Oracle CRM On Demand server:

migrationtool -u UserID -s ServerURL Upsert ReportFolder "C:\Oracle Migration Tool On Demand\repository\ReportFolder\MyFolder.xml"

Note: Quotation marks are required only if the path or file name contains spaces.