At G Portal Admin Guide

atg
Version 2007.1
Portal Administration Guide
ATG
One Main Street
Cambridge, MA 02142
www.atg.com
ATG Portal Administration Guide

Document Version
Doc2007.1 PORTALADMINv1 7/13/07
Copyright
Copyright 1998-2007 Art Technology Group, Inc. All rights reserved.
This publication may not, in whole or in part, be copied, photocopied, translated, or reduced to any electronic medium or machine-readable
form for commercial use without prior consent, in writing, from Art Technology Group, Inc. (ATG) ATG does authorize you to copy
documents published by ATG on the World Wide Web for non-commercial uses within your organization only. In consideration of this
authorization, you agree that any copy of these documents which you make shall retain all copyright and other proprietary notices
contained herein.
Trademarks
ATG, Art Technology Group, and DYNAMO are registered trademarks of Art Technology Group, Inc.
ATG Wisdom, ATG Dynamo Application Server, ATG Adaptive Scenario Engine, ATG Scenario Personalization, ATG Portal, ATG Commerce,
ATG Content Administration, ATG Data Anywhere Architecture, ATG Search, ATG Response Management, ATG Merchandising, ATG
Knowledge, ATG Self Service, ATG Commerce Assist, ATG Advisor, ATG Forum and ATG Business Control Center are trademarks of Art
Technology Group, Inc.
Microsoft, Windows and Word are the trademarks or registered trademarks of Microsoft Corporation in the United States and other countries.
IBM, AIX, and MQ-Series are the trademarks or registered trademarks of IBM Corporation in the United States and other countries. Oracle is a
registered trademark, and other Oracle product names, service names; slogans or logos referenced in this document are trademarks or
registered trademarks of Oracle Corporation. Adobe Acrobat Reader is a registered trademark of Adobe. CORBA is a trademark of the OMG
(Object Management Group). Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems,
Inc. in the United States and other countries. Primus, and its respective logo, and Primus Knowledge Solutions, are trademarks, registered
trademarks, or service marks of Primus.
This product includes software developed by the Apache Software Foundation (http://www.apache.org/).
EditLive Authoring Software Copyright 2004 Ephox Corporation. All rights reserved. Includes code licensed from RSA Security, Inc. Some
portions licensed from IBM are available at http://oss.software.ibm.com/icu4j/. Includes software developed by the Apache Software
Foundation (http://www.apache.org/). Contains spell checking software from Wintertree Software Inc. The Sentry Spell Checker Engine
2000 Wintertree Software Inc.
All other product names, service marks, and trademarks mentioned herein are trademarks of their respective owners. This publication may
not, in whole or in part, be copied, photocopied, translated, or reduced to any electronic medium or machine-readable form for commercial
use without prior consent, in writing, from Art Technology Group (ATG), Inc. ATG does authorize you to copy documents published by ATG
on the World Wide Web for non-commercial uses within your organization only. In consideration of this authorization, you agree that any
copy of these documents which you make shall retain all copyright and other proprietary notices contained herein.
No Warranty
This documentation is provided as is without warranty of any kind, either expressed or implied, including, but not limited to, the implied
warranties of merchantability, fitness for a particular purpose, or non-infringement.
The contents of this publication could include technical inaccuracies or typographical errors. Changes are periodically added to the
information herein; these changes will be incorporated in the new editions of the publication. ATG may make improvements and/or changes
in the publication and/or product(s) described in the publication at any time without notice.
Limitation of Liability
In no event will ATG be liable for direct, indirect, special, incidental, economic, cover, or consequential damages arising out of the use of or
inability to use this documentation even if advised of the possibility of such damages. Some states do not allow the exclusion or limitation of
implied warranties or limitation of liability for incidental or consequential damages, so the above limitation or exclusion may not apply to
you.
ATG One Main Street Cambridge MA 02142
617.386.1000 phone 617.386.1111 fax www.atg.com
Contents
Getting Started
Installation
Starting up the Portal Application
Portal.paf
Portal.gears
Portal.<gearname>
Portal Web Applications
Accessing ATG Portal
Opening a Portal Page
Opening the Portal Administration Pages
Accessing the Default Portal
1
1
1
2
2
2
3
3
4
4
Administration Pages
Portal Administration Pages

Portal Administration Navigation
Communities Tab
Gears Tab
Styles Tab
Alerts Tab
Community Administration Pages
Community Settings Tab
Community Users Tab
Community Pages Tab
Community Gears Tab
Reset Buttons
Portal Configuration
Configuring Your Database
Configuring Your Repositories
Portal Repository Creation
Portal Repository Configuration
Profile Repository
Portal Personalization
Profile Template
Business Rules
Page Templates and Branding
Shared and Full Page Template
5
5
6
6
7
8
8
9
9
10
10
10
11
11
11
11
12
12
12
12
13
13
14
iii
Contents
Layout Templates
Gear Title Template Files
Stylesheet Files
Additional Branding Files
Creating Style Element Templates
Localizing a Portal
Configuring E-mail Templates for Alerts
Portal and the Global Scenario Server
Community Administration
Community
Individual
Organization
Community Folders
Creating Community Folders
Deleting Community Folders
Reserved Community Names
Specifying a Home Community
Reserving a Web-Friendly Name
Community Roles
Global Roles
Relative Roles
Community Role IDs
Community Membership
Membership Settings
Canceling Community Membership
Adding and Removing Community Members
Working with Communities
Creating a Community
Making Gears Available to a Community
Limiting a Communitys Access to Gears
Editing a Community
Disabling a Community
Deleting a Community
Editing a Community Portal Page
Adding a Community Portal Page
Adding Gears to a Community Portal Page
Viewing a Community Portal Page
Deleting a Community Portal Page
Creating Communities from Community Templates
Using the Community Templates User Interface
Using the SpawnCommunity Tool
Automating the Portal Creation Process
Community Proposals
Creating a Workflow for Community Proposals
Creating a Scenario for Community Proposal Workflows
Creating a Community Proposal
14
14
15
15
16
16
17
17
19
19
19
19
20
20
20
20
21
21
21
22
22
23
23
23
24
24
24
24
25
26
27
27
27
28
29
30
30
30
31
31
32
34
34
35
37
37
iv
Contents
Working with Community Membership

Adding a Member to a Community
Approving or Declining Membership Requests
Enabling Membership Request E-mail Notification
Assigning a Community Leader Role to a Member
Adding a Guest to a Community
Creating New Portal Users
Searching for Members in an LDAP Repository
Portal Administration
Manifest Files
Style Administration
Page Templates
Adding Page Templates to the PAF
Layout Templates
Adding Layout Templates to the PAF
Gear Title Templates
Adding Gear Title Templates to the PAF
Color Palettes
Adding Color Palettes to the PAF
Stylesheets
Adding Stylesheets to the PAF
Gear Administration
Gear Folders
Gear Configuration Types
Gear Installation Configuration
Gear Instance Configuration
Gear Parameter Configuration
Adding Gears to the PAF
Deleting a Gear from the PAF
Sharing Gears in the PAF
Configuring Alerts
Creating New Administrative or Framework Alerts
Configuring an Alert
Deleting an Alert
Customization Administration
Using Scenarios with ATG Portal

Using Portal Attributes in a Scenario
Displaying a Gear in a Slot
Creating a Slot to Display a Gear
Creating Scenarios to Display Gears in Slots
Portal Scenario Events and Actions
Preconfigured Portal Scenarios
38
39
39
39
40
41
41
42
43
43
44
44
44
44
45
45
45
45
46
46
46
47
47
47
47
47
48
48
48
49
49
50
50
51
51
53
53
53
54
54
56
56
v
Contents
Portal Access Control

J2EE Security
Community Security Administration
Setting Basic Access Levels for a Community
Setting Advanced Access Controls for a Community
Setting Community Access by Role
Page and Gear Level Access Control
Predefined Secured Areas
59
59
59
60
60
61
62
63
63
63
Baseline Gear Administration
65
Baseline Gears Overview

Configuring Baseline Gears
Alerts Gear
Bookmarks Gear
Calendar Gear
Community Members Gear
Discussion Gear
Document Exchange Gear
Favorite Communities Gear
HTML Content Gear
Login Gear
Outlook Gear
Poll Gear
Quicklinks Gear
Repository Search Gear
Repository View Gear
Targeted Content (Slot) Gear
Web Services Client Gear
XML-Feed Gear
XML Protocol Gear
65
66
67
68
69
70
70
71
75
75
77
77
79
79
80
81
83
84
87
89
Index
92
vi
Contents
1 Getting Started
This document provides guidelines for administering and configuring the Portal Application Framework,
or PAF, for ATG Portal. The PAF serves as a structure for a series of customized Internet communities.
Using the PAF you can create communities of users, joined by purpose or common interest. The PAF can
provide these communities with specialized portals. Each portal can be customized for content,
appearance, and functionality, on both the community and individual level. For more technical
information intended for Java programmers, see the ATG Portal Development Guide.
The PAF provides two Web-based administration user interfaces: the Portal Administration, which system
administrators can use to manage the portal and its communities as a whole, and the Community
Administration, which community leaders can use to manage individual communities in the portal.
Access to Portals is controlled by a series of security measures based on community roles. A visitors role
within a community determines that persons ability to view content, interact with other users, and
customize the appearance and content of the portal page.
Installation
Read the ATG Installation and Configuration Guide for information about how to download and install ATG
Portal. Check the technical specifications at www.atg.com to see which operating systems, application
servers, and database software you can run ATG Portal on.
Starting up the Portal Application

To use ATG Portal, you assemble an EAR file that includes the modules you want to use. Once you have an
EAR file, you deploy it to the appropriate location and startup the Web application it contains. For
information on assembling applications, see the ATG Programming Guide. Deploy and start your
application according to the instructions in the manuals provided with your application server.
The following sections describe the Portal modules that you may want to specify during application
assembly.
Portal.paf
The Portal.paf module contains the PAF itself. At a minimum, you must specify this module to use ATG
Portal.
1
1 - Getting Started
Portal.gears
The Portal.gears module contains the collection of baseline gears as well as the PAF module. You must
use this module to make the baseline gears available.
Portal.<gearname>
You use this module to make additional gears available to your portal visitors. For example, if you created
a gear called productprices, you would include the module Portal.productprices.
Portal Web Applications

ATG Portal includes the following four J2EE Web applications:
Web Application
Archive
Module
Description
admin.war
PAF
The Portal Administration
settings.war
PAF
The Community Administration
portal.war
PAF
The default Portal
In addition, each of the baseline gears included in ATG Portal is a J2EE Web application, all of which are
included collectively with the gears module, but any one of which can be included with its own module
name:
Gear Name
Module Name
Alert
Alert
Bookmarks
bookmarks
Calendar Publisher
calendar
Community Members
contacts
Discussion
discussion
Document Exchange
docexch
Favorite Communities
communities
HTML Content
screenscraper
Login
user_registration
Outlook
exchange
2
1 - Getting Started
Poll
poll
Quicklinks
quicklinks
Repository Search
search
Repository View
repview
Targeted Content (Slot)
slotgear
Web Services Client
soapclient
XML Protocol
xmlprotocol
XML Feed
xmlfeed
Accessing ATG Portal

The first time you access ATG Portal, use admin as your user ID and admin as your password to enter the
portal. This user has Portal Administrator authority. For security, you will eventually want to create new
Portal Administrator user accounts and delete the admin user account.
Opening a Portal Page

To open a portal page, enter the URL into your Web browser. This URL is structured in the form of:
http://hostname:port/portalcontext/communityfoldername/communityname
/pagename
The elements of the URL are as follows:
Port
The default port number depends on the application server you are
using. For example, for JBoss, the default is 8080. See the ATG
Installation and Configuration Guide for specific information.
Portalcontext
The portal context is portal for the default portal
communityfoldername
The name of the community folder
Communityname
The name of the community that you want to view
pagename
The name of a specific page in the community. If no page name is

specified, the default page for the community opens.
The portal page opens in the browser window.
3
1 - Getting Started
Opening the Portal Administration Pages

You can use the Portal Administration Pages to create communities and assign roles in your portal and to
configure the appearance and content of the portal pages and communities. To use the Portal
Administration Pages, enter the URL into your Web browser. This URL is structured in the form of
http://hostname:port/portal/admin. Note that the port number depends on the application server
you are using. See the ATG Installation and Configuration Guide for the default number. For example, the
default URL on JBoss is:
http://hostname:8080/portal/admin
Accessing the Default Portal

If you use ATG Portal with the Portal.paf and Portal.gears modules, you can access an empty Portal
application. This default Portal provides you with a starting point for Portal development. It defines the
basic information (colors, templates, the admin user) needed to start building your own portal, but does
not define any communities or community pages. To administer the default Portal and begin
development of a new Portal:
1.
Assemble an application that includes the Portal.gears module.

For information about assembling applications, see the ATG Programming Guide.
2.
Deploy and start your application according to the instructions provided in your
application server manuals.
3.
Open the Portal Administration, as described in the Opening the Portal Administration
Pages section, by pointing your browser to:
http://hostname:port/portal/admin
where hostname is the machine that runs your application server and port is the port
number your application server uses to listen for HTTP requests. For the default port,
see the ATG Installation and Configuration Guide.
4.
Create a new community folder, new communities, and new community pages, as
described in the Community Administration chapter.
4
1 - Getting Started
2 Administration Pages
You administer the PAF from two Web-based user interfaces called the Portal Administration Pages and
the Community Administration Pages. From the Portal Administration Pages you can create communities,
administer the content and appearance of the portal, and make gears and other features available to the
portals communities. From the Community Administration Pages you can create the content, administer
the membership, and configure the appearance of a specific community. The following sections describe
these administration pages:

The Portal Administration Pages provide access to all aspects of the PAF, as described below. If you are a
Portal Administrator, you can reach the Portal Administration Pages at
http://hostname:port/portal/admin. The default port number depends on the application server
you are using. See the ATG Installation and Configuration Guide for port information. For example, on
JBoss, the Portal Administration URL is:
http://hostname:8080/portal/admin
Portal Administration Navigation

The Portal Administration has two main navigation aids, the top navigation bar and the side navigation
panel. When you open the Portal Administration Home Page, you see four main tabs in the navigation bar
at the top. These are the:
Communities Tab
Gears Tab
Styles Tab
Alerts Tab
5
2 - Administration Pages
As you work with the Portal Administration, this navigation bar continues to be displayed, letting you
switch immediately to another work area.
In addition, each of these four tabs has a navigation panel at the side. The side navigation panels link to
particular tasks within the main tabs work area.
Communities Tab
When you open the Communities tab, the Portal Administration displays the Available Communities
page, which lists all of the communities in the portal. As the Portal Administrator, you have access to all of
these communities, and can view and edit all of them. The side navigation panel in the Communities tab
lists the tasks you can perform:
For more information on communities, refer to the Community Administration Pages section in this
chapter and the Community Administration chapter.
Gears Tab
Gears provide content and functionality within the portal pages. When you open the Gears tab, the Portal
Administration displays the Available Gears page, which lists all of the gears available in the PAF. You can
use this page to configure existing gears. Any configuration done at this level applies to default instances
of the gear. You can configure the gear at the community level to make community-specific changes in
the gear instance. You can use the New Gear page to add more gears to the PAF.
The side navigation panel in the Gears tab lists the tasks you can perform:
6
For more information on baseline gears, the set of prefabricated gears provided with the PAF, refer to
Gear Administration. For more information on developing your own gears, refer to the ATG Portal
Development Guide.
Styles Tab
The Styles tab provides a set of style element tools you can use to standardize or customize the
presentation of pages in your portal. These tools are page templates, layout templates, gear title
templates, color palettes, and stylesheets. When you open the Styles tab, the Portal Administration
displays the Page Templates page, which lists all of the page templates available in the PAF.
Page Templates
Page templates supply the underlying HTML and WML wrappers for the portal pages. The Page Templates
tab lists all of the page templates available in the PAF. You can use this page to add more page templates
to the PAF. For more information on page templates, refer to Page Templates and Branding in the Portal
Configuration chapter.
Layout Templates
Layouts arrange the appearance of gears within the portal pages. The Layouts Templates page lists all of
the layouts available in the PAF. You can use this page to add more layouts to the PAF. For more
information on layouts, refer to Layout Templates in the Page Templates and Branding section of the Portal
Configuration chapter.

Gear titles provide a decorative title and border for gears appearing in a portal page. The Title area may
contain an Edit control for Community Members to customize the gear. You can use this page to add
more gear titles to the PAF. For more information on gear titles, refer to Gear Title Templates in the Style
Administration section of the Portal Administration chapter and to Gear Title Template Files in the Page
Templates and Branding section of the Portal Configuration chapter.
7
Color Palettes
Color palettes provide color and background images within the portal pages. The Color Palettes page lists
all of the color palettes available in the PAF. You can use this page to add more color palettes to the PAF.
For more information on color palettes, refer to Color Palettes in the Style Administration section of the
Portal Administration chapter.
Stylesheets
Stylesheets describe how the portal page is presented. The Stylesheets page lists all of the stylesheets
available in the PAF. You can use this page to add more stylesheets to the PAF. For more information on
color palettes, refer to Stylesheets in the Style Administration section of the Portal Administration chapter.
Alerts Tab
Alerts are messages generated by events occurring within the portal. Alert messages can be delivered
through the Web channel, appearing in portal pages, or through the e-mail channel. Alerts can be either
administrative alerts, which are messages that are generated from the Portal Administration pages, or
framework alerts, which are messages that are generated from community pages in the portal. When you
open the Alerts tab, the Portal Administration displays the Administrative Alerts page, which lists all of the
administrative alerts available in the PAF.
The side navigation panel in the Alerts tab lists the tasks you can perform:
You can create new administrative or framework alerts or configure existing alerts using the Portal
Administration. See Configuring Alerts in the Portal Administration chapter for information about creating
new alerts. See the Adding Gear Alerts chapter in the ATG Portal Development Guide for additional
information about alerts.

Each community has Community Administration Pages, which are an interface for community
administration. The Community Administration Pages provide access to all aspects of the community, as
described below. If you are a Community Leader or Portal Administrator, you can reach the Community
Administration Pages by clicking on the Administer link that appears on each page of the community.
It is important to distinguish between the Community Administration Pages and the Communities tab of
the Portal Administration. The Communities tab in the Portal Administration is where you create new
8
communities. Once you have created a community, you can create pages for and administer the
community in the Community Administration Pages.
When you open the Community Administration Pages, you see four main tabs in the navigation bar at the
top. These are the:
Community Users Tab
Community Pages Tab
Community Gears Tab
As you work with the Community Administration, this navigation bar continues to be displayed, letting
you switch immediately to another work area.
In addition, each of these four tabs has a navigation panel at the side. The side navigation panel links to
particular tasks within the main tabs work area.

The Community Settings tab specifies the name, URL, default access settings, style elements, and
customization settings for the community.
Community Users Tab

The Community Users tab specifies the membership of the community. There are six classes of
community membership:
members
member organizations
guests
guest organizations
leaders
leader organizations
The Community Leader can use this page to create, add and remove users of any of these membership
classes from the community.
9
Community Pages Tab
The Community Pages tab specifies the content and layout of the pages in the community. The
Community Leader can use this page to create, edit and remove pages, and to edit the content and layout
of the community.
Community Gears Tab

The Community Leader can use the Community Gears tab to administer instances of gears used in the
communitys pages.
Reset Buttons
A number of pages in the Community Administration include a reset button. This button resets the form
elements of the page to the most recently saved values. The reset button does not reset the default
values once you have clicked the update or save button on the page.
10
3 Portal Configuration
Once the PAF is installed, you must configure it to work with your production Web server and database.
You must also update your template files to display your branding information and graphics. This chapter
includes the following sections that describe various configuration options:
Business Rules
Localizing a Portal

ATG Portal may require some product-specific configuration to work with your database. See the
Configuring Databases and Database Access chapter in the ATG Installation and Configuration Guide for
information about how to configure database access and install the Portal database.

You must configure the repositories for your PAF, as well as for any gears. For a general discussion of
repositories, refer to the ATG Repository Guide.
Portal Repository Creation

The PAF requires a SQL repository to store the various components and gears that make up the PAF itself.
The PAF automatically creates this repository during installation. The Nucleus address of the repository
component is /atg/portal/framework/PortalRepository. For most portal applications, the default
repository component and database script is sufficient. For custom implementations of the PAF, you can
modify the PortalRepository definition file and database schema to create and extend repositories
that suit your specific needs. However, ATG technical support cannot support any changes you make to
the default PortalRepository definition file and database schema.
11
3 - Portal Configuration
Portal Repository Configuration
A SQL repository uses cache modes to define how its repository items are cached. For evaluation and
development, the Portal repository is configured to use the simple cache mode. For deployment, you
should set the cache mode for each of the item descriptors of the Portal repository to locked mode. You
can do this easily by enabling the liveconfig configuration layer before you go live with your Portal
application. The changes needed in the PortalRepository definition file can be found at
<ATG2007.1dir>/Portal/paf/framework/liveconfig/atg/portal/framework/portalReposito
ry.xml. For more information about SQL repository cache modes, see the SQL Repository Caching chapter
of the ATG Repository Guide. For more information about liveconfig, see the ATG Installation and
Configuration Guide.
Profile Repository
Since a portal typically relies on user profile information to determine what information should be
delivered to which users, in most cases you will want to customize your user profile repository to include
item descriptors and properties that allow you to differentiate among different classes of users and store
their portal preferences and other user information. See the Portal Personalization section for more
information.
Portal Personalization
Registered visitors to the portal are recorded in the ATG profile repository. The profile repository stores
information on each registered user, such as name, gender, and address. The profile repository is installed
as part of the ATG platform, and is used by several different parts of the ATG product suite. For more
information on the profile repository, refer to the Configuring the Profile Repository Component section of
the Setting Up a Profile Repository chapter in the ATG Personalization Programming Guide. If you are using
an LDAP-based profile repository, see the Setting Up an LDAP Profile Repository chapter in the ATG
Personalization Programming Guide.
Profile Template
The profile repository requires a template to define users in the profile repository. The ATG platform
features a default profile template that you can redesign to suit your needs. However, as you customize
the profile template, be sure that your schema retains the item descriptors and properties that are
required by the PAF and the baseline or custom gears you are using in your portal application. The PAF
expects a profile item descriptor named user, with at a minimum properties named login, firstName,
and lastName
The PAF extends the default profile template to include new item descriptors (gearUser,
personalizedRegion, personalizedCommunity, personalizedPage) that store information about
how a user may have customized his or her portal pages. These profile template changes are added in the
following file:
<ATG2007.1dir>/Portal/paf/config/atg/userprofiling/userProfile.xml
12
In addition, the Favorite Communities gear extends the default profile template to include a
userCommunity property that describes the communities to which a visitor belongs. This property is
added in the following file:
<ATG2007.1dir>/Portal/communities/config/atg/userprofiling/userProfile.xml
The Alerts gear extends the default profile template to include properties that store the users alerts and
alert preferences. These profile template changes are added in the following file:
<ATG2007.1dir>/Portal/alert/config/atg/userprofiling/userProfile.xml
When you use the ATG platform with the Portal module, these files are included in your Dynamo
CONFIGPATH and are combined with the other user profile template definition files that share its Nucleus
address of /atg/userprofiling/userProfile.xml.
You can add user information to your repository by editing the ATG platform user profile template, or by
extending the template to include other tables. For more information on modifying the profile template,
refer to the ATG Personalization Programming Guide.
Business Rules
ATG Portal can use ATG Scenario Personalization to provide customized content based on the scenarios
that you create. For more information on personalization, alerts, and scenarios, refer to the ATG
Personalization Programming Guide and the ATG Personalization Guide for Business Users.

ATG Portal includes a set of style elements, including templates and images, that you can use to
familiarize yourself with the structure and conventions of the PAF. You can change the appearance of
your portal pages and insert your own portal branding by making copies and editing the JSP and image
files, or by creating your own. Once you are familiar with the style elements, you can create new ones and
add them to the default versions. The recommended way for you to brand your portal is to create a new
Web application containing your new branded template files.
The default storage location for JSP page template files is in the
<ATG2007.1dir>/Portal/paf/starter-portal/paf-dar/portal/templates folder. Note that in
many cases there are separate versions of the templates for HTML and for WML. Also note that there is a
folder named <ATG2007.1dir>/Portal/templates. The templates in that folder are there for
backwards compatibility with ATG 5. They should not be used as a basis for page development in the ATG
platform. For more detailed information about creating and using style elements, see the Style
Administration section in the Portal Administration chapter of this guide and the Customizing Portal
Appearance section of the Creating a Custom Portal chapter of the ATG Portal Development Guide.
13
Shared and Full Page Template
The shared and full page template (<ATG2007.1dir>/Portal/paf/starter-portal/pafdar/portal/templates/page/html/shared.jsp and <ATG2007.1dir>/Portal/paf/starterportal/paf-dar/portal/templates/page/html/full.jsp) are the primary template file, and
function as the outermost wrapper for the page. These page templates specify the header and footer
HTML tags for the dynamically generated page.
Layout Templates
The layout template file specifies the layout of the page, creating a portal page framework for the
placement of your gears. ATG Portal includes four layout templates for use with your portal. The default
storage location for layout template files is the <ATG2007.1dir>/Portal/paf/starter-portal/pafdar/portal/templates/layout folder. For information on creating your own page layouts and
templates, refer to the Customizing Portal Appearance section of the Creating a Custom Portal chapter in
the ATG Portal Development Guide.
100.jsp Template
This template creates a page with one column spanning the full width of the page.
25_50_25.jsp Template
This template creates a page with three columns. The leftmost and rightmost columns span a quarter of
the page each. The center column spans fifty percent of the page width.
25_75.jsp Template
This template creates a page with two columns. The left column spans a quarter of the page width. The
right column spans the remaining seventy-five percent of the page width.
75_25.jsp Template
This template creates a page with two columns. The left column spans seventy-five percent of the page
width. The right column spans the remaining quarter of the page width.
region.jspf
Each layout template defines a table, the cells of which each contain a separate gear. The layout template
file calls the region template file once for each table cell in the page, until it has formatted all of the cells
in the page. The region template file specifies the formatting of regions within the portal page. A region is
defined as an individual table cell.
Gear Title Template Files

A gear is rendered in stages. First the titlebar.jsp file renders the title bar above the gear. The
titlebar_pre.jsp creates the table that contains the gear. Then the gear itself is rendered, and the
titlebar_post.jsp closes the table. The default storage location for gear title template files is the
<ATG2007.1dir>/Portal/paf/starter-portal/paf-dar/portal/templates/titlebar folder.
14
titlebar.jsp
The gear title template file specifies the title formatting at the gear level, providing a decorative title and
border for the gear. The gear title area may also contain an Edit control for Community Members to
customize the gear, if the gear and the community allow customization. The gear title template is used for
all the gears in a given community.
titlebar-pre.jsp
The gear pre-treatment template creates an HTML table to contain the gear itself.
titlebar-post.jsp
The gear post-treatment template closes the HTML table created by the titlebar-pre.jsp template
file.
Stylesheet Files
A simple cascading stylesheet is located at <ATG2007.1dir>/Portal/paf/starter-portal/pafdar/portal/templates/style/css. See the Style Administration in the Portal Administration chapter
for information about adding new stylesheets to your portal application.
Additional Branding Files

You can also customize the login, logout, registration, error, and authentication pages. This allows you to
ensure that these pages match the design and branding of your portal. Customizing these files requires
knowledge of JSP.
Files
File Name
Location
Login
login.jsp
<ATG2007.1dir>/Portal/paf/starterportal/paf-dar/portal/userprofiling
Logout
logout.jsp
Registration
register.jsp
Error
error.jsp
<ATG2007.1dir>/Portal/paf/starterportal/paf-dar/portal
Access Denied
accessDenied.jsp
<ATG2007.1dir>/Portal/paf/starterportal/paf-dar/portal/access
Community Offline
offline.jsp
<ATG2007.1dir>/Portal/paf/starterportal/paf-dar/portal/access
15
Creating Style Element Templates
You can create additional templates to determine the style and structure of your portal pages. Only
developers familiar with Java server pages should attempt to do this. Create copies of the original style
element files, and move them to a separate directory. Using the copies as an example, and, referring to
ATG Portal Development Guide, you can create new style element templates. The original template files are
stored in the templates folder in <ATG2007.1dir>/Portal/paf/starter-portal/paf-dar/portal.
Once you have created the new style element files, refer to Style Administration in the Portal
Administration chapter to make the style element available to communities.
Localizing a Portal
If you want to create a portal application that can serve users in different languages and locales, you
should read the Internationalizing a Dynamo Web Site chapter in the ATG Programming Guide. This section
describes a few considerations that are specific to an ATG Portal application.
You can enable support for additional locales and change character encodings used for the entire portal.
This is done by copying, renaming, and (if you want to change a locales default character set) editing a
file that is provided with the Portal module. Use the following procedure:
1.
In your <ATG2007.1dir> directory, create the following directory branch:

<ATG2007.1dir>/home/locallib/atg/portal/framework
2.
Locate and copy the LocaleSettings.properties file within your ATG installation.
The file is in:
<ATG2007.1dir>/Portal/lib/classes.jar
3.
Place the copy of the LocaleSettings.properties file into the new directory you
created, and make additional copies for each locale you want to add to the portal.
4.
Add the language and/or locale setting to the filename, as follows:

LocaleSettings_language_country.properties
where the required language is the desired Java language code (which is the same as
the ISO two-letter language code) and the optional country is the desired Java locale
code (which is the same as the ISO two-letter country code). For example, if you want
to add French, you would name your file LocaleSettings_fr.properties and if
you wanted to add French with a country of Canada, you would name your file
LocaleSettings_fr_CA.properties. For more details, refer to the Java
internationalization documentation.
5.
If you also want to change the default character set for the language or
language/locale combination, open the file and add the non-default character set.
The following sample illustrates how you would change Japanese with an EUC
character set to Japanese with an SJIS character set:
16
# Version: $Change: 219562 $$DateTime: 2001/11/12 13:47:44 $

# If you want to override the default Java-chosen charset for this locale
# add a line charset=the-charset to this file.
# For example for Japanese using SJIS in place of EUC:
# charset=Shift_JIS
# Or for Unicode:
# charset=UTF-8
charset=Shift_JIS
In addition, you need to make sure that the gears you want to use in your localized portals are also
localized into each of the locales you want to support. See Localization Considerations in the Designing a
Gear chapter of the ATG Portal Development Guide.

Many events in ATG Portal can trigger alerts, which can be sent by Web channel for display in a portal
page or by e-mail. To use e-mail alerts, you need to set the messageFrom and messageReplyTo fields in
the Portal e-mail templates to a valid e-mail address for your organization. The following e-mail templates
are included in the Portal module.
/alert/src/alert.war/email/DefaultEmail.jsp
/calendar/src/src/calendar.war/email/CalendarEventCreatedEmail.jsp
/calendar/src/src/calendar.war/email/CalendarEventDeletedEmail.jsp
/calendar/src/src/calendar.war/email/CalendarEventEditedEmail.jsp
/calendar/src/src/calendar.war/email/CalendarEventViewedEmail.jsp
/discussion/src/src/discussion.war/email/NewForumEmail.jsp
/docexch/src/src/docexch.war/email/DocCreatedEmail.jsp
/docexch/src/src/docexch.war/email/DocDeletedEmail.jsp
/docexch/src/src/docexch.war/email/DocUpdatedEmail.jsp
/docexch/src/src/docexch.war/email/DocViewedEmail.jsp
/screenscraper/src/doc/Portal/email/FullPageURLChangedEmail.jsp
/screenscraper/src/doc/Portal/email/SharedPageURLChangedEmail.jsp
You may have custom e-mail templates as well. If you do not supply valid e-mail addresses, no alerts will
be sent by e-mail and the portal will generate errors if e-mail alerts are configured.

The Portal Alerts system uses the ATG platform Global Scenario Server. Because running the Global
Scenario Server places an additional burden on your server, consider configuring the global servers to not
accept any user sessions. Do this by setting the drpEnabled property to false in the
/atg/dynamo/Configuration component for that server instance. For additional material on
configuring ATG products for improved performance, programming efficiently and troubleshooting
server performance problems, refer to the ATG Installation and Configuration Guide.
17
18
4 Community Administration
Most visitors to your portal belong to one or more communities. By creating separate communities within
your portal, you can determine what access your portal visitors have to content and functionality. You can
even specify community-specific settings for the gears that appear on the portal page. For example, you
could customize a weather forecasting content gear to provide local weather information for a remote
office.
Each community has its own pages, with customized content, layout, and colors. The more your visitors
tell you about themselves and their preferences, the more specific and customized their communities can
become.
Community
A community is a collection of portal users and content. A typical community shares a common purpose
or hobby. The community might be a company department, such as a human resources group, or it might
be a group of users with a common interest, such as a social group. Each community has its own portal
pages, with content and functionality specific to the needs and interests of the community.
Individual
An individual is a unique visitor to the portal site. Depending on the permissions set by the Community
Leader, individuals can view content, and interact with other individuals in their community. Individuals
can belong to any number of communities. The individuals role can also vary from community to
community.
The Community Leader can allow individuals to customize their portal pages on an individual level. As an
individual, you can set the color palette of your personal portal, the layout of your gears, and which gears
and content appear in your portal page.
Organization
An organization is a group of individuals that are members of a common group. Community membership
can be assigned on an organization membership basis. Once an employee is a member of an
organization, that employee has access to all communities that the organization belongs to. For example,
all HR employees might be members of the HR organization. You could add a new hire to the HR
organization, and that new hire would automatically receive membership to all the communities in which
the HR organization has membership. You can designate an organization to have guest, member, or
leader access to a community.
19
4 - Community Administration
Community Folders
Community folders organize communities hierarchically within the PAF. Visitors to the portal site see the
Community name, rather than the name of the community folder. Each community folder contains both a
name and a Web-Friendly URL. The Web-Friendly URL is used to generate the URL for the Community
pages. Consequently, the Web-Friendly URL can contain only alphanumeric characters. Spaces and
symbol characters in the Web-Friendly URL are removed, because they would otherwise cause the page
to generate an error.
Creating Community Folders

A Portal Administrator can create a new community folder in the Portal Administration. To create a new
community folder:
1.
Open the Communities tab in the Portal Administration.
2.
Click the New Community Folder link in the side navigation bar.
The New Community Folder page opens.
3.
Select the parent folder for the new folder. The root folder is named Default
Community Folder.
4.
Enter the name and Web-Friendly URL for the new folder and click Save. Remember
that the Web-Friendly URL can contain only alphanumeric characters. Nonalphanumeric characters will be stripped out.
Deleting Community Folders

If you want to delete a community folder, you must first delete all of its child folders and communities
using the Communities tab in the Portal Administration. Once youve done this, to delete a community
folder, use the ATG Control Center:
1.
Start the ACC and open the Portals > Portal Repository window.
2.
Display Items of type Community folder, then click List.
3.
Select the parent folder of the folder you want to delete. Select its Child folders
property and click the ... button.
4.
Select the folder that you want to delete and click Remove.
5.
Click OK. You are returned to the Portals > Portal Repository window.
6.
Select the folder that you want to delete. Be sure that its Child folders property is
empty. Right click on the folder you want to delete and select Delete from the menu.
Click Yes in response to the Delete Confirmation prompt.
Reserved Community Names

You can reserve community Web-Friendly names for administrative use. The Portal Administrator can
reserve other names using the ACC, as described in the Reserving a Web-Friendly Name section below.
20
For more information on the ACC, refer to the ATG Installation and Configuration Guide. If a user tries to
create a community using a name included on reserved list, the user receives an error, and cannot use the
name.
Note that you should not use as a URL any of the file names found in
<ATG2007.1dir>/Portal/paf/starter-portal/paf-dar/portal/, including access, portlets,
templates, or userprofiling.
Specifying a Home Community

The Web-Friendly name home is special for communities. If a community has the Web-Friendly name home
then it can be accessed through a URL by specifying just the path of the Community Folder, and not the
complete URL. For example if you have a Community Folder named /foo and a community named Bar,
which has a Web-Friendly name home then you can access the Bar community via the URL /foo/ instead
of /foo/home. The advantage to naming a community home appears when you have multiple
communities in the same folder. The home community becomes the primary community for that
community folder, and is the default community when visitors enter the community folder URL. There can
be only one home community in a given community folder.
Reserving a Web-Friendly Name

The PortalPropertyManager component maintains a list of reserved names for the portal. If you have
Administrator privileges, you can edit this list in the ATG Control Center. To add a reserved name:
1.
Open the ATG Control Center.
2.
Select Pages and Components, followed by Components by Path.
3.
Navigate to /atg/portal/admin/PortalPropertyManager.
4.
Within the PortalPropertyManager module, select the reservedCommunityNames

property.
The default settings are admin and settings.
5.
Add the new reserved names to the property, and click Save.
The new names are added to the list of reserved names.
Community Roles
Most visitors to your portal will belong to one or more communities within that portal. When a visitor
belongs to a community, the visitor takes on a role within that community. The scope of that role can vary
from anonymous access visitor to global Portal Administrator. Your role determines your ability to
customize your portal, view content, and to interact with other users. At administrative levels, your role
also determines your ability to grant and restrict the authority of other users.
21
Global Roles
Administrators with global roles have authority across all portals and communities within the PAF.
Administrators with global roles are responsible for installing and maintaining the PAF, as well as creating
the communities that populate it.
Portal Administrator
The Portal Administrator creates and deletes community folders and communities, and manages gear
folders. The Portal Administrator is responsible for day-to-day issues of portal and community
membership administration using the administrative interface provided by the PAF. These tasks include
adding new gears and style elements to the portals, and maintaining and updating existing portals. Portal
Administrators have authority over all of the communities in the PAF, including those created by other
Portal Administrators.
The Portal Administrator is the only role that has access to the Portal Administration Pages. These pages
allow access to the gears and style elements that make up the PAF.
Relative Roles
Relative roles apply to leaders, members, and guests of a particular community. The administrative
authority granted by a relative role applies only to the community in which it was given, and does not
apply to any other community. The ability of relative role holders to administer their communities and
personal portals is subject to the limits set by the Portal Administrator.
Community Leader
The Community Leader assigns new members to the community, and chooses the default gears, color,
and layouts for the communitys pages. Community Leader status is assigned by the Portal Administrator.
Existing Community Leaders can also assign Community Leader status to other Community Members.
Community Leaders can also configure default gear settings and permissions for their communities.
Community Member
A Community Member is one of the most common roles in a community. Once they have logged in,
members typically have full read/write access to the community. For example, a community member
could read and write to a community discussion board. Members usually also have the ability to
customize the appearance and content of their personal portals.
Community Guest
A Community Guest is a logged in user who has permission to view a community portal page, but does
not have full membership access to that portal. For example, a companys Sales community might have
permission to view the portals of other communities as guests of those communities. The ability of
Community Guests to interact with portals is subject to the security settings of the portal.
Registered User
A registered user visitor is a visitor that has logged in to the portal, but does not have a role as a leader or
member within the community. Depending on the permissions in the PAF, registered user access may not
be permitted in your portals and communities.
22
Anonymous Access
An anonymous access visitor is a visitor that has not logged in to the portal. Depending on the
permissions in the PAF, anonymous access may not be permitted in your portals and communities. Once
anonymous access visitors log in to the portal, they automatically lose anonymous access status and
assume their community roles, or registered user status if the visitors do not have community roles.
Community Role IDs

The PAF creates a role ID for each type of member role when the community is created. These role IDs are
stored in the PAF repository in the form of <communityID>-<roletype>. For example, a member of the
Tennis Community (community number 10004) might appear as 10004-member. Although you can view
these role IDs using the ACC, you cannot edit the role ID without making the role unrecognizable to the
PAF, and causing errors in the community.
Community Membership
Community membership can be handled in a variety of manners, depending on how much administrative
involvement the community requires. You can specify the membership settings of a community from the
Community Settings and Community Users tabs of the Community Administration Pages.
Membership Settings
The Community Settings tab lets you choose one of these membership settings:
Allow Membership Requests and Automatically Accept New Members

This setting allows visitors to request membership in the community. The PAF automatically accepts
these requests without checking with the Community Leader. Visitors seeking membership apply by
clicking the Become a member link on the community page. This setting allows the greatest public
access to the portal page.
Allow Membership Requests and Notify Community Leaders

This membership setting allows visitors to request community membership, but withholds membership
until the Community Leader has approved the request. Visitors seeking membership apply by clicking the
Become a member link on the community page. When a visitor applies for membership, the visitors
name and e-mail address appear on the Approve/Decline Membership Requests page in the Community
Users tab. The Community Leader can then use that page to either approve or decline the membership
request. This setting allows conditional public access to the portal page.
Do Not Allow Membership Requests

This membership setting prevents visitors from applying for membership at all. The Portal Administrator
and Community Leaders can still grant community membership.
23
Canceling Community Membership
Community Members can terminate their membership in the community by clicking the Unsubscribe
link on the community page. Once they are unsubscribed, former members can reapply for membership
by following that communitys standard membership process.
Adding and Removing Community Members

From the Community Users tab, a Community Leader can add or remove users and organizations as
community members or leaders or approve or decline membership requests from guest users. You can
also use the Create user link on the Community Users tab to add new user profiles to the Profile
repository. Once you have created a new user profile, that user can then become a community member.
Note that when you remove users as community members, you are not removing their profiles from the
profile repository.
Working with Communities

The Portal Administrator handles community-level tasks from the Portal Administration Pages, including:
Editing a Community
A Community Leader performs other community tasks in the Community Administration Pages,
including:
In addition, Community Leaders can use the Community Administration Pages to control access and
assign community roles to users, as described in the Working with Community Membership section in this
chapter.
The first step to creating a portal is creating a community. Each community is a group of users for whom
the portal is designed. The community is, in effect, your audience. Communities are created by Portal
Administrators, using the Communities tab in the Portal Administration.
24
1.
Enter the Portal Administration and click on the Communities tab.
2.
Click New Community.
The New Community Page opens.

3.
Select or create a folder for the community.

The community can reside within an existing folder, or you can create a new folder for
the community.
4.
Enter a Community Name and a Web-Friendly URL.

The Community Name is used in the portal and the Portal Administration to refer to
the community. The Web-Friendly URL is used in generating the URL for the
Community pages. As a result, non-alphanumeric characters are stripped out of the
Web-Friendly URL.
You can also specify other settings for the new community now, or you can specify
them later as you develop the community; these are described in the Editing a
Community section.
5.
Click Save.
The community is created, but is left inactive.
6.
To make the community available online, select Active from the Status dropdown list
on the New Community page in the Portal Administration or the Community Settings
Page in the Community Administration and click Update.
You can also create multiple similar communities using a community template. For example, if you are
creating a portal for an organization with many local branches, you can create a community for one
branch, using the procedure described in this section. You can then create a community template based
on this community, then use the template to create a similar community for each branch. For a
description of how to make and use a community template, see Creating Communities from Community
Templates.
Making Gears Available to a Community

Before you can add a gear to a portal page, the gear must first be made available to the community. To
make a gear available:
1.
The gear must be added to the PAF. See Adding Gears to the PAF in the Portal
Administration chapter.
2.
The gears folder must be made available to the community, using the gear folders
link for the community on the Available Communities page in the Portal
Administration. See the Limiting a Communitys Access to Gears topic in this section.
3.
Make an instance of the gear available. Enter the Community Administration for the
community and click the Community Gears tab.
4.
Click the Select New Gears option in side navigation panel of the Community Gears
tab. The Add gears page opens.
5.
Click the select >> link for the gear you want to make available. The Configure Gear
page opens.
25
6.
Enter a name and description for this instance of the gear.
7.
Select whether this gear should be shared with other communities and which users
the gear should be visible to. Click Done.

By default, a community has access to all gear definition folders and hence has access to all gears. If
necessary, you can limit the access of any community to the gears contained in specific folders. For
example, if you had a gear containing sensitive financial information, you might want to prevent all
communities except the Accounting community from having access to the gear. To limit gear access:
1.
2.
Select the community for which you want to limit gear access and click its gear
folders link.
The Assign gear folders to the Community page opens.
3.
Click the Select Folders below radio button and then check only the gear folders to
which you want the community to have access.
4.
Click Save.
Note that if a gear already exists in the community, this procedure will not remove that gear from the
community. To remove access to a gear that already exists in a community, you need to:
1.
Remove the gear from each community page on which it appears.
26
2.
Use the Community Gears tab of the Community Administration to delete the gear
instance.
Editing a Community
Once you have created a community, a Portal Administrator or Community Leader can edit it to change
settings for the community and that communitys portal page.
1.
2.
Locate the community that you want to edit and click the edit link next to the
community name.
Or, enter the Community Administration for the community and click the Community
Settings tab.
The Community Settings Page in the Community Administration opens.
3.
Specify a Description and Request for membership options for the new community.
4.
Specify Page template, Style, Gear title template and Customization options for
this communitys portal pages.
5.
If you want to make the community visible to members, set the communitys Status
option to Active.
6.
Click Update.
The settings you have specified are applied to the community and the Communities
page opens.
You can disable a community, preventing all access to that community.
1.
Log in to the Portal Administration Pages and click on the Communities tab.
2.
Locate the community that you want to edit and click the edit link next to the
community name.
Or, enter the Community Administration for the community and click the Community
Settings tab.
The Community Settings Page opens.
3.
To disable the community, set the Community Status option to Inactive.
4.
Click Update.
The settings you have specified are applied to the community. If a user tries to visit the
community, the portal will display a page that says this community is offline.
A Portal Administrator can also delete an entire community. You should never delete a community using
the ATG Control Center; instead, use the Portal Administration. To delete a community:
27
1.
Open the Communities tab in the Portal Administration and click the delete link for
the community.
2.
A confirmation message appears, warning Are you sure you want to delete the
community <name>? Deleting this community will also delete any of this communitys
shared gears from other communities. Click on the Yes button to delete the
community and all its pages.
Deleted communities will appear as nulls in the userCommunities property of a user profile in the ACC.

Each community has its own portal pages. A default page is created when you create the community. You
can redesign this page to suit the needs of that particular community. To edit an existing page:
1.
As a Portal Administrator, log in to the Portal Administration and click on the

Communities tab. Locate the community whose page you want to create, and click the
edit link next to the community name. Or, as a Community Leader, click on the
Administer link on the communitys home page.
The Community Settings Page opens.
2.
Click on Community Pages in the top navigation bar.

The Community Pages page opens, displaying all of the portal pages that belong to
the community.
3.
Select the page that you want to edit and click edit.
The Edit page for that portal page opens.
Use the Basics tab in the Edit Page to change the pages name or URL, set the access
permissions, and specify whether users are allowed to customize the page.
Customization lets users modify the appearance of their view of the page. It can also
28
let them delete from their view gears that the Community Leader wants them to see,
however.
4.
Use the Gears tab in the Edit Page to add and remove gears from the portal page. See
Adding Gears to a Community Portal Page for more details.
5.
Use the Layout tab in the Edit Page to specify a layout template and the placement of
gears within the portal page. Click Update to apply your layout to the page.
6.
Use the Color tab in the Edit Page to specify the color palette to use on the portal
page. Click on a color theme to preview the color palette, then click Update to apply
that palette to the page.

Once you have created a community, you can create additional pages for that community.
1.
As a Portal Administrator, log in to the Portal Administration Pages and click on the
Communities tab. Locate the community to receive the new page, and click the edit
link next to the community name.
Or, as a Community Leader, click on the Administer link on the communitys home
page.
The Community Settings page opens.
2.
Click on Community Pages in the navigation bar.

The Current Pages page opens, displaying all of the portal pages that belong to the
community.
3.
Click on the Create New Page link in the side task bar.
The Create New Page page opens.
4.
Enter a name for the page.
5.
Choose a position number from the dropdown list. The position number indicates the
place of the page in the list of all community pages.
6.
Enter a Web-Friendly URL. The Web-Friendly URL can contain only alphanumeric
characters. Spaces and symbol characters cause the Create New Page page to
generate an error. You can click the Generate URL button to automatically generate a
URL based on the page name you entered.
7.
Choose who can access the page by selecting a radio button under Make visible to.
8.
Check the appropriate box if you want to permit users to customize the page or if you
want to make this page the default page for the community.
9.
When you have finished editing the portal page, click Update.
The changes you specified are made and the Current Pages page of the Community
Pages tab opens.
29

When you create a community portal page, you can add gears to those already included in the page
template. To add a new gear to a page:
1.
Navigate to the Gears tab on the Edit Page for the page, as described in the Editing a
Community Portal Page section.
2.
Check the boxes of the gears you want to include in the page and click Update.
3.
Use the Layout tab on the Edit Page to arrange the position of gears in the page.
Note that only those gears that have already been made available to the community are displayed in the
Gears tab of the Edit Page. To make a gear available to the community, a Portal Administrator must add it
to the PAF using the Gears tab in the Portal Administration and make sure that the gear folder that
contains the gear is itself available to the community. See Adding Gears to the PAF in the Portal
Administration chapter. Next, a Community Leader must add an instance of the gear to the community.
See Making Gears Available to a Community in this chapter.

You can view a community portal page using the Portal Administration. When you view a page using the
preview link in the administrator pages, you see the default version of those pages, regardless of any
customization you may have applied to your own individual pages in the community. The preview link
only appears for communities that are currently active. To view an inactive community, change its online
status to active.
1.

Communities tab.
2.
Locate the community you want to view, and click the preview link next to the
community name.
The default version of the community page opens in your browser window.
Alternatively, you can view a community portal page as a Community Leader:

1.
Enter the Community Administration for the community whose page you want to
view.
2.
Click the Community Pages tab.
3.
Click the view link for the page you want to view.
The default version of the community page opens in your browser window.
Note that if you have changed the portals context root in its deployment descriptor (application.xml),
you also need to change the value of the contextPath property in the
/atg/portal/framework/Portal component. Otherwise, the preview feature in the Community
Administration will not work correctly.

You can remove pages from a community. As a Portal Administrator or Community Leader, removing
pages from a community affects the entire community. If a Community Member deletes a page, only that
30
Members pages are affected. Once a Community Member deletes a page, however, that Member cannot
restore the page to his or her own portal pages, even though the page still is available to other
Community Members.
1.

Communities tab. Or, as a Community Leader, click on the Administer link on the
communitys home page.
2.
Locate the community whose page you want to delete, and click the edit link next to
the community name.
The Community Settings page opens.
3.
Click on Community Pages in the navigation bar.

The Community Pages page opens, displaying all of the portal pages that belong to
the community.
4.
Select the page that you want to remove and click delete. Confirm the deletion by
clicking the Yes, Delete button.
The portal page is deleted.
Creating Communities from Community Templates

ATG Portals provides two methods for copying an existing community to make multiple similar
communities. You can do this using the Community Templates and New Community Template pages in
the Portal Administration, or you can do this using a command line tool named SpawnCommunity. Using
community templates through the Portal Administration may be easiest when you have just a few new
communities to create based on a template. Using the SpawnCommunity tool may be easier if you have a
large number of new communities to create.
Once youve created a community template, you can use the ATG Portal Process Automation
(Portal.ppa) tools to create workflows that can automate the process of creating new communities
from the template. See Automating the Portal Creation Process for more information.
Using the Community Templates User Interface

Creating a New Community Template
To create a new community template using the Portal Administration:
1.
Click the New Community Template link on the main Communities page in the Portal
Administration.
2.
Click the save as template link to create a new community template based on an
existing community.
3.
Enter a name for the new template and click Save.
31
Creating a New Community from a Template
Once youve created a community template based on an existing community, you can create new similar
communities based on the template. To create a new community based on a template:
1.
Click the Community Templates link on the main Communities page.
2.
Click the spawn community link for the community template you want to use.
3.
On the Spawn new community from template page, enter a name and other
information for the new community. Click Save.
Using the SpawnCommunity Tool

You can create new communities from a command line using the SpawnCommunity tool. You can find
UNIX and Windows versions of this tool in the <ATG2007.1dir>/Portal/PDK/ManifestLoader folder.
To create a new community using the SpawnCommunity tool:
1.
Create a new community template using the Portal Administration, as described in the
Using the Community Templates User Interface section.
2.
Go to the Community Templates page and click the export link for the community
template you want to use. This creates an XML file that represents the community
template. You need to pass this XML file to the SpawnCommunity tool.
3.
Run the SpawnCommunity tool. The syntax and arguments of the SpawnCommunity
tool are described below.
A new community is created, taking its values from the community template. You can then edit the gears
and pages of the new community as needed. Note that you can pass arguments to the SpawnCommunity
tool to override many of the parameters of the community template.
The SpawnCommunity tool uses the following syntax:
SpawnCommunity.sh -template COMMUNITY_TEMPLATE -name COMMUNITY_NAME
-url COMMUNITY_URL <optional arguments>
SpawnCommunity Arguments
The SpawnCommunity command takes the following arguments:
Argument
Description
Default Value
-template
The template XML file exported

from the Portal Administration.
Required. Use the pathname

of the template file, which
can be either an absolute
pathname or a pathname
relative to the directory from
which you run
SpawnCommunity.
32
-name
The name of the new spawned

community.
Required. No default.
-url
The URL of the new spawned

community.
Required. No default.
-parentFolder
The ID of the parent folder for

the spawned community.
The parent folder ID of

community template
-enabled
Is the new community enabled?

One of true or false.
The enabled value of

community template
-description
Description text for the spawned

community.
The description of the

community template
-membership
Membership request level for

Membership request level of

community template.
-pageTemplate
The ID of the page template for

The page template ID of

community template.
-style
The ID of the style for the

spawned community.
The style ID of community

template.
-gearTemplate
The ID of the gear template for

The gear template ID of

community template.
-customization
The customization level for the

spawned community.
The customization level of

community template.
-access
The access control level for the

spawned community.
Integer. The access control

level of the community
template.
-host
The hostname of the machine

currently running you
application server. If you do not
specify this argument and the port argument, then the
SpawnCommunity tool will start
and stop its own Nucleus service
rather than using the currently
running Dynamo.
Defaults to localhost if no
hostname is specified.
-port
The port for the RMI server on

the currently running Dynamo
server.
8860
-cloneSharedGears
Should the spawned community

clone shared gears, rather than
refer to the original gears?
Boolean. Defaults to false.
33
Automating the Portal Creation Process

You can combine an ATG Portal community template with the ATG Workflow engine to automate the
process of creating new communities in your portal application. ATG Portal includes a
CommunityProposal class, which embodies the basic properties of a proposed new community, as well
as scenario and workflow actions that you can use to handle the process of approving the new
community and automatically creating it from a community template.
To set up a community proposal workflow:
1.
Assemble an application that includes the Portal.ppa module, which represents the
Portal Process Automation. For information about application assembly and about
ATG modules, see the ATG Programming Guide. Deploy and start the application you
created according to the instructions from your application server manuals.
2.
In the ATG Portal Administration interface, create a community template that you
want to use as the basis of your new communities. You can have more than one
community template. See the Creating Communities from Community Templates
section in the Community Administration chapter.
3.
In the ACC Workflow window, create a workflow to handle proposals to create new
communities. See Creating a Workflow for Community Proposals.
4.
In the ACC Scenarios window, create a scenario that listens for community proposal
creation events and starts the community proposal workflow. See Creating a Scenario
for Community Proposal Workflows.
5.
Create a page or other code that initiates community proposals and creates
community proposal creation events. See Creating a Community Proposal.
Community Proposals
A community proposal is represented as a Java object that can be handled in a workflow. Community
proposals are maintained in a database and represented in a SQL repository named the Portal Process
Repository. The Portal Process Repository has a Nucleus address of
/atg/portal/process/ProcessRepository.
Community Proposal Properties

ATG Portal includes a simple repository schema to support community proposal workflows. The Portal
Process Repository defines a item descriptor named communityProposal. Each communityProposal
repository item represents an individual community proposal. An item of type communityProposal
includes the following properties:
Property
Description
community
The name of the community to be created
communityTemplate
The community template file. This file is created using the Portal
Administration interface, as described in the Creating Communities from
Community Templates section in the Community Administration chapter.
34
creationDate
A property automatically calculated from the current time when the

community proposal is created.
creator
The user who created the community proposal. This property is a user
profile maintained in the Profile Repository.
id
A string ID for the community proposal.
lastModified
A property automatically calculated from the current time when the

community proposal is modified.
name
The name of the community proposal.
url
The URL segment for the new community.
version
An integer for the version number of the community proposal.
You can customize the community proposal to include other properties. To do so, you need to:
1.
Modify the database schema for the Portal Process Repository. The SQL scripts that
define this database schema are located at
<ATG2007.1dir>/Portal/ppa/sql/install.
2.
Modify the repository definition file for the Portal Process Repository. This definition
file is located at
<ATG2007.1dir>/Portal/ppa/config/atg/portal/process/ppa.xml.
3.
Create a new community proposal Java class that implements the

atg.portal.process.CommunityProposal interface, adding methods to handle
your new properties.
Creating a Workflow for Community Proposals

Use the Workflow window of the ATG Control Center to create a workflow to handle proposals to create
new communities. For more information about workflows in general, see the Creating and Configuring
Workflows chapter in the ATG Personalization Programming Guide and the Using Workflows chapter in the
ATG Personalization Guide for Business Users.
If you use ATG with the Portal.ppa module, then the ACC Workflow window includes a category named
Community Proposal. Create your workflows in this window. The Portal.ppa module makes all the
properties of a community proposal available in the Workflow editor.
A simple community proposal workflow might look like this:
35
This simple workflow has the following elements:

1.
The examine task calls for a worker to examine the community proposal. The result
can be either approve or reject. If the community proposal is approved, then:
2.
A new community is created, using the communityTemplate, name, and url

properties specified in the community proposal. See Community Proposal Properties
for a complete list of the properties of a community proposal.
3.
The creator of the community proposal is assigned the role of leader for the new
community.
4.
The community specified by the community proposal is enabled (made active).
Create Community from Template Action

A Community Proposal workflow or scenario can make use of the Create Community from Template
action. This action triggers the creation of a portal community. It takes the following input from the
CommunityProposal object:
Action Field
CommunityProposal Property
Community Template
communityTemplate
Community Name
name
Web Friendly URL
url
In addition, the Create Community from Template action takes the following input:
Action Field
Description
Community folder
Which community folder should this community be created in?
36
Clone shared gears
Should this community get its own copy of its gear, or share an instance of
the gear with the template?
Assign Community Role Action

A Community Proposal workflow or scenario can make use of the Assign Community Role action. This
action assigns roles in the community to designated users. It takes the following input:
Action Field
Description
Community id
The ID of the community in which you want to assign roles.
User id
The ID of the user to whom you want to assign a role.
Role Name
The name of the role you want to assign to the user.
Creating a Scenario for Community Proposal Workflows

Use the Scenarios window of the ATG Control Center to create a scenario that listens for community
proposal creation events and starts the community proposal workflow.
A simple scenario to start a workflow might look like this:
The scenario starts with the creation of a community proposal. The scenario listens for
CommunityProposalMessages. A CommunityProposalMessage includes the CommunityProposal as a
property. Given the CommunityProposalMessage, the scenario starts a workflow, assigning the id
property of the CommunityProposal as the subject ID of the workflow.
Creating a Community Proposal

ATG Portal includes a Nucleus component, /atg/portal/process/CommunityProposalHome, that can
be used to create, edit, and delete community proposals. It includes getItem, createItem, addItem,
and removeItem methods that work on CommunityProposal objects. The
CommunityProposalHome.addItem method creates a CommunityProposalMessage, which can be
37
used by scenarios or other components as a starting point for creating new communities based on the
CommunityProposal object.
You can use the CommunityProposalHome component as a basis for form handlers, portlets, JSP pages or
other interfaces that allow users to create, edit, and delete community proposals.
The following example creates a CommunityProposal, setting its name, url, and creator properties to
joe:
import javax.servlet.http.*
import atg.portal.process.*
import atg.userdirectory.*
import atg.userprofiling.*
CommunityProposalHome home =
(CommunityProposalHome)request.resolveName
("/atg/portal/process/CommunityProposalHome");
CommunityProposal cp = home.createItem();
cp.setName("joe");
cp.setUrl("joe");
UserDirectory ud = (UserDirectory)
request.resolveName("/atg/userprofiling/ProfileUserDirectory");
Profile profile = (Profile)request.resolveName("/atg/userprofiling/Profile");
User user = ud.findUserByPrimaryKey(profile.getRepositoryId());
System.out.println("user = " + user);
cp.setCreator(user);
home.addItem(cp);
You could create a form page for creating community proposals that allows users to input the properties
of the proposal.
Working with Community Membership

The Community Leader handles community membership tasks from the Community Administration
Pages, including:
38

Community membership can be assigned automatically. For more information on automatic
membership, refer to the Community Membership section in this chapter. You can assign membership
manually from the Community Users page of the Community Administration.
1.
Log in to the Community Administration.
2.
Click the Community Users tab.

The Community Members page opens.
3.
Click add individuals.

The Add / Remove Individual Member page opens.
4.
Use the search form to locate the individual you want to add to the community.
5.
Check the box next to the new members name and click Add Selected.
The individual is now a community member.
You can also add all the members of an organization as members using the Member Organizations link:
1.
Click Member Organizations in the side navigation panel.
2.
Click add organizations.
3.
Check the box next to the names of the organizations you want to add and click Add
Selected.
Each of the individuals in the organizations you selected is now a community member.

If your portal uses the manual approval membership policy (Allow requests for membership and notify
Community Leaders on the Community Settings page), then membership requests will be sent to the
Approve/Decline Membership Requests page. The Community Leader uses this page to either approve or
decline membership requests.
1.
Log in to the Community Administration Pages.
2.

3.
Click membership-request.
A page listing all pending membership requests appears. Each membership request
shows the name and e-mail address of the person requesting membership.
4.
For each person requesting membership, click later, approve or decline, then click
Update. You can also select all pending requests at once by clicking one of the all
later, approve all, or decline all links.

The Portal Administrator can enable e-mail notification about membership requests. With this
functionality enabled, members would receive an e-mail notifying them when their membership request
39
is either approved or declined. You can do this by creating a Scenario based on the Membership
Approved and Membership Declined events, which are generated when the Community Leader accepts
or declines a membership request.
If you only need a simple e-mail notification, you can use the ATG Control Center to enable membership
requests by e-mail, using the following procedure:
1.
2.
3.
Navigate to the /atg/portal/admin/CommunityPrincipalFormHandler.
4.
Select the sendUserEmail property and set the value to true. Note that by default
this property is set to point to the sendUserEmail property in
/atg/portal/framework/Configuration, so you could also set this property in the
Configuration component.
5.
Specify text strings for the requestEmailSubject, preMessage,

postAcceptedMessage, and postDeclinedMessage properties.
The requestEmailSubject string appears in the e-mails Subject line; the
preMessage string appears before the community name, the postAcceptedMessage
string appears after the community name when the membership request is accepted;
and the postDeclinedMessage appears after the community name when the
membership request is declined. For example, when these properties are
concatenated and the community name is included, the message might read: Your
membership request for the Tennis community has been approved.
6.
Make sure the emailer and emailSenderAddress properties are set properly.
7.
Click Save.

Community Leaders are responsible for assisting the Portal Administrator in membership and
administration issues within a community. Portal Administrators and Community Leaders can assign the
Community Leader role.
1.
Log in to the Community Administration and click the Community Users tab.
2.
Click the Leaders link in the side navigation bar.

The Leaders Page opens.
3.
Click the add individuals link in the side navigation panel.
4.
The Add / Remove Individual Leader page opens.
5.
Use the search form to locate the individual to whom you want to assign a Community
Leader role.
6.
Check the box next to the new leaders name and click Add Selected.
The individual is now a Community Leader.
You can also add all the members of an organization as Community Leaders using the Leader
Organizations link:
40
1.
Click Leader Organizations in the side navigation panel.
2.
3.
Selected.
Each of the individuals in the organizations you selected is now a Community Leader.

You can assign the Guest role to any registered user.
1.
Log in to the Community Administration and click on the Community Users tab.
2.
Click the Guests link in the side navigation bar.

The Guests page opens.
3.
Click the add individuals link in the side navigation panel.

A page listing all community guests opens.
4.
Use the search form to locate the individual you want to add to the community.
5.
Check the box next to the new guests name and click Add Selected.
The individual is now a Community Guest.
You can also add all the members of an organization as members using the Guest Organizations link:
1.
Click Guest Organizations in the side navigation panel.
2.
3.
Selected.
Each of the individuals in the organizations you selected is now a community guest.

You can add new users to the Profile Repository using the Community Administration Pages.
1.
Log in to the Community Administration Pages.
2.

3.
Click create user in the side navigation panel.

The Create New Portal User page opens. Enter the profile information for the new user.
Note that fields marked with an asterisk are required properties. Click Done to create a
new user profile. You can then use the Community Users tab to assign roles to this
user.
41

If your user profiles are maintained in an LDAP profile repository, you need to configure ATG Portal to use
a different search form handler:
1.
Change the Java class of the /atg/portal/admin/SearchUsers component to

atg.portal.admin.ldap.LDAPSearchUsersFormHandler.
2.
Set the properties of this component to use the LDAP repository and its profile
properties:
# /atg/portal/admin/SearchUsers
$class=atg.portal.admin.ldap.LDAPSearchUsersFormHandler
emailPropertyName=email
firstNamePropertyName=firstName
lastNamePropertyName=lastName
loginPropertyName=login
ldapRepository=/atg/adapter/ldap/LDAPRepository
42
5 Portal Administration
The Portal Administrator is responsible for the content, appearance, and functionality of the portal, its
communities, and pages. The Portal Administrator is also responsible for updating and maintaining the
components of the portal site. As the Portal Administrator, you can control these settings using the Portal
Administration Pages in the Portal Application Framework.
Manifest Files
The various gear components and style elements that make up the portal are added to the portal
repository using manifest files. A manifest file is an XML file containing descriptions of one or more portal
components, as well as links to any necessary resource files for those components. The component
descriptions themselves can vary greatly, depending on the types of components they describe. Gear
descriptions contain XML describing the size, shape, content, repository and functionality of the gear
component. Layout descriptions contain XML describing the placement of the various gears in the portal.
Color palette descriptions contain XML describing the various colors present in the page background and
text of the portal.
You must import a manifest file into the portal repository before you can use the gears or style elements
that it describes. To update a component in a repository, import a manifest file using the same
component name as the existing setting. The new information overwrites the existing component
description.
You can add component descriptions as a group by including them within the same manifest. When you
upload a manifest to the Portal Administration Pages, only those components that match the type
expected by the current administration page are added to the repository. For example, if you import a
manifest from the Page Templates page, only page templates are added to the repository, even if the
manifest contains descriptions of other components. Manifest files are discussed in depth in the Creating
a Custom Portal chapter of the ATG Portal Development Guide.
You can see examples of gear manifest files in the module directory for each baseline gear included in
ATG Portal. For example, the manifest file for the Calendar Gear is:
<ATG2007.1dir>/Portal/calendar/calendar-manifest.xml
You can see examples of manifests for style elements in:

<ATG2007.1dir>/Portal/paf/starter-portal/paf-dar/portal/templates
43
5 - Portal Administration
We recommend that you save your manifest files after you have imported them into the PAF as they
simplify the process of upgrading gears or moving them to another portal.
Style Administration
The Community Leader specifies the style elements that determine the appearance of community pages,
including page templates, stylesheets, and gear title templates, for a community from the Community
Settings page in the Community Administration Pages. Each setting has a unique name that you use to
identify the style element. You can preview a page to see how your settings would look to a visitor to your
site. The Portal Administrator makes these style elements available by uploading their manifest files from
the Styles tab in the Portal Administration.
Page Templates
You can specify banners and other site wide graphics using page templates. Refer to Page Templates and
Branding for more information on using page templates.
Adding Page Templates to the PAF

After you have created a page template manifest file, as described in the Creating a Custom Portal chapter
of the ATG Portal Development Guide, you can add the manifest file to the PAF to make the new page
template available to Community Leaders.
1.
On the Portal Administration Home Page, click on the Styles tab.

The Page Templates page opens.
2.
Enter the location of the page template manifest file in the text field, or use the
Browse button to locate the file, then click Upload.
The page template is added to the list of available page templates on the page. You
can use any of the listed page templates to design your portal pages.
Layout Templates
Layout templates let you specify the layout of your gears on the portal page. For example, you might
choose to have all of your gears appear in two columns down the page, or you might choose to have your
gears appear in three columns. Layout becomes very important when you are trying to arrange gears of
different sizes and shapes for maximum usability and aesthetic value. The PAF installs with a set of four
default layouts for your use. You can create your own layouts or edit the existing ones to fit the needs of
your communities and portals. You can test the appearance of a layout template by applying it to a
community and using the view link to view its effect on that communitys pages. For a listing of the
default layout templates, refer to the Page Templates and Branding section of the Portal Configuration
chapter of this guide.
44
Adding Layout Templates to the PAF

After you have created a layout template manifest file, as described in the Creating a Custom Portal
chapter of the ATG Portal Development Guide, you can add the manifest file to the PAF to make the new
layout template available to Community Leaders.
1.
On the Portal Administration Home Page, click on the Styles tab.

Click on the Layout Templates link in the side navigation panel.
2.
Enter the location of the layout template manifest file in the text field, or use the
The layout template is added to the list of available layout templates on the page. You
can use any of the listed layouts to design your portal pages.

Gear Title templates let you specify the formatting that appears around gears. Gear Title options include:
Gear title bar
Gear table formatting
For information on creating your own gear title templates, refer to the Customizing Portal Appearance
section of the Creating a Custom Portal chapter in the ATG Portal Development Guide. In addition, the
standard gear title templates are described in the Page Templates and Branding section of the Portal
Configuration chapter of this guide.
Adding Gear Title Templates to the PAF

After you have created a gear title template manifest file, as described in the Creating a Custom Portal
chapter of the ATG Portal Development Guide, you can add the manifest file to the PAF to make the new
gear title template available to Community Leaders.
1.
In the Portal Administration Pages, click on the Styles tab.

Click on the Gear Title Templates link in the side navigation panel.
2.
Enter the location of the gear title template manifest file in the text field, or use the
The gear title template is added to the list of available templates on the page. You can
use any of the listed templates to design your portal pages.
Color Palettes
The Color Palettes Page lets you set the colors and background images that appear in your portal. Color
palette options include:
Background color
45
Text color
Active link color
Visited link color
Background image
For information on creating your own color palettes, refer to the Customizing Portal Appearance section of
the Creating a Custom Portal chapter in the ATG Portal Development Guide.
Adding Color Palettes to the PAF

After you have created a color palette manifest file, as described in the Creating a Custom Portal chapter of
the ATG Portal Development Guide, you can add the manifest file to the PAF to make the new color palette
available to Community Leaders.
1.
On the Portal Administration Home Page, click on the Color Palettes tab.
The Color Palettes page opens.
2.
Enter the location of the color palette manifest file in the text field, or use the Browse
button to locate the file, then click Upload.
The color palette is added to the list of available color palettes on the page. You can
use any of the listed color palettes to design your portal pages.
Stylesheets
The Stylesheets Page lets you apply cascading stylesheets to your portal pages. You can upload a
stylesheet manifest file that specifies a location for cascading stylesheets by providing a servlet context
and a URL. For information on creating your own stylesheet manifests, refer to the Customizing Portal
Appearance section of the Creating a Custom Portal chapter in the ATG Portal Development Guide.
Adding Stylesheets to the PAF

After you have created a cascading stylesheet and a stylesheet manifest file, as described in the Creating a
Custom Portal chapter of the ATG Portal Development Guide, you can add the manifest file to the PAF to
make the new stylesheet available to Community Leaders.
To add a stylesheet manifest file to your PAF:
1.
On the Portal Administration Home Page, click on the Stylesheets tab.

The Stylesheets page opens.
2.
Enter the location of the stylesheet manifest file in the text field, or use the Browse
button to locate the file, then click Upload.
The stylesheet is added to the list of available stylesheets on the page. You can use any
of the listed stylesheets to design your portal pages.
46
Gear Administration
The most technical task of the Portal Administrator is gear administration. The gears are the site
components that provide content and functionality. The content and functionality provided by the gear
can vary greatly depending on the gear itself. For more information on gears, and how to create, package,
and deploy them, refer to the ATG Portal Development Guide. You can customize the functionality of each
gear at the portal and community level, to provide your visitors with the functionality that best suits their
needs.
Portal Administrators should make sure that the assets of the loaded layout templates, styles, color
palettes, and gears are loaded into the application server. For example, if the gear is contained within a
J2EE application, then the Portal Administrators need to configure the application server so that it
registers the J2EE application before the manifest is loaded. For more information, see the ATG
Programming Guide.
Gear Folders
Gears are organized into gear folders. Gear folders let you make gears available to communities in logical
groups. To create a new gear folder:
1.
In the Portal Administration Pages, click the Gears tab.

The Available Gears page opens showing a list of gear folders and the gears they
contain.
2.
Click the New Gear Folder link in the side navigation panel.
3.
Enter a name for the new gear folder and click Done.
Gear Configuration Types

Depending on how it was designed, a gear may be configurable from the Portal Administration Pages, the
Community Administration Pages, or both. In addition, you can configure any gear by editing the gear
parameters and reloading the gear manifest file. If the instructions in the Baseline Gear Administration
chapter do not specify the type of configuration, the instructions are for a gear instance configuration.
Gear Installation Configuration

Some gears are configurable only by Portal Administrators from the Portal Administration Pages. When
you configure one of these gears, the changes take effect across all of your communities. This is called a
gear installation configuration; changes made here apply to all instances of the gear, regardless of
community. For example, when you set the source feed for an XML-Feed Gear, that source is used in all
instances of that gear in all communities.
Gear Instance Configuration

Some gears are configurable by Community Leaders from the Community Administration Pages. When
you configure one of these gears, the changes take effect only in the current community. This is called a
47
gear instance configuration; changes made here apply only to the current instance of the gear, and do not
appear in any other community. For example, when you configure a Discussion Gear for the Tennis
Community, those changes apply only to the Tennis Community. It is often helpful to give a gear instance
a name that helps you distinguish it from the installation name of the gear, for example, Tennis
Discussions for an instance of the Discussion Gear.
Gear Parameter Configuration

You can also configure a gear by altering its parameters in the gear manifest and importing the manifest
again. For more information on editing gear manifest files, refer to the ATG Portal Development Guide.
Adding Gears to the PAF

Once a gear has been created and its manifest file written, as described in the ATG Portal Development
Guide, you can use the manifest file to add the gear to your portal.
1.

The Available Gears page opens, showing a list of gear folders and the gears they
contain.
2.
Click the New Gear link in the side navigation panel.

The New Gear page opens.
3.
Select a gear folder. Alternatively, you can click the New Gear Folder link to create a
new folder.
4.
Enter the location of the gear manifest file in the Upload gear manifest file field, or
use the Browse button to locate the file.
5.
Click Upload.
The gear is added to list of available gears (in the folder you specified) on the Available
Gears page. To add the new gear to your portal pages, first make the gear folder
available to the community, using the gear folders link for the community on the
Available Communities page in the Portal Administration. Then, make an instance of
the gear available, using the Select New Gears option on the Community Gears tab in
the Community Administration. See Making Gears Available to a Community in the
Community Administration chapter.
Deleting a Gear from the PAF

The following procedure removes a gear from a portal.
1.

The Available Gears page opens.
2.
Locate the gear you want to remove and click its delete link.
48
3.
Confirm the deletion.

The gear is no longer available to the PAF. Deleting a gear deletes all instances of the
gear on all community pages.
Sharing Gears in the PAF

You can share an instance of a gear across multiple communities. For example, if you create an instance of
the Poll Gear asking a question that applies to many communities within a company, you can share that
instance of the Poll Gear across these communities rather than creating many duplicate instances of the
same gear. Although a shared gear instance can appear in many communities, it is only configurable from
the community in which it was created.
Shared gears are configured in the Community Administration Pages. Once a gear is shared, you cannot
unshare it. To share a gear:
1.
In the Community Administration Pages for the community where the gear was
created, click the Community Gears tab in the top navigation bar.
The Current Gear Instances page opens.
2.
In the list of available gears, click the Configure link for the gear you want to set as a
shared gear.
The Configure Gear basics page opens.
3.
Give the gear instance a name and a description.
4.
Under the Sharing heading, check the Allow this gear to be shared with other
communities check box.
5.
Finish configuring the gear and click Update.

This instance of the gear is now available to other communities from the Select Shared
Gears page of the Community Gears tab in the Community Administration. Its instance
name appears listed beneath the community in which it was created.
Configuring Alerts
ATG Portal includes alerts, which are notifications that originate from a gear event, are filtered and
targeted by ATG Scenario Personalization, and are presented to their target audience. Alerts can be
presented through different channels, including the Alert Gear, which can be included in portal pages, or
by e-mail sent to the portal member.
Most alerts in ATG Portal are gear alerts, which are generated by particular gears in the portal application.
The Adding Gear Alerts chapter of the ATG Portal Development Guide describes how to create a new gear
alert. The Alerts tab in the Portal Administration does not affect gear alerts.
In addition, ATG Portal includes administrative alerts and framework alerts. Administrative alerts are
messages that are generated from the Portal Administration Pages, while framework alerts are generated
49
by the PAF. You can use the Alerts tab in the Portal Administration to manage and create administrative
and framework alerts. You should not need to create new administrative or framework alerts unless you
have extended the Portal Administration or the PAF.
Creating New Administrative or Framework Alerts

Once you have created the alert, you can add it to the PAF using the Alerts tab in the Portal
Administration. To add a new alert:
1.
Enter the Portal Administration and click on the Alerts tab.
2.
Click either New Administrative Alert or New Framework Alert on the side navigation
bar.
3.
Enter the following information about the new alert and click Save:
Message Name
A name that identifies the message. This is not a

unique identifier.
Message Type
The message type is the full package name of the

message type, for example:
atg.portal.messaging.OrangeAlert
The message type is a unique identifier.

Resource Bundle
The full package name of the resource bundle used by

the message type, for example:
atg.portal.messaging.MyMessageResources
Select a radio button to indicate how this alert can be configured:

User alerts not allowed
Alerts allowed, but not user-configurable
Alerts allowed, configurable by user
Configuring an Alert
You can configure existing administrative or framework alerts to a limited extent. To configure an alert:
1.
2.
Click either New Administrative Alert or New Framework Alert on the side navigation
bar.
3.
Click the configure link for the message name you want to configure.
4.
Modify either the resource bundle pathname or the configurability setting for the alert
and click Save.
50
Deleting an Alert
You can delete an existing administrative or framework alert in the Portal Administration. To delete an
alert:
1.
2.
Click either Administrative Alerts or Framework Alerts on the side navigation bar.
3.
Click the delete link for the message name you want to configure.
4.
When the confirmation message appears, click Yes, Delete.
Customization Administration
Depending on the permissions set by the Community Leader, portal users can customize the appearance
and content of their portal pages. These permissions are configurable under the Customization heading
on the Community Settings page of the Community Administration.
If you allow community customization, changes made by the Community Leader do not automatically
appear on individual user pages. The following settings are available
Allow users to customize, add and delete

pages
This setting gives users the ability to customize their

pages, as well as the ability to create and remove
additional pages within the community. This setting
provides the broadest customization options.
Allow users to customize pages
This setting gives users the ability to customize their

pages. The ability to create new pages is limited to the
Community Leader.
Do not allow customization
This setting prevents users from customizing their pages.

The Community Leader must make any changes in
portal appearance or design.
51
52
6 Using Scenarios with ATG Portal
ATG Scenario Personalization provides advanced targeting features that companies can use to plan and
manage long term personalization and customer relationships. You can use scenarios to enhance your
users experience in your portal application and to gather information about how your users are using
your portal application.
Using Portal Attributes in a Scenario

You can easily set up scenarios that key off of portal attributes. The Portal Servlet Request object is
accessible in the Scenario editor, enabling scenarios based on any of its attributes.
Displaying a Gear in a Slot

ATG Scenarios can employ slots to display targeted variable content on a page. You can learn more about
slots in the Creating Scenarios chapter of the ATG Personalization Guide for Business Users and the Using
Slots chapter in the ATG Personalization Programming Guide. One of the ATG Portal baseline gears, the Slot
53
6 - Using Scenarios with ATG Portal
Gear, lets you display a slots content in a portal page. This section describes how, in an ATG Portal
application, you can use a slot to display different gears based on targeting rules.
Creating a Slot to Display a Gear

The first step in using a slot to display gears is creating the slot component.
1.
In the ACC, navigate to Scenarios > Slots.
2.
Click the New Slot button.
3.
Use the Create New Slot wizard, providing a name for the slot. Click Next.
4.
In the Specify Slot Content Type dialog, select Repository Item as the type of items
stored in the slot. Click Next.
5.
In the Specify Slot Content Source field, select the Portal Repository as the content
source and Gear as the content type. Click Next.
6.
Use the Specify Slot Options dialog to configure the slot. See the Using Slots chapter in
the ATG Personalization Programming Guide for more information about configuring
slot options.
Creating Scenarios to Display Gears in Slots

After you create your slot component, you can use ATG Scenarios to determine under what circumstances
a gear will be displayed in a slot. The Creating Scenarios chapter in the ATG Personalization Guide for
Business Users provides information about how to create a scenario.
For example, you could create a scenario that adds a poll to a portal users home page upon login, and
removes the poll after the user has voted in the poll. To do this, create a new scenario with the Logs in
event followed by the Add items to slot action segment, and the Poll vote event followed by the
Remove items from slot action segment:
The following JSP example shows how you might use a slot to render a gear. It assumes youve created a
slot named /com/acme/slots/MyGearSlot. The TargetingFirst servlet bean is used to display the
appropriate gear.
54
<%@ page import="atg.portal.servlet.*,atg.portal.framework.*" %>

<%@ taglib uri="/paf-taglib" prefix="paf" %>
<%@ taglib uri="/dsp" prefix="dsp" %>
<dsp:page>
<dsp:droplet name="/atg/targeting/TargetingFirst">
<dsp:param name="targeter" bean="/com/acme/slots/MyGearSlot"/>
<dsp:oparam name="output">
<dsp:getvalueof id="gearId" param="element.repositoryId"

idtype="java.lang.String">
<%
//Obtain request/response
PortalServletResponse portalServletResponse =
(PortalServletResponse)request.getAttribute(Attribute.PORTALSERVLETRESPONSE);
PortalServletRequest portalServletRequest =
(PortalServletRequest)request.getAttribute(Attribute.PORTALSERVLETREQUEST);
Portal portal = portalServletRequest.getPortal();
if(portal != null) {
Gear gear = portal.getGearById(gearId);
if(gear != null) {
//Create Gear Context
GearContextImpl gearContext =
new GearContextImpl((GearContext)portalServletRequest);
gearContext.setGear(gear);
gearContext.setGearMode(GearMode.CONTENT);
//Dispatch Gear
RequestDispatcher dispatcher =
portalServletRequest.getRequestDispatcher(gearContext);
if(dispatcher != null)
dispatcher.include(request,response);
}
}
%>
</dsp:getvalueof>
</dsp:oparam>
</dsp:droplet>
</dsp:page>
55
Portal Scenario Events and Actions

ATG Portal is configured with the following scenario events, which can serve as triggers for scenario
actions:
Calendar Event Created
Calendar Event Deleted
Calendar Event Updated
Calendar Event Viewed
Community Page Viewed
Document Created
Document Deleted
Document Updated
Document Viewed
Favorite Community Added
Favorite Community Removed
Full URL Changed
Gear Added to Community
Gear Added to Page
Gear Removed from Community
Gear Removed from Page
Membership Accepted
Membership Declined
Membership Request
Membership Unsubscribe
New Forum Created
Poll Vote
Registers
ATG Portal is configured with the following community- and gear-related scenario actions:
Send alert
Store Last downloaded Document
Store Last viewed Calendar Event
Create Community from Template
Assign Community Role
Preconfigured Portal Scenarios

ATG Portal includes the following already-configured scenarios:
Scenario Name
Description
Discussions
Send alerts to community members when a new discussion forum is

created.
Gear Added Alert
Send alerts to community leaders when a gear is added to the

community.
56
Gear Removed Alert
Send alerts to community users when a gear is removed from the

community.
Membership Request
Send alerts to community leaders when a user requests to be made a

member of the community.
Page Gear Added Alert
Send alerts to community members when a gear is added to a

community page.
Page Gear Removed Alert
Send alerts to community members when a gear is removed from a

community page.
Portal Calendars
Send alerts to community members when Calendar gear events are

created, updated, or deleted.
Portal Usage
Record community page views, document views, calendar event views,

and Poll gear votes in the appropriate dataset. See Using Scenario
Recorders in the ATG Personalization Programming Guide for more
information about data recording scenarios.
Profile Updates
When a user updates his profile, send him an email to confirm.
Registration
When a user registers, send an email to confirm.
Site Retention
If a user goes 15 days without logging in, send a reminder email.
Track Portal Behavior
Modify a users profile to track the number of times he publishes

documents, views documents, creates calendar events or views
calendar events.
57
58
7 Portal Access Control
ATG Portal is subject to the security settings specified within the ATG Relationship Management Platform.
PAF security settings are handled primarily from the administrator interface, although additional tags and
methods are available to further maintain portal security from within individual gears and the PAF itself.
For a more detailed discussion of security within the ATG platform, refer to the Managing Access Control
chapter in the ATG Programming Guide and the Working with the Dynamo User Directory chapter in the ATG
Personalization Programming Guide.
J2EE Security
ATG Portal makes limited use of J2EE security features in the portal. It calls
request.getUserPrincipal() and uses the returned information, but makes no use of contextual
security. Portal security is handled dynamically, and is relative to the current community.
Community Security Administration

Each page in a community can be restricted according to access level, allowing some areas of a
community to be accessible to some users but not others. Community-level access supersedes page-level
access, so looser page level access control levels are ignored if the pages community is more restrictive.
Beyond the page level, the security provided by the PAF security methods and tags can apply restrictions
at the gear level. For example, a particular page might be available to members of a community, but a
gear on that page might only be available to Community Leaders. Gears that a user does not have access
to are not rendered on the page.
ATG Portal contains options for community-specific and gear-specific security settings. You can specify
page security settings from the Community Access section of the Community Settings page of the Portal
Administration pages. You can specify gear security settings by editing the individual gear configuration.
If users attempt to access a community page for which they do not have access, one of two events takes
place:
If the user is not logged in, the user is directed to the login page. After authentication,
the user is redirected to the desired page.
If the user is logged in, and does not have permission to view the page, the user is
redirected to the access denied page.
59
7 - Portal Access Control
Gears will not function correctly if you try to access them directly in their servlet context (for example
http://hostname:port/gear/gearname/shared.jsp).
Setting Basic Access Levels for a Community

A Community Leader can set the access levels for the community using the Community Administration.
1.
Click the Community Settings tab in the Community Administration.
2.
Click Community Access in the side navigation bar.
3.
Select one security level from the Basic Access page and click Update.
The following access levels are available:
Allow anyone, including Unregistered Users
This is the most open level of security. Any

visitor can view the community pages without
registering or logging in.
Allow all Registered Users
This setting requires that users register before

viewing the community pages. There are no
restrictions on who can or cannot register.
Allow Community Guests, Members, and Leaders
This setting requires that the visitor have a

defined role within the community, but places
no restriction on what the community role
must be.
Allow Community Members and Leaders
This setting requires that the visitor have

Community Member or Community Leader
status.
Allow Community Leaders only
This setting is the most restrictive level of

community-based security. Only Community
Leaders and Portal Administrators have access
to the community.
Setting Advanced Access Controls for a Community

The basic access controls let you assign access to a community based on broad categories of roles in the
community, like Guest, Member, and Leader. The advanced access controls let you assign access with
finer granularity, allowing or denying access to particular organizations and even individuals among your
portals users. Note that advanced access is additive to the permissions granted by the basic access
controls. For example, if you allow access to all registered users with the basic access controls, and then
allow access to an organization using the advanced access controls, then all members of that organization
will have access, whether they are registered users or not.
To use the advanced access controls to set access for a particular individual:
60
1.
2.
Click Community Access in the side navigation bar to make the Advanced Access
option visible.
3.
Click Advanced Access in the side navigation bar.
The Configure Community Access page opens.

4.
Select Search Users in the pulldown menu at step 1 of the Configure Community
Access page and click find.
5.
Enter a name to search by in the search form at step 2 of the Configure Community
Access page and click Search.
6.
Select either the allow or deny button at step 3 of Configure Community Access page
and click Update.
To use the advanced access controls to set access for a member organization:
1.
2.
Click Community Access in the side navigation bar.
3.
Click Advanced Access in the side navigation bar.

The Configure Community Access page opens.
4.
Select Member Organizations in the pulldown menu at step 1 of the Configure

Community Access page and click find.
All of the member organizations are displayed in step 3 of Configure Community
Access page.
5.
Optionally, you can limit the number of organizations displayed by entering a name to
search by in the search form at step 2 of the Configure Community Access page and
clicking Filter.
6.
Select either the Allow or Deny button at step 3 of Configure Community Access page
and click Update.
Setting Community Access by Role

An ATG application allows you to assign roles to users. A role corresponds to specific functions that a
person can perform within an organization, such as vice president or administrator. You can use the
Community Administration interface to assign access based on roles, as well as based on organizations.
This lets you have gears or pages that are accessible to people in different organizations who have the
same roles in their organizations. For example, you might have a gear that can be accessed by users who
have a budget making role in their organization.
For more information about how roles work in ATG applications, see the Setting Up Visitor Profiles chapter
in the ATG Personalization Guide for Business Users or the Working with the Dynamo User Directory chapter in
the ATG Personalization Programming Guide.
Use the Community Administration interface to assign access based on roles:
61
1.
From the Community Settings page for a community, click Community Access >
Advanced Access.
2.
In the Configure Community Access page, select All Roles from the pulldown menu in
the pages step 1, then click the find button.
3.
In the step 3 section of the Configure Community Access page, use the radio buttons
to allow or deny access to the community for any applicable roles. Click the Update
button when you are done.
If you allow access for a particular role, then users with that role are allowed access unless another access
rule specifically denies access for them. If you deny access for a particular role, then users with that role
are denied access, even if another access rule would allow them access. If you do not specifically set allow
or deny access for a particular role, then that role is ignored for the purpose of determining access. In that
case, access is determined by a users organization or username.
Page and Gear Level Access Control

You can also use the Community Administration interface to set access controls for individual pages or
gears in a community. This works in basically the same way as setting access at the community level.
To set access controls for a page:
1.
From the Community Pages page for a community, click Current Pages.
2.
Click the access link for the page you want to configure access for.
62
3.
In the Configure Access page, make a selection from the pulldown menu in the pages
step 1, then click the find button.
4.
In the step 3 section of the Configure Access page, use the radio buttons to allow or
deny access to the page for any applicable users, organizations, or roles. Click the
Update button when you are done.
To set access controls for a gear:

1.
From the Community Gears page for a community, click Current Gear Instances.
2.
Click the Access link for the gear instance you want to configure access for.
3.
In the Configure Access page, make a selection from the pulldown menu in the pages
step 1, then click the find button.
4.
In the step 3 section of the Configure Access page, use the radio buttons to allow or
deny access to the community for any applicable users, organizations, or roles. Click
the Update button when you are done.
Predefined Secured Areas

Some areas in the PAF have built-in security. Any pages generated within the areas below by default
require a minimum level of security. In addition, you may wish to implement SSL security for the Portal
Administration interface. See the documentation for your application server for information about
deploying Web applications that use SSL.

The Portal Administration, including all pages in the /portal/admin area, manages portal-wide
configuration settings, including the importation and configuration of gears. By default, only users who
have the Portal Administrator role are allowed access to this area.

The Community Administration, including all pages in the /portal/settings area, manages
community-specific configuration settings. By default, only Portal Administrators and Community Leaders
are allowed access to this area.
63
64
8 Baseline Gear Administration
ATG Portal includes a number of baseline gears that provide basic gear functionality. You can configure
the gears to provide specific functionality for your communities.
Baseline Gears Overview

A standard installation of ATG Portal includes the following gears.
Alerts Gear
The Alerts Gear displays alert notifications generated by events occurring within the portal. For example,
the Alerts Gear might notify a visitor that a new document has been added to the Document Exchange
Gear.
Bookmarks Gear
The Bookmarks Gear makes available a list of user-customizable bookmarks.
Calendar Gear
The Calendar Gear displays a monthly list of important events for the community. Events added to the
Calendar Gear are visible to all visitors of a community.
The Community Members Gear displays a list of the members of the community. The list is updated as
community membership changes.
Discussion Gear
The Discussion Gear lets users participate in threaded online discussions with other users in the
community. Registered users can create discussion boards as well as read, reply to, and post messages.
Portal Administrators and Community Leaders can moderate these forums and edit the discussion boards
as necessary.
The Document Exchange Gear lets visitors interact with any document repository. Depending upon their
security permissions, visitors can upload, download, annotate, edit, and share documents with other
registered users in the portal community. Portal Administrators can use security permissions to maintain
the integrity of the document repository. ATG can also use the documents in the repository to create new
dynamic content within the PAF.
The Favorite Communities Gear displays a list of the members favorite communities. Community
65
8 - Baseline Gear Administration
Members can individually configure their own list of favorite communities, or they can display a list of all
the available communities.
HTML Content Gear
The HTML Content Gear retrieves the contents of the Web location, given its URL, the renders it as gear
content. The gear ensures that all the URIs in the Web content are properly rewritten so that the links
shown in the gear content point to the original Web server.
Login Gear
The Login Gear provides a secure interface for visitors to log in to the community. Once they are
authenticated, visitors assume their role within the community.
Outlook Gear
The Outlook Gear gives visitors access to their Microsoft Outlook account. Visitors can use this access to
send and receive e-mail from within the portal.
Poll Gear
The Poll Gear asks a single question, and presents a visitor with a set of responses. Visitors can respond to
the poll question, and view the results of the previous respondents.
Quicklinks Gear
The Quicklinks Gear provides a list of bookmarks for the community, created and customized by the
Community Leader.
The Repository View Gear can display information about repository items from any ATG repository.
The Web Services Client Gear enables portal visitors to access Web services made available on remote
computers. A Web service application can describe itself, publish this description to a directory, and be
invoked remotely over a network via Simple Object Access Protocol (SOAP). The Web Services Client Gear
acts as a client in Web service transactions. For example, the Web Services Client Gear might be used to
access stock market information and functionality made available as a Web Service by a financial content
provider.
XML-Feed Gear
The XML-Feed gear acts as a content feed, providing information from an external source that displays
within your portal. Information fed through the XML-Feed Gear is not stored in any way.
Configuring Baseline Gears

You can configure gears within a community, or directly from the Portal Administration Pages. To
configure a gear, you must have a Portal Administrator or Community Leader role and be able to access
the Gears tab of the Portal Administration or the Community Gears tab of the Community Administration.
This section includes the following topics:
Alerts Gear
66
Bookmarks Gear
Calendar Gear
Discussion Gear
HTML Content Gear
Login Gear
Outlook Gear
Poll Gear
Quicklinks Gear
XML-Feed Gear
Alerts Gear
Module name: alert
The Alerts Gear displays alert notifications generated by events occurring within the portal. For example,
the Alerts Gear might notify a visitor that a new document has been added to the Document Exchange
Gear.
Instance Configuration
To configure an instance of the Alerts Gear:
1.
Enter the Community Administration and click the configure link for the Alert Gear
instance.
2.
In the configuration basics page, enter a gear name and description. Select sharing
and Make visible to options and click Done.
3.
Click the additional configurations link. Set the display count parameter for this gear
instance to specify how many alerts display in the shared view of the gear.
4.
Click the access parameters link. Specify which alerts are to be displayed, based on
where they were targeted by the Send Alert Scenario action. You can enable or disable
the following alert categories:
aggregated community alerts
community alerts
role alerts
67
organization alerts
user alerts
5.
Click Update.
Configuring the Alerts Gear Repository Module in ACC

You can use the ACC to control data removal for the Alerts Gear repository. Over time, as the actions of
users on your portal generate more and more alerts, the amount of data storage required by alerts
increases. If you do not configure data removal settings, you can potentially exceed your data storage
capacity. For more information on using the ACC, refer to the ATG Personalization Guide for Business Users.
To configure the Alerts Gear repository for data removal:
1.
2.
3.
Open the /atg/portal/alert/AlertRepositoryAdmin component.
4.
In the AlertRepositoryAdmin component, set the properties for data removal.

The properties and their options are listed in the table below.
5.
Once you have set the data removal properties, click Start.
The component starts, using the settings you have specified.
AlertRepositoryAdmin Properties
Description
expirationDate
Specifies the date after which data is outdated and ready to

be deleted.
expirationDays
Specifies the number of days after which data is outdated

and ready to be deleted. Use this property if you are going
to run the removal process as a recurring event.
schedule
Specifies the interval at which the removal process runs. The

default setting for this property is one hour.
Bookmarks Gear
Module name: bookmarks
The Bookmarks Gear makes available a list of user-customizable bookmarks. Users can add bookmarks by
clicking the Edit button in the gear and entering URLs.
The Bookmarks Gear has only the usual basics to configure. To configure an instance of the Bookmarks
Gear:
68
1.
Enter the Community Administration and click the configure link for the gear
instance.
2.
Calendar Gear
Module name: calendar
The Calendar Gear displays a monthly list of important events for the community. An event added to the
Calendar Gear can be labeled private, in which case only the user who entered the event can view it, or
public/community, in which case the event is visible to all visitors of a community.
To configure an instance of the Calendar Gear:
1.
instance.
2.
3.
Click the additional configurations link.
4.
On the calendar parameters page, select basic or detailed for the calendar default
event type. Detailed events will prompt for name and address information for the
event. Select a calendar year end. The calendar will allow the creation of events only
until the end of the year you specify.
5.
Click the permissions link. This page governs who can create private and public
events. By default, users with the calWriter role can create only private events; users
with the calAdmin role can create public or private events. Set the Allow open access
to create public and private events? field to true to permit anyone who can use the
Calendar gear instance to create a public or private event. Set the Allow open access
to create private events only? field to true to permit anyone who can use the
Calendar gear instance to create a private event.
See the Assigning and Revoking Roles topic for more information about calendar roles.
6.
Click the alerts page. This page governs whether users receive an alert when an
calendar event is created, modified, or deleted.
Assigning and Revoking Roles

You can further configure an instance of the Calendar Gear by assigning or revoking roles in the gear
instance. The calendar role, together with the permissions setting, determines who can view or create
private or public events. To assign a role:
1.
Enter the Community Administration and go to the Current Gear Instances page.
2.
Click the Assign/Revoke Roles link for the Calendar Gear.
3.
Use the dropdown list and the search feature in step 2 of the Assign/Revoke gear
role page to locate the individual user or organization whose role you want to change.
69
4.
Click the Assign/Revoke Roles link for that individual or organization. Check or
uncheck the box for the roles you want to assign or revoke.

Module name: contacts
The Community Members Gear displays a list of the members of the community. The list contains an email link and a link to the portal profile for each community member. The list is updated as community
membership changes.
To configure an instance of the Community Members Gear:
1.
instance.
2.
3.
Click the additional configurations link. The additional configurations page has
two subpages, display parameters and sort parameters.
On the display parameters subpage, you can configure how many members are
displayed on a shared view of the gear (where the gear is one of many on the page)
and on a full view of the gear (where the gear occupies the whole page).
On the sort parameters subpage, you can configure the default sorting of members
in the list.
Discussion Gear
Module name: discussion
The Discussion Gear lets users participate in threaded online discussions with other users in the
community. Registered users can create discussion boards as well as read, reply to, and post messages.
Portal Administrators and Community Leaders can moderate these forums and edit the discussion boards
as necessary.
To configure an instance of the Discussion Gear:
1.
instance.
2.
3.
five subpages, select/administer forums, Display Attributes, access controls,
alerts, and resource bundle.
70
select/administer forums: Create and delete discussion boards, and to make

discussions from other communities available in this instance of the Discussion Gear.
To create a new discussion board, click the create new forum link. Enter a name for
the new discussion board. Select private to make the discussion board available only
to members of this community. Select public to allow other communities to view the
discussion board in shared instances of the Discussion Gear.
Display Attributes: Set the number of forums and posts and the length of texts that
appear in the shared and full views of the gear.
access controls: Specify which classes of users can post to the discussion boards in
this gear instance.
alerts: You can configure whether alerts are generated by the gear instance.
resource bundle: You can change the resource bundle for this gear. You should not
need to change the resource bundle unless this gear instance is intended for a
language other than English.
Discussion Gear messageThread Cache

The Discussion Gear maintains forums in a SQL repository. If the messageThread item cache in the
repository is too small, the Discussion Gears performance will not scale as the size of the forum or threads
increase. The item cache must be large enough to hold a list of all threads in the forum, and it must be
large enough to hold a list of all replies to a thread in the forum. The default size of the item cache is 1000.
The appropriate size for your site depends heavily on the amount of activity in a forum.
Set the item cache in the definition of the messageThread item descriptor in the Discussion Gear
repository definition file. Set the item-cache-size attribute by including a file like this in your
CONFIGPATH at /atg/portal/gear/discussion/discussionRepository.xml :
<gsa-template>
<item-descriptor name="messageThread" item-cache-size="50000">
</item-descriptor>
</gsa-template>

Module name: docexch
The Document Exchange Gear lets visitors interact with any document repository. Depending upon their
security permissions, visitors can upload, download, annotate, edit, and share documents with other
registered users in the portal community. Portal Administrators can use security permissions to maintain
the integrity of the document repository. ATG Portal can also use the documents in the repository to
create new dynamic content within the PAF. Portal users can perform keyword searches on the repository
using the Repository Search Gear.
Configuring a Document Repository

To specify the location of the document repository, you must be a Portal Administrator.
71
A repository used by the Document Exchange Gear needs to have one item descriptor that corresponds
to a document. The document item descriptor needs to define properties that store the following
information:
file name
file data
MIME type
file size
description
title
author
create date
status
gear ID
discussion ID
If you configure the gear to point to your own repository, you should set the maxlength attribute of the
document title and description properties in the repository so that users creating documents are
informed if they attempt to create documents with titles or descriptions that overflow the size of the
database column. These properties are already set in the default document repository. You must do this
only if you configure the gear to use another repository. To set the maxlength attribute, edit the
repository definition XML file and add the maxlength attribute as in this example:
<property name="title" column-name="title" data-type="string">

<attribute name="maxLength" value="254"/>
</property>
<property name="description" column-name="description" data-type="string">
<attribute name="maxLength" value="400"/>
</property>
When you configure the document exchange gear to use a repository other than the default repository
and RQL query, you must tune your database and repository to achieve the best possible performance.
For more information on performance tuning, refer to the ATG Installation and Configuration Guide.
Configuring the Expression Editor

Note that the expression editor in the ATG Control Center is configured to point to the default document
repository, /atg/portal/gear/docexch/SplitDocumentRepository in the
/atg/portal/gear/docexch/docexch-expression-grammar.xml file found in
<ATG2007.1dir>/Portal/docexch/lib/docexch.jar:
...
<token>
<expression-class>atg.ui.expreditor.targeting.RepositoryItemSetExpression
</expression-class>
<assistant-class>atg.ui.expreditor.targeting.RepositoryItemSetAssistant
</assistant-class>
<attribute
72
name="repositoryName"
value="/atg/portal/gear/docexch/SplitDocumentRepository"/>
<attribute name="repositoryItemType" value="document"/>
<required/>
<description>Choose document...</description>
</token>
...
If you use a different document repository, you need to modify this token tag in the docexchexpression-grammar.xml expression editor grammar file to point to the appropriate document
repository and document repository item type. See the Configuring the ATG Expression Editor chapter in
the ATG Personalization Programming Guide for more information about how to modify expression editor
grammar files.
Installation Configuration
To configure the Document Exchange Gear in the Portal Administration:
1.
Click the configure link for the gear in the Available Gears page. A page opens titled
Configure Gear Definition: Document Exchange.
2.
Enter the Nucleus address of the repository that will store the gears documents and
click Continue.
3.
In the Repository Item Type field, select the item type that corresponds to documents
in the repository and click Continue.
4.
Map the properties of the selected item type to the properties needed by the gear.
Select the property from the document item descriptor that is used for each of the
following:
file name
file data
mime type
file size
description
title
author
create date
status
gear id
discussion id
Click Finish.
5.
Click the Repository Limitations link.
6.
Select whether the gear exposes the repository as read-only or read/write. If the gear
uses a read-only repository, portal users will not be able to add documents. You can
configure an instance of the gear to adjust the permissions of a read/write gear to limit
who can add or modify documents.
7.
Set a maximum file size for documents in the repository and click Finish.
73
To create an instance of the Document Exchange Gear in a community:

1.
Enter the Community Administration and click the Select New Gears link in the side
navigation panel.
2.
Enter a gear name and description.
3.
Select sharing and Make visible to options.
4.
Click Done.
To configure an instance of the Document Exchange Gear:

1.
instance.
2.
Click the additional configurations link.
3.
Apply the appropriate settings in the appearance page. Click Save.
4.
Click the permission link. You can select which groups of portal users are permitted
to:
Read and discuss documents
Add new documents
Change the status field for documents
Click Save.
5.
Click the functionality link. You can select the features rendered in the Document
Exchange Gear instance.
Select Enable Discussion to include the discussion board feature in the gear instance.
Select Enable Search to include a search field in the gear instance. Note that this
search field enables searches only within the documents of this gear instance. For a
broader search function, use the Repository Search Gear.
Select Attachment Required to require that each new item have a file attachment.
Click Save.
6.
Click the alerts link. You can configure whether alerts are sent to users when
documents are added, modified, or deleted in the gear instance.
Virus Protection for the Document Exchange Gear

The Document Exchange Gear allows users to upload files into the portal. There is a risk that some of
these files might contain viruses. The gear does not check for viruses or other unacceptable content.
However, it includes a stub method that a gear developer could override to implement document
checking.
The stub method is found in the atg.portal.gear.docexch.DocumentFormHandler class. You can
find the source code for this class at:
74
<ATG2007.1dir>/Portal/docexch/src/classes.jar/atg/portal/gear/docexch/
DocumentFormHandler.java
The stub method is:

public void validateFileContents(UploadedFile pUploadedFile) { // no op }
You can extend the DocumentFormHandler and override this method to reject an uploaded document
based on any criteria. For example, you might implement virus scanning, looking for offensive words, or
whatever checks your application requires. In addition to overriding the validateFileContents
method, you should also add an exception to the file upload form, as in this example:
addFormException( new DropletException(getAbsoluteName() + ".value."
+ "uploadedFile", "FILE_CONTENT_REJECTED")); */
Announcements Gear
Module name: docexch
The Announcements Gear is just a different version of the Document Exchange Gear. You can install the
Announcements Gear, using the Gears > New Gear page in the Portal Administration interface. Browse to
the gears manifest at <ATG2007.1dir>/Portal/docexch/announcements-manifest.xml and
upload the manifest.
The Announcements Gear is configured just like the Document Exchange Gear. See the Installation
Configuration and Instance Configuration sections of Document Exchange Gear.

Module name: communities
The Favorite Communities Gear displays a list of the members favorite communities. Community
Members can individually configure their own list of favorite communities, or they can display a list of all
the available communities. This provides quick navigation to any community from any page that has an
instance of the Favorite Communities Gear.
To configure an instance of the Favorite Communities Gear:
1.
instance.
2.
HTML Content Gear

Module name: screenscraper
75
The HTML Content Gear retrieves the contents of a Web location, given its URL, then renders the location
as gear content. The gear also ensures that all the URIs in the Web content are properly rewritten so that
the links shown in the gear content point to the original Web server.
To configure an instance of the HTML Content Gear:
1.
instance.
2.
3.
two subpages, url settings and alerts.
url settings: Enter the URL of the content you want displayed in the gear. You can also
include a URL and link text for users to display the content in a full page. You can
change the resource bundle if you are localizing this gear instance for a language
other than English. If you specify something other than the default, you must make
sure the new resource bundle location is specified in the CLASSPATH.
alerts: Specify whether users can receive alerts from this gear.
Configuring the HTMLFilterParser

The behavior of the HTML Content Gear is also affected by a Nucleus component named
/atg/portal/gear/screenscraper/HtmlFilterParser. This component has three properties that
you may want to configure:
tagsToRemove
A list of tags that you want to remove from the source Web page so that those tags from the source page
do not interfere with the rendering of the content into the gears content pages. For example, suppose
something like this appears in the source content:
<title>This is the Title</title>
and you have specified title as one of the items in the property tagsToRemove. Then, the above string
will be rendered in the gears content pages as This is the title, without the <title> tags.
tagsToRemoveWithBody
A list of tags that you want to remove, together with the tags contents, from the source Web page. This
does the same thing as the tagsToRemove property, except that it will remove not just the specified tags
but also anything between the start and end tags.
For example, if this appears in the source content:
<title>This is the Title</title>
and you specified title as one of the items in the property tagsToRemoveWithBody, then whole string
will be removed, including both the <title> tags and the This is the title string.
76
replaceBodyTagWithTableTag
The parser replaces the <body> tag with a <table> tag so that the community page where the gear is
installed is not messed up due to the bgcolor or background attributes of the source pages <body>tag.
This functionality can be turned off by setting the replaceBodyTagWithTableTag property to false.
Extending the HtmlFilterParser

The Portal module includes the source code for the
atg.portal.gear.screenscraper.HtmlFilterParser class in the
<ATG2007.1dir>/Portal/screenscraper/src/classes.jar/atg/portal/gear/screenscraper
directory. You can modify the class to do your own custom parsing. You can even replace this parser with
a parser of your own by subclassing the atg.portal.gear.screenscraper.HtmlFilterParser and
overriding the parse(Reader pIn, Writer pWriter) and parse(InputStream pIn,
OutputStream pOut) methods. This might enable, for example, the capability of replacing other tags in
the source page.
Login Gear
Module name: user_registration
The Login Gear provides a secure interface for visitors to log in to the community. Visitors must login
using this gear before they can assume their roles within the community.
To configure an instance of the Login Gear:
1.
instance.
2.
3.
Click the additional configurations link. Here, you can configure some optional
behavior for the login page:
Show registration message and link?: If true, the login page offers users a link that
allows them to register for the portal. Set this to false if you do not want to allow new
members to register and join.
Flag to show username on shared view when logged in: If true, the portal displays
the users username.
page to forward to after login: By default, the login page returns the user to the
current page after login. You can specify the URL of a different page here.
Click Finish.
The gear is updated to use the new settings and information.
Outlook Gear
Module name: exchange
77
The Outlook Gear gives visitors access to their Microsoft Outlook account. Visitors can use this access to
send and receive e-mail from within the portal.
You can configure the Web Access Host and Proxy Servlet Host settings in an installation configuration of
the Outlook Gear. To configure the Web Host and Proxy Host settings of your MS Outlook server you must
be a Portal Administrator.
To configure the Outlook Gear in the Portal Administration:
1.
Click the configure link for the gear in the Available Gears page. A page opens titled
Configure Outlook Server URLs.
2.
Enter the Web Access Host URL. The form of your URL may vary depending on the
settings chosen by your Web Access Administrator.
3.
Enter the SSL Proxy Servlet Host URL. This is used to transmit user ID and password
information using a separate SSL encoded instance of ATG. If you are using an SSL
secured session of ATG, provide the URL for that other session here. To use the SSL
secured session, your MS Exchange Web Access settings must allow basic
authentication. If you are not using SSL encoding, enter the same URL that you used
for the Web Access Host.
4.
Click Update.
You can configure the descriptive information and access settings in an instance configuration of the
Outlook Gear.
1.
Enter the Community Administration. Click the Community Gears tab to view the
Configure Gear Instances page.
2.
Click the Configure link next to the Outlook Gear name.

The Configure Gear: Outlook Page opens.
3.
Enter a gear name and description. Select sharing and Make visible to options.
4.
Click Done.
The gear is updated to use the new information.
Logging In to the Outlook Gear

If a visitor enters an invalid username and password into the login fields for the Outlook Gear, the
community pages still render the Outlook Gear with Inbox, Calendar, Contacts, and Task links. If the visitor
clicks on these links, the visitor is asked to login again. Any attempts, however, to login from this location
fail, even if the login information is valid. The visitor must return to the community page, click the Edit
button in the gear title, and re-enter the login information in the Gear Configuration Pages.
78
Poll Gear
Module name: poll
The Poll Gear asks a single question, and presents a visitor with a set of responses. Visitors can respond to
the poll question, and view the results of the previous respondents.
You can configure the following settings in an instance configuration of the Poll Gear:
Gear name and description
General administration settings
Access settings
Poll parameters
You can configure the descriptive information and access settings in an instance configuration of the
Outlook Gear.
1.
2.
Click the Configure link next to the Poll Gear name.

The Configure Gear: Poll Page opens.
3.
4.
Click Done.
5.
Click additional configurations. This page has five parts: set current poll, create new
poll, available polls, resource bundle, and alerts.
set current poll: Select one of the existing polls to be displayed in the Poll Gear
instance.
create new poll: Enter a poll title and a poll question. Also enter the possible answers
to the poll; all polls must be multiple choice.
available polls: This page displays all polls available for this gear. You may view poll
results, edit an existing poll, clear votes (returning the vote totals to zero), or delete a
poll.
resource bundle: If you have localized the Poll Gear, you can change the resource
bundle used for it.
alerts: You can configure whether alerts are generated by the gear instance.
Quicklinks Gear
Module name: quicklinks
The Quicklinks Gear provides a list of bookmarks for the community, created and customized by the
Community Leader.
To configure the Quicklinks Gear:
79
1.
2.
Click the Configure link next to the Quicklinks Gear name.

The Configure Gear: Outlook Page opens.
3.
4.
Click Done.
5.
Click the additional configurations link. Enter the URL and link text for each link
appearing in the gear and click Save.

Module name: search
Several of the baseline gears store content in a SQL Repository. These gears are the Document Exchange
Gear, the Discussion Gear, and the Calendar Gear. The Repository Search Gear lets users search by
keywords for content in all instances of these repository-based gears in the portal at once. The user can
also restrict a search to the current community or page.
The installation configuration for the Repository Search Gear consists of two parameters that are designed
to make sure that a search doesnt return an excessively large result set or absorb an excessive amount of
system resources:
Parameter
Default
Maximum Results Per Repository
10
Maximum Number of Gears to Search Per Repository
25
The additional configurations page for an instance of the Repository Search Gear allows you to set
parameters to make sure a search doesnt return an excessively large result set, per page or in total:
Parameter
Default
Maximum Results Per Page
10
Maximum Total Search Results
100
80

Module name: repview
The Repository View Gear displays a read-only view of items from any repository. Display can be
automatic or highly customized. The items displayed are selected by configurable targeters.
Repository and Targeter Configuration

The Repository View Gear requires an existing repository. The gear displays items of one type from the
repository you specify. You need to create targeters keyed to that repository and repository item type so
that the gear can determine which repository items to display. See Setting Up Targeting Services in the ATG
Personalization Programming Guide for information about creating targeters.
To configure the Repository View Gear in the Portal Administration:
1.
Click the configure link for the gear in the Available Gears page. The configuration
page opens, presenting the following seven steps in configuration: repository,
delegate, resource bundle, featured item, short list, full list, display item.
2.
Click the repository link. Enter the Nucleus address of the repository whose items the
gear will display and click Continue.
Select the item descriptor of the type of repository items this gear will display and click
Update.
3.
Click the delegate link. Check the box if you want to enable community leaders to
configure each instance of this gear independently. Please note that the configuration
is somewhat technically oriented and gives a higher than normal level of access to the
data and repositories. It is not recommended to enable delegated configuration for
non-technical or untrusted community leaders.
4.
Click the resource bundle link. If you want to change the gears user-visible text,
because you want to change its labeling or because you have localized the Repository
View Gear, you can specify the resource bundle to use.
5.
An instance of the Repository View Gear can be configured to display a single featured
item, a short list of selected items, or a full list of all items in the repository. The next
three steps, featured item, short list, and full list, let you configure which targeters are
used to select the items and which properties of the items are displayed in each of
these views.
6.
Click the featured item link.

Select a targeter that chooses which item to display as the featured item.
There are two ways to configure how the gear displays the properties of a featured
item. Either enter the relative pathname of a custom JSP fragment that displays the
item properties you want, or enter the names of the properties that should appear in
the featured item display and the gear will create the display automatically.
Two sample JSP fragments are included in
<ATG2007.1dir>/Portal/repview/src/repview.war/html/content/custom. If
you create a custom JSP fragment, specify its pathname is relative to the
81
<ATG2007.1dir>/Portal/repview/repview.war/html/content/ directory. For
example, if you put your custom JSP fragment in the same directory as the two sample
fragments, enter custom/mycustom.jsp.
Click Update.
7.
Click the short list link.

Select a targeter that chooses which items to display in the short list of items in the
shared view of the gear.
Enter the names of the properties that should appear in the short list of items.
Click Update.
8.
Click the full list link.

Select a targeter that chooses which items to display in the full list of items in the full
page view of the gear.
Enter the names of the properties that should appear in the full list of items in the full
page view of the gear.
Click Update.
9.
Click the display item link. When a user clicks on an individual repository item to view
it, the gear displays the properties you select on this subpage. As with the featured
item, you can choose either to create a custom JSP page to display the selected item,
or select the properties you want to display and the gear will create the display
automatically.
Click Update.
To configure an instance of the Repository View Gear:
1.
instance.
2.
3.
Click the additional configurations link. If, in the installation configuration, the Portal
Administrator did not enable delegation of configuration, then this page has two
parts: functionality and appearance. If this gear uses delegated configuration, then
the additional configurations page also includes featured item, short list, full list,
and display item.
4.
Click the functionality link. Specify whether you want the shared view of the gear to
display one or more of a featured item, a short list, a link to the full list. Click Update.
5.
Click the appearance link. Here you can configure how the gear displays times and
dates, whether the gear uses column headers for property names, and whether items
are displayed with a link to the full item.
6.
The featured item, short list, full list, and display item subpages of the Instance
Configuration are displayed only if the Portal Administrator has enabled delegated
82
configuration in the installation configuration of the gear. These subpages are

identical to the same pages described in the Installation Configuration topic above.
User Configuration
An instance of the Repository View Gear provides an Edit button that portal users can click to set the
maximum number of items displayed in the full and shared views of the gear.

Module name: slotgear
The Targeted Content Gear lets you display targeted content to portal users, using an ATG Relationship
Management Slot component. Slots are often used to show images, but you can use them to display any
repository items that you choose. See Using Slots section of the Creating Scenarios chapter in the ATG
Personalization Guide for Business Users for an introduction to slots, and Using Slots in the ATG
Personalization Programming Guide for a more detailed view of creating slots.
There is no installation configuration for the Targeted Content Gear itself. Note, however, that you may
need to create slot components for the Targeted Content Gear to use. Use the ACC to create a slot
component, as described in Using Slots in the ATG Personalization Programming Guide. You also need to
create a SQL content repository to contain the content rendered in the Targeted Content Gear.
Targeted Content Gear Repository Configuration

When you configure a slot component, you specify a repository name and an item descriptor name. This
defines what type of item the slot will display. How the item is rendered depends on the items media
type (i.e. text, image, or a product). The Targeted Content Gear includes a Nucleus component that
defines a mapping of repository item descriptors to the JSP files that are used to render that particular
item type. The Nucleus address of this component is
/atg/portal/gear/slotgear/SlotConfiguration. The slotPages property of the
SlotConfiguration component contains this map. The default configuration (properties file) that is
installed with the gear is shown below:
%cat SlotConfiguration.properties
# Version: $Change: 234577 $$DateTime: 2002/04/03 09:25:14 $
# Global configuration properties for the portal
$class=atg.portal.gear.slotgear.SlotConfiguration
$scope=global
# A mapping of itemDescriptorNames used for slots to jsp pages used to render them
slotPages=\
media=mediaInternalBinary.jsp,\
media-internal-binary=mediaInternalBinary.jsp,\
media-internal-text=mediaInternalText.jsp,\
media-external=externalMedia.jsp,\
product=productSlot.jsp
When you design the repository that holds content for the Targeted Content Gear, you must either:
83
Use one or more item descriptors named media, media-internal-binary, mediainternal-text, media-external, or product.
Configure the slotPages property to include a mapping of the item descriptor names
you use in your slot content repository to the JSP pages used to render them in the
Targeted Content Gear.
In addition, you may want to customize one of the JSP pages used to render content in the Targeted
Content Gear. These JSP files are located in <ATG2007.1dir>Portal/slotgear/slotgear-war.
The Configure Basics page for an instance of the Targeted Content Gear allows you to configure the usual
gear basics:
Gear Name
Gear Description
Sharing
Make visible to
The additional configuration page for the Targeted Content Gear has three steps:
1.
Click the define slot link.

Select the name of the Nucleus component for the slot. The dropdown list includes all
slot components that are created in the ACC or otherwise created in the CONFIGPATH
at /atg/registry/Slot. The slot component defines the repository and item
descriptor from which it derives repository items to display.
Enter the pathname of an image to display if the slot is empty. Click Save.
2.
Click the targeting params link. A slot can use a targeting servlet bean that applies a
set of targeting rules to a repository, retrieves a result set of repository items, and
renders one or more of the repository items in the page region allocated to the slot.
On this page, you can set the input parameters for the targeting servlet bean that
renders the slot. For information about these parameters, see the description of the
TargetingFirst, TargetingForEach, TargetingRange, or TargetingRandom
servlet beans in the ATG Page Developers Guide.
After you configure the input parameters for the targeting servlet bean, click Save.
3.
Click the property names link. A slot renders an image or text from a repository item.
The URL property defines the property in the repository item that points to the
location of an image on the file system. The data property represents text to be
displayed in the slot.
The external media context root property is used to specify the root for external media
item types. In the baseline Slot Gear, the external media you are using need to exist
inside the Slot Gear Web application.
After you configure the property names, click Save.

Module name: soapclient
84
The Web Services Client Gear enables portal visitors to access Web services made available on remote
computers. A Web service application can describe itself, publish this description to a directory, and be
invoked remotely over a network via Simple Object Access Protocol (SOAP). The Web Services Client Gear
acts as a client in Web service transactions.
For example, there might be a Web service that exposes the top five news headlines for a given topic. A
client of this service would provide a topic (technology, financial, entertainment etc.) that it would like the
top five headlines for. The server exposing this service would then return the matching headlines. In this
example, the Web Services client gear provides the ability for a portal user to configure the gear to
connect to the service as well as provide the topics that should be obtained from the server. These
headlines will then be displayed on a given portal page where the gear is deployed.
There are several restrictions on the type of Web services and Web Services Description Language (WSDL)
documents that the gear can handle. The gear can only support the invocation of services where the
types of the parameters to the service as well as the return value are simple types. The following types are
supported:
string
integer
byte
short
boolean
long
float
double
These types are expected to be declared in the WSDL document as the associated schema data type.
Additionally, a WSDL document that is to be uploaded can contain only the definition of a single method
for a service.
There are two types of configuration information that must be supplied in order to successfully invoke a
Web service:
Protocol-level connection information
Runtime values to pass as parameters to a service
Using the above example, protocol-level connection information would be things like a URL to connect to
and a method name to invoke. The runtime parameter would be the news topic you are requesting.
Configuring protocol-level connection information is a technical task and thus is the responsibility of the
Portal Administrator. Each user will then want to customize the parameters passed to a given service in
order to personalize the service. Thus, the Web Services client gear can be configured at both the Portal
Administrator level as well as user level.
Before the gear can be successfully used, it must be configured with its connection-level information. The
installation configuration is the only place that this can be done. The information that must be supplied is
85
information that is specific to SOAP (the RPC layer in the Web Services protocol) as well as the transport
information that the SOAP message will be sent over. The Web Services gear supports invoking Web
Services over the HTTP-based protocol.
The following SOAP connection information is required:
Method name
The method name that is to be invoked on the

remote service
Parameters
The name and type of the parameters that are

to be supplied to a particular method
URI of target object
The URI for the remote service
The following HTTP connection information is required:
Target URL
The URL where the remote service is located
SOAP Action
Value that can be placed into HTTP header to indicate

intent
Web services provide a way to describe this information in a single document. This is done via the Web
Services Description Language (WSDL). The WSDL specification provides a standard way to model the
definition of a particular service. The modeling is done via an XML document. Typically, any Web service
that is available will provide a WSDL document that describes the service. The Web Services gear only
needs this WSDL document in order to know its connection information. It will take this WSDL document
and parse out all of the SOAP- and HTTP-specific information. To configure the gear with this WSDL
document follow these steps:
1.
On the Gears tab of the Portal Administration Pages click the configure link next to
the Web Services Client Gear name.
2.
Browse to the location of the WSDL document on your machine and then click
Upload.
This will upload the WSDL document from your local machine to the server. The server
will then attempt to extract all of the necessary connection information from this
document. If any errors occur then the user will remain on the same page and the
errors that resulted will be displayed.
Each user must now customize the values of the parameters to pass to the Web service
by using the User Configuration pages. For example, the user must specify what type
of news headlines to receive.
User Configuration
Users set the value of the parameters to pass to a given service. They are personalizing the service to
obtain the information that interests them.
86
In the News Service example, if the Portal Administrator has uploaded a WSDL document describing the
service to connect to (News), then the gear has all the information necessary to connect to the service. In
addition, the News Service has defined a single parameter for the service, newsTopic. Before the gear can
successfully invoke the News Web service, it must know what newsTopic it should request the headlines
for. It is up to the user to set the runtime values to pass to a particular service. While these values could be
supplied in a variety of ways (form input, user configuration, JSP value passing, etc.) the Web Services gear
only supports configuration of runtime parameters through the user configuration pages.
The user configuration page will expose form input fields for each parameter that can be passed to a
particular service. The name and number of these parameters will vary depending on the service you are
invoking. The service pages are built up dynamically depending on the WSDL document that the gear
installation configuration was supplied with. The user configuration pages will determine all the
parameters from the WSDL document that was previously uploaded and then generate the form input on
the fly. So, for the News Service the user configuration page would expose a single input box. The name
for this input box would be News Topic and then the user would be expected to type in the News topic
that they wanted to receive headlines for: financial, technology, etc.
To configure the value of the parameters, follow these steps. (This assumes that the Gear has been
installed onto a particular community page).
1.
In the Web Services gear, click the edit button.

The user configuration page for the gear opens.
2.
Enter or set the appropriate values.
3.
Click the done button.
XML-Feed Gear
Module name: xmlfeed
The XML-Feed Gear uses XSL-Transformation to display content from a local or remote XML file according
to the transformation rules provided by a local or remote XSL file. This gear can serve as a simple XSLT
gear or can display content from various external content providers. For example, an instance of the XMLFeed Gear can be configured to act as a real-time stocks, weather, or news gear.
The XML-Feed Gear uses the standard Jakarta Xtags tag library. You should enable gear caching to
optimize gear performance for gears that utilize XML parsing. Gear caching is enabled by default for the
sample XML Feed Gear. Gear caches use time-based expiration so any changes made to the underlying
XML file are reflected in the users portal experience once the cache timeout expires.
You can have more than one XML-Feed Gear on a page, with each gear receiving a different feed.
Configuring the XML-Feed Gear for Simple XSLT

Point the XML and XSL sources to the appropriate location. The Stocks, Weather and Business-News
versions of the XML-Feed Gear in the Content Syndication Gear Folder are good examples of how to use
this gear for simple XSLT.
87
Configuring the XML-Feed Gear for External Content Providers

The XML-Feed Gear provides a framework for configuring it with various external XML content providers.
The gear users can customize the content. These customization parameters are mapped to the URL of the
XML source. For more information on gear parameters and customization, refer to the ATG Portal
Development Guide.
You can configure the source feed installation settings of the XML-Feed Gear.
1.
On the Gears tab of the Portal Administration Pages click the configure link next to
the XML-Feed Gear name.
The Xmlfeed Gear Install Configuration Page opens.
2.
Set the following source feed and output parameters:

Base XML Source:
Additional Query Parameters Mapping:
XSL Source for Shared Mode, HTML Output:
XSL Source for Full Mode, HTML Output:
XSL Source for Shared Mode, WML Output:
XSL Source for Full Mode, WML Output:
Show a link to the full mode in shared mode: Enter true if you want the shared
display mode version of the gear to include a link that opens the gear in full display
mode.
3.
Click Update.
The gear is updated to use the new settings.
The Configure Basics page for an instance of the XML-Feed Gear allows you to configure the usual gear
basics:
Gear Name
Gear Description
Sharing
Make visible to
The additional configuration page for the XML-Feed Gear allows you to configure each of the source
feed and output parameters that you can configure in the Portal Administrations installation
configuration for the gear:
Base XML Source
Additional Query Parameters Mapping
XSL Source for Shared Mode, HTML Output
XSL Source for Full Mode, HTML Output
88
XSL Source for Shared Mode, WML Output

XSL Source for Full Mode, WML Output
Show a link to the full mode in shared mode
XML Protocol Gear

Module name: xmlprotocol
The XML Protocol Gear communicates with external XML-based service providers. The gear can retrieve
and display XML documents such as headlines, categories, or articles from service providers such as
syndicated news services. The XML Protocol Gear can communicate with stateful or stateless service
providers.
The Configure Basics page for an instance of the XML Protocol Gear allows you to configure the usual
gear basics:
Gear Name
Gear Description
Sharing
Make visible to
The additional configuration page for the XML Protocol Gear has two subpages: Edit gear
configuration and Edit user defaults.
Edit gear configuration

The Edit gear configuration subpage allows you to configure the source of the XML service and the
stylesheets used to display the XML provided by the service:
Instance Authentication Parameters
User ID: The user ID required to access the XML service provider.
Password: The password associated with the user ID required to access the XML service provider.
Service Configuration Parameters
Service provider: Enter the name of the adapter class for communicating with a provider service. The
default is atg.portal.gear.xmlprotocol.GenericXPathAdaptor. You need to create a new adapter
class for each service provider you want to communicate with. See Creating New Adapter Classes for
information.
Enter the URL required by the service provider (including an appropriate port number, if any) for each of
the following:
Authentication URL: The URL for authenticating with the service provider.
Categories URL: The URL for retrieving a list of categories from the service provider.
89
Headlines URL: The URL for retrieving headlines from the service provider.
Article URL: The URL for retrieving articles from the service provider.
Feed Display Configuration Parameters
Enter the URLs of XSL stylesheets for full and shared views of content from the service provider:
Full View Categories Stylesheet URL
Full View Article Stylesheet URL
Full View Headlines Stylesheet URL
Shared View Categories Stylesheet URL
Shared View Headlines Stylesheet URL
The gear includes a set of example XSL stylesheets for each of these content view categories. The
stylesheets can be found in the /xmlprotocol/src/xmlprotocol.war/templates folder.
Edit user defaults

The Edit user defaults subpage allows you to configure the default display options for users. The
parameters you can set are:
Number of headlines to display in shared mode
Number of headlines to display in full mode
Categories to display
Creating New Adapter Classes

The XML Protocol Gear requires a Java adapter class to be generated for each service provider it
communicates with. The gear includes a base class, XpathBaseAdaptor, that you can use in combination
with an XSLT stylesheet to generate the adapter class. To generate an adapter class:
1.
Create an adapter manifest file. Base this manifest file on the example at
<ATG2007.1dir>/Portal/xmlprotocol/src/etc/adaptor.definitions/Gener
icXPath-manifest.xml. Enter values appropriate for the service provider in the
fields of the manifest file.

2.
Perform an XSLT transform, using the XSLT stylesheet found at together with your
adapter manifest file.
3.
Compile the resulting Java class and put it in your CLASSPATH.
4.
When you create an instance of the XML Protocol Gear for this service provider, enter
the class name of the adapter class in the Service Configuration Parameters: Service
provider field of the Edit gear configuration page.
90
91
Index
A
alerts
configuring, 49, 50
configuring e-mail, 17
creating, 50
deleting, 51
Alerts Gear, 67
Announcements Gear, 75
anonymous access, 23
B
baseline gears, 65
Alerts Gear, 67
Announcements Gear, 75
Bookmarks Gear, 68
Calendar Gear, 69
Community Members Gear, 70
configuring, 66
Discussion Gear, 70
Document Exchange Gear, 71
Favorite Communities Gear, 75
HTML Content Gear, 76
Login Gear, 77
Outlook Gear, 78
Poll Gear, 79
Quicklinks Gear, 79
Repository Search Gear, 80
Repository View Gear, 81
Targeted Content Gear, 83
Web Services Client Gear, 85
XML Protocol Gear, 89
XML-Feed Gear, 87
Bookmarks Gear, 68
branding, 13
business rules, 13
C
Calendar Gear, 69
cascading stylesheets. See stylesheets
color palettes, 45
adding, 46
Communities, 19
copying from templates, 31
creating, 21, 24
deleting, 27
disabling, 27
editing, 27
Guests, 22
Leaders, 22
Members, 22
membership, 23
role IDs, 23
Community Administration pages, 8
color palettes, 44
community gears tab, 10
community members tab, 39
community pages tab, 10
community settings tab, 9, 23
community users tab, 9
layout templates, 44
page layouts, 44
reset buttons, 10
security, 63
Community folders, 20
creating, 20
deleting, 20
Community Guests
adding, 41
Community Leaders
adding, 40
Community Members
adding, 39
approving or declining, 39
enabling membership request notification, 39
Community Members Gear, 70
Community pages
adding, 29
adding gears, 30
deleting, 30
editing, 28
viewing, 30
community proposals, 34
creating, 37
scenarios, 37
workflows, 35
Community roles, 21
community templates, 31
creating, 31
creating new users, 41
customization administration, 51
D
database
configuring, 11
92
Index
default Portal, 4
Discussion Gear, 70
item cache, 71
Document Exchange Gear, 71
virus scanning, 74
localization, 16
Login Gear, 77
M
manifest files, 43
F
Favorite Communities Gear, 75
organizations, 19
Outlook Gear, 78
gear administration, 47
gear folders, 47
gear title templates, 14, 45
adding, 45
titlebar.jsp, 15
titlebar-post.jsp, 15
titlebar-pre.jsp, 15
gears
adding to the PAF, 48
baseline, 65
deleting, 48
installation configuration, 47
instance configuration, 47
limiting access by communities, 26
parameter configuration, 48
sharing, 49
H
HTML Content Gear, 76
configuring parser, 76
HtmlFilterParser component, 76
I
individuals, 19
internationalization, 16
J
J2EE security, 59
L
layout templates, 14, 44
100.jsp, 14
25_50_25.jsp, 14
25_75.jsp, 14
75_25.jsp, 14
adding, 45
creating, 16
LDAP profile repositories
searching for users, 42
P
page templates, 13, 44
adding, 44
full page template, 14
shared page template, 14
performance
Scenario Server, 17
Poll Gear, 79
Portal
development basics, 4
Portal Administration pages, 5, 24
Alerts tab, 8
color palettes, 8
communities tab, 6
community members tab, 24
gear title templates, 7
Gears tab, 6
launching, 4
layout templates, 7
page templates, 7
security, 63
Styles tab, 7
stylesheets, 8
Portal Administrator, 22
Portal Process Automation, 34
Portal.<gearname>, 2
Portal.gears module, 2
Portal.paf module, 1
Profile repository, 12
profile template, 12
Q
Quicklinks Gear, 79
R
region.jspf, 14
registered user, 22
relative roles, 22
repositories
configuring, 11
creating, 11
profile, 12
93
Index
Repository Search Gear, 80

Repository View Gear, 81
roles
Community, 21
Community Leader, 22
Community Member, 22
global, 22
IDs, 23
relative, 22
scenarios, 13
scenarios for community proposals, 37
security, 59
administering, 59
secured areas, 63
security levels
see access levels, 60
Slot Gear. See Targeted Content Gear
SlotConfiguration component, 83
SpawnCommunity tool, 32
stylesheets, 46
adding, 46
user profiles
creating, 41
Targeted Content Gear, 83

repository configuration, 83
SlotConfiguration component, 83
templates
gear title, 45
layout, 44
page, 44
W
Web Services Client Gear, 85
workflows for community proposals, 34, 35
X
XML Protocol Gear, 89
adapter classes, 90
XSL stylesheets, 90
XML-Feed Gear, 87
94
Index

At G Portal Admin Guide

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

At G Portal Admin Guide

Uploaded by

Copyright:

Available Formats

atg

ATG Portal Administration Guide

ATG Portal Administration Guide

Portal Administration Pages

ATG Portal Administration Guide

ATG Portal Administration Guide

Working with Community Membership

Using Scenarios with ATG Portal

ATG Portal Administration Guide

Portal Access Control

Baseline Gear Administration

Baseline Gears Overview

ATG Portal Administration Guide

Starting up the Portal Application

ATG Portal Administration Guide

Portal Web Applications

The Portal Administration

The Community Administration

The default Portal

ATG Portal Administration Guide

Targeted Content (Slot)

Web Services Client

Accessing ATG Portal

Opening a Portal Page

The elements of the URL are as follows:

The portal context is portal for the default portal

The name of the community folder

The name of the community that you want to view

The name of a specific page in the community. If no page name is

The portal page opens in the browser window.

ATG Portal Administration Guide

Opening the Portal Administration Pages

Accessing the Default Portal

Assemble an application that includes the Portal.gears module.

ATG Portal Administration Guide

Portal Administration Pages

Portal Administration Navigation

ATG Portal Administration Guide

ATG Portal Administration Guide

Gear Title Templates

ATG Portal Administration Guide

Community Administration Pages

ATG Portal Administration Guide

Community Settings Tab

Community Users Tab

Community Pages Tab

Community Gears Tab

Community Settings Tab

Community Users Tab

ATG Portal Administration Guide

Community Pages Tab

Community Gears Tab

ATG Portal Administration Guide

Configuring Your Database

Configuring Your Repositories

Portal Repository Creation

ATG Portal Administration Guide

Portal Repository Configuration

ATG Portal Administration Guide

Page Templates and Branding

ATG Portal Administration Guide

Shared and Full Page Template

Gear Title Template Files