Portals Requirements

by Tarik Alatovic

I. Introduction

This document records the requirements for the Portals package v2.0, compatible with ACS 3.4.x.

II. Vision Statement

Arsdigita Portals solves two major problems with presentation of information to users:

  1. Aggregating information from an organization's internal and external data sources.
  2. Customization of information content and layout on the personal and group level.

Portal Interface Diagram

As figure above shows, portals are an interface between the information content distributed among multiple databases and clients who are presented with the information relevant to them.

III. System/Application Overview

The portal system consists of five entities:

Portal is a user interface that presents information collected from multiple data sources to the user. Every portal belongs to either a user or a group. User portals aggregate information that is personalized for the individual. Group portal aggregate information that is of interest to group members.

Portal Domain is a collection of portals that share display settings, authorization procedures, and a default configuration. A single portal domain may be defined for all of the user portals, and one each for the various group types, such as suppliers or customers.

Portal page is a component of the portal corresponding to a single web page. Every portal consists of one or more portal pages. (screenshot of a typical portal page)

Portlet is a user interface component displaying information that has something in common. For example, the "announcements" portlet displays the latest news headlines. Every portal page consists of one or more portlets. (screenshot of a typical portlet)

Portal data feed is a piece of tcl or adp code that generates content to be served inside the portlet. This code makes a connection to an internal or external database, retrieves the data, and returns the information that the user is interested in.

IV. User Classes

There are three classes of users in the portal system:

Portal users use portals to either access their personalized information through a user portal, or group customized information through group portals.

Portal managers customize the layout and content of the portal. Note that a portal user is, in fact, manager for her own personal portal. Managers of group portals are usually group administrators, although this can be changed through portal authorization mechanism (see requirement 80.10.20).

ACS Administrators are the primary administrators of the ACS installation. They are in charge of creating portal domains, setting up default portal configurations, setting domain level display settings for all portals in the domain, and configuring the root URLs for portal domains (see requirements 30.10.10 and 30.10.20 for the specification of portal URLs).

V.A Portal User Scenarios

Viewing content aggregated from multiple data sources

It's 15 minutes before John's marketing meeting where last month's sales are to be discussed. John visits the Marketing Department portal at http://xyz.com/departments/marketing and takes a look at the [hypothetical] quarter sales portlet. He goes to the meeting with the grin on his face because the quarter sales report shows a 7% increase over the last year's sales for the same quarter.

After the meeting, John is in very good mood and feels like driving to Mt. Washington for some fresh mountain air. He goes to his personal portal and checks the weather in New Hampshire. Unfortunately, there's a storm coming. John drops the idea of mountain adventure.

While checking the weather on the portal page, his eye is caught by some red text on the calendar portlet. The text reads: "Meeting with Tom, the new CEO of XYZ corporation at 4:30PM." John glimpses at his watch and the expression on his face changes from exuberant to gravely serious. "How could I forget the most important meeting of my career," he says to himself". "Calendar portlet, thank you so much for reminding me." John rushes out of the office and makes it in time to the meeting where he is promoted to vice president of sales.

Customizing portlet information

The Marketing Department's quarter sales portlet shows only the sales figures from the last period. For the next meeting, John is supposed to talk about fluctuations in sales between consecutive quarters, so he would really like to see figures for the past four quarters instead of just the last one.

John clicks the portal customization link in the upper right corner of the quarter sales portlet and gets to the screen for customizing that portlet. He changes the option "Number of quarters displayed" from 1 to 4 and clicks the "Update" button. Now, the quarter sales portlet shows figures for the last four quarters and John goes to the meeting pleased with his ability to extract useful information from the computer.

Switching between portal pages

The first page of John's home portal shows him news, his personal calendar, and reports from the company's various departments. John's address book portlet is on the second page of the portal. To access the second page of the portal, John simply clicks its link in the portal navigation bar.

Submitting a bug to the portal administrator

Oops! The quarter sales portlet shows zero sales for all the four quarters. John knows that's not right and immediately sends a bug report to the portal administrator by clicking the link at the bottom of the portal page.

V.B Portal Manager Scenarios

Customizing the content and layout of portals

Now, that John is convinced that portals are very useful tool for accessing the information of interest to him, he decides to spend some time and personalize his portal. He clicks on the portal customization link, which takes him to the customization page for portal content and layout.

Adding a portlet to the portal page

Since, John likes to keep in touch with the latest news, he selects the "company news" portlet and places it at the upper left corner of his first portal page.

Removing a portlet from the portal page

John is a very cautious person and has no interest in the risky stock market, so he removes the stock quotes portlet, provided by default, from his personal portal page.

Moving portlets around

