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.

Email

Optional. The e-mail address of the user.

Example:

Label Name Email

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:

  1. Export all role and user permissions in the CSV files and then back up these files.

  2. 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.csv

  3. Modify 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.csv

  4. Modify 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