uPortal 4.1+ DB-backed PAGS store

With uPortal 4.1 the default configuration for PAGS is a database-backed storage. To use the previous XML-based configuration alter the file pags.properties to set the property org.jasig.portal.groups.pags.PersonAttributesGroupStore.configurationClass=org.jasig.portal.groups.pags.XMLPersonAttributesConfiguration, then follow the uPortal 4.0 instructions below.

Step 1: Modify default.person-attribute-group-store.xml

...

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

...

uPortal 4.1/4.2 DB-backed PAGS store

With uPortal 4.1 there is an optional database-backed storage configuration for PAGS. To use the default XML-based configuration, see the XML-backed PAGS instructions below. With uPortal 4.2, the DB-backed PAGS (also called Entity-based PAGS or Entity PAGS) is the default configuration.

The advantage of the DB-backed PAGS store is that you can create or modify PAGS groups on the fly by importing the PAGS XML files so it is more dynamic than the XML-backed PAGS . Also DB-backed PAGS groups are required for certain features such as Multi-Tenancy that require dynamic PAGS groups.

Step 1: Create your new pags-group xml file

1. Create a new xml file such as uportal-war/src/main/data/default_entities/pags-group/staff.pags-group.xml.

For these examples the new PAGS groups are being created in default_entities because they will be added to PAGS groups defined in default_entities. Another strategy is to copy default_entities/pags-group/* to quickstart_entities/pags-group and add make the modifications in quickstart_entitites directory.

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

Code Block

	xml
	xml

<?xml version="1.0" encoding="UTF-8"?>
<pags-group script="classpath://org/jasig/portal/io/import-pags-group_v4-1.crn">
    <name>All Staff (PAGS)</name>
    <description>All Staff Users</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>
</pags-group>

Below is an additional example that groups "All Staff" users from above into a department based on if the attribute ou=ITS (Information Technology Services)

Code Block

	xml
	xml

<?xml version="1.0" encoding="UTF-8"?>

<pags-group script="classpath://org/jasig/portal/io/import-pags-group_v4-1.crn">
    <name>ITS Dept (PAGS)</name>
    <description>All ITS department Users</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>
        <name><</name>test>
        <description></description></test-group>
    </selection-test>
   <test>
          <name></name>
          <description></description>
          <attribute-name></attribute-name>
          <tester-class>org.jasig.portal.groups.pags.testers.AlwaysTrueTester</tester-class>
          <test-value></test-value>
        </test>
      </test-group>
    </selection-test>
  </pags-group>

<!-- ********** Here's our new "All Staff" group we are declaring *********** -->
  <pags-group>
    <name>All Staff (PAGS)</name>
    <description>All Staff Users</description>
    <selection-test>
      <test-group>
        <name></name>
        <description></description>
        <test>
          <name></name>
          <description></description>
          <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>
  </pags-group>

...

<!-- End Group declarations: -->
</pags-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

<!-- Example Group Declarations --> 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<pags-store xmlns="https://source.jasig.org/schemas/uportal/io/pags" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://source.jasig.org/schemas/uportal/io/pags https://source.jasig.org/schemas/uportal/io/pags/pags-4.1.xsd">
    <name>Default</name>
    <description>Default Person Attribute Group Store</description>

<!-- 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
-->
  <pags-group>
    <name>PAGS Root</name>
    <description>Root group for all PAGS groups.  Convenience for adding PAGS groups to a local group.</description>
    <members>
      <member-key>All Users (PAGS)</member-key>
      <member-key>Authenticated Users</member-key>
      <member-key>Desktop Device Access</member-key>
      <member-key>Mobile Device Access</member-key>
      <member-key>Respondr Theme Users</member-key>
    </members>
  </pags-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
-->
  <pags-group>
    <name>All Users (PAGS)</name>
    <description>All Portal Users</description>
    <members>
      <member-key>All Staff</pags-group>

2. Add the new PAGS group to the PAGS Root group or wherever appropriate

To allow finding the new group in the Manage Groups admin UI, the group should be included as a member of an existing group. The PAGS Root or another PAGS group are logical places (arguably for this example the 'All Staff (PAGS)' group should also be added to the uportal-war/src/main/data/quickstart_entities/group_membership/Staff.group-membership.xml Staff local group since the Staff local group is used extensively in role-based permission checks).

Add to PAGS Root group

Code Block

language	xml
title	uportal-war/src/main/data/default_entities/pags-group/PAGS_Root.pags-group.xml

<pags-group script="classpath://org/jasig/portal/io/import-pags-group_v4-1.crn">
  <name>PAGS Root</name>
  <description>Root group for all PAGS groups.  Convenience for adding PAGS groups to a local group.</description>
  <members>
    <member-name>All Users (PAGS)</member-key>name>
    </members>
    <selection-test><member-name>Authenticated Users</member-name>
      <test<member-group>name>Desktop         <name></Device Access</member-name>
    <member-name>Mobile Device   <description></description>
        <test>
  Access</member-name>
    <member-name>Respondr Theme  <name><Users</member-name>
    <member-name>All Staff (PAGS)</member-name>  <!-- new <description></description>group added -->
        <attribute-name></attribute-name>
          <tester-class>org.jasig.portal.groups.pags.testers.AlwaysTrueTester</tester-class>
          <test-value></test-value>
        </test>
      </test-group>
    </selection-test>
  </pags-group>

<!-- ********** Here's our new "All Staff" group we are declaring *********** -->
  <pags-group>
    <name>All Staff (PAGS)</name>
    <description>All Staff Users</description>
    <!--
         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 Dept (PAGS)</member-key>
    </members>
    <selection-test>
      <test-group>
        <name></name>
        <description></description>
        <test>
          <name></name>
          <description></description>
          <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>
  </pags-group>

  <pags-group>
    <name>ITS Dept (PAGS)</name>
    <description>All ITS department Users</description>
    <selection-test>
      <test-group>
        <name></name>
        <description></description>
        <test>
          <name></name>
          <description></description>
          <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>
  </pags-group>


...

<!-- End Group declarations: -->
</pags-store>

...

Image Removed

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

Code Block

language	bash

# creates tables and imports the PAGS data
ant clean initdb

Step 3: Restart uPortal

Restart your Tomcat instance

Code Block

language	bash

TOMCAT_HOME/bin/shutdown.sh
TOMCAT_HOME/bin/startup.sh

Upgrading from XML-backed PAGS to database-backed PAGS

Update code base to 4.1 (4.1 will include the change to pags.properties to toggle the configuration to be Entity based)
Run initdb or dbupdate and then import Default.pags-store.xml

uPortal 4.0 XML-backed PAGS store

...

</members>
</pags-group>

Example of adding to hierarchy

Code Block

language	xml
title	uportal-war/src/main/data/default_entities/pags-group/All_Users.pags-group.xml

<pags-group script="classpath://org/jasig/portal/io/import-pags-group_v4-1.crn">
  <name>All Users (PAGS)</name>
  <description>All Portal Users</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>
  <members>
    <member-name>All Staff (PAGS)</member-name>  <!-- new group added -->
  </members>
</pags-group>

From the example above we have created a hierarchy of groups (below is a screen shot of the Groups Administration listing the new PAGS groups, ITS Dept (PAGS), from the declaration above).

Image Added

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

Code Block

language	bash

# creates tables and imports the PAGS data
ant clean initdb

 
# or
ant data-import -Ddir=uportal-war/src/main/data/default_entities/pags-group

Step 3: Restart uPortal

If you initialized the database, restart your Tomcat instance

Code Block

language	bash

TOMCAT_HOME/bin/shutdown.sh
TOMCAT_HOME/bin/startup.sh

Upgrading from XML-backed PAGS to database-backed PAGS

1. Update code base to 4.1

2. Incorporate your custom changes from PAGSGroupStoreConfig.xml into separate *.pags-group.xml files in uportal-war/src/main/data/default_entities/pags-group

3. Alter uportal-war/src/main/resources/properties/groups/compositeGroupServices.xml to switch from XML-based to database-based PAGS groups.

Code Block

<!--
 | Configure your person attributes groups for the entity implementation of PAGS.  PAGS data is defined in
 | *.pags-group.xml files that are imported into the database.
 |
 | IMPORTANT: The pags service is REQUIRED for uPortal to correctly function.  Do not comment out
 | this service unless you uncomment the XML PAGS implementation below
 +-->
  <service>
    <name>pags</name>
    <service_factory>org.jasig.portal.groups.ReferenceIndividualGroupServiceFactory</service_factory>
    <entity_store_factory>org.jasig.portal.groups.pags.dao.EntityPersonAttributesEntityStoreFactory</entity_store_factory>
    <group_store_factory>org.jasig.portal.groups.pags.dao.EntityPersonAttributesGroupStoreFactory</group_store_factory>
    <entity_searcher_factory>org.jasig.portal.groups.pags.dao.EntityPersonAttributesEntitySearcherFactory</entity_searcher_factory>
    <internally_managed>false</internally_managed>
    <caching_enabled>true</caching_enabled>
  </service>
<!--
 | Used for XML PAGS implementation. PAGS data is defined in PAGSGroupStoreConfig.xml.
 |
 | IMPORTANT: The pags service is REQUIRED for uPortal to correctly function.  Do not comment out this
 | service unless you uncomment the entity PAGS implementation above.
 +-->
<!--
  <service>
    <name>pags</name>
    <service_factory>org.jasig.portal.groups.ReferenceIndividualGroupServiceFactory</service_factory>
    <entity_store_factory>org.jasig.portal.groups.pags.PersonAttributesEntityStoreFactory</entity_store_factory>
    <group_store_factory>org.jasig.portal.groups.pags.PersonAttributesGroupStoreFactory</group_store_factory>
    <entity_searcher_factory>org.jasig.portal.groups.pags.PersonAttributesEntitySearcherFactory</entity_searcher_factory>
    <internally_managed>false</internally_managed>
    <caching_enabled>true</caching_enabled>
  </service>
-->

4. Rebuild and redeploy uPortal (ant clean deploy-war)

5. Run initdb, or run dbupdate and then import PAGS xml files (see previous - may need to reimport all files from src/main/data if PAGS groups are referenced in local groups, portlet definitions, or other locations).

XML-backed PAGS store (default)

With uPortal 4.0 and the default uPortal 4.1 configuration, the PAGS configuration is stored in an XML file PAGSGroupStoreConfig.xml. uPortal 4.1 by default uses a DB-backed store. Changes cannot be imported into the system. uPortal must be rebuilt and redeployed to parse the XML file to define the groups.

Step 1: Modify the PAGSGroupStoreConfig.xml file

...

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 memebersmembers 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>

...

Versions Compared

Old Version 10

New Version Current

Key

uPortal 4.1+ DB-backed PAGS store

Step 1: Modify default.person-attribute-group-store.xml

uPortal 4.1/4.2 DB-backed PAGS store

Step 1: Create your new pags-group xml file

Step 2: Deploy your Groups

Step 3: Restart uPortal

Upgrading from XML-backed PAGS to database-backed PAGS

uPortal 4.0 XML-backed PAGS store

Step 2: Deploy your Groups

Step 3: Restart uPortal

Upgrading from XML-backed PAGS to database-backed PAGS

1. Update code base to 4.1

XML-backed PAGS store (default)

Step 1: Modify the PAGSGroupStoreConfig.xml file

Page Comparison

Versions Compared

Old Version 10

New Version Current

Key

uPortal 4.1+ DB-backed PAGS store

Step 1: Modify default.person-attribute-group-store.xml

Step 1: Create your new pags-group xml file

Step 2: Deploy your Groups

Step 3: Restart uPortal

Upgrading from XML-backed PAGS to database-backed PAGS

uPortal 4.0 XML-backed PAGS store

Step 2: Deploy your Groups

Step 3: Restart uPortal

Upgrading from XML-backed PAGS to database-backed PAGS

1. Update code base to 4.1

XML-backed PAGS store (default)

Step 1: Modify the PAGSGroupStoreConfig.xml file