Recently, John has noticed that he is using the address book portlet very often and would like it to be more readily accessible. Using the customization page, he moves the address book portlet from the second to the first page of his portal.

Creating a new portal page

John realizes that his first page is now too cluttered. He decides to create a new page "Reports" and move all the company reports from the first page to the newly created "Reports" page.

Reverting a portal to the default portal configuration

After spending half an hour customizing his portal, John is not satisfied at all with the new portal configuration he's produced. Being a conservative person, he decides to scrap his changes and return to the portal configuration provided by default. He clicks the "revert portal" link on the portal customization page and gets the default portal configuration back.

V.C ACS Administrator Scenarios

Creating a portal domain

Jessica, the ACS administrator, is instructed to set up a new portal domain for all suppliers of XYZ corporation. She clicks the "add domain" link on the main admin page, specifies the "suppliers" group type, and chooses the URL root "suppliers" for this new portal domain.

Removing an existing portal domain

Jessica, who is skeptical, in nature defines a "test" domain with which to test the features of portal domains. After studying the test portal domain and realizing how useful portal domains really are, she wants to get rid of the test domain. She goes to the administration page for managing the test domain and clicks the "remove this domain" button. Portals responds with a confirmation window asking Jessica to confirm the removal of the entire portal domain. Jessica confirms her decision, and the test portal domain is gone forever.

Changing the root URL of a portal domain

John complains to Jessica that portal URLs are too long. To access his home page John has to type http://xyz.com/my-home-portal/. Jessica says, "No problem," and changes the portal URL root "my-home-portal" to "home" through admin interface. Now, John can access his personal portal at http://xyz.com/home.

Adding a portlet to a portal domain

After creating the suppliers portal domain, Jessica is asked to make an auction portlet where suppliers can make their bids for delivery of XYZ corporation materials. Jessica creates an auction portlet by using the auction data feed available for free from Arsdigita. She names the portlet "Auction", and provides an administration URL where users can customize the auction portlet display options.

Removing a portlet from a portal domain

New company policy is to avoid supplier auctions and instead built strong alliances with suppliers. As a result, all of the company's supply is obtained through direct sales and the auction portlet in not used anymore. Jessica goes to the suppliers domain administration page and removes the auction portlet, at which point it is automatically removed from all the portals in the domain.

Setting a default portal for a portal domain

Jessica reviews the notes from her MIT class on the user interface design, and comes across very important point: "Users are not going to go through the pain of customizing the portals if they are not offered a sensible default configuration". "Hmm ...," Jessica murmurs, "I can do that. Setting a default portal for the portal domain is no more complicated than customizing a regular portal."

She goes to the admin page, and sets up the default portal for the suppliers domain. The next time members of ABC Supplier Co. (supplier group) log in, they will be immediately presented with the default portal. The portal manager of ABC Supplier Co can now further customize the portal starting from the default portal configuration specified by Jessica.

Reverting all portals in a portal domain

Jessica's boss, Tom, has a new idea for how the various department portals should look, and demands that all department portals be changed. Jessica is not very happy with Tom's proposal but has no choice, and ends up modifying the default department portal, such that Tom is satisfied with it. After sending an e-mail to all departments alerting them of new change to their portals, she clicks the "Revert all portals in this domain" button and all of the department portals are reverted to new portal configuration.

Making required portlets

After 2 months, Tom accesses marketing department portal and to his surprise, the portal doesn't look like the one he designed. He immediately calls Jessica on her cell phone and orders her to quit whatever she is doing and come to his office immediately. "What's happening Jessica?," Tom asks, "Why is the Marketing portal different from what I gave you 2 months ago?" "Well, the portal manager of the marketing department customized the portal," Jessica answers, "Two months ago, we only changed the default configuration and replaced old department portals with new ones."

Tom nods his head in understanding and tells Jessica: "OK, let the Marketing Department customize their portal as they wish, but they must have the company announcement portlet. All of us together make a community and everybody has to be informed of company events." Jessica agrees: "Okay, that's easy. I'll make announcements a required portlet, and no department will be able to remove it from its portal configuration." Jessica goes to the admin page does just that.

Setting domain level display properties

At the same meeting, Tom notices that personal portals and department portals look the same: "Jessica, this is so confusing. I have a hard time distinguishing between my personal portal and the marketing department portal. Both of them use the same red color for portlet backgrounds. Can you give portlets on personal portals a blue background and portlets on department portals a green one?" Jessica answers: "Sure, just give me a minute and I'll change display settings for personal and marketing portals." Jessica goes to the portal admin pages and sets a blue background for portlets on personal portals and a green background for those in the department domain.

Changing the name of a portlet

