Change a Role Entry on an Unscoped Top-Level Role

Applies to: Exchange Server 2013

Topic Last Modified: 2012-10-03

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 Advanced Permissions.

What do you need to know before you begin?

Estimated time to complete each procedure: 5 minutes
You need to be assigned permissions before you can perform this procedure or procedures. To see what permissions you need, see the "Management roles" entry in the Role Management Permissions topic.
You must use the Shell to perform these procedures.
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:
- Manage Role Groups
- Add a Role to a User or USG
For information about keyboard shortcuts that may apply to the procedures in this topic, see Keyboard Shortcuts in the Exchange Admin Center.

Tip:
Having problems? Ask for help in the Exchange forums. Visit the forums at: Exchange Server, Exchange Online, or Exchange Online Protection

What do you want to do?

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

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.

	Copy Code
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.

	Copy Code
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

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.

Caution:
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.

	Copy Code
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.

	Copy Code
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

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.

Caution:
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.

	Copy Code
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.

	Copy Code
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

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.

Caution:
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.

	Copy Code
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.

	Copy Code
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

Manage Role Groups

Manage Role Group Members

Add a Role to a User or USG

Remove a Role from a User or USG