ManagementPolicyRule

Article
06/14/2010

Specifies an event and the rights and workflows associated with that event. A ManagementPolicyRule (MPR) resource can be used to grant rights, associate one or more workflows with the event, or both. There are two main types of MPRs: Request MPRs (ManagementPolicyRuleType property value is Request) and Transition MPRs (ManagementPolicyRuleType property value is SetTransition).

Request MPRs: Create, Read, Update, and Delete (CRUD) requests to the FIM Service database are mapped to all Request MPR resources that are relevant to the request to determine whether the requestor has the rights to perform the CRUD operation, and what additional workflows must be run before or after the CRUD operation is committed to the FIM Service database. The request is evaluated and processed as described in Request Processing. See also Management Policy Example.
Set Transition MPRs: This type of ManagementPolicyRule (MPR) resource maps what happens when resources move in or out of a set in or out of a set for any reason. This could occur as an indirect consequence of another MPR or because the set is defined in terms of a dateTime value (for more information, see Temporal property of Set).

For example, you could create a Set Transition MPR that is triggered when the Owner property of a Group is not set to a valid person. That MPR could have action workflows associated with it that assigns a FIM administrator to be the owner of that group and sends a notification to the administrator about why the change was made. For more information, see Examples.

Authentication or authorization workflows cannot be associated with this type of MPR.

Schema

<?xml version="1.0"?><xs:schema xmlns:rm="https://schemas.microsoft.com/2006/11/ResourceManagement" targetNamespace="https://schemas.microsoft.com/2006/11/ResourceManagement" version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:complexType name="ManagementPolicyRule">
    <xs:sequence>
      <xs:element minOccurs="0" name="ObjectID" type="rm:ReferenceType" />
      <xs:element minOccurs="1" name="ObjectType">
        <xs:simpleType>
          <xs:restriction base="xs:string">
            <xs:pattern value=".{0,448}" />
          </xs:restriction>
        </xs:simpleType>
      </xs:element>
      <xs:element minOccurs="1" name="CreatedTime" type="xs:dateTime" />
      <xs:element minOccurs="0" name="Creator" type="rm:ReferenceType" />
      <xs:element minOccurs="0" name="MVObjectID">
        <xs:simpleType>
          <xs:restriction base="xs:string">
            <xs:pattern value=".{0,448}" />
          </xs:restriction>
        </xs:simpleType>
      </xs:element>
      <xs:element minOccurs="0" name="DeletedTime" type="xs:dateTime" />
      <xs:element minOccurs="0" name="Description">
        <xs:simpleType>
          <xs:restriction base="xs:string">
            <xs:pattern value=".{0,448}" />
          </xs:restriction>
        </xs:simpleType>
      </xs:element>
      <xs:element minOccurs="0" name="DetectedRulesList" type="rm:ReferenceCollectionType" />
      <xs:element minOccurs="0" name="DisplayName">
        <xs:simpleType>
          <xs:restriction base="xs:string">
            <xs:pattern value=".{0,448}" />
          </xs:restriction>
        </xs:simpleType>
      </xs:element>
      <xs:element minOccurs="0" name="ExpectedRulesList" type="rm:ReferenceCollectionType" />
      <xs:element minOccurs="0" name="ExpirationTime" type="xs:dateTime" />
      <xs:element minOccurs="0" name="Locale">
        <xs:simpleType>
          <xs:restriction base="xs:string">
            <xs:pattern value=".{0,448}" />
          </xs:restriction>
        </xs:simpleType>
      </xs:element>
      <xs:element minOccurs="0" name="ResourceTime" type="xs:dateTime" />
      <xs:element minOccurs="0" name="ActionParameter" type="rm:StringCollectionType" />
      <xs:element minOccurs="1" name="ActionType" type="rm:StringCollectionType" />
      <xs:element minOccurs="0" name="ActionWorkflowDefinition" type="rm:ReferenceCollectionType" />
      <xs:element minOccurs="0" name="AuthenticationWorkflowDefinition" type="rm:ReferenceCollectionType" />
      <xs:element minOccurs="0" name="AuthorizationWorkflowDefinition" type="rm:ReferenceCollectionType" />
      <xs:element minOccurs="1" name="Disabled" type="xs:boolean" />
      <xs:element minOccurs="1" name="GrantRight" type="xs:boolean" />
      <xs:element minOccurs="0" name="PrincipalRelativeToResource">
        <xs:simpleType>
          <xs:restriction base="xs:string">
            <xs:pattern value=".{0,448}" />
          </xs:restriction>
        </xs:simpleType>
      </xs:element>
      <xs:element minOccurs="0" name="PrincipalSet" type="rm:ReferenceType" />
      <xs:element minOccurs="0" name="ResourceCurrentSet" type="rm:ReferenceType" />
      <xs:element minOccurs="0" name="ResourceFinalSet" type="rm:ReferenceType" />
      <xs:element minOccurs="0" maxOccurs="1" name="ManagementPolicyRuleType">
        <xs:simpleType>
          <xs:restriction base="xs:string">
            <xs:pattern value="^(Request|SetTransition)?$" />
          </xs:restriction>
        </xs:simpleType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>
