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 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.
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 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>
<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> |
- 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 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> <name></name> <description></description> <test> <name></name> <description></description> <attribute-name><name>ou</attribute-name> <tester-class>org.jasig.portal.groups.pags.testers.AlwaysTrueTester<StringEqualsTester</tester-class> <test-value><value>ITS</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 | xml | <!-- Example Group Declarations |
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 | ||||
|---|---|---|---|---|
| ||||
<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 --> <?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/members> </pags-group> |
- Example of adding to hierarchy
| Code Block | ||||
|---|---|---|---|---|
| ||||
<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-key>name> <!-- new group added <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)</member-key> </members> <selection-test> <test-group> <name></name> <description></description> <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> <!-- 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> |
...
| 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 | ||
|---|---|---|
| ||
# creates tables and imports the PAGS data
ant clean initdb
|
Step 3: Restart uPortal
- Restart your Tomcat instance
| Code Block | ||
|---|---|---|
| ||
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> |
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).
| 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 | ||
|---|---|---|
| ||
# 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 | ||
|---|---|---|
| ||
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 | ||||
|---|---|---|---|---|
| ||||
<!-- 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> |
...