This document records the requirements for the Portals package v2.0, compatible with ACS 3.4.x.
Arsdigita Portals solves two major problems with presentation of information to users:
- Aggregating information from an organization's internal and external data sources.
- Customization of information content and layout on the personal and group level.
![]()
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.
The portal system consists of five entities:
- Portals
- Portal Domains
- Portal Pages
- Portlets
- Portlet Data Feeds
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.
There are three classes of users in the portal system:
- Portal users
- Portal managers
- ACS administrators
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).
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.
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.
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".
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.
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.
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
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.
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.
60.10.10 User and group portals are automatically created and set to the default the first time these portals are accessed.
70.10.10 A portlet whose data feed raises an error is not displayed on the portal page.
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.
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.
Take a look at the Historical Considerations section of the design document.
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