Administering Portals With Scripts

Print-friendly Version

For most portal administration tasks, the Administration Consoles for Sun Java System Portal Server 7 (henceforth, Portal Server) and Sun Java System Access Manager 7 (henceforth, Access Manager) suffice. For repetitive tasks, however, scripts not only save you time but also ensure accuracy and consistency across your portals.

This article demonstrates how to invoke the command-line interface (CLI) utilities in Portal Server and Access Manager and how to configure scripts for common tasks.

Portal Server manages many typical administration tasks, such as those on organizations, roles, users, and services, through Access Manager. The CLI for those tasks is amadmin. Management of portal configurations, such as channels and containers, is through the Portal Server Administration Console. The corresponding CLI is psadmin.

This article describes the common uses for amadmin and psadmin and leads you through an example scenario. There, you create an organization with a portal desktop based on the Enterprise Sample that is part of Portal Server. You can do that from the two Administration Consoles, but that would involve numerous steps and is subject to human error. The scripts that accompany this article automate many of those steps. In this article, you also learn how to create a script that performs many common tasks.

Figure 1 illustrates the script process.

Figure 1: Administration of Sun Java System Portal Server With Scripts

To perform the tasks, you must have Portal Server and Access Manager installed on your system.

Before stepping through the example, download the scripts. Table 1 lists and describes the files.

File Name	Description
copyEnterpriseSample.sh	A UNIX shell script that executes amadmin and psadmin CLIs for copying the Enterprise Sample Portal.
createEnterpriseSample.xml	An amadmin script that creates the organization, services, user accounts, and roles for the Enterprise Sample Portal.
copyDeveloperSample.sh	A UNIX shell script that executes amadmin and psadmin CLIs for copying the Developer Sample Portal.
createDeveloperSample.xml	An amadmin script that creates the organization, services, and user accounts for the Developer Sample Portal.

Installing Portal Server also installs the Enterprise Sample into an organization called o=EnterpriseSample located directly under the root suffix of the directory.

The Enterprise Sample comprises the following components:

Component	Details
One organization	o=EnterpriseSample
Two roles	cn=AustraliaExpansionRole cn=NewCustomerToursRole
Three users	uid=ed, a member of the AustraliaExpansionRole role uid=mary, a member of the AustraliaExpansionRole and NewCustomerToursRole roles uid=chris, a member of the NewCustomerToursRole role
One authless anonymous user	uid=authlessenterprisesample
Portal display profiles	Organization, role, and user levels
Portal desktop JSP pages	/var/opt/SUNWportal/portals/portal-ID/desktop

You can manage the entire sample portal with three tools:

• amadmin — For configuring Access Manager to manage organizations, roles, and users
• psadmin — For configuring Portal Server to manage display profiles
• cp (UNIX command) — For handling JavaServer Pages (JSP) pages on the file system

The scripts create a copy of the Enterprise Sample Portal. Also in place are new organizations, roles, and users that mirror the ones installed with the Enterprise Sample. Table 2 lists the mappings.

New Sample Values (Copy)	Original Sample Values
Organization o=ExampleOrg	Organization o=EnterpriseSample
Role cn=AustraliaExpansionRole	Role cn=AustraliaExpansionRole
Role cn=NewCustomerToursRole	Role cn=NewCustomerToursRole
User uid=authlessanonymous_example_org userPassword=authlessanonymous_example_org	uid=authlessenterprisesample userPassword=authlessenterprisesample
User uid=ernie userPassword=password	User uid=ed userPassword=ed
User uid=charles userPassword=password	User uid=chris userPassword=chris
User uid=martin userPassword=password	User uid=mary userPassword=mary
Portal PortalID=portal1	Portal PortalID=portal1

The amadmin CLI is a robust utility that handles numerous management tasks for Access Manager. This article focuses on the import task, which operates on an XML script that contains configuration instructions for Access Manager.

Access Manager manages configurations in the form of services. When installing Portal Server, you add services, such as the following, to Access Manager to handle the configurations in Portal Server.

The amadmin command in Access Manager is in the Access-Manager-install-dir/bin directory, where Access-Manager-install-dir is the directory in which you installed Access Manager.

The import task of amadmin operates on an XML document that holds Access Manager instructions for copying the Enterprise Sample Portal. Additional instructions are in the amAdmin.dtd file in the Access-Manager-install-dir/dtd directory. Many sample scripts reside in the Access-Manager-install-dir/samples/admin/cli/bulk-ops directory.

The amadmin command reads an XML document with a script of instructions for Access Manager. Here is the syntax (all on one line) for the sample:

Access-Manager-install-dir/bin/amadmin -u amadmin -f pwdfile -v -t instructionFile.xml

