02 DLM Administration Guide

Distributed Layout Management (DLM)

additional guidances and best practices

What is DLM and where did it come from?

In uPortal, Layout Management refers to how the user interface seen by a user is generated and changed. In version 2.0, only Simple Layout Management, SLM, was available in the portal. All layout pieces like tabs, columns, and channels were owned by the user. There was little control available for an institution to control a user's layout. When Sungard SCT, then Campus Pipeline, adopted uPortal for their Luminis product they had to allow schools to choose how much or how little of the layout is locked in place. Furthermore, this should be modifiable at any time and such changes should then appear in the portal. The result was Distributed Layout Management or DLM which debuted in Luminis in 2002.

This resulted in JA-SIG designing a similar feature known as Aggregated Layout Management or ALM. With the advent of ALM there were two approaches to dynamic layout management. However, although they have complimentary features, ALM and DLM each provide benefits that are not had by the other implementation. In 2004 Sungard SCT was contacted to see if the features of ALM and DLM could converge into a single offering. The benefits are obvious. With the community working to enhance the features of a single offering all will benefit. Accordingly, work was started in late 2004 to contribute DLM back to the community and have it available starting in uPortal version 2.5.0.

Configuring uPortal to Use DLM

uPortal version 2.5 comes configured to use ALM by default. To convert between the different layout management approaches follow these simple steps.

Step 1: Stop the web server if not stopped already.

Step 2: Open portal.properties and search for any of these three accronyms. There are two properties that the portal uses to startup the appropriate code to perform that layout management functionality. Preceding each of these properties is a comment block outlining what value that property should have for each of the respective layout management approaches. The properties that need to be changed are:

portal.properties to be Changed

portal.properties to be Changed
org.jasig.portal.layout.UserLayoutStoreFactory.implementation
org.jasig.portal.layout.UserLayoutManagerFactory.coreImplementation

After changing this value redeploy using, "ant deploy", so that the modified portal.properties file is pushed to <webApplicationRoot>/WEB-INF/classes/properties unless you changed the version in that location.

Step 3: Modify user accounts in the database. Specifically, the UP_USER_PROFILE table contains a lookup of the structure and theme stylesheets that should be used by users. The following SQL can be used to modify the values for the respective layout management approaches. See the following table for the specific stylesheet values that come in the default uPortal database.


UPDATE up_user_profile
SET structure_ss_id=<struct Id From Below>,
theme_ss_id=<theme Id From Below>
WHERE theme_ss_id=<current Theme Id In up_user_profile>

Approach	Structure Stylesheet Id	Theme Stylesheet Id

Approach	Structure Stylesheet Id	Theme Stylesheet Id
SLM	1	1
ALM	3	11
DLM	4	3

Step 4: Restart the web server.

DLM Guest Fragment

When you first configure the portal to use DLM, start up the web server, and go to the portal with a browser you will notice a new "Welcome" tab appears. Of the tabs in the login page, this one is unique. Most are part of the guest user's own layout. This tab isn't. In DLM terminology it is a fragment that was merged in by DLM. Traditionally, if you wanted to change what guests see you would set a password for the guest user, log in as guest, and change the layout. Not with DLM. To change the contents of this tab log in with the following user id and password:

User Id: guest-lo, Password: guest-lo

This user is a DLM fragment owner. This account has all of the same capabilities as a regular user with one exception, no fragments are merged into a fragment owner's layout. Fragment owners see only their owned layout since that layout becomes the fragment that is pushed into other layouts.

Now once you log in, change the guest fragment, and log out, you will notice that this tab didn't change. Doesn't DLM push changes to the guest layout? Of course it does. The problem here is that the guest layout that you see is cached in a layout manager. For regular users a layout manager is loaded when they log in. Hence, so is their layout. The guest layout manager is loaded when the first request is made to the portal after starting up and is cached in memory thereafter. So changes made to fragments that go to regular users will present their changes the next time that a user logs in after that fragment has been changed. But currently, to see changes pushed to the guest layout, the portal must be restarted. This will be fixed soon. We hope.

Introducing dlm.xml

When DLM was developed, time was of the essence. A new user interface taylored to building fragments and a new database schema was too aggresive an undertaking for engineers new to the uPortal code base. Upon further investigation of the portal architecture and database schema it was determined that a derivative approach could be taken instead. In a derivative approach, existing, reliable pieces of the portal could be used to produce layout fragments to be pushed to users. Furthermore, there would be no database schema changes. Specifically, fragments would be obtained by using regular portal accounts to define what each fragment should look like. Such was and is the design of DLM. A configuration file, dlm.xml defines fragments, their audiences, and the special portal accounts used to set up their layouts. (See Future Direction on how dlm.xml will be replaced in the near future.)

