Share via


Role Object (Model Designer)

The Role object defines a role of an entity. A role is a description of two related entities. This object inherits properties from the Field object.

Properties

Name

Cardinality

Type

Description

Name

0-1

String

The name of the role. If the Cardinality is One or OptionalOne, the Name of the related entity is the default. Otherwise, the string value defaults to the CollectionName of the related entity.

Linguistics

0-1

Object

The Linguistics properties of the role. This element is not allowed if Name is omitted. In this case, SingularName and PluralName default to the Name and Collection of the related entity, respectively.

RelatedRoleID

1

String

The ID of the corresponding role on the target entity. This role cannot be the RelatedRole. In addition, the RelatedRole of the RelatedRole must be this role.

Cardinality

1

Enum

There are four options: One, Many, OptionalOne, OptionalMany.

ContextualName

0-1

Enum

When the role is used to reach the entity, the ContextualName enumerator overrides the ContextualName setting for attributes in the role's target entity. The enumerator can be one of three values: Attribute, Merge, or Role. The enumerator value defaults to Attribute, which uses the attribute name as the contextual name. Specify Merge to cause the attribute name and role name to be merged and used as the contextual name. If this attribute is the single identifying attribute of the entity, specifying Role uses the role name as the contextual name. If it is not the single identifying attribute of the entity, Role is treated like Merge.

HiddenFields

0-1

Object

A set of fields and field folders that the client application should not display for the role's target entity when the role is used to reach the entity. For example, the AddressType attribute should be hidden when Address is displayed by using the HomeAddress role.

ExpandInline

0-1

Boolean

Indicates that the client application should not show the role to the user and that the fields of the related entity should be displayed instead as if they were part of this entity. Role expansion is favored over lookup behavior when both are specified.

PromoteLookup

0-1

Boolean

Indicates that the client application, when the containing entity is displayed as a lookup, also displays the target entity as a lookup. This value is allowed only if the role's containing entity and target entity are both lookup entities. Lookup roles on the related entity of a lookup role are promoted if the value of PromoteLookup is true and the promoted role's related entity is not the entity to which the role is being promoted or one of its direct ancestors or descendents.

Preferred

0-1

Boolean

Indicates that Paths containing this role should be preferred over Paths that do not contain preferred roles. Use this Boolean to indicate which path should be used to reach another entity when there is more than one path from which to choose.

Recursion

0-1

Boolean

Indicates whether the relationship should be traversed recursively by default. Recursion is allowed only if the containing entity is the same as the target entity. Roles are recursively expanded, but the recursion stops when a attempt is made to expand items from entity A into the context of A, or one of its direct ancestors or descendents.

Binding

0-1

Object

The database object that represents this role. Note that the specified end of the relation must bind to columns in the table to which the Entity containing the RelatedRole element is bound, or equal to the column to which that entity is bound. The other end of the relation must be in the table to which this Role's containing Entity is bound, or equal to the column to which this entity is bound. Binding is required unless this Role's entity is bound to a table that contains the column to which the RelatedRole's entity is bound (or vice versa). In this case, the containment relationship between the column and the table is implied, and the binding is not specified.

Remarks

In Report Builder, a role is a description of the relationship between two entities.

For more information about valid Enum values, see Model Designer Data Types.