26Migrating Role Associations for Analytics Folders
Migrating Role Associations for Analytics Folders
This chapter describes how to migrate the associations between roles and analytics folders using the command-line interface of 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.
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 |
---|---|
|
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. |
|
This command extracts the details of all analytics folders and their role associations. |
|
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
andReadAll
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:
|
<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:
|
<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.
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"
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.
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"
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\windows\repository\ReportFolder\MyFolder.xml"