XYZ corporation has just introduced a new "industry news" portlet. To distinguish the old company news portlet named "announcements" from the new "industry news" portlet, Tom wants to change its name to "company news". He sends e-mail to Jessica asking her to make the change. Jessica, delighted that she's finally received a task from Tom that makes sense, goes to the admin page and changes name of the company news portlet to "company news".

VI. Related Links

VII.A Requirements: Data Model

Portal Data Feeds

10.10.10 Data feeds are identified by a unique data feed id

10.10.20 Data feed consists of either tcl or adp code

10.10.30 There are two types of data feeds: (1) predefined data feeds, defined by developers and cannot be subsequently modified through the web interface, and (2) user-defined data feeds, created and modified through the web interface

10.10.40 Predefined data feeds are identified by a unique name, so that an ACS administrator can create portlets from the admin interface by selecting the data feed by name.

Portals

10.20.10 Portals are identified by a unique portal id

10.20.20 Portal is owned by either a user (identified by user_id) or a group (identified by group_id).

10.20.22 Default portals are not owned by anybody, and they define default portal configurations for all portals within a domain.

10.20.24 Every portal belongs to exactly one portal domain identified by domain id.

10.20.30 A name can be optionally associated with every portal

Portal Domains

10.30.10 Portal domains are identified by a unique portal domain id

10.30.20 Portal domain can be either user or a group portal domain. There is only one user domain to which all the user portals belong. One portal domain can be defined for every group type.

10.30.30 Unique URL root is associated with each portal domain (see 30.10.20 for specification of portal URLs)

10.30.40 Optionally, a control panel can be specified for the portal domain by providing the data feed id of the data feed that contains control panel code.

10.30.50 Domain level display properties can be specified for a domain.

Portal Pages

10.40.10 Portal pages are identified by a unique portal page id.

10.40.20 Each portal page belongs to exactly one portal identified by the portal id.

10.40.30 Each portal page may have a pretty name.

10.40.40 Each portal page has a page number that is unique across the portal to which the page belongs. This page number is used for two purposes: (1) for portal URL construction (see 30.10.10 and 30.10.20), and (2) for construction of pretty name of portal pages where pretty name is not provided by the user.

Portlets

10.50.10 Portlets are identified by a unique portlet id.

10.50.20 Every portlet belongs to exactly one domain identified by the domain id.

10.50.30 Every portlet has a name associated with it. This name is unique across the domain to which the portlet belongs.

10.50.40 Every portlet uses exactly one data feed that generates the portlet's HTML content.

10.50.50 Portlet may be specified as "required." If portlet is specified as required, then users cannot remove it from their portal configurations.

10.50.60 An optional link URL may be specified for a portlet. Link URL is commonly used for accessing the portlet administration page. The Link URL may consist of adp or HTML code.

Placement of portlets on portal pages

10.60.10 A portlet can belong to one or more portal pages that share the same domain as the portlet.

10.60.20 The horizontal position of a portlet on the page is either the left side or the right side.

10.60.30 The vertical position of a portlet on the page is specified relative to the position of other portlets on the page.

VII.B Requirements: API

The API of the portal system is object-based. It contains methods for creating, destroying, modifying, and getting information about all of the portal objects: portals, portal domains, portal pages, portlets, and portal data feeds.

Portal API

20.10.10 Method for creating the user portal for a given user_id and the group portal for a given group_id.

20.10.20 Method for destroying a portal.

20.10.30 Method for modifying a portal.

20.10.40 Method for getting information about the portal.

Portal Domain API

20.20.10 Method for creating the users domain and the group type domain for given group_type.

20.20.20 Method for destroying a portal domain.

20.20.30 Method for modifying a portal domain.

20.20.40 Method for getting information about the portal domain.

Portal Page API

20.30.10 Method for creating a portal page.

20.30.20 Method for destroying a portal page.

20.30.30 Method for modifying a portal page.

20.30.40 Method for getting information about the portal page.

Portlet API

20.40.10 Method for creating a portlet.

20.40.20 Method for destroying a portlet.

20.40.30 Method for modifying a portlet.

20.40.40 Method for getting information about a portlet.

Portal Data Feed API

20.50.10 Method for creating a portal data feed.

20.50.20 Method for destroying a portal data feed.

20.50.30 Method for modifying a portal data feed.

20.50.40 Method for getting information about a portal data feed.

User Interface Widgets API

20.60.10 Method for generating portlet HTML.

20.60.20 Method for generating portal page HTML.

20.60.30 Method for generating a navigation bar that includes liks to all of the portal pages.

Authorization API

20.70.10 Method that returns permission (administer, view, or none) for portal identified by portal id and user identified by user id.

20.70.20 Method for registering a domain specific authorization procedure.

Portal Info API

