Change a Role Entry on an Unscoped Top-Level Role

 

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

Management role entries on unscoped top-level management roles refer to the scripts and non-Exchange cmdlets, and their parameters, that you want to make available to those assigned the role. By changing the parameters available on a role entry, you control what those assigned the role can do with the script or non-Exchange cmdlet. For more information about unscoped role entries, see Understanding Management Roles.

Note

If you want to change a role entry on a management role that contains Exchange cmdlets, see Change a Role Entry.

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

Prerequisites

The ability to change 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 or change an unscoped top-level role entry. For more information about adding a role to a user, USG, or role group, see the following topics:

• Add a Role to a Role Group

• Add a Role to a User or USG

Note

You can't use the EMC to change a role entry.

Use the Shell to add one or more parameters to a role entry

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.

To add parameters to an unscoped top-level role entry, you need to do the following:

• Specify the parameters you want to add using the Parameters parameter.

• Specify the AddParameter parameter to indicate that you want to perform an add operation.

• Specify the UnscopedTopLevel parameter to indicate that you're changing a role entry on an unscoped top-level role. If you don't specify this parameter when you change a role entry on an unscoped role, an error occurs.

To add parameters to a role entry, use the following syntax.

Set-ManagementRoleEntry <role name>\<script or non-Exchange cmdlet> -Parameters <parameter 1>, <parameter 2>, <parameter...> -AddParameter -UnscopedTopLevel

This example adds the EmailAddress and City parameters to the CreateUsers.ps1 script on the Recipient Administrators unscoped role.

Set-ManagementRoleEntry "Recipient Administrators\CreateUsers.ps1" -Parameters EmailAddress, City -AddParameter -UnscopedTopLevel

For detailed syntax and parameter information, see Set-ManagementRoleEntry.

Use the Shell to remove one or more parameters from a role entry

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.

To remove parameters from a role entry, you need to do the following:

• Specify the parameters you want to remove using the Parameters parameter.

• Specify the RemoveParameter parameter to indicate that you want to perform a remove operation.

• Specify the UnscopedTopLevel parameter to indicate that you're changing a role entry on an unscoped top-level role. If you don't specify this parameter when you change a role entry on an unscoped role, an error occurs.

Warning

You can't undo remove operations. If you mistakenly remove a parameter from a role entry, you must add it again manually.

To remove parameters from a role entry, use the following syntax.

Set-ManagementRoleEntry <role name>\<script or non-Exchange cmdlet> -Parameters <parameter 1>, <parameter 2>, <parameter...> -RemoveParameter -UnscopedTopLevel

This example removes the Delay, Force, and Credential parameters from the Start-Widget non-Exchange cmdlet on the Tier 1 Server Administrators role.

Set-ManagementRoleEntry "Tier 1 Server Administrators\Start-Widget" -Parameters Delay, Force, Credential -RemoveParameter -UnscopedTopLevel

For detailed syntax and parameter information, see Set-ManagementRoleEntry.

Use the Shell to remove all parameters from a role entry

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.

To remove all of the parameters from a role entry, you need to do the following:

• Specify the value $Null on the Parameters parameter. You don't need to include the RemoveParameter parameter.

• Specify the UnscopedTopLevel parameter to indicate that you're changing a role entry on an unscoped top-level role. If you don't specify this parameter when you change a role entry on an unscoped role, an error occurs.

Removing all the parameters from a role entry is most useful when you want to make only a few parameters available on a script or non-Exchange cmdlet and exclude all of the other parameters.

If you don't want the role to have access to a script or non-Exchange cmdlet, remove the associated role entry from the role completely instead of just removing the parameters. For more information about how to remove a role entry from a role, see Remove a Role Entry from a Role.

Warning

You can't undo remove operations. If you mistakenly remove all the parameters from a role entry, you must add them again manually.

To remove all the parameters from a role entry, use the following syntax.

Set-ManagementRoleEntry <role name>\<script or non-Exchange cmdlet> -Parameters $Null -UnscopedTopLevel

This example removes all the parameters from the FindMailboxesOverQuota.ps1 script on the Recipient Administrators role.

Set-ManagementRoleEntry "Recipient Administrators\FindMailboxesOverQuota.ps1" -Parameters $Null -UnscopedTopLevel

For detailed syntax and parameter information, see Set-ManagementRoleEntry.

Use the Shell to apply a specific set of parameters

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 only a specific set of parameters to be included on a role entry, you need to do the following:

• Specify the Parameters parameter only. Don't include the AddParameter or RemoveParameter parameters.

• Specify the UnscopedTopLevel parameter to indicate that you're changing a role entry on an unscoped role. If you don't specify this parameter when you change a role entry on an unscoped top-level role, an error occurs.

Warning

When you specify only the Parameters parameter, only the parameters you specify in the command are included on the role entry. All other parameters are removed.

To specify a specific set of parameters, use the following syntax.

Set-ManagementRoleEntry <role name>\<script or non-Exchange cmdlet> -Parameters <parameter 1>, <parameter 2>, <parameter...> -UnscopedTopLevel

This example includes only the Alias, DisplayName, WidgetConfig, and Enabled parameters on the Set-Widget cmdlet on the Seattle Mail Recipient Admins role.

Set-ManagementRoleEntry "Seattle Mail Recipient Admins\Set-UMMailbox" -Parameters Alias, DisplayName, WidgetConfig, Enabled -UnscopedTopLevel

For detailed syntax and parameter information, see Set-ManagementRoleEntry.

Other Tasks

After you change a role entry on 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.