Professional Documents
Culture Documents
Version 2007.1
Portal Administration Guide
ATG
One Main Street
Cambridge, MA 02142
www.atg.com
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 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
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
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
59
59
59
60
60
61
62
63
63
63
65
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.
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.
Web Application
Archive
Module
Description
admin.war
PAF
settings.war
PAF
portal.war
PAF
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
slotgear
soapclient
XML Protocol
xmlprotocol
XML Feed
xmlfeed
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
communityfoldername
Communityname
pagename
3
1 - Getting Started
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:
Portal Administration Pages
Community Administration Pages
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
2 - Administration Pages
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.
7
2 - Administration Pages
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.
8
2 - Administration Pages
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:
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.
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
2 - Administration Pages
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.
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
2 - Administration Pages
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:
Configuring Your Database
Configuring Your Repositories
Business Rules
Page Templates and Branding
Localizing a Portal
Configuring E-mail Templates for Alerts
Portal and the Global Scenario Server
11
3 - Portal 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
3 - Portal Configuration
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.
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
3 - Portal Configuration
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.
14
3 - Portal Configuration
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.
Files
File Name
Location
Login
login.jsp
<ATG2007.1dir>/Portal/paf/starterportal/paf-dar/portal/userprofiling
Logout
logout.jsp
<ATG2007.1dir>/Portal/paf/starterportal/paf-dar/portal/userprofiling
Registration
register.jsp
<ATG2007.1dir>/Portal/paf/starterportal/paf-dar/portal/userprofiling
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
3 - Portal Configuration
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.
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.
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
3 - Portal Configuration
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.
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.
17
3 - Portal Configuration
18
3 - Portal Configuration
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.
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.
Start the ACC and open the Portals > Portal Repository window.
2.
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.
20
4 - Community Administration
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.
2.
3.
Navigate to /atg/portal/admin/PortalPropertyManager.
4.
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
4 - Community Administration
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
4 - Community Administration
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 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:
23
4 - Community Administration
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.
Creating a Community
Editing a Community
Disabling a Community
Deleting 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.
Creating a Community
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
4 - Community Administration
1.
2.
4.
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.
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
4 - Community Administration
6.
7.
Select whether this gear should be shared with other communities and which users
the gear should be visible to. Click Done.
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.
26
4 - Community Administration
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.
Disabling a Community
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.
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.
Deleting a Community
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
4 - Community Administration
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.
2.
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
4 - Community Administration
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.
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.
3.
Click on the Create New Page link in the side task bar.
The Create New Page page opens.
4.
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
4 - Community Administration
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.
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.
Enter the Community Administration for the community whose page you want to
view.
2.
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.
30
4 - Community Administration
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.
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.
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.
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.
31
4 - Community Administration
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.
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.
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
32
4 - Community Administration
-name
Required. No default.
-url
Required. No default.
-parentFolder
-enabled
-description
-membership
-pageTemplate
-style
-gearTemplate
-customization
-access
-host
Defaults to localhost if no
hostname is specified.
-port
8860
-cloneSharedGears
33
4 - Community Administration
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.
Property
Description
community
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
4 - Community Administration
creationDate
creator
The user who created the community proposal. This property is a user
profile maintained in the Profile Repository.
id
lastModified
name
url
version
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.
35
4 - Community Administration
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.
3.
The creator of the community proposal is assigned the role of leader for the new
community.
4.
Action Field
CommunityProposal Property
Community Template
communityTemplate
Community Name
name
url
In addition, the Create Community from Template action takes the following input:
Action Field
Description
Community folder
36
4 - Community Administration
Should this community get its own copy of its gear, or share an instance of
the gear with the template?
Action Field
Description
Community id
User id
Role Name
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.
37
4 - Community Administration
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.
38
4 - Community Administration
2.
3.
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.
2.
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.
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.
39
4 - Community Administration
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.
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.
6.
Make sure the emailer and emailSenderAddress properties are set properly.
7.
Click Save.
Log in to the Community Administration and click the Community Users tab.
2.
3.
4.
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
4 - Community Administration
1.
2.
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 Leader.
Log in to the Community Administration and click on the Community Users tab.
2.
3.
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.
2.
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 guest.
2.
3.
41
4 - Community Administration
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
4 - Community Administration
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
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.
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
5 - Portal Administration
2.
Enter the location of the layout template manifest file in the text field, or use the
Browse button to locate the file, then click Upload.
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.
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.
2.
Enter the location of the gear title template manifest file in the text field, or use the
Browse button to locate the file, then click Upload.
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
5 - Portal Administration
Text 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.
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.
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
5 - Portal Administration
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.
2.
Click the New Gear Folder link in the side navigation panel.
3.
Enter a name for the new gear folder and click Done.
47
5 - Portal Administration
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.
2.
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.
2.
Locate the gear you want to remove and click its delete link.
48
5 - Portal Administration
3.
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.
4.
Under the Sharing heading, check the Allow this gear to be shared with other
communities check box.
5.
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
5 - Portal Administration
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.
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
Message Type
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
5 - Portal Administration
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.
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
51
5 - Portal Administration
52
5 - Portal Administration
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.
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.
2.
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.
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
6 - Using Scenarios with ATG Portal
55
6 - Using Scenarios with ATG Portal
Scenario Name
Description
Discussions
56
6 - Using Scenarios with ATG Portal
Membership Request
Portal Calendars
Portal Usage
Profile Updates
Registration
Site Retention
57
6 - Using Scenarios with ATG Portal
58
6 - Using Scenarios with ATG Portal
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.
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).
2.
3.
Select one security level from the Basic Access page and click Update.
60
7 - Portal Access Control
1.
2.
Click Community Access in the side navigation bar to make the Advanced Access
option visible.
3.
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.
3.
4.
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.
61
7 - Portal Access Control
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.
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
7 - Portal Access Control
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.
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.
63
7 - Portal Access Control
64
7 - Portal Access Control
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.
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.
Repository View Gear
The Repository View Gear can display information about repository items from any ATG repository.
Web Services Client Gear
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.
66
8 - Baseline Gear Administration
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
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
8 - Baseline Gear Administration
organization alerts
user alerts
5.
Click Update.
2.
3.
4.
5.
Once you have set the data removal properties, click Start.
The component starts, using the settings you have specified.
AlertRepositoryAdmin Properties
Description
expirationDate
expirationDays
schedule
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.
Instance Configuration
The Bookmarks Gear has only the usual basics to configure. To configure an instance of the Bookmarks
Gear:
68
8 - Baseline Gear Administration
1.
Enter the Community Administration and click the configure link for the gear
instance.
2.
In the configuration basics page, enter a gear name and description. Select sharing
and Make visible to options and click Done.
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.
Instance Configuration
To configure an instance of the Calendar Gear:
1.
Enter the Community Administration and click the configure link for the 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.
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.
Enter the Community Administration and go to the Current Gear Instances page.
2.
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
8 - Baseline Gear Administration
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.
Instance Configuration
To configure an instance of the Community Members Gear:
1.
Enter the Community Administration and click the configure link for the 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. 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.
Instance Configuration
To configure an instance of the Discussion Gear:
1.
Enter the Community Administration and click the configure link for the 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. The additional configurations page has
five subpages, select/administer forums, Display Attributes, access controls,
alerts, and resource bundle.
70
8 - Baseline Gear Administration
<gsa-template>
<item-descriptor name="messageThread" item-cache-size="50000">
</item-descriptor>
</gsa-template>
71
8 - Baseline Gear Administration
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:
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.
...
<token>
<expression-class>atg.ui.expreditor.targeting.RepositoryItemSetExpression
</expression-class>
<assistant-class>atg.ui.expreditor.targeting.RepositoryItemSetAssistant
</assistant-class>
<attribute
72
8 - Baseline Gear Administration
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.
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
8 - Baseline Gear Administration
Instance Configuration
Enter the Community Administration and click the Select New Gears link in the side
navigation panel.
2.
3.
4.
Click Done.
Enter the Community Administration and click the configure link for the gear
instance.
2.
3.
4.
Click the permission link. You can select which groups of portal users are permitted
to:
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.
74
8 - Baseline Gear Administration
<ATG2007.1dir>/Portal/docexch/src/classes.jar/atg/portal/gear/docexch/
DocumentFormHandler.java
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.
Instance Configuration
To configure an instance of the Favorite Communities Gear:
1.
Enter the Community Administration and click the configure link for the gear
instance.
2.
In the configuration basics page, enter a gear name and description. Select sharing
and Make visible to options and click Done.
75
8 - Baseline Gear Administration
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.
Instance Configuration
To configure an instance of the HTML Content Gear:
1.
Enter the Community Administration and click the configure link for the 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. The additional configurations page has
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.
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
8 - Baseline Gear Administration
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.
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.
Instance Configuration
To configure an instance of the Login Gear:
1.
Enter the Community Administration and click the configure link for the 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. 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.
Outlook Gear
Module name: exchange
77
8 - Baseline Gear Administration
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.
Installation Configuration
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.
The gear is updated to use the new settings and information.
Instance Configuration
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.
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.
78
8 - Baseline Gear Administration
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:
Access settings
Poll parameters
Instance Configuration
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.
3.
Enter a gear name and description. Select sharing and Make visible to options.
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
8 - Baseline Gear Administration
1.
Enter the Community Administration. Click the Community Gears tab to view the
Configure Gear Instances page.
2.
3.
Enter a gear name and description. Select sharing and Make visible to options.
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.
The gear is updated to use the new settings and information.
Installation Configuration
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
10
25
Instance Configuration
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
10
100
80
8 - Baseline Gear Administration
Installation Configuration
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.
you create a custom JSP fragment, specify its pathname is relative to the
81
8 - Baseline Gear Administration
example, if you put your custom JSP fragment in the same directory as the two sample
fragments, enter custom/mycustom.jsp.
Click Update.
7.
8.
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.
Instance Configuration
To configure an instance of the Repository View Gear:
1.
Enter the Community Administration and click the configure link for the 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. 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
8 - Baseline Gear Administration
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.
Installation Configuration
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.
%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
8 - Baseline Gear Administration
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.
Instance Configuration
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.
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.
84
8 - Baseline Gear Administration
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:
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.
Installation Configuration
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
8 - Baseline Gear Administration
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
Parameters
Target URL
SOAP Action
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
8 - Baseline Gear Administration
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.
2.
3.
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.
87
8 - Baseline Gear Administration
Installation Configuration
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.
3.
Click Update.
The gear is updated to use the new settings.
Instance Configuration
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
8 - Baseline Gear Administration
Instance Configuration
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.
89
8 - Baseline Gear Administration
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.
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
Perform an XSLT transform, using the XSLT stylesheet found at together with your
adapter manifest file.
3.
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
8 - Baseline Gear Administration
91
8 - Baseline Gear Administration
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
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
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