20.80.10 Method for getting the information about the currently served portal page: portal id, portal page id, portal type (user or group), domain id to which the portal belongs, URL root of that domain, and whether user has administrative privilege for that portal.

VII.C Requirements: Portal User Interface

Portal URL Specification

30.10.10 User portal URL is of the form /root_url/page-number. For example, John accesses the second page of his personal portal from http://xyz.com/home/page-2. The page-number portion of url isn't required. When it's not provided, the first page of the portal is served. Therefore, John can access the first page of his portal at http://xyz.com/home/.

30.10.20 Group portal URL is of the form /root_url/short_name/page-number. To access the third page of the portal for the marketing department of XYZ corporation, John uses the following URL http://xyz.com/deparment/marketing/page-3 where "department" is the root_url, and "marketing" is the short_name of the marketing group. The page-number portion of url isn't required. When it's not provided, the first page of the group portal is served. Therefore, John can access the first page of the marketing portal at http://xyz.com/department/marketing.

Portal User Interface

30.20.10 Portal user interface consists of one or more portal pages. Each portal page is a single HTML page consisting of four elements: header, footer, navigation bar and one or more portlets.

30.20.20 Header contains an appropriate name for the portal. For example, a user's full name can be used for the header of a user portal, and a group name for the header of a group portal.

30.20.30 Footer contains the e-mail address of the portal administrator.

30.20.40 Navigation bar consists of links to portal pages other than the portal page currently selected. It also includes a link to the control panel if one exists.

30.20.50 Each portlet is a box with two parts: header and body.

30.20.54 Header of a portlet displays the name of the portlet and, optionally, a link to the page where the contents of the portlet are administered.

30.20.54 Body of the portlet displays information generated by the portlet's data feed.

30.20.60 Portal user is not allowed to remove the portlets that ACS administrator designates required portlets

VII.D Requirements: Portal Manager Interface

For a user portal, the portal manager is the user himself. For a group portal, the manager is usually the group administrator.

Portal Customization

40.10.10 Portal manager can easily customize the portal content by specifying which portlets are displayed in the portal.

40.10.20 Portal manager can easily customize the layout of the portal by specifying the number and names of portal pages, deciding which portlets go to each of the portal pages, and specifying vertical and horizontal position of the portlet.

VII.E Requirements: ACS Administrator Interface

Portal Domain Management

50.10.10 ACS admin can create a single user portal domain.

50.10.20 ACS admin can create one portal domain for each of the defined user group types.

50.10.30 ACS admin can change the root URL of a portal domain.

50.10.40 ACS admin can remove a portal domain.

50.10.50 ACS admin can change domain level display settings for a portal domain.

Portlet Management

50.20.10 ACS admin can create a new portlet for the domain by specifying portlet name, portlet data feed (predefined, or new adp code), and optionally specifying the link URL, which is used for accessing the administration page of the portlet

50.20.20 ACS admin can remove a portlet from the portal domain.

50.20.30 ACS admin can change name, portal data feed, and link URL of a portlet.

Default Configurations

50.30.10 ACS admin can set up a default portal configuration for every portal domain.

50.30.20 ACS admin can revert all of the portals in a portal domain to the default portal configuration for that domain.

VII.F Requirements: Usability

60.10.10 User and group portals are automatically created and set to the default the first time these portals are accessed.

VII.G Requirements: Reliability and Robustness

70.10.10 A portlet whose data feed raises an error is not displayed on the portal page.

VII.H Requirements: Authorization

80.10.10 Portal system provides default authorization procedure. For user portals, the default authorization procedure grants users a right to view and administer their portals. For group portals, the default authorization procedure grants group administrators a right to administer their group portals, and group members right to view their group portals.

80.10.20 Portal system provides means for registering domain specific authorization procedures. For each domain, a procedure can be registered that determines whether the user has a right to view or administer the portal.

VII.I Requirements: Performance

90.10.10 The portal system serves two important functions: (1) it provides a universal entry point for accessing a large amount of information, and (2) that information is relevant and up-to-date. As a result, portal pages are frequently accessed and must have excellent performance. In order to achieve this performance and scale to a reasonable number of users, the portal system cannot repeatedly query the database for each hit. Instead, the portal system should have all the data necessary to generate portals cached in memory.

VIII Implementation Notes

Take a look at the Historical Considerations section of the design document.

IX Revision History

Document Revision # Action Taken, Notes When? By Whom?
0.1 Creation 10/13/2000 Tarik Alatovic
0.2 Proofread, moved into distribution. 10/19/2000 Ian Baker

tarik@alatovic.com
Last modified: $Id: requirements.html,v 1.1.1.1 2001/01/24 18:03:35 tarik Exp $