Understanding Custom Resource and Attribute Management

Applies To: Forefront Identity Manager 2010

Microsoft® Forefront® Identity Manager (FIM) 2010 provides an extensible schema with a predefined set of resource types and associated attributes.

What This Document Covers

This document discusses the components and structure of the FIM schema: resource types, attributes, and bindings.

The conceptual information in this document is complemented by the following document, which provides step-by-step, hands-on guidance for these features:

• Introduction to Custom Resource and Attribute Management (https://go.microsoft.com/fwlink/?LinkID=165857)

For an overview of FIM 2010 documentation and guidance for using it, see the Documentation Roadmap.

If you have questions regarding the content of this document or if you have general feedback, post a message to the Forefront Identity Manager 2010 TechNet Forum.

Audience

This document is intended for information technology (IT) planners, systems administrators, and infrastructure planners.

Understanding the FIM 2010 Schema

The FIM schema consists of three components:

• Resource Type - Each instance of a resource type definition (ObjectTypeDescription) defines the basic properties of a resource type. A resource type can specify both a collection of attributes which must be present on resources of that type, and a collection of attributes the may be present as an option on resources of that type.

• Attributes - Each instance of an attribute definition (AttributeTypeDescription) defines the basic properties of an attribute. An attribute can be bound to one or more resource types.

• Bindings - Each instance of a binding definition (BindingDescription) maps an attribute to a resource type. It also makes it possible for the administrator to customize the display name of the attribute when it is used in a resources of a particular resource type.

  The following illustration shows the relationship among these three elements.

Basic Bindings

Each resource type, including all schema-related resource types, binds to a list of built-in attributes, which are listed below. The relationship between the bound attributes and the bound resource types is defined by default, and it cannot be changed on these bindings.

• CreatedTime - This indicates at what time the resource was created. This is a system created attribute, and cannot be modified, deleted, or created by the user.

• Creator - This holds the reference to the resource for the user that created the resource. This is a system-created element, and it cannot be modified, deleted, or created by the user. If the user who created this resource is deleted, the value is also deleted.

• DeletedTime - This attribute is deprecated.

• Description – An optional description of the resource.

• DisplayName - This is an optional user=friendly screen name for the resource instance. This is a string type, and it cannot be longer than 448 characters. If you are using the FIM Portal, we recommend that you make this attribute required for any new resource types. It is used in various user interface (UI) components to help the user identify different resources.

• ExpectedRulesList – Indicates which Synchronization Rules that this resource has been linked with. This is an optional field that is populated by the FIM Service.

• ExpirationTime – This is an optional binding that indicates the date and time at which the resource instance expires. You can use this attribute in combination of custom workflow to manage the expiration of a resource.

• Locale – This is an optional attribute that indicates the default locale of the resource at creation time.

• MVObjectID - The globally unique identifier (GUID) of the resource in the FIM metaverse that this resource instance has been linked to. This field is optional, and it is set by the FIM Synchronization Service.

• ObjectID – Displays as Resource ID. This required binding is generated by the FIM Service to uniquely identify every resource instance in FIM. This is a read-only attribute, and it is globally unique.

• ObjectType – Displays as Resource Type. This is a required binding that defines the type of the resource. You cannot create or edit this field.

• ResourceTime – The date and time of a resource instance, updated by the FIM Service. This attribute can be used to define time-triggered Management Policy Rules (MPRs). It cannot be created or modified by the user.

Resource Type

The Resource Type schema is defined by ObjectTypeDescription resources. You can create new resource type definitions or edit existing resource type definitions on the Schema Management – All Resource Types page in the FIM Portal. The following is a list of the settings you can create or modify on the resource type definitions. You must run the iisreset command to refresh the FIM Portal's cache of the schema after you create a new resource type.

• Specify General Settings

  There are three settings on the General tab of the Resource Type definition:

  • System Name – This is the name that is used to uniquely identify the resource type by the system. You must supply a unique value across all existing resource types when you create a new resource type. After the resource type has been created, the System Name cannot be changed.

    Note

    Do not use MicrosoftResourceManagement as a prefix in this field. It is reserved by the Microsoft FIM product team for future schema expansion. We recommend that you use a prefix that is specific to your environment. This will help avoid clashes of newly added resource types by the FIM product team or other non-Microsoft vendors in the future.

  • Display Name – This is the user-friendly name that appears in the FIM Portal. This is one of the basic bindings that is described in the previous section. This is a required attribute in the FIM Portal for a resource type definition. This value appears by default in the FIM Portal for a custom resource type. Subject to MPRs, the FIM Service allows the administrator to change this value.

  • Description – An optional description of the resource type. This value appears on the All Resources page in the FIM Portal to help clarify what the resource is to be used for.

• Localize Resource Type resources

  When a new resource type is created, it is not localized automatically into different languages by default. Administrators must provide localization information for it manually. You can use the Localization tab to do this. For more information, see Introduction to Custom Resource and Attribute Management. The Localization tab includes the following settings:

  • Supported languages – This list displays all the language packs that you install for FIM. This field is not modifiable. The selected value indicates the language in which Localized Display Name and Localized Description will appear.

  • Localized Display Name – This attribute holds the localized version of your resource type's Display Name in the language that you selected. When that locale is used by the user who is accessing the FIM Portal, the Display Name will appear in that language. A different value can be stored for each language pack that you support on the FIM Service server.

  • Localized Description – Like the Localized Display Name, this attribute holds the localized version of your resource type's Description in the language that you selected. When that locale is used by the user who is accessing the FIM Portal, the Description appears in that language. A different value can be stored for each language pack that you support on the FIM Service server.

• Customize Usage Keyword

  You have to modify this attribute through the Advanced View of the selected resource type definition.

  • Usage Keyword – Usage Keyword is used to indicate what resource type is essential for what component or components of FIM. It is a multivalued string attribute. It can be used by the third party ISV developers to mark resource types that are essential to their application. In FIM, the key resource types are protected by the system as well as by selected Management Policy Rules. The following is a list of reserved Usage Keywords for FIM. Microsoft.ResourceManagement is the reserved prefix for Usage Keywords that the Microsoft FIM product team uses. The user cannot remove or modify these Usage Keyword entries on the resource types that contain any of these values.

    Usage Keyword	Description
    Microsoft.ResourceManagement.WebServices	Resource types that contain this Usage Keyword are necessary resource types for the correct internal operation of the FIM Service. Users cannot create a required binding that binds with this resource type. User can only modify Display Name and Description on these resource type definitions.
    Microsoft.ResourceManagement.PortalClient	Resource types that contain this Usage Keyword are necessary resource types for the correct internal operation of the FIM Service. The management policy rule Administration - Schema: Administrators can change selected attributes of schema related resources is used to allow users to modify the Display Name and Description of these resource types.
    Microsoft.ResourceManagement.OfficeIntegration	Resource types that contain this Usage Keyword are necessary resource types for the correct internal operation of the FIM Outlook Add-in client. The management policy rule Administration - Schema: Administrators can change selected attributes of schema related resources is used to allow users to modify the Display Name and Description of these resource types.
    Microsoft.ResourceManagement.PasswordReset	Resource types that contain this Usage Keyword are necessary resource types for correct internal operation of the FIM Password Reset client. The Management Policy Rule Administration - Schema: Administrators can change selected attributes of schema related resources is used to allow users to modify the Display Name and Description of these resource types.

• Grant permission to New Resource Types

  When a new resource type is created, members of the Administrators set must define new Management Policy Rules (MPRs) to grant users (including themselves) the rights to manage them.

• Deleting a resource type

  You cannot delete a resource type after an instance of that resource has been created, even if that instance has been deleted.

  You can delete a resource type if no instances of it have ever been created. However, you must remove all bindings that are attached to the resource before you delete it.

  When a resource is deleted, the resources that depend on the deleted resource may become broken. Before you delete a resource, it is important to check for other resources that depend on that resource.

Attributes

FIM contains a default collection of system attributes. In addition, you can create custom attributes. Attributes may be bound to multiple resource types, and they must be one of the supported FIM data types:

• Binary – This is a Binary data type.

• Boolean – A standard Boolean data type. Multivalued Boolean attributes are not supported in FIM.

• DateTime - The format of DateTime data type is YYYY-MM-DDThh:mm:ss, in compliance with Universal Coordinate Time (UCT).

  Note

  In the FIM Portal, attribute values of this data type will be displayed in the format that is compliant with the current FIM-supported, Internet Explorer language setting.

• Integer - This is a 64-bit integer data type.

• Indexed String - A string that will be indexed for searching, with a maximum length of 448 characters.

• Reference – This data type takes the GUID value of the ObjectID of another known resource in the FIM Service database as its value.

• Unindexed string – A string that cannot be indexed. It is unlimited in length.

When you create or modify a custom attribute, you can perform the following tasks:

• Specify General Settings

  There are five settings on the General tab of the Attribute Type definition:

  • System Name - This is the name that is used to uniquely identify the attribute by the system. You must supply a unique value across all existing attributes when you create a new attribute. After the attribute is created, the System Name cannot be changed. After an attribute name is used, it cannot be reused by other attributes.

    Note

    Do not use MicrosoftResourceManagement as a prefix. It is reserved by the Microsoft FIM product team for future schema expansion. We recommend that you use a prefix that is specific to your environment. This helps avoid clashes of newly added resource types by the FIM product team or by other non-Microsoft vendors in the future.

  • Display Name –This is the user-friendly name that appears in the FIM Portal. This is one of the basic bindings that is described in the previous section. This is a required attribute in the FIM Portal for attribute type definition, and it appears by default in the FIM portal for a custom resource type. Administrators can change this attribute value at any time for any attribute.

  • Data Type – The data type of the new attribute. For descriptions of the supported data types, see the previous section. You must provide this field during creation. After an attribute is created, this setting cannot be modified.

  • Multivalued – Selecting this option allows the attribute to contain multiple entries. This value must be defined during creation, and it cannot be changed after the attribute is created. All data types except Boolean data types can be multivalued.

  • Description – An optional description of the attribute. This appears on the All Attributes page in the FIM Portal to help clarify what the attribute is to be used for.

• Localize Attribute resources

  Like a localization of new resource type, when a new attribute is created, it will not be localized automatically into different languages by default. Administrators have to provide localization information for it manually. The same settings that are used to localize resource types are used here to make it possible for you to do this. For more information, see the “Localize Resource Type resources” section of this document.

• Provide Attribute Schema Validation

  • Validation– This option is available only for Indexed String and Integer data types. It is used to ensure that the value that is entered meets certain criteria.

    • String Pattern – Takes a regular expression to validate the string value. For more information about regular expressions, see this article about Regular Expressions, Second Edition of the W3C Extensible Markup Language (XML) 1.0 (https://go.microsoft.com/fwlink/?LinkId=32824). This validation applies only to attributes with Indexed String as the data type.

    • Minimum Inclusive Integer and Maximum Inclusive Integer – Stores a minimum and maximum range that the entered value must fall between. This validation applies only to attributes with the Integer data type.

• Customize Usage Keyword

  You have to modify this attribute in the Advanced View of the selected attribute definition.

  • Usage Keyword – Usage Keyword is used to indicate what attribute is needed for what component or components of FIM. This is a multivalued string attribute. It can be used by independent software vendor (ISV) developers to mark attributes that are mandatory for their application. In FIM, the key attributes are protected by the system as well as by selected Management Policy Rules. The following table contains a list of reserved Usage Keywords for FIM.Microsoft.ResourceManagement is the reserved prefix for Usage Keywords that are used by the FIM product team. You cannot remove or modify these values on the attributes that contain any of these values.

    Usage Keyword	Description
    Microsoft.ResourceManagement.WebServices	Attributes that contain this Usage Keyword are key attributes for the FIM Service. The user can only modify Display Name and Description on these resource type definitions. This is protected by the system and not configurable. Users cannot delete these attributes.
    Microsoft.ResourceManagement.PortalClient	Attributes that contain this Usage Keyword are key attributes to the FIM Portal. The Management Policy Rule Administration - Schema: Administrators can change selected attributes of schema related resources is used to allow users to modify the Display Name and Description of these attributes.
    Microsoft.ResourceManagement.OfficeIntegration	Attributes that contain this Usage Keyword are key attributes to the FIM Outlook Add-in client. The Management Policy Rule Administration - Schema: Administrators can change selected attributes of schema related resources is used to allow users to modify the Display Name and Description of these attributes.
    Microsoft.ResourceManagement.PasswordReset	Attributes that contain this Usage Keyword are key attributes to the FIM Password Reset client. The Management Policy Rule Administration - Schema: Administrators can change selected attributes of schema related resources is used to allow users to modify the Display Name and Description of these attributes.

• Grant permission to New Attributes

  When a new attribute is created, members of the Administrators set must define new MPRs to grant users (including themselves) rights to manage them.

• Deleting an attribute

  If you add a new attribute to a resource type, the attribute can be removed from the resource type only if it has never been used in any instance of that resource type. If you created a resource type with a valid attribute value, you cannot remove the attribute for that resource type even after you delete the resource type.

  An attribute can be deleted only when it meets all the following conditions:

  • The attribute is not currently bound to any resource type.

  • The attribute is not currently used in any instances of a resource type.

  • The attribute is not currently used in the Allowed Attribute field of any MPRs.

Bindings

A binding maps an attribute to a resource type. A resource type can be bound to multiple attributes, and attributes can be bound to multiple resources, but each binding’s bound attribute and bound resource type combination must be unique. For custom resource types, bound attributes appear automatically in the default detail view of the resource. For system resources, you must modify the RCDC for that resource type in order for them to appear in the UI. For more information, see the Resource Control Display Configuration XML Reference (https://go.microsoft.com/fwlink/?LinkID=183265) in the FIM documentation.

When you create a new binding in the FIM Portal, you can perform the following tasks:

• Define General Settings

  • Resource Type – This specifies the single existing resource that the attribute will be bound to. This attribute must be defined during creation, and it cannot be modified after creation.

  • Attribute Type – This specifies the single existing attribute that will be bound to the selected resource type. This attribute must be defined during creation, and it cannot be modified after creation.

  • Required – Selecting this field specifies that this attribute must have a value when a new instance of the resource type is created or modified. A required field is indicated in the UI, when you create or edit the resource. If an attribute is currently marked as required, the FIM Service permits the administrator to change the Required value from true to false. When you change the value from false to true, all instances of the resource type in the system must already have values defined for this binding. Otherwise, the modification request will fail because there are instances in the store that are not compliant with the new schema. For the same reason, you cannot create a required binding that is bound to resource types that are already instantiated. You must create an optional binding, change all resources of that type to have a value for that binding, and modify the optional binding to Required.

    Note

    Reference-valued attributes cannot be marked as Required.

• Override Bound Attribute Settings

  Users can override bound attribute settings by providing information on the binding. This setting allows attributes to appear differently, depending on the resource type that it binds to. Following is a list of the settings that you can override in the binding.

  Note

  In this release, the administrator must supply a Display Name or Description during the creation of a binding in the FIM Portal. Failure to do this causes the binding to display no name. The default value that appears in the binding Attribute Override tab is not preserved during the creation. You can retype the Display Name or Description that is the same as the default value to give the binding the same Display Name or Description as the default value shown.

  • Attribute Override Display Name – By default, the binding display name is the same as the Display Name of the attribute that is used in the binding. If you want to change the Display Name to something more descriptive of the new binding, enter the new Display Name, and this new name will appear where the binding is listed in the FIM Portal in the bound resource type context.

  • Attribute Override Description – Similar to the Attribute Override Display Name, the Attribute Override Description replaces the binding Description in the FIM Portal when it appears under the bound resource type context.

  • Localization information:

    • Supported Languages

    • Localized Display Name

    • Localized Description

  • Validation – This setting works in the same way as the corresponding attribute settings. When this setting is specified, the attribute has a different validation rule under the bound resource type context.

• Customize Usage Keyword

  You have to modify this attribute through the Advanced View of the selected binding definition.

  • Usage Keyword – Usage Keyword is used to indicate which binding is needed for which components of FIM. It is a multivalued string attribute. It can be used by the ISV developers to mark bindings that are mandatory to their application. In FIM, the key bindings are protected by the system, as well as by selected MPRs. The following table contains a list of reserved Usage Keywords for FIM. Microsoft.ResourceManagement is the reserved prefix for Usage Keywords that are used by the Microsoft FIM product team. Users cannot remove or modify these values on the bindings that contain any of these values.

    Usage Keyword	Description
    Microsoft.ResourceManagement.WebServices	Bindings that contain this Usage Keyword are key attributes to the FIM Service. The user can modify only Display Name and Description on these bindings. This is protected by the system, and it is not configurable. Users cannot delete these bindings.
    Microsoft.ResourceManagement.PortalClient	Bindings that contain this Usage Keyword are key bindings to the FIM Portal. The MPR Administration - Schema: Administrators can change selected bindings of schema related resources is used to allow users to modify the Display Name and Description of these bindings.
    Microsoft.ResourceManagement.OfficeIntegration	Bindings that contain this Usage Keyword are key bindings to the FIM Outlook Add-in client. The MPR Administration - Schema: Administrators can change selected bindings of schema related resources is used to allow users to modify the Display Name and Description of these bindings.
    Microsoft.ResourceManagement.PasswordReset	Bindings that contain this Usage Keyword are key bindings to the FIM Password Reset client. The MPR Administration - Schema: Administrators can change selected bindings of schema related resources is used to allow users to modify the Display Name and Description of these bindings.

Uniqueness Rules

FIM supports the following default uniqueness rules. You cannot update or delete these rules.

• The combination of BoundAttributeType and BoundObjectType must be unique across all BindingDescription instances at the current time.

• Name must be unique across all AttributeTypeDescription instances at the current time.

• Name must be unique across all ObjectTypeDescription instances at the current time.

• ObjectID must be unique across all the resources in FIM.

• Domain and AccountName combination must be unique across all the resource instances. When the Domain attribute does not exist for a resource type, the AccountName attribute must be unique across all the resources in the FIM system. When the AccountName attribute does not exist for a resource type, the uniqueness rule does not apply to the Domain attribute. This is because when a value is not present, it does not qualify as a unique value. When a custom resource type only has Domain as an attribute, but not AccountName as an attribute, the rule does not apply. When a custom resource type only has an AccountName as an attribute, but not Domain as an attribute, the rule does apply among all the AccountName instances without Domain.

Recommendations and Known Issues

Custom resources with ":", "(", or ")" in the name will render the FIM Portal inoperable

In this release, do not use a colon (:) or parentheses [()] in the system name of a custom resource. Creation of custom resources with these characters in the system name will cause the FIM Portal to become inoperable, and a reinstallation of the FIM Portal will be necessary.

Domain attribute binding requires Domain Configuration binding

If you bind the Domain attribute to a resource, you must also bind the Domain Configuration attribute to the resource or the Create request will fail.

Dependency on auditing requirements

We recommend that you not delete your schema resources while you still have auditing requirements for these resources.

Making regular expressions case insensitive

In FIM 2010, it can be helpful to make some regular expressions case insensitive. You can ignore case within a group by using ?!:. For example, for Employee Type, use the following:

^(?!:contractor|full time employee)%

Calculation of the member attribute

The Member attribute that the mms Management Agent provides to the synchronization engine during an import run is actually mapped to ComputedMember. The value of ComputedMember is generated automatically as a combination of criteria-based members and manually selected members.

The following attributes cannot be bound to any resources other than Group or Set:

• ExplicitMember

• Filter

• ComputedMember

To achieve similar functionality when you synchronize a custom resource, you must create a custom reference-valued attribute—for example, ExplicitMember2—and bind it to your custom resource.

Strings with leading and trailing spaces

In FIM, you can enter strings with leading spaces and trailing spaces. However, the FIM Service and the FIM Synchronization Service ignore those spaces. If you submit a string with a leading space and a trailing space, the synchronization engine and Web services ignore those spaces.

Empty strings

For string-valued attributes, an empty string value is not the same as an absence of a value. Empty string input is regarded as a valid value. Not present is regarded as a null.

Making certain unsupported attributes required

The following attribute types are not supported:

1. Multivalued binary

2. Multivalued text

If you create these attributes, designate them as required, and then bind a resource to them, you will not be able to create that resource or update any existing instance of that resource in the FIM Portal UI. You will receive an error message when you attempt to submit the change.

To work around this issue, either mark the attribute as not required, or, if it must be required, do not expose it in the FIM Portal.