Page Comparison

PAGS Overview

The PAGS defines group memberships by logical expressions on attributes retrieved by PersonDirectory. (PersonDirectory initializes IPersons with attributes retrieved from one or more sources of directory information, including, for example LDAP.)

Capabilities of PAGS

PAGS computes entity memberships by testing the value of selected IPerson attributes. Like PersonDirectory, the PAGS retrieves information one user at a time. As a result, it can answer inquiries about what groups a particular IPerson or _group member_ belongs to, but it cannot answer inquiries about what entity members are contained by a given group.

Can do:

Code Block
contains() find() findContainingGroups()

Can't do:

Code Block
findEntitiesForGroup()

Although PAGS groups cannot answer their entity members, they are aware of their member groups. So they can also do:

Can do

Code Block
findMemberGroupKeys() findMemberGroups()

...

Tests. Each of the tests to be applied to an IPerson is described in a <test> element, which consists of 3 required sub-elements, the name of the test class, the name of the attribute to be tested, and the value against which the attribute is to be tested by the tester class. In the example below, the test is true if the String value of the attribute "sn" equals "Jones".

Code Block

	xml
	xml


<test>
    <attribute-name>sn</attribute-name>
    <tester-class>org.jasig.portal.groups.pags.testers.StringEqualsTester</tester-class>
    <test-value>Jones</test-value>
</test>

The PAGS currently ships with 8 tester classes, and you can easily create your own. Each tester class must implement the IPersonTester interface, which consists of a single method:

Code Block

	java
	java

  public interface IPersonTester {
    public boolean test(IPerson person);
}

...

Tester	Use
IntegerEQTester	Converts attribute and test value to ints. Attribute must be EQ to the test value. In the event of a NumberFormatException, the test fails (true for all Integer testers.)
IntegerGETester	Attribute must be GE test value.
IntegerGTTester	Attribute must be GT test value.
IntegerLETester	Attribute must be LE test value.
IntegerLTTester	Attribute must be LT test value.
RegexTester	Attribute must match a regular expression. Do not include the delimiter.
StringEqualsIgnoreCaseTester	String comparison ignoring case.
StringEqualsTester	String comparison.
ValueExistsTester	True if the attribute has any non-blank value.
ValueMissingTester	True if the attribute is null or none of its values equals the specified value.

...

Recursive Testing. If one PAGS group (the child group) belongs to another PAGS group (the parent group), then an IPerson member of the child group must also pass the test(s) required for membership in the parent group. This is a more restrictive contract than the group system in general requires, where membership in a group only means that some relationship exists between a group and its members. Here, when an entity group member belongs to a group, it means that the underlying entity has some specific attribute value(s). The PAGS enforces this by testing the entity for membership in all its parent groups, which means you can nest the testing of entity members. For example, assume a group named named "employees" requires status equal to "employed" and a group named "seniors" requires age GE 65. If "seniors" is a member of "employees", then any IPerson member of "seniors" is required to have both age GE 65 and status equal to "employed".

Configuring the Store

Step 1. Modify the PAGSGroupStoreConfig.xml file

1. Open the PAGSGroupStoreConfig.xml file for editing, located in your uPortal source directory at uportal-imp/src/main/resources/properties/groups/PAGSGroupStoreConfig.xml
2. Declare a new group.

Below is an example of an "All Staff" group that groups users based on if the attribute eduPersonAffiliation=staff

Code Block

	xml
	xml


<!-- Example Group Declarations --> 

<?xml version="1.0"?>
<!DOCTYPE Group-Store PUBLIC "-//uPortal//PAGSGroupStore/EN" "PAGSGroupStore.dtd">
<Group-Store>

<!-- Group declarations: -->

<!--
  Group pags_root: "PAGS Root"
  IMPORTANT: The PAGS Root group is REQUIRED for uPortal to function. It Must be a member of the Everyone group in the
  local group store
-->
  <group>
    <group-key>pags_root</group-key>
    <group-name>PAGS Root</group-name>
    <group-description>Root group for all PAGS groups.  Convenience for adding PAGS groups to a local group.</group-description>
    <members>
      <member-key>all_users</member-key>
    </members>
  </group>


<!--
  Group all_users: "All Users (PAGS)"
  All IPersons are memebers of this group
  IMPORTANT: The All Users group is REQUIRED for uPortal to function. It Must be a member of the PAGS Root group
-->
  <group>
    <group-key>all_users</group-key>
    <group-name>All Users (PAGS)</group-name>
    <group-description>All Portal Users</group-description>
    <selection-test>
      <test-group>
        <test>
          <attribute-name></attribute-name>
          <tester-class>org.jasig.portal.groups.pags.testers.AlwaysTrueTester</tester-class>
          <test-value></test-value>
        </test>
      </test-group>
    </selection-test>
   <!-- Don't forget to define your new sub-group using the members directive if you want the group to be a sub-group of "All Users" -->
   <members>
      <member-key>all_staff</member-key>
    </members>
  </group>