</xs:schema>

Properties

The following table lists the properties of the ManagementPolicyRule resource:

Property	Description
ActionType	Required multi-valued String property. Defines an action type against which the management policy rule will be evaluated. The operations are mapped to Web-service requests received by the FIM Service. See ActionType Property table for a list of values. For details of the web-service protocols supported see Web Services API. If `Create` is one of the ActionType values then the ResourceCurrentSet value will be ignored. If `Delete` is one of the ActionType values then the ResourceFinalSet value will be ignored. If `Read` is one of the ActionType values then the ResourceCurrentSet and ResourceFinalSet values will be ignored. If the ManagementPolicyRuleType value is `SetTransition` then the only valid values for ActionType are `TransitionIn` and `TransitionOut`, and only one ActionType value should be defined. Workflows included in AuthenticationWorkflowDefinition and AuthorizationWorkflowDefinition will be ignored.
ActionParameter	Optional multi-valued String property. Name of a property of the resource that the management policy rule applies to. A value of “`*`" indicates all properties.
ActionWorkflowDefinition	Optional multi-valued property. Reference to a WorkflowDefinition resource. For Request MPRs, specifies workflows that will be run after a Request is committed to the FIM Service database. For Set Transition MPRs, specifies workflows that will be run after the set transition takes place.
AuthenticationWorkflowDefinition	Optional multi-valued property. Reference to a WorkflowDefinition resource. Specifies an authentication workflow that must be run successfully before a CRUD request is committed to the FIM Service database. For more information, see Request Processing. These workflows are ignored if ManagementPolicyRuleType is set to `SetTransition`.
AuthorizationWorkflowDefinition	Optional multi-valued property. Reference to a WorkflowDefinition resource. Specifies authorization workflows that must be run successfully before the CRUD request is committed to the FIM Service database. For more information, see Request Processing. These workflows are ignored if ManagementPolicyRuleType is set to `SetTransition`.
Disabled	Required Boolean property. Indicates if the management policy rule is disabled.
GrantRight	Required Boolean property. If false, the ManagementPolicyRule defines an event and any workflows associated with that event but does not grant any rights. If true, the ManagementPolicyRule is also granting rights to perform the actions specified by the ManagmentPolicyRule resource. This property is automatically set to false if ManagementPolicyRuleType is set to `SetTransition`.
ManagementPolicyRuleType	Optional String property. Defines whether the MPR is a Request MPR or a Set Transition MPR. See ManagementPolicyRuleType Property table for a list of valid values.
PrincipalSet	Optional Set Reference property, but either PrincipalSet or PrincipalRelativeToResource must be specified, and they cannot both be specified. Specifies a set that the initiator of an action must belong to in order for the management policy rule to apply.
PrincipalRelativeToResource	Optional String property, but either PrincipalSet or PrincipalRelativeToResource must be specified, and they cannot both be specified. Specifies a reference property of the resources in the ResourceCurrentSet which will be evaluated as valid initiators of the action This property is a reflexive property; its value is defined in terms of one of the Resource properties. Reflexive properties make it possible to define dynamic management policy rules which whose conditions are evaluated in the context of each target resource being processed. This property is ignored if ManagementPolicyRuleType is set to `SetTransition`. The String length must be no more than 448 characters.
ResourceCurrentSet	Optional Set Reference property. For Request MPRs, specifies a set that the resource must currently belong to in order for the management policy rule to apply. ResourceCurrentSet must be specified for all types of requests except `Create` requests. ResourceCurrentSet value is ignored for `Create` requests. For Set Transition MPRs that have an ActionType value of `TransitionOut`, indicates the set that the resource is transitioning out of. ResourceCurrentSet value is ignored if the ActionType is `TransitionIn`.
ResourceFinalSet	Optional Set Reference property. For Request MPRs, specifies the set that the target resource must belong to after the request is completed in order for the management policy rule to apply. This property must be specified for all types of requests except `Delete` and Read (Get or Enumerate) requests. For SetTransition MPRs that have an ActionType value of `TransitionIn`, indicates the set that the resource is transitioning into. ResourceFinalSet value is ignored if the ActionType is `TransitionOut`.

