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

Topic Last Modified: 2012-11-19

Use the Add-ManagementRoleEntry cmdlet to add management role entries to an existing management role.

Syntax

Add-ManagementRoleEntry -Identity <RoleEntryIdParameter> [-Confirm [<SwitchParameter>]] [-DomainController <Fqdn>] [-Force <SwitchParameter>] [-Overwrite <SwitchParameter>] [-Parameters <String[]>] [-PSSnapinName <String>] [-Type <Cmdlet | Script | ApplicationPermission | All>] [-UnScopedTopLevel <SwitchParameter>] [-WhatIf [<SwitchParameter>]]
Add-ManagementRoleEntry -ParentRoleEntry <RoleEntryIdParameter> -Role <RoleIdParameter> [-Confirm [<SwitchParameter>]] [-DomainController <Fqdn>] [-Force <SwitchParameter>] [-Overwrite <SwitchParameter>] [-WhatIf [<SwitchParameter>]]

Detailed Description

The cmdlet and its parameters that you add to a role entry must exist in the parent role. You can't add role entries to built-in roles.

Important:
You can only add a role entry to a management role if the role entry exists in the role's parent role. For example, if you try to add the Search-Mailbox role entry to a role that's a child of the Mail Recipients role, you'll receive an error. This error occurs because the Search-Mailbox role entry doesn't exist in the Mail Recipients role. To add the Search-Mailbox role entry to a role, you need to create a new role that's a child of the Mailbox Import Export role, which does contain the Search-Mailbox role entry. Then you can use the Add-ManagementRoleEntry cmdlet to add the Search-Mailbox role entry to the new child role.

For more information about management role entries, see Understanding Management Roles.

You need to be assigned permissions before you can run this cmdlet. Although all parameters for this cmdlet are listed in this topic, you may not have access to some parameters if they're not included in the permissions assigned to you. To see what permissions you need, see the "Management role entries" entry in the Role Management Permissions topic.

Parameters

Parameter Required Type Description

Identity

Required

Microsoft.Exchange.Configuration.Tasks.RoleEntryIdParameter

The Identity parameter specifies the role entry to add. You must specify the value of the Identity parameter in the format: <management role>\<role entry name>, for example, ExampleRole\Set-Mailbox.

For more information about how management role entries work, see Understanding Management Roles.

The role entry you want to add must exist in the parent role. If the role entry name contains spaces, you must enclose the name in quotation marks (").

ParentRoleEntry

Required

Microsoft.Exchange.Configuration.Tasks.RoleEntryIdParameter

The ParentRoleEntry parameter specifies the role entry in the parent role to add to the role specified with the Role parameter. This parameter generally isn't used directly, but exists to enable the piping of role entries from the Get-ManagementRoleEntry cmdlet. If you use the ParentRoleEntry parameter, you can't use the UnScopedTopLevel switch.

Role

Required

Microsoft.Exchange.Configuration.Tasks.RoleIdParameter

The Role parameter specifies the role to which the new role entry, specified by the ParentRoleEntry parameter, is added.

Confirm

Optional

System.Management.Automation.SwitchParameter

The Confirm switch causes the command to pause processing and requires you to acknowledge what the command will do before processing continues. You don't have to specify a value with the Confirm switch.

DomainController

Optional

Microsoft.Exchange.Data.Fqdn

The DomainController parameter specifies the fully qualified domain name (FQDN) of the domain controller that writes this configuration change to Active Directory.

Force

Optional

System.Management.Automation.SwitchParameter

This parameter is reserved for internal Microsoft use.

Overwrite

Optional

System.Management.Automation.SwitchParameter

The Overwrite parameter causes existing role entries to be overwritten by the role entries being added.

Parameters

Optional

System.String[]

The Parameters parameter specifies the parameters to be included in the role being added. The parameters specified must exist on the cmdlet associated with the role entry. You can specify multiple parameters, separated with commas.

PSSnapinName

Optional

System.String

The PSSnapinName parameter specifies the Windows PowerShell snap-in that contains the cmdlet associated with the role being added. Use the Get-PSSnapin cmdlet to retrieve a list of available Windows PowerShell snap-ins.

Type

Optional

Microsoft.Exchange.Data.Directory.Management.ManagementRoleEntryType

The Type parameter specifies the type of role entry being added. The valid values are Cmdlet, Script, and ApplicationPermission.

UnScopedTopLevel

Optional

System.Management.Automation.SwitchParameter

The UnScopedTopLevel switch specifies that you're adding a custom script or non-Exchange cmdlet to an unscoped top-level management role. You can only use the UnScopedTopLevel switch when you add a role entry to an unscoped top-level role. If you use the UnScopedTopLevel switch, you can't use the ParentRoleEntry parameter.

WhatIf

Optional

System.Management.Automation.SwitchParameter

The WhatIf switch instructs the command to simulate the actions that it would take on the object. By using the WhatIf switch, you can view what changes would occur without having to apply any of those changes. You don't have to specify a value with the WhatIf switch.

Input Types

To see the input types that this cmdlet accepts, see Cmdlet Input and Output Types. If the Input Type field for a cmdlet is blank, the cmdlet doesn’t accept input data.

Return Types

To see the return types, which are also known as output types, that this cmdlet accepts, see Cmdlet Input and Output Types. If the Output Type field is blank, the cmdlet doesn’t return data.

Examples

EXAMPLE 1

This example adds a new role entry for the Get-Mailbox cmdlet to the Recipient Administrators management role. The role entry for the Get-Mailbox cmdlet is added exactly as it's configured in the Recipient Administrators parent role.

Copy Code
Add-ManagementRoleEntry "Recipient Administrators\Get-Mailbox"

EXAMPLE 2

This example adds a new role entry for the Get-Mailbox cmdlet to the Recipient Administrators role. Only the Identity, Anr, Server, and Filter parameters are added to the new role entry.

Copy Code
Add-ManagementRoleEntry "Recipient Administrators\Get-Mailbox" -Parameters Identity, Anr, Server, Filter

EXAMPLE 3

This example uses the Get-ManagementRoleEntry cmdlet to retrieve a list of all the role entries that exist on the Mail Recipients management role that contain the string "Mailbox" in the cmdlet name, and then adds them to the Mailbox Administrators role using the Add-ManagementRoleEntry cmdlet. The role entries are added to the child role exactly as they're configured on the parent role.

Copy Code
Get-ManagementRoleEntry "Mail Recipients\*Mailbox*" | Add-ManagementRoleEntry -Role "Mailbox Administrators"

EXAMPLE 4

This example adds the MailboxAudit script with the Department and Location parameters to the IT Scripts unscoped top-level role.

Copy Code
Add-ManagementRoleEntry "IT Scripts\MailboxAudit" -Parameters Department, Location -UnScopedTopLevel