<!-- ********** Here's our new "All Staff" group we are declaring *********** -->
<group>
<group-key>all_staff</group-key>
    <group-name>All Staff (PAGS)</group-name>
    <group-description>All Staff Users</group-description>
    <selection-test>
      <test-group>
        <test>
          <attribute-name>eduPersonAffiliation</attribute-name>
          <tester-class>org.jasig.portal.groups.pags.testers.StringEqualsTester</tester-class>
          <test-value>staff</test-value>
        </test>
      </test-group>
    </selection-test>
   </group>

...

<!-- End Group declarations: -->
</Group-Store>

Now, what if I wanted to refine the staff group into departments? Below is an additional example that groups "All Staff" users from above into departments based on if the attribute ou=ITS (Information Technology Services)

Code Block

	xml
	xml


<!-- Example Group Declarations -->

<?xml version="1.0"?>
<!DOCTYPE Group-Store PUBLIC "-//uPortal//PAGSGroupStore/EN" "PAGSGroupStore.dtd">
<Group-Store>
<!-- Group declarations: -->

<!--
  Group pags_root: "PAGS Root"
  IMPORTANT: The PAGS Root group is REQUIRED for uPortal to function. It Must be a member of the Everyone group in the
  local group store
-->
  <group>
    <group-key>pags_root</group-key>
    <group-name>PAGS Root</group-name>
    <group-description>Root group for all PAGS groups.  Convenience for adding PAGS groups to a local group.</group-description>
    <members>
      <member-key>all_users</member-key>
    </members>
  </group>


<!--
  Group all_users: "All Users (PAGS)"
  All IPersons are members of this group
  IMPORTANT: The All Users group is REQUIRED for uPortal to function. It Must be a member of the PAGS Root group
-->
  <group>
    <group-key>all_users</group-key>
    <group-name>All Users (PAGS)</group-name>
    <group-description>All Portal Users</group-description>
    <selection-test>
      <test-group>
        <test>
          <attribute-name></attribute-name>
          <tester-class>org.jasig.portal.groups.pags.testers.AlwaysTrueTester</tester-class>
          <test-value></test-value>
        </test>
      </test-group>
    </selection-test>
    <!-- Don't forget to define your new sub-group using the members directive if you want the group to be a sub-group of "All Users" -->  
    <members>     
      <member-key>all_staff</member-key>
    </members>
  </group>

<group>
<group-key>all_staff</group-key>
    <group-name>All Staff (PAGS)</group-name>
    <group-description>All Staff Users</group-description>
    <selection-test>
      <test-group>
        <test>
          <attribute-name>eduPersonAffiliation</attribute-name>
          <tester-class>org.jasig.portal.groups.pags.testers.StringEqualsTester</tester-class>
          <test-value>staff</test-value>
        </test>
      </test-group>
    </selection-test>
    <!--
         If you want to declare a group within another, you must include the <members> directive.
         In other words, the "ITS Dept" below is a subgroup of the "All Staff" group as indicated in the example
     -->
    <members>
      <member-key>its</member-key>
    </members>
</group>

<group>
<group-key>its</group-key>
    <group-name>ITS Dept (PAGS)</group-name>
    <group-description>All ITS department Users</group-description>
    <selection-test>
      <test-group>
        <test>
          <attribute-name>ou</attribute-name>
          <tester-class>org.jasig.portal.groups.pags.testers.StringEqualsTester</tester-class>
          <test-value>ITS</test-value>
        </test>
      </test-group>
    </selection-test>
</group>


...

<!-- End Group declarations: -->
</Group-Store>

From the example above we have created a hierarchy of groups (below is a screen shot of the Groups Manager listing the new PAGS groups from the declaration above)

Warning
NOTE: It's very important that you keep the PAGS Root and All Users group declaration. These group declarations are REQUIRED.

Step 2. Deploy your Groups

From the uPortal root source directory deploy your group changes

No Format
ant clean deploy-ear

Step 3. Restart uPortal

Restart your Tomcat instance

No Format
TOMCAT_HOME/bin/shutdown.sh TOMCAT_HOME/bin/startup.sh

...

Versions Compared

Old Version 3

New Version 4

Key

PAGS Overview

Capabilities of PAGS

Can do:

Can't do:

Can do

Configuring the Store

Step 1. Modify the PAGSGroupStoreConfig.xml file

Step 2. Deploy your Groups

Step 3. Restart uPortal