Add a Role Entry to an Unscoped Top-Level Role

Applies to: Exchange Server 2010 SP3, Exchange Server 2010 SP2

You can add scripts and non-Exchange cmdlets to unscoped top-level management roles if you want to make new scripts or non-Exchange cmdlets available to existing unscoped roles. These scripts and non-Exchange cmdlets are added as management role entries to unscoped top-level management roles. They can then be used by those unscoped top-level role entries or any unscoped roles derived from the top-level roles. For more information about unscoped role entries, see Understanding Management Roles.

Looking for other management tasks related to roles? Check out Managing Advanced Permissions.

Prerequisites

The ability to add a role entry on an unscoped top-level role isn't included in any management role group by default. You must first assign the Unscoped Role Management role to a user, or to a universal security group (USG) or role group of which the user is a member, before the user is able to add an unscoped top-level role entry. For more information about adding a role to a role group, user, or USG, see the following topics:

• Add a Role to a Role Group

• Add a Role to a User or USG

Add a script role entry to an unscoped top-level role

You need to be assigned permissions before you can perform this procedure. To see what permissions you need, see the "Unscoped management roles" entry in the Role Management Permissions topic.

If you want to add a script to an existing unscoped role, use this procedure. If you want to add a non-Exchange cmdlet to an existing unscoped role, see "Add a non-Exchange cmdlet role entry to an unscoped top-level role" later in this topic.

To add a Windows PowerShell script to an unscoped top-level role, you must add a management role entry to the role. The role entry contains the script's name and the parameters on the script that you want to make available to the role.

The script must reside in the Scripts directory in the Microsoft Exchange Server 2010 installation path on every server running Exchange 2010 where users might connect to run the script. If a user has access to run a script, but the script isn't located on the Exchange 2010 server the user is connected to, an error occurs. By default, the path to the Scripts directory is C:\Program Files\Microsoft\Exchange Server\V14\Scripts.

After you copy the script to the appropriate Exchange 2010 servers and you decide what script parameters should be used, create the role entry using the following syntax.

Add-ManagementRoleEntry <unscoped top-level role name>\<script filename> -Parameters <parameter 1, parameter 2, parameter...> -Type Script -UnscopedTopLevel

This example adds the BulkProvisionUsers.ps1 script to the IT Scripts role with the Name and Location parameters.

Add-ManagementRoleEntry "IT Scripts\BulkProvisionUsers.ps1" -Parameters Name, Location -Type Script -UnscopedTopLevel

Add a non-Exchange cmdlet role entry to an unscoped top-level role

You need to be assigned permissions before you can perform this procedure. To see what permissions you need, see the "Unscoped management roles" entry in the Role Management Permissions topic.

If you want to add a non-Exchange cmdlet to an existing unscoped role, use this procedure. If you want to add a script cmdlet to an existing unscoped role, see "Add a script role entry to an unscoped top-level role" earlier in this topic.

To add a non-Exchange cmdlet to an unscoped top-level role, you must add a management role entry to the role. The role entry contains the cmdlet snap-in, cmdlet name, and the parameters on the cmdlet that you want to make available to the role.

If you add non-Exchange cmdlets to the new role, the cmdlets must be installed on every Exchange 2010 server where users might connect to run the cmdlets. To learn how to properly install and register the Windows PowerShell snap-ins that contain the cmdlets you want to use, refer to the documentation for your product.

After you install the Windows PowerShell snap-in that contains the cmdlets on the appropriate the Exchange 2010 servers and you decide what cmdlet parameters should be used, create the role entry using the following syntax.

Add-ManagementRoleEntry <unscoped top-level role name>\<cmdlet name> -PSSnapinName <snap-in name> -Parameters <parameter 1, parameter 2, parameter...> -Type Cmdlet -UnscopedTopLevel

This example adds the Set-WidgetConfiguration cmdlet in the Contoso.Admin.Cmdlets snap-in to the Widget Cmdlets role with the Database and Size parameters.

Add-ManagementRoleEntry "Widget Cmdlets\Set-WidgetConfiguration" -PSSnapinName Contoso.Admin.Cmdlets -Parameters Database, Size -Type Cmdlet -UnscopedTopLevel

Other Tasks

After you add a role entry or an unscoped top-level role, you may also want to:

• Add a Role Entry to a Role

• Add a Role to a Role Group

• Remove a Role from a Role Group

• Add Members to a Role Group

• Remove Members from a Role Group

• Add a Role to a User or USG

• Remove a Role from a User or USG

 © 2010 Microsoft Corporation. All rights reserved.