ActionType Property

The following table lists the values for the ActionType property. For details of the web-service protocols that support each type of action, see Web Services API.

Value	Description
Create	Create a resource. This ActionType value is only valid if the ManagementPolicyRuleType is set to `Request`.
Delete	Delete a resource. This ActionType value is only valid if the ManagementPolicyRuleType is set to `Request`.
Read	Read and search. This ActionType value is only valid if the ManagementPolicyRuleType is set to `Request`.
Modify	Modify a single-valued property of a resource. This ActionType value is only valid if the ManagementPolicyRuleType is set to `Request`.
Add	Change a resource by adding one or more values to a multi-valued property of the resource. This ActionType value is only valid if the ManagementPolicyRuleType is set to `Request`.
Remove	Change a resource by deleting one or more values of a multi-valued property of a resource. This ActionType value is only valid if the ManagementPolicyRuleType is set to `Request`.
TransitionIn	Triggered when a resource transitions into a set for any reason. This ActionType value is only valid if the ManagementPolicyRuleType is set to `SetTransition`. The Transition Set is stored in the ResourceFinalSet property.
TransitionOut	Triggered when a resource transitions out of a set for any reason. This ActionType value is only valid if the ManagementPolicyRuleType is set to `SetTransition`. The Transition Set is stored in the ResourceCurrentSet property.

ManagementPolicyRuleType Property

The following table lists the values for the ManagementPolicyRule property.

Value	Description
Request	The combination of the values in the PrincipalSet, PrincipalRelativeToResource, ActionType, ActionParameter, ResourceCurrentSet and ResourceFinalSet and properties define a condition which needs to be satisfied by a request in order for the policy to apply, and the other properties define what happens when that condition occurs in the system. Create, Read, Update, and Delete (CRUD) requests to the FIM Service database are mapped to all Request MPR resources that are relevant to the request to determine whether the requestor has the rights to perform the CRUD operation, and what additional workflows must be run before or after the CRUD operation is committed to the FIM Service database. The request is evaluated and processed as described in Request Processing.
SetTransition	This type of ManagementPolicyRule (MPR) resource maps what happens when resources move in or out of a set in or out of a set for any reason. This could occur as an indirect consequence of another MPR or because the set is defined in terms of a dateTime value.

Request

The combination of the values in the PrincipalSet, PrincipalRelativeToResource, ActionType, ActionParameter, ResourceCurrentSet and ResourceFinalSet and properties define a condition which needs to be satisfied by a request in order for the policy to apply, and the other properties define what happens when that condition occurs in the system. Create, Read, Update, and Delete (CRUD) requests to the FIM Service database are mapped to all Request MPR resources that are relevant to the request to determine whether the requestor has the rights to perform the CRUD operation, and what additional workflows must be run before or after the CRUD operation is committed to the FIM Service database. The request is evaluated and processed as described in Request Processing.

SetTransition

This type of ManagementPolicyRule (MPR) resource maps what happens when resources move in or out of a set in or out of a set for any reason. This could occur as an indirect consequence of another MPR or because the set is defined in terms of a dateTime value.

Parent Elements

None

Remarks

All of the resource types in FIM have the same attribute bindings as the Resource type by default. For more information, see Forefront Identity Manager Schema.

Examples

Granting Rights

The following is an example of a Request ManagementPolicyRule resource that grants rights but does not include any additional workflows. The ManagementPolicyRule grants all users that are full-time employees (FTE) users the ability to create groups.

Code

<ManagementPolicyRule>
  <ManagementPolicyRuleType>Request</ManagementPolicyRuleType>
  <PrincipalSet>Reference to “All FTE Users" Set</PrincipalSet>
  <ActionType>Create</ActionType>  <ActionParameter>*</ActionParameter>
  <ResourceFinalSet>Reference to “All Groups" Set</ResourceFinalSet>
  <GrantRight>true</GrantRight>
  <Disabled>false</Disabled>
</ManagementPolicyRule>

Request ManagementPolicyRule that Includes an Action Workflow

The following is an example of a Request ManagementPolicyRule resource that associates workflows with a condition but does not grant the associated rights. In this example, whenever a new executive is identified (through promotion, hiring or any other system update), a “Notify the board of directors" action workflow is executed. In this example, the system needs to have permission defined through a separate set of ManagementPolicyRules in order for this request to be fulfilled.