The next subsections describe the content of the script for creating the Enterprise Sample Portal. Each section explains a portion of the script.

To copy the Enterprise Sample Portal, first create an organization with the CreateSubOrganization instruction.

To create an organization:

1. Define the OrganizationRequests element with the DN attribute to specify the organization for the included instructions.
   
   
2. Define the CreateSubOrganization element with the createDN attribute to specify the organization name.

See the following code segment in createEnterpriseSample.xml.

...
<OrganizationRequests DN="dc=example,dc=com">
    <CreateSubOrganization createDN="ExampleOrg"/>
</OrganizationRequests>
...

Access Manager locates the organization in Directory Server by means of the attribute OrganizationAlias.

To set the organization alias:

1. Define OrganizationAlias with the ModifySubOrganization instruction and its modifyDN attribute.
   
   
2. Specify the attribute name as sunOrganizationAlias with the AttributeValuePair element.

See the following code segment in createEnterpriseSample.xml.

...
<OrganizationRequests DN="dc=example,dc=com">
    <ModifySubOrganization modifyDN="o=ExampleOrg,dc=example,dc=com">
	<AttributeValuePair>
	    <Attribute name="sunOrganizationAlias"/>
	    <Value>ExampleOrg</Value>
	</AttributeValuePair>
    </ModifySubOrganization>
</OrganizationRequests>
...

To have the portal function properly, add services to the new organization. The required ones are SunPortalportal1DesktopService and SunPortalportal1SubscriptionsService. The service names include the portal ID, portal1.

To add services to the organization, register the services and then create the service templates with the RegisterServices and CreateServiceTemplate instructions. Specifically:

1. Define the organization to be updated with, again, the OrganizationRequests element.
   
   
2. Define RegisterServices and CreateServiceTemplate under OrganizationRequests.

See the following code segment in createEnterpriseSample.xml.

...
<OrganizationRequests DN="o=ExampleOrg,dc=example,dc=com">
    <!-- Register the Desktop and Subscriptions Services -->
    <RegisterServices>
	<Service_Name>SunPortalportal1DesktopService</Service_Name>
	<Service_Name>SunPortalportal1SubscriptionsService</Service_Name>
	<Service_Name>SunSSOAdapterService</Service_Name>
    </RegisterServices>

    <!-- Create the Desktop and Subscriptions Service Templates -->
    <CreateServiceTemplate>
	<Service_Name>SunPortalportal1DesktopService</Service_Name>
	<Service_Name>SunPortalportal1SubscriptionsService</Service_Name>
	<Service_Name>SunSSOAdapterService</Service_Name>
    </CreateServiceTemplate>

</OrganizationRequests>
...

Organizations contain a list of required services, which Access Manager automatically adds to user accounts that you create in the organization. That add task represents a significant convenience: You need not explicitly add the services each time you create an account. The attribute in question is iplanet-am-required-services.

See the following code segment in createEnterpriseSample.xml.

...
<OrganizationRequests DN="o=ExampleOrg,dc=example,dc=com">
    <AddServiceTemplateAttributeValues serviceName="iPlanetAMAdminConsoleService" schemaType="Organization">
	<AttributeValuePair>
	    <Attribute name="iplanet-am-required-services"/>
	    <Value>SunPortalportal1DesktopService</Value>
	    <Value>SunPortalportal1SubscriptionsService</Value>
	    <Value>SunSSOAdapterService</Value>
   	</AttributeValuePair>
     </AddServiceTemplateAttributeValues>
</OrganizationRequests>
...

The Enterprise Sample Portal employs two custom service attributes:

• A custom Portal Desktop, enterprise_sample
• A new default container, ASCTabContainer

Accordingly, do the following:

1. Specify the enterprise_sample and ASCTabContainer values as attributes of the sunPortalportal1DesktopService service. The attributes are—
   
   • sunPortalportal1DesktopType
   • sunPortalportal1DesktopDefaultChannelName
   • sunPortalportal1DesktopEditProviderContainerName
   
   
2. Set those values for the new organization with the ModifyServiceTemplate instruction.

See the following code segment in createEnterpriseSample.xml.

...
<OrganizationRequests DN="o=ExampleOrg,dc=example,dc=com">
    <ModifyServiceTemplate serviceName="SunPortalportal1DesktopService" schemaType="Dynamic">
	<!-- Set the Desktop Type -->
	<AttributeValuePair>
	    <Attribute name="sunPortalportal1DesktopType"/>
	    <Value>example_org</Value>
	</AttributeValuePair>
	<!-- Set the Default Channel Name -->
	<AttributeValuePair>
	    <Attribute name="sunPortalportal1DesktopDefaultChannelName"/>
	    <Value>ASCTabContainer</Value>
	</AttributeValuePair>
	<!-- Set the Edit Provider Container Name -->
	<AttributeValuePair>
	    <Attribute name="sunPortalportal1DesktopEditProviderContainerName"/>
	    <Value>JSPEditContainer</Value>
	</AttributeValuePair>
    </ModifyServiceTemplate>
