Pulled DLM Fragments

Pulled DLM Fragments Overview

Yale University has donated an implementation of pulled DLM fragments that relies on DLM evaluators to allow users to choose to subscribe to appropriately-permissioned fragments. This code has been integrated into the pre-3.3 trunk by Unicon on behalf of Brigham Young University.

Architecture

Permissions Framework

This feature introduces a new permissions owner named "UP_FRAGMENT" and a new permission activity with the fname "FRAGMENT_SUBSCRIBE." This activity represents the ability to subscribe to the fragment layout owned by the target user.

By default, uPortal now includes a "Subscribable Fragments" subgroup of the "Fragment Owners" group. To create a new subscribable fragment, a uPortal administrator might perform the following steps:

1. Create a new user, potentially by importing a new .user file.
2. Add an appropriate fragment definition to dlm.xml (described below).
3. Add this user to the "Subscribable Fragments" group. This step will ensure that the user is both available in the Fragment Administration portlet and is available as a subscription option.
4. Configure the desired fragment layout for the new user, either by importing a .fragment-layout file or by impersonating the user.

While the default "Subscribable Fragments" group allows any user to subscribe to a fragment, institutions are free to design more complex and interesting permissions rules. For example, an administrator might choose to grant the "FRAGMENT_SUBSCRIBE" permission on an "Academics" fragment only to users in the "Students" group. At that point, the fragment in question would only appear in the subscribable tabs list to members of the specified group.

Fragment Subscription Store

Fragment subscriptions are persisted to the uPortal database in a new JPA-managed table. This table records subscribed fragments for each user by associating the user's internal ID with a fragment owner's username. When a user unsubscribes from a previously-selected fragment, the fragment subscription is marked as inactive in the database.

Subscribed Tab DLM Evaluator

Subscribed tabs are included in a user's layout by a special DLM evaluator. While most DLM fragments are traditionally loaded based on decisions about the user's attributes or group membership, the new SubscribedTabEvaluator determines if the user should receive a tab based on registered fragment subscriptions. This evaluator also checks the permissions system to ensure that the user is still permitted to subscribe to the fragment in question.

In order for a user to inherit a subscribed fragment, the following conditions must be met:

1. An active fragment subscription must exist for the logged in user for the fragment in question.
2. The user must have the FRAGMENT_SUBSCRIBE permission on the fragment.

Sample subscribable tab fragment definition:

  <dlm:fragment name='News' ownerID='news-lo' precedence='60'>
    <dlm:audience evaluatorFactory="org.jasig.portal.layout.dlm.providers.SubscribedTabEvaluatorFactory"/>
  </dlm:fragment>

The fragment definition above configures the fragment layout owned by the "news-lo" user as a subscribable tab. The SubscribedTabEvaluatorFactory automatically configures an evaluator using the parent dlm:fragment element's ownerID as the fragment username, so it's not necessary to define any child elements of the dlm:audience.

Institutions adopting pulled DLM fragments may find it desirable to configure DLM fragment definitions through the database: Defining Fragments as Database Entities.

Limitations

Duplicate Subscriptions

Because the solution described above relies on a DLM evaluator including a fragment in a user's layout, a user may only subscribe to each pulled tab once.

Multi-tabbed Fragments

The current logic for unsubscribing from a pulled tab is unlikely to work well for multi-tabbed fragments.

Future Enhancements

In order to support subscribing to a tab mulitple times, we might someday create a new DLM node type representing a pulled fragment. Placing a fragment in a particular spot in the layout would also allow us better control in a nested tabs implementation.

Adding Pulled DLM Fragments to uPortal 3.2

A patch for the 3.2.x branch is attached to this wiki page. This patch was generated against revision 20795 of the 3.2.x maintenance branch. Revision 20795 is from July 2010, prior to the 3.2.2 release.

Modifying a new portal instance

Adding pulled fragments to a new 3.2 instance should generally involve applying the patch to the portal source, tweaking the DLM fragments and permissions as required, and running "ant initdb" and "ant deploy-war".

Modifying an existing database

If you do not wish to run "initdb" against your portal, it should be possible to update the portal database with the following steps:

1. Run the against your codebase and deploy with an "ant deploy-war".
2. Start up the portal and allow hibernate to update UP_FRAGMENT_DEFINITION and create the new table UP_USER_FRAGMENT_SUBSCRIPTION.
3. Import the new fragment owners, permissions, group memberships, and layouts.