Configuring Person Attribute Group Store (PAGS)
DB-backed PAGS store (default with uPortal 4.2)
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 or Custom PAGS groups (uPortal 4.3 only).
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
<?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)
<?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>
</test>
</test-group>
</selection-test>
</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
<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-name>
<member-name>Authenticated Users</member-name>
<member-name>Desktop Device Access</member-name>
<member-name>Mobile Device Access</member-name>
<member-name>Respondr Theme Users</member-name>
<member-name>All Staff (PAGS)</member-name> <!-- new group added -->
</members>
</pags-group>
- Example of adding to hierarchy
<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).
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
# 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
TOMCAT_HOME/bin/shutdown.sh TOMCAT_HOME/bin/startup.sh
Upgrading from XML-backed PAGS to database-backed PAGS
With uPortal 4.2 there is a groovy script that can be executed with the command 'ant pagsXmlToEntity -Ddir=outputDir' that will process the XML PAGS file and output
- A set of PAGS entity files representing the data that can be included in uportal-war/src/main/data for the initdb process, or imported into an existing database via 'ant data-import -Dir=outputDir'
- A sql file that can be run on an existing database created when using XML-based PAGS to update the PAGS names referenced in the database from the XML-based PAGS name to the database-based PAGS name that is required when using the database-backed PAGS configuration.
You will still need to have uportal-war/src/main/resources/properties/groups/compositeGroupServices.xml configured for 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.
<!--
| 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 in uPortal 4.1)
With uPortal 4.0 and the default uPortal 4.1 configuration, the PAGS configuration is stored in an XML file PAGSGroupStoreConfig.xml. 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
1. Open uportal-war/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
<!-- 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>
<!-- ********** 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)
<!-- 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 Administration listing the new PAGS groups, ITS Dept (PAGS), from the declaration above).
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
ant clean deploy-war
Step 3: Restart uPortal
- Restart your Tomcat instance
TOMCAT_HOME/bin/shutdown.sh TOMCAT_HOME/bin/startup.sh