Defining relationship groups

If multiple relationships are required to grant a user access to certain resource, use the RelationGroup construct. However a relationship usually satisfies most of the requirement for this scenario. Relationship groups contain open conditions which are the conditions for belonging to the relationship group. If you need to define relationship groups, you must do so by defining the relationship group information in your XML file, or by modifying the defaultAccessControlPolicies.xml file.

<RelationGroup Name="aValue" OwnerID="Root Organization">
        <RelationCondition>
                <profile>                        
                    Relationship Chain Open Condition XML
                </profile>;
        </RelationCondition>;
</RelationGroup>;

Relationship chains

Each relationship group consists of one or more RELATIONSHIP_CHAIN open conditions, grouped by andListCondition or orListCondition elements. A relationship chain is a series of one or more relationships. The length of a relationship chain is determined by the number of relationships it consists of. To determine the length of the relationship chain, count the number of <parmeter name= "X" value="Y"> entries in the XML representation of the relationship chain. The following is an example of a relationship chain with a length of one.

<openCondition name="RELATIONSHIP_CHAIN">
   <parameter name="RELATIONSHIP" value="aValue"/>
</openCondition>;
where:
aValue
A string representing the relationship between the user and the resource. Ensure that the string is one of the relationships checked in the fulfills method of the resource.
When a relationship chain has a length of two or more it is a series of two relationships. The first <parmeter name= "X" value="Y"> entry is between a user and an organizational entity. The last <parmeter name= "X" value="Y"> entry is between an organizational entity and the resource. Intermediate <parmeter name= "X" value="Y"> entries in the chain are between organizations. The following is an example of a relationship chain with a length of two.
<openCondition name=RELATIONSHIP_CHAIN">
   <parameter name="aValue1" value="aValue2"/>
   <parameter name="RELATIONSHIP" value="aValue3"/>
</openCondition>;
where:
aValue1
Possible values include HIERARCHY and ROLE. HIERARCHY specifies that there is a hierarchical relationship between the user and the organizational entity in the membership hierarchy. ROLE specifies that the user plays a role in the organizational entity. If the value of aValue1 is HIERARCHY, the possible values of aValue2 include child. The value child returns the organizational entity for which the user is a direct child in the member hierarchy. If the value of aValue1 is ROLE, possible values of aValue2 include any valid entries in the NAME column of the ROLE table which return all of the organizational entities for which the current user plays this role.
aValue3
A string representing the relationship between one or more organizational entities retrieved from evaluating the first parameter and the resource. This value corresponds to the relationship parameter of the fulfills() method on the protectable resource. If more than one organizational entity was returned by evaluating parameter aValue1, this part of the RELATIONSHIP_CHAIN is satisfied if at least one of these organizational entities satisfies the relationship specified by parameter aValue2.

For more information about defining relationships, see Defining relationships.

Defining single-chain relationship groups

For example, to create an access control policy that enforces that a user must belong to the organizational entity of the resource, create a relationship group that is composed of one relationship chain that has a length of two.
<RelationGroup Name="MemberOf->;BuyerOrganizationEntity" OwnerID="RootOrganization">
   <RelationCondition>
      <profile>
         <openCondition name="RELATIONSHIP_CHAIN">
            <parameter name="HIERARCHY" value="child"/>
            <parameter name="RELATIONSHIP" value="BuyingOrganizationalEntity"/>
         </openCondition>
      </profile>
   <RelationCondition>
<RelationGroup>

The relationship chain has a length of two because it consists of two separate relationships. The first relationship is between the user and its parent organizational entity. The user is the child in that relationship. For the second relationship, the access control policy manager checks if the parent organizational entity fulfills the BuyingOrganizationalEntity relationship with the resource. In other words, it returns true if it is the buying organizational entity of the resource.

Another example is an access control policy that enforce that a user has the role of Account Representative for the organizational entity that is the buying organizational entity of the resource. Again, this policy uses a relationship group that is composed of one relationship chain of a length of two. The first part of the chain finds all of the organizational entities for which the user has the Account Representative role. Then for the set of organizational entities, the access control policy manager checks if at least one of them fulfills the BuyingOrganizationalEntity relationship with the resource. If it does, a value of true is returned.

The following example shows how to define this type of relationship group:
<RelationGroup Name="AccountRep->BuyerOrganizationalEntity" OwnerID="RootOrganization">
   <RelationCondition>
      <profile>
          <openCondition name="RELATIONSHIP_CHAIN">
             <parameter name="ROLE" value="Account Representative"/>
             <parameter name="RELATIONSHIP" value="BuyingOrganizationalEntity"/> 
         </openCondition>
       </profile>
   <RelationCondition>
<RelationGroup>

Defining multiple-chain relationship groups

To compose a relationship group that contains a multiple-chain relationship, specify whether the user must satisfy all of the relationship chains or if the user must satisfy at least one of the relationship chains.

In the following example, the user must be the creator of the resource and must belong to the BuyingOrganizationalEntity specified in the resource. The first chain, that specifies the user must be the creator of the resource is has a length of one. The second chain, that specifies that the user must belong to the BuyingOrganizationalEntity specified in the resource, has a length of two.
<RelationshipGroup Name="Creator_And_MemberOf->BuyerOrganizationalEntity" OwnerID="RootOrganization">
   <RelationCondition>
      <profile>
            <andListCondition>
               <openCondition name="RELATIONSHIP_CHAIN">
                  <parameter name="RELATIONSHIP" value="creator" />
               </openCondition>
               <openCondition name="RELATIONSHIP_CHAIN">
                  <parameter name="HIERARCHY" value="child"/>
                  <parameter name="RELATIONSHIP" value="BuyingOrganizationalEntity"/>
               </openCondition>
            </andListCondition>
      </profile>
   </RelationCondition>
</RelationGroup>

If you require the user to satisfy either of the two relationship chains, change the <andListConditon> tag to the <orListConditon> tag.