</OrganizationRequests>
...

The new organization must contain two roles—AustraliaExpansionRole and NewCustomerToursRole—that mirror those in the Enterprise Sample Portal. Create the roles as static ones because they explicitly specify their members. You can also create them as filtered roles. For details, see "Filtered Role" in the Sun Java System Access Manager 7 2005Q4 Administration Guide.

See the following code segment in createEnterpriseSample.xml.

...
<OrganizationRequests DN="o=ExampleOrg,dc=example,dc=com">
    <CreateRole createDN="AustraliaExpansionRole" roleType="static" />
    <CreateRole createDN="NewCustomerToursRole" roleType="static" />
</OrganizationRequests>
...

The new roles also need the portal services. You need not register the roles with the RegisterServices instruction. Simply set the services and attribute values simultaneously with a compound instruction for the role.

See the following code segment in createEnterpriseSample.xml.

...
<RoleRequests DN="cn=AustraliaExpansionRole,o=ExampleOrg,dc=example,dc=com">
    <!-- Create the Desktop and Subscriptions Service Templates -->
    <CreateServiceTemplate>
	<Service_Name>SunPortalportal1DesktopService</Service_Name>
	<Service_Name>SunPortalportal1SubscriptionsService</Service_Name>
	<Service_Name>SunSSOAdapterService</Service_Name>
    </CreateServiceTemplate>
    <ModifyServiceTemplate serviceName="SunPortalportal1DesktopService" schemaType="Dynamic">
	<!-- Set the Desktop Type -->
	<AttributeValuePair>
	    <Attribute name="sunPortalportal1DesktopType"/>
	    <Value>example_org</Value>
	</AttributeValuePair>
	<!-- Set the Default Channel Name -->
	<AttributeValuePair>
	    <Attribute name="sunPortalportal1DesktopDefaultChannelName"/>
	    <Value>ASCTabContainer</Value>
	</AttributeValuePair>
	<!-- Set the Edit Provider Container Name -->
	<AttributeValuePair>
	    <Attribute name="sunPortalportal1DesktopEditProviderContainerName"/>
	    <Value>JSPEditContainer</Value>
	</AttributeValuePair>
    </ModifyServiceTemplate>
</RoleRequests>
...

The Enterprise Sample includes several user accounts that demonstrate the anonymous access and role membership capabilities of Portal Server.

To create a user account:

1. Define the PeopleContainerRequests element.
   
   
2. Specify the related user information with the CreateUser instruction.

See the following code segment in createEnterpriseSample.xml.

...
<PeopleContainerRequests DN="ou=People,o=ExampleOrg,dc=example,dc=com">
    <!-- This user is like the 'ed' user in the Enterprise Sample -->
    <CreateUser createDN="ernie">
	<AttributeValuePair>
	    <Attribute name="givenname" />
	    <Value>Ernie</Value>
	</AttributeValuePair>
	<AttributeValuePair>
	    <Attribute name="sn" />
	    <Value>User</Value>
	</AttributeValuePair>
	<AttributeValuePair>
	    <Attribute name="cn" />
	    <Value>Ernie User</Value>
	</AttributeValuePair>
	<AttributeValuePair>
	    <Attribute name="userpassword" />
	    <Value>password</Value>
	    </AttributeValuePair>
	</AttributeValuePair>
    </CreateUser>
</PeopleContainerRequests>
...

Each user account belongs to one or multiple roles. Add user accounts to roles with the RoleRequests element. Within that element is the AddUsers instruction, which contains a list of users.

See the following code segment in createEnterpriseSample.xml.

...
<RoleRequests DN="cn=AustraliaExpansionRole,o=ExampleOrg,dc=example,dc=com">
    <AddUsers>
	<DN>uid=ernie,ou=People,o=ExampleOrg,dc=example,dc=com</DN>
	<DN>uid=martin,ou=People,o=ExampleOrg,dc=example,dc=com</DN>
    </AddUsers>
</RoleRequests>
...

Portal Server maintains a list of users who are authorized to access the portal anonymously. You can view the list in the Portal Server Admin Console by selecting TopLevel from the list of DNs. The attribute is sunPortalDesktopAuthorizedAuthlessUIDs.

See the following code segment in createEnterpriseSample.xml.

...
<SchemaRequests serviceName="SunPortalportal1DesktopService" SchemaType="Global">
    <AddDefaultValues>
	<AttributeValuePair>
	    <Attribute name="sunPortalDesktopAuthorizedAuthlessUIDs"/>