Code

<ManagementPolicyRule>
  <ManagementPolicyRuleType>Request</ManagementPolicyRuleType>
  <PrincipalSet>Reference to “All People" Set</PrincipalSet>
  <ActionType>Create</ActionType>
  <ActionType>Modify</ActionType>
  <ActionType>Add</ActionType>
  <ActionType>Remove</ActionType>
  <ActionParameter>*<ActionParameter/>
  <ResourceCurrentSet>Reference to “All Resources" Set</ResourceCurrentSet>
  <ResourceFinalSet>Reference to a custom “Executive" Set</ResourceFinalSet>
  <GrantRight>false</GrantRight>
  <Disabled>false</Disabled>
  <ActionWorkflowDefinition>Reference to a custom “Notify board of directors" action WorkflowDefinition</ActionWorkflowDefinition>
</ManagementPolicyRule>

Request ManagementPolicyRule that Uses Reflexive Property

The following is an example of a Request ManagementPolicyRule resource that uses the PrincipalRelativeToResource property. This property is a reflexive property; its value is defined in terms of one of the Resource properties. This ManagementPolicyRule resource defines a management policy in which only group owners can modify a group type. For each request matching this policy, the owner of the target resource will be evaluated to see if it contains the initiator of the request. Note that “Owner" is a default property of the Group resource.

Code

<ManagementPolicyRule>
  <ManagementPolicyRuleType>Request</ManagementPolicyRuleType>
  <PrincipalRelativeToResource>Owner</PrincipalRelativeToResource>
  <Action>Update</Action>
  <ActionParameter>GroupType</ActionParameter>
  <ResourceCurrentSet>Reference to “All Groups" Set</ResourceCurrentSet>
  <ResourceFinalSet>Reference to “All Groups" Set</ResourceFinalSet>
  <ActionWorkflowDefinition>Reference to a custom “Notify board of directors" action WorkflowDefinition</ActionWorkflowDefinition>
</ManagementPolicyRule>

Set Transition for Invalid Group Owner

The following is an example of a Set Transition MPR that is triggered when the Owner of a Group is no longer set to a valid Person resource. When this occurs, the FIM Administrator is assigned as the Owner and a notification email is sent.

Code

<ManagementPolicyRule>
  <ManagementPolicyRuleType>SetTransition</ManagementPolicyRuleType>
  <PrincipalSet>Reference to “All Groups" Set</Principal>
  <ActionType>TransitionOut</ActionType>
  <ActionParameter>Owner</ActionParameter>
  <ResourceCurrentSet>Reference to “All People" Set</ResourceCurrentSet>
  <GrantRight>false</GrantRight>
  <Disabled>false</Disabled>
  <ActionWorkflowDefinition>Reference to a custom “Assign FIM Administrator as New Group Owner" action WorkflowDefinition</ActionWorkflowDefinition>
  <ActionWorkflowDefinition>Reference to a custom “Notify new group owner" action WorkflowDefinition</ActionWorkflowDefinition>
</ManagementPolicyRule>

Set Transition for Temporal Set

The following is an example of a Set Transition MPR that is based on a calculation of time passed. In this example, the MPR is triggered when an employee has an expiration date of greater than one week ago.

Code

<ManagementPolicyRule>
  <ManagementPolicyRuleType>SetTransition</ManagementPolicyRuleType>
  <PrincipalSet>Reference to “All People" Set</Principal>
  <ActionType>TransitionIn</ActionType>
  <ActionParameter>EmployeeExpirationDate</ActionParameter>
  <ResourceFinalSet>Reference to a custom “All People with EmployeeExpirationDate of at least one week" Set</ResourceCurrentSet>
  <GrantRight>false</GrantRight>
  <Disabled>false</Disabled>
  <ActionWorkflowDefinition>Reference to a custom “Archive User's Mailbox."</ActionWorkflowDefinition>
</ManagementPolicyRule>

Share via

ManagementPolicyRule

Schema

Properties

ActionType Property

ManagementPolicyRuleType Property

Parent Elements

Remarks

Examples

Granting Rights

Code

Request ManagementPolicyRule that Includes an Action Workflow

Code

Request ManagementPolicyRule that Uses Reflexive Property

Code

Set Transition for Invalid Group Owner

Code

Set Transition for Temporal Set

Code

See Also

Concepts

Other Resources

Additional resources