Although dlm.xml is xml based it does not have a defined schema or DTD. Its expected structure is defined by the expectations of the DLM loading infrastructure. This is in part due to the extensible nature of dlm.xml as will be seen in the declarations of the fragment audience definitions. Therefore, the remaining information in this section and related sections will portray the implicit structure expected by the DLM loading infrastructure.

The dlm.xml file is located in the properties directory. The top level element in dlm.xml is the <managedLayoutFragments> element. It includes the namespace declaration for DLM used to prefix all expected DLM property, fragment, and audience elements. This element appears as follows in dlm.xml.<managedLayoutFragments xmlns:dlm="http://org.jasig.portal.layout.dlm.config">
The only two supported child elements for managedLayoutFragments are <dlm:property> and <dlm:fragment>. Others may be included but they will be ignored. The <dlm:property> element has two required attributes, 'name' and 'value'. There are currently only two properties supported by DLM and if not defined, suitable defaults will be used as explained below.

The 'defaultLayoutOwner' Property

If defined the value of this property should be the user ID (ie: the log-in ID) of an account whose layout should be copied for all new fragment owners. When a fragment is defined in dlm.xml it includes an ownerID attribute. (See the related section on defining fragments.) Since fragments are layouts for special accounts then these accounts must have a layout. When regular users log in for the first time and have no layout, the portal gives them a copy of a default account's layout as declared in portal.properties. This default should not be used for fragment owner accounts since it will result in that entire layout being pushed to all users. The approach take by the default dlm.xml is to use a special account included in the portal. To change this account you can use the following credentials.

User Id: fragmentTemplate, Password: fragmentTemplate

Warning: It is strongly recommended that you do not change this user account's layout. It is empty except for hidden content like the header and footer folders and their channels. The layout for this account including hidden but necessary content is copied whenever a new fragment owner is declared in dlm.xml. The layout for the owner account is created immediately after adding the fragment's declaration to dlm.xml and restarting the portal. These accounts should be empty until such time that the account can be accessed and the proper layout set up that should be pushed for that fragment.

The 'org.jasig.portal.layout.dlm.RDBMDistributedLayoutStore.fragment_cache_refresh' Property

For performance, DLM caches the layout for each defined fragment in memory. When layout owners modify the layout, those changes are pushed into the database and into the in-memory cache in the server handling the session for that account. If multiple servers are employed, the other servers will not see these changes made by the fragment owner. This property determines how often the cache of fragment layouts is reloaded to force such changes to appear in other servers. This does not include instantiating new fragments declared in dlm.xml. This only forces a reload of the fragments seen in dlm.xml when the servers were last restarted.

Defining Fragments

The <dlm:fragment> child element of the outer most managedLayoutFragments element is used to define a fragment. There is no restriction on the number of child <dlm:fragment> elements of managedLayoutFragments. The following sample is one of the fragments defined in the default dlm.xml file that comes with uPortal.


<dlm:fragment name='Guests' ownerID='guest-lo' precedence='10'>
  <dlm:audience evaluatorFactory='org.jasig.portal.layout.dlm.providers.GuestUserEvaluatorFactory'/>
</dlm:fragment>

All elements defined and expected by DLM are prefixed with dlm indicating that they are part of the DLM namespace. The fragment element has a name attribute that should be unique for all fragments. This name is presented in the title bar of the portal when the owner of this fragment is logged in as shown below.

The 'ownerID' Attribute

Each fragment must declare an ownerID attribute. This is the log-in to use when logging in to edit the layout for this fragment. It is important that this account not exist prior to adding the fragment. When dlm.xml is modfied, the portal must be restarted for the configuration to be loaded. Upon loading, if that account already exists and has a layout it will immediately be pushed to users. If the account does not exist, then upon restarting the portal, DLM will create that account and populate its layout with a copy of the layout of the account specified with dlm.xml's defaultLayoutOwner property. That layout has no visible content. In this way this fragment does not push any content to users until the owner has time to set up the layout that should be pushed. Note: the md5passwd command line utility must still be used after restarting to set the password for the new account to allow a fragment maintainer to log in to that account and set up the layout: