Importsecurity: Planning Command Utility operation
Updated: 2010-01-11
Use the importsecurity command to import users and roles, apply users to specific roles, and set custom security on roles. The functionality is intended to provide a scriptable way to set the security settings that exist in Planning Business Modeler. All definitions for users and roles are defined in a separate CSV file for the specific operation type.
Note
You must be a member of the UA role to use this command.
Syntax
ppscmd importsecurity [switches] file [files]
Note
If the application and the model site have same label, use the following syntax: application_label.model site_label.
Command switches
Parameters
| Parameter | Required? | Description |
|---|---|---|
/server <ServerUri> |
No |
Specifies the server URI to connect to. The default is the Modeler default server. |
/application <AppLevel> |
No |
Specifies the application to open. The default is the Modeler default application. |
/site <SiteLabel> |
No |
Specifies the Model site to open. The default is the Modeler default site. |
/type <ObjType> |
Yes |
Specifies the type of file contents to import. ObjType can be one of the following: User – adds system users; UserPermission – adds user permissions (same as in the UI – BizModeler: Read, Read+Write, Write) to dimensions members; UserRoleAssociation – adds users to roles (same as in the UI); ModelRolePermission – set the Model ON/OFF for a certain Role; Role – add Business Roles to Applications (same as in the UI); RolePermission – adds role permissions (same as in the UI – BizModeler: Read, Read+Write, Write) to dimensions members |
/encoding <FileEncoding> |
No |
Specifies file encoding for the CSV file. The default is UTF8. FileEncoding can be: ISO-8859, UTF8, UNICODE, or ASCII. Use ISO-8859 for 8-bit character encoding. |
Note
The /application and /site parameters are available with Planning Business Modeler Service Pack 3.
Flags
The following flags provide additional instructions to the server when used with the importsecurity command.
Important
The QFE26 update for Microsoft Office PerformancePoint Server 2007 Service Pack 3 (SP3) is required in order to use the importsecurity command with the /Replace flag. To download and install Microsoft Office PerformancePoint Server 2007 QFE26 (KB978617) you must contact Microsoft Customer Support Services.
| Flag | Description |
|---|---|
/Override |
Overrides the existing object when importing a CSV file. |
/IgnoreExtraColumns |
Ignores extra columns in the CSV file. |
/Replace |
Replaces the existing object when importing a CSV file. Any objects in the CSV file that are not specified are removed. |
Note
The /Replace flag is available with Planning Business Modeler SP3.
Return value
None
Examples
The following command-line examples show the use of the importsecurity command.
ppscmd importsecurity /type user users.csv
ppscmd importsecurity /type role /encoding iso-8859 roles.csv
ppscmd importsecurity /type userrole /encoding iso-8859 userroles.csv
ppscmd importsecurity /type modelroleassociation modelroles.csv
ppscmd importsecurity /type rolepermission /app testapp /site testappsite rolepermissions.csv
ppscmd importsecurity /type userpermission userpermissions.csv
Requirements
The CSV file format for all Import Security types is described in the following sections.
Roles
The Role option for the importsecurity command defines custom roles for model sites. If the role already exists, the importsecurity operation will ignore the role and continue processing the rest of the CSV file. The CSV file must contain first column headers followed by the roles you are defining.
The column headers and definitions are shown in the following table.
| Column header | Definition |
|---|---|
Label |
The Role label |
Name |
The user-friendly name of the role |
Description |
Description of the role |
Application |
The application for which the role is defined |
DefaultSecurity |
The security settings for the role. The valid values correspond to the Modeler security settings. The options are: No Access, Read-Only, and Read + Write. |
Scope |
The Model Site label for the role |
Note
There is a white space character before and after the plus sign in "Read + Write". These spaces are required.
Example:
The following example table uses an application named testapp. The testapp application has role1 (contains multiple users) and role2 (empty and contains no users). The sample CSV file that is used for importsecurity has only role3 and role4 available. If the following sample command is run, D:\Program Files\Microsoft Office PerformancePoint Server\3.0\BizModeler>PPSCmd ImportSecurity /app testapp/ser http://<servername>:<port#>/replace/type role, then role2 is deleted, and both role3 and role4 are added. This sample command does not delete role1 because there are current users assigned to this role.
| Label | Name | Description | Application | DefaultSecurity | Scope |
|---|---|---|---|---|---|
CustomRole |
My Custom Role |
Some text |
BizCorp |
Read-Only |
Corporate |
Users
Importing a user CSV file with the /type parameter set as ‘User’ will add users to the PerformancePoint Planning system. It will add only new users and skip any users that are already in the system. You cannot delete existing users by using this operation; you can only add/update new users.
A CSV file must be created with the header columns of Label, Name, and Email. Associated users are added but giving their label, name, and e-mail address.
The column headers are described in the following table.
| Column header | Description |
|---|---|
Label |
Required. The domain and user name of the user. |
Name |
Required. The name of the user. |
Optional. The e-mail address of the user. |
Example:
| Label | Name | |
|---|---|---|
DOMAIN\USER1 |
User1 |
user1@domain.com |
DOMAIN\USER2 |
User2 |
user2@domain.com |
DOMAIN\USER3 |
User3 |
user3@domain.com |
User roles
The UserRoles import option associates defined system users with roles in the system. You can assign existing users to system roles and any custom roles defined in an application. Users and roles must be already in the system. If they are not, the importsecurity operation will display an error and continue processing the CSV file.
User roles are described in the following table.
User |
This is the user to associate with the role. The user must be defined in the system. |
Role |
This is the role. The role can be one of the four system roles: global administrator, user administrator, data administrator, or modeler, or it can be any custom-defined role in a model site. In the following example, User5 is using the custom-defined role “BusinessUsers”. |
Application |
This is the application for the role. Global administrator roles are for all system applications, so no application is defined for a global administrator. |
Scope |
This can be application or model site level for user administrator, data administrator, or modeler. The global administrator does not need a scope defined. For custom roles, the scope will be the model site that the role is defined for. |
Example:
| User | Role | Application | Scope |
|---|---|---|---|
Domain\User1 |
Global administrator |
||
Domain\User2 |
User administrator |
BizCorp |
BizCorp |
Domain\User3 |
Data administrator |
BizCorp |
BizCorp |
Domain\User4 |
Modeler |
BizCorp |
Corporate |
Domain\User5 |
BusinessUsers |
BizCorp |
Corporate |
Role model associations
The user roles import option associates defined roles with models in the system. Models and roles must already exist in the system; if they do not, the importsecurity command displays an error and continues processing the CSV file.
Role model associations are described in the following table.
Role |
The role label. |
Model |
The model label. |
Allow Journal |
(Optional) Defines the journal permission switch. When this is not specified the default is off. |
Application |
Defines the application. |
Scope (ModelSite) |
Defines the Model Site. |
The following is a sample Role Model Associations csv file:
| Role | Models | Access | Allow Journal | Application | Scope |
|---|---|---|---|---|---|
RoleLabel1 |
HR |
On |
Off |
BizCorp |
EMEA |
RoleLabel2 |
Cost |
On |
Off |
BizCorp |
EMEA |
RoleLabel3 |
ExchangeRate |
On |
Off |
BizCorp |
Corporate |
RoleLabel4 |
Financial1 |
On |
On |
BizCorp |
Corporate |
RoleLabel5 |
Financial2 |
Off |
Off |
BizCorp |
Corporate |
The allow Journal column specifies if the “Allow Journal” permission is set to on for a financial model. If the “Allow Journal” permission is set to on for a model and the model does not have the model property, value journal set to true, the system sends an error message. If the “Allow Journal” permission is set to on for a model and the model access is set to off, the system sends an error message. If a role has an existing association for a specific model and the association is not specified in the CSV file, the import does not change the RoleModel access. When an error occurs all valid entries are still imported.
For user-to-role association, the behavior is when the /Replace switch is used:
If a role has an existing association for a specific model and the association is not specified in the CSV file, importsecurity sets the RoleModel access to off. (The Role/Model association is removed from the back end.)
Example:
PPSCmd ImportSecurity /type userpermissions / userpermissions.csv
PPSCmd ImportSecurity /type rolemodelassociations / rolesmodels.csv
User permissions
The UserPermission import option allows you to import new or additional user permissions and also to overwrite the system’s existing user permissions.
User permissions are described in the following table.
User |
The user Label. This can be an Active Directory group. |
Role |
The role Label. This can be an Active Directory group. |
Hierarchy |
The dimension Hierarchy. |
MemberDef |
Defines what members are in the scope. Use the same syntax as in the Rolepermission import command. |
Application |
Defines the Application. |
Scope |
Defines the ModelSite. |
Permission |
Records the permissions. |
Example:
| User | Role | HierarchyDef | MemberDef | Permission | Application | Scope |
|---|---|---|---|---|---|---|
Redmond\biuser2 |
Role1 |
[Account].[accountmemberset] |
members() |
Read + Write |
BizCorp |
Corporate |
Redmond\biuser2 |
Role1 |
[Account].[accountmemberset] |
members() |
Read + Write |
BizCorp |
Corporate |
Redmond\biuser2 |
Role1 |
[Account].[accountmemberset] |
Member1 |
Read + Write |
BizCorp |
Corporate |
Redmond\biuser3 |
Role1 |
[BusinessProcess].[Standard] |
members() |
Write-Only |
BizCorp |
Corporate |
Redmond\biuser4 |
Role1 |
[BusinessProcess].[Standard] |
[AUTOADJ] |
Read-Only |
BizCorp |
Corporate |
Redmond\biuser2 |
Role2 |
[BusinessProcess].[Standard] |
[INPUT] |
Read-Only |
BizCorp |
Corporate |
Redmond\biuser3 |
Role2 |
[BusinessProcess].[Standard] |
[MANADJ] |
Read-Only |
BizCorp |
Corporate |
Redmond\biuser4 |
Role2 |
[BusinessProcess].[Standard] |
[FXADJ] |
Read-Only |
BizCorp |
Corporate |
Role permissions
The RolePermissions import option allows you to import custom role security definitions for custom roles. You cannot set permissions on system-defined roles (that is, global administrator, data administrator, modeler, and user administrator). If the role does not exist or if any column value is invalid, the importsecurity operation will ignore the row and process the remaining role definitions.
Role permissions are described in the following table.
Role |
This is the role you want to set custom security on. |
HierarchyDef |
This is the dimension and hierarchy that you are applying custom security to. When defining your hierarchy, use the following syntax: [DimensionLabel].[MemberSetLabel]. If you want to reference the All Members member set of a dimension, use the following syntax: [DimensionLabel].[Standard]. |
MemberDef |
This is the definition of the member or members you want to set permission on. |
Permission |
This is the permission for the members. It must one of the following: Read + Write, Write-Only, Read-Only. |
Application |
This is the application on which the role exists. |
Scope |
This is the model site on which the role exists. |
Example:
| Role | HierarchyDef | MemberDef | Permission | Application | Scope |
|---|---|---|---|---|---|
ReadWriteAccessRole |
[Account].[accountmemberset] |
members() |
Read + Write |
BizCorp |
Corporate |
ReadWriteAccessRole |
[BusinessProcess].[Standard] |
members() |
Write-Only |
BizCorp |
Corporate |
ReadWriteAccessRole |
[BusinessProcess].[Standard] |
[AUTOADJ] |
Read-Only |
BizCorp |
Corporate |
ReadWriteAccessRole |
[BusinessProcess].[Standard] |
[INPUT] |
Read-Only |
BizCorp |
Corporate |
ReadWriteAccessRole |
[BusinessProcess].[Standard] |
[MANADJ] |
Read-Only |
BizCorp |
Corporate |
ReadWriteAccessRole |
[BusinessProcess].[Standard] |
[FXADJ] |
Read-Only |
BizCorp |
Corporate |
File encoding can be ISO-8859, UTF8, UNICODE, or ASCII. Use ISO-8859 for 8-bit character encoding.
Exporting and importing user permissions and role permissions
You can use PPSCmd.exe utility to import larger numbers of user permissions and role permissions. When existing custom user permissions and role permissions need to be updated, ppscmd.exe provides a /replace switch to make it possible to perform this task as a batch (versus manually changing each value individually). The /replace switch is available with PerformancePoint Server Service Pack 3 (SP3). This switch can delete all roles in the application and add the roles provided in the CSV file. The /replace switch will not delete a role that has users assigned to it.
Note that Microsoft does not recommend using /app or /site switches with the PPSCmd.exe utility when exporting or importing role and user permissions with the replace method. Instead, the recommended process to load role and user permissions is as follows:
Export all role and user permissions in the CSV files and then back up these files.
Use the /replace switch to load an empty user permissions CSV file. This clears the user permissions table in the database. For example:
Ppscmd importsecurity /type userpermission /server https://localhost:46787 /replace userpermission.csvModify the role permissions in the CSV file that you originally exported in step 1 so that this file contains the permissions you want. Use the /replace switch to load the empty CSV file with the desired role permissions from the original file. For example:
Ppscmd importsecurity /type rolepermission /server https://localhost:46787 /replace rolepermission.csvModify the user permissions in the CSV file you originally exported in step 1 so that this file contains the permissions you want. Use either the /replace or /override switch to load the user permissions.
The CSV file you use with the importsecurity command must contain all role and user permissions that exist in the system. If the CSV file does not contain the current role and user permissions, then they will be removed when you run the importsecurity command.
Download this book
This article is included in the following downloadable book for easier reading and printing:
See the full list of available books at Downloadable content for PerformancePoint Planning Server.
See Also
Concepts
Exportdimension: Planning Command Utility operation
Reprocess: Planning Command Utility operation
New: Planning Command Utility operation
Upgrade: Planning Command Utility operation
Stagingdb: Planning Command Utility operation
Run: Planning Command Utility operation
Modelsitedeploy: Planning Command Utility operation
Migrate: Planning Command Utility operation
Importdimension: Planning Command Utility operation
Delete: Planning Command Utility operation
Help: Planning Command Utility operation