<Value>uid=authlessanonymous_example_org,ou=People,o=ExampleOrg,dc=example,dc=com|
authlessanonymous_example_org</Value>
	</AttributeValuePair>
    </AddDefaultValues>
</SchemaRequests>
...

The psadmin CLI is a useful, all-in-one administration command for Portal Server. It contains many subcommands that perform numerous tasks—from managing display profiles to configuring the search engine. To copy the Enterprise Sample Portal, run two subcommands:

• list-display-profile — Extracts the display profile for a specific target DN.
• update-display-profile — Replaces the display profile for a specific target DN.

By running both subcommands, you can copy the display profile from one location to another.

Executing psadmin can extract and update display profiles for specific target DNs. Here are the syntaxes (each on one line) for extracting (list-display-profile) and modifying (modify-display-profile) profiles for the sample:

Portal-Server-install-dir/bin/psadmin list-display-profile -u amadmin -f pwdfile -p portal-ID -d targetDN -o outputFile

Portal-Server-install-dir/bin/psadmin modify-display-profile -u amadmin -f pwdfile -p portal-ID -d targetDN inputFile

The next subsections describe how to copy a display profile from one DN to another.

A portal display profile is a special XML document that specifies organizations, roles, and users. You can manage the profile with the psadmin CLI in Portal Server. psadmin resides in the Portal-Server-install-dir/bin directory. Copy the display profiles for the Enterprise Sample organization, roles, and users to the new organizations, roles, and users.

See the following code segment in copyEnterpriseSample.sh.

...
# ./psadmin list-display-profile -u amadmin -f pwdfile -p portal1 -d
"o=EnterpriseSample,dc=example,dc=com" -o /tmp/entSampleDP.xml
# ./psadmin modify-display-profile -u amadmin -f pwdfile -p portal1 -d
"o=ExampleOrg,dc=example,dc=com" /tmp/entSampleDP.xml
...

The overall look and feel of the Enterprise Sample is reflected in the JSP files. The instructions for creating the services for the organization include the sunPortalportal1DesktopType attribute. That attribute's value refers to a directory that contains the JSP files for the containers and providers in the user desktop.

The example_org directory does not exist. Create it by copying over the enterprise_sample directory. Both directories are under the /etc/opt/SUNWportal/portals/portal1/desktop directory.

See the following code segment in createEnterpriseSample.xml.

...
cd /var/opt/SUNWportal/portals/portal1/desktop
cp -rp enterprise_sample example_org
...

You can test the new portal at http://server.domain.com:port/portal/dt?desktop.suid=uid=authlessanonymous_example_org,ou=people,
dc=ExampleOrg,dc=example,dc=com. The browser displays the anonymous desktop for the newly created portal.

Further test the portal by verifying that charles, ernie, and martin can log in.

Here are a few helpful tips for creating scripts:

• Before running any amadmin or psadmin scripts, back up Directory Server with the db2bak command. To restore the directory, run bak2db. For details, see the Sun Java System Directory Server Administration Guide.
  
  
• Turn on the debug logs:
  • Set com.iplanet.services.debug.level=message in the AMConfig.properties file.
  • Set debug.com.sun.portal.admin.cli.level=FINEST in the PSAdminLogConfig.properties file.
  
  The log files reside at the following locations:
  
  
• On the Solaris Operating System:
  /var/opt/SUNWam/debug
/var/opt/SUNWportal/logs/admin
/var/opt/SUNWportal/portals/portal-ID/logs/instance-name
  
  
• On Linux:
  /var/opt/sun/identity/debug
/var/opt/sun/portal/logs/admin
/var/opt/sun/portal/portals/portal-ID/logs/instance-name
  
  
• Become familiar with the following topics:
  
  

  Topic	Location
  amadmin sample	Access-Manager-install-dir/samples/admin/cli/bulk-ops
  amadmin DTD	Access-Manager-install-dir/dtd/amAdmin.dtd
  Portal samples	Portal-Server-install-dir/samples/portals

   
  
• Develop the scripts in stages and test them on a development system. Each time you run the scripts, restore Directory Server.

Do create similar scripts to automate your portal deployment tasks! You can manage the scripts along with the source code that constitutes your portal project. Furthermore, automate the deployment of portals in development, test, and production environments with scripts. Not only do they save time, they are much less error-prone than manual tasks.

• Sun Java System Access Manager
  • Main page
  • Developer home
  • Software Forum
  • Sun Java System Access Manager 7 2005Q4 Administration Guide
  
  
• Sun Java System Portal Server
  • Main page
  • Developer home
  • Software Forum
  • Command-Line Reference
  
  
• Weblogs
  • The Portal Post
  • The Aquarium
  
  
• Developer services
  • Support
  • Training and certification