Sun ONE Portal Server 6.0 Administrator's Guide: Chapter 5 Administering the Display Profile

Sun ONE Portal Server 6.0 Administrator's Guide

Chapter 5 Administering the Display Profile

This chapter describes the Sun™ ONE Portal Server display profile component and how to administer it.

This chapter contains these sections:

Overview of Display Profile

Putting Together Display Profile Objects

Display Profile Object Lookup

Display Profile Properties

Display Profile Merge Semantics

Display Profile and iPlanet Directory Server Access Management Edition

Administering the Display Profile

Overview of Display Profile

This section describes the display profile component of Sun ONE Portal Server.

The display profile creates the display configuration for the Desktop by defining the following three items:

Provider definition—Specifies the name and the Java™ class for the provider. A provider is the programmatic entity responsible for the generation of content, which is displayed in the channel. See "Provider Types" for more information.

Channel definition—Specifies an instance of the provider class. A channel is a unit of content, usually (but not necessarily) arranged in rows and columns. You can also have channels of channels, that is, container channels.

Provider and channel property definitions—Specify the values for provider and channel properties. Properties defined in a provider usually specify default values for the channels that are derived from the provider. The display configurations for the channels include properties such as the title, description, channel width, and so on. The properties defined in the channel usually specify the specific value for that channel that is different from the default value.

Container properties define the display definition about how to display the contained channels in the container, including: the layout of the container (thin-wide, wide-thin, or thin-wide-thin); a list of the contained channels; the position of the channel (the row and column number); and the window state of the contained channels (minimized or detached).

Note
The display profile does not actually define the overall layout or organization of what users see on their Desktops. The display profile exists only to provide property values for channels. However, the display profile does indirectly control some aspects of channel presentation, such as column layout for a table container or how the table container draws channels in a table.

The display profile determines the layout in that channel properties determine layout. For example, the display profile for the sample portal's table provider definition contains the following statement:

<Integer name="layout" value="1"/>

This refers to thin-thick columns. However, there is nothing here in the structure of the display profile regarding actual layout.

The display profile does not control such things as how XMLProvider parses XML, it only has a definition of the kind of rules (XSL file) that are in it.

The Desktop implements a display profile data storage mechanism on top of the iPlanet™ Directory Server Access Management Edition service for storing content provider and channel data. In addition, properties are set for the channels and providers.

The user's display profile is a series of XML documents describing container management and properties for channels. (One display profile document is equivalent to one XML document.) The display profile documents are stored in their entirety as a single attribute in the iPlanet Directory Server Access Management Edition services layer. That is, the display profile documents are an LDAP attribute residing in an instance of Sun™ ONE Directory Server.

To change display profile property values, the providers use the provider APIs (PAPI) to get and set the values. When the channel values are set to the display profile, the PAPI internal implementation uses the iPlanet Directory Server Access Management Edition SDK to set the display profile document in the iPlanet Directory Server Access Management Edition Desktop service attribute.

Caution

Though possible, you should not edit the display profile using the iPlanet Directory Server Access Management Edition SDK.

Display Profile and the Admin Console

You can edit the display profile and other Desktop service data through the iPlanet Directory Server Access Management Edition admin console and the dpadmin command. When you edit the display profile, you add, modify, and remove providers, containers, and channels, and edit properties. The Upload XML and Download XML links allow you to upload and download the display profile document. In addition, the iPlanet Directory Server Access Management Edition admin console provides an Channel and Container Management link in the Desktop attributes page to add channels and containers and edit existing properties. The Channel and Container Management link enables you to define properties when a new channel or container is created. You can also use the Channel and Container Management link to add, modify, and remove channels and containers. See "Administering the Display Profile" for more information.

Note
As the Channel and Container Management link enables access to only a portion of the display profile, it is envisioned that delegated administrators will use it. See Chapter 3 "Configuring Delegated Administration," for more information on how to configure delegated administrators.

Display Profile Document Structure

This section describes the overall structure of the display profile documents. The underlying data format for a display profile document is XML. See Appendix B "XML Reference" for information on the display profile DTD syntax.

The display profile format establishes the Desktop's display configuration by defining provider and channel objects and their properties. The display profile is stored in the Sun ONE Directory Server at the isp level (or the top most directory node), the organization level, the role level, or the user level. At run time, a user's display profile is a result of "merging" all the display profile documents from the the user's specific profile in the directory tree, and the value of a specific display profile object for that user is decided by the "merge" semantics of the display profile.

The display profile objects map directly to the XML tag that defines them. For example, the <Channel name> </Channel> XML tags define a channel object.

In general, the document structure of the display profile resembles the following:

<DisplayProfile>

  <Properties>...global properties...</Properties>

  <Channels>...channel definitions...</Channels>

  <Providers>...provider definitions...</Providers>

</DisplayProfile>

<Properties>, <Channels>, and <Providers> are mechanisms to do grouping. These mechanisms make the XML display profile document more structured, so that like objects are in each "bag." See "Putting Together Display Profile Objects" for more information on "bags."

The following sections describe the display profile objects in more detail.

DisplayProfile root Object

The DisplayProfile root container object enables the Desktop servlet to act as a container provider to get handles to providers, and so forth. There is no actual provider class associated with the channel. This channel should not be referenced by any other display profile object.

DisplayProfile root Object XML Syntax

   <Container name="_desktopRoot" provider="none">

   <Properties />

   <Available />

   <Selected />

   <Channels/>

   </Container>

Provider Object

A provider is the software entity executed at run time when a channel is rendered. (Thus, a channel is the instance of a provider at run time.) A provider object is a pointer to the display profile provider definition. The provider is a contract between the ProviderContext class and channel instance (provider object).

The <Provider name> definition contains the information necessary for a client of the display profile to construct the provider object, namely, the Java™ class name.

The <Provider name> definition sets default property values for all channels that point to this provider. Channel-specific properties are only necessary when the provider defaults need to be overwritten. The provider display profile object should contain default values for all properties that are used in the provider Java object. For example, if the provider Java code contains:

getStringProperty("color")

the provider display profile object should have a default value for color.

Provider Types

Sun ONE Portal Server distinguishes between building-block providers and content providers. Building-block providers can generate more than one channel in the Desktop, thus the relationship between the provider and the channel is one to many. Content providers can have only a one-to-one relationship between provider and channel. These kind of providers are not building block providers.

Building-block providers include leaf building-block providers (XMLProvider, URLScraperProvider, and JSPProvider), and container building-block providers (JSPTableContainerProvider, JSPTabContainerProvider, and JSPSingleContainerProvider). Leaf building-block providers generate their own content. Container building-block providers enable you to aggregate channels inside the Desktop. The container building-block providers are building blocks in a sense since you can also customize them or use them differently by changing the container properties.

Note
Content providers are the providers that Sun ONE Portal Server supplies in the sample portals. This includes BookmarkProvider, UserInfoProvider, SimpleWebServiceProvider, and so on.

Using building block providers, you can:

Build more specific, custom functionality by extending the provider Java class

Create more than one channel based on the same provider, with each channel behaving and looking differently by modifying channel properties

Example Provider Object XML Syntax

<Provider name="XMLProvider" class="com.sun.portal.providers.xml.XMLProvider">

    <Properties>
      <String name="title" value="*** XML Provider ***"/>
      <String name="description" value="*** DESCRIPTION ***"/>
      <String name="width" value="thick"/>
      <String name="refreshTime" value="0" advanced="true"/>
      <Boolean name="isEditable" value="false" advanced="true"/>
      <String name="helpURL" value="desktop/xmlchann.htm" advanced="true"/>
      <String name="fontFace1" value="Sans-serif"/>
      <String name="productName" value="Sun ONE Portal Server"/>
      <String name="url" value="file:///etc/opt/SUNWps/desktop/default/xml/getQuotes.xml"/>
      <String name="xslFileName" value="html_stockquote.xsl"/>
      <Integer name="timeout" value="100"/>
      <String name="inputEncoding" value="iso-8859-1"/>
      <String name="urlScraperRulesetID" value="default_ruleset"/>
      <Boolean name="cookiesToForwardAll" value="true"/>
      <Collection name="cookiesToForwardList">
      </Collection>
    </Properties>
</Provider>

Channel Object

A channel object represents a single display element. The objects contained by a channel object can be thought of as properties for the channel. The <Channel name> definition includes a symbolic reference to the provider. In addition, you can define channel-specific properties to overwrite default values defined in the provider definition. A channel name needs to be unique within a display profile document.

Example Channel Object XML Syntax

<Channel name="SampleXML" provider="XMLProvider">

    <Properties >
        <String name="refreshTime" value="600" advanced="true"/>
        <String name="title" value="XML Test Channel"/>
        <String name="description" value="This is a test of the XML Provider system"/>
        <String name="url" value="file:///etc/opt/SUNWps/desktop/default/SampleXML/getQuotes.xml"/>
        <String name="xslFileName" value="/etc/opt/SUNWps/desktop/default/SampleXML/html_stockquote.xsl"/>
    </Properties>

</Channel>

Container Object

A container object is identical to a channel object, except that it primarily generates its content by aggregating the content of other (its child) channels. That is, a container is a channel that gets its content from other channels. A container object allows for available and selected channel lists and can contain leaf channel definitions. A leaf channel is typically aggregated on a page with other channels and generates its own content. A container channel primarily generates content by aggregating the content of one or more leaf channels.

Note
A leaf channel defined within a container is local to that container. Other containers cannot access this leaf channel.

Example Container Object XML Syntax

<Container name="TemplateTableContainer"provider="TemplateTableContainerProvider">
  <Properties>
      <String name="title" value="Template Based Table Container"/>
      <String name="description"
       value="This is the channel for the front provider"/>
      <Collection name="channelsColumn" advanced="true">
       <String name="SampleJSP" value="2"/>
       <String name="SampleXML" value="2"/>
       <String name="Notes" value="2"/>
      </Collection>
      <Collection name="channelsRow" advanced="true">
       <String name="MailCheck" value="3"/>
       <String name="SampleRSS" value="2"/>
       <String name="SampleXML" value="2"/>
       <String name="App" value="5"/>
       <String name="SampleSimpleWebService" value="6"/>
       <String name="Bookmark" value="4"/>
       <String name="Notes" value="3"/>
      </Collection>
      <Collection name="channelsIsRemovable">
       <Boolean name="UserInfo" value="false"/>
      </Collection>
  </Properties>

  <Available>
      <Reference value="UserInfo"/>
      <Reference value="MailCheck"/>
      <Reference value="SampleRSS"/>
      <Reference value="SampleJSP"/>
      <Reference value="SampleXML"/>
      <Reference value="App"/>
      <Reference value="SampleSimpleWebService"/>
      <Reference value="Bookmark"/>
      <Reference value="Notes"/>
  </Available>

  <Selected>
      <Reference value="UserInfo"/>
      <Reference value="MailCheck"/>
      <Reference value="SampleRSS"/>
      <Reference value="SampleJSP"/>
      <Reference value="SampleXML"/>
      <Reference value="App"/>
      <Reference value="SampleSimpleWebService"/>
      <Reference value="Bookmark"/>
      <Reference value="Notes"/>
  </Selected>

  <Channels>
  </Channels>

</Container>

Putting Together Display Profile Objects

The root, provider, and channel objects can have properties associated with them. The display profile groups properties inside of a properties "bag." The term bag is used to indicate that its only purpose is a holding place for properties. A property does not have a properties bag associated with it. See Sun ONE Portal Server 6.0 Desktop Customization Guide for property definitions.

Property bags in channels, providers, and the root level have different semantics. Global properties are shared for all channels. A property defined as a global property here can be accessed by any channel. Themes are an example of a global property. Theme data isb defined globally so they can be shared among all channels.

Properties defined in providers are defaults for channels based on that provider. If the property is not defined in the channel, then the default is used. The implication is that a provider must define every property used by a provider Java object. Thus, if the Java code contains:

String f = getStringProperty("color");

the corresponding <Provider name> definition in the display profile must define:

<String name="color" ... />

Note
Do not use global properties as defaults for all channels. A display profile provider definition defines the property interface used by the provider object that will use the provider definition.

Channel properties override the defaults in the provider definition to customize the channel. For example, URLScaperProvider defines a url property. A default does not make sense here, as a channel would naturally override this value.

Display Profile Object Lookup

At runtime, the system never asks for properties directly from a provider. The request always goes to a channel. If a Java provider object requests a property, it searches the display profile in the following order until it finds the property, or until it reaches the top of the containment hierarchy:

Channel's properties

Channel's provider's properties

Channel's parent's properties

Channel's parent's provider's properties

Channel's parent's parent's properties (and so on)

The global properties bag defined in the display profile root definition

Therefore, when a channel asks for the names of its properties, it gets the set of the union of all the above.

Properties that exist in a provider object are intended to have the semantics of default values for the channel. For example, for a provider xml that defines property title, all channels that are derived from provider xml inherit the title property. If the channel wants to override this property, it can set the value within its own properties.

Display Profile Properties

This section describes display profile properties and how to specify them.

Display Profile Property Types

The display profile property types are:

Boolean—An atomic object representing a Boolean value. Example:

<Boolean name="isEditable" value="false"/>

Collection—An object representing either a list or hash table. A collection is a type of property, or named bag, in which to put other properties. Example:

<Collection name="channelsRow">

    <String name="MailCheck" value="4"/>

    <String name="App" value="5"/>

</Collection>

Integer—An atomic object representing an integer value. Example:

<Integer name="numberOfHeadlines" value="7"/>

String—An atomic object representing a string value. Example:

<String name="title" value="Table Container Channel 1"/>

Reference—An object representing a pointer to a channel definition (that is, to a channel name in a container's selected and available channel lists.) Reference is an unnamed string useful for design tools to be able to distinguish such things from strings. Example:

<Reference value="UserInfo"/>

Document Type Definition Element Attributes

The Desktop DTD defines element attributes that allow you to control usage of display profile and its properties. Table 5-1 lists document type definition element attributes. This three column table lists the attributes in the first column, a brief description in the second column, and an example in the third.

.

Table 5-1    Display Profile Attributes

Attribute

Definition

Example

advanced

"Hides" the display profile property from users in the iPlanet Directory Server Access Management Edition admin console Channel and Container Management link when set to true. However, the property is not hidden when using the Edit XML or Download XML links.

The advanced attribute is a Boolean attribute that can take a value of true or false. The default value is false.

<String name="refreshTime" value="0" advanced="true"/>

lock

Enables high-priority documents to prevent a lower-priority document from using merge semantics to change particular aspects of the display profile. When a display profile object is locked, it cannot be affected by merge semantics in lower priority documents.

The lock attribute is a Boolean attribute that can take a value of true or false. The default value is false.

<Selected merge="fuse">

...

<Reference value="EmployeeNews" lock="true"/>

...

</Selected>

merge

Controls how properties are combined as display profile documents from different LDAP nodes (base DN, DN, and role DNs) are merged to form a single representation (that is, Desktop).

Allowable values are replace, remove, and fuse. The default value is fuse.

See"Display Profile Merge Types"" for replace, remove, and fuse examples.

priority

Sets the priority of the display profile document. A lower number represents a lower priority. For example, a 1 is a lower priority than a 2.

Allowable values are integers and the keyword user, which indicates that the current display profile is the user level display profile.

<DisplayProfile version="1.0" priority="10">

propagate

Controls how properties are treated when they are read non-locally but set locally. You can mark all display profile properties, including Boolean, Collection, Integer, Strings, and Reference, with the propagate attribute.

The propagate attribute is a Boolean attribute that can take a value of true or false. The default value is true.

<String name="color" value="blue" propagate="false"/>

Specifying Display Profile Properties

When you specify display profile properties, you need to consider how to "nest" them, how to use unnamed properties in collections, and how properties can be propagated.

Property Nesting

The display profile can contain nested properties (properties within properties) to any depth. This enables you to have collections of collections of collections of strings, or a collection of strings and collections, and so on. For example, here is a collection of collections:

<Collection name="people">
    <Collection name="john">
        <Integer name="age" value="31"/>
        <String name="eyes" value="hazel"/>
    </Collection>
    <Collection name="bob">
        <Integer name="age" value="35"/>
        <String name="eyes" value="blue"/>
    </Collection>
    ... etc ...
</Collection>

Unnamed Properties

Atomic property types (Boolean, Integer, and String) can be unnamed, for example:

<String value="apple"/>

is equivalent to

<String name="apple" value="apple"/>

That is, if an atomic property does not have a name then it is equivalent to the string value of that property.

For all practical purposes, this is useful only inside a collection, because it enables you to use collections to represent an ordered set (almost a list), instead of a table. For example, here is a collection representing a list of zip codes:

<Collection name="zipcodes">
    <Integer value="95112"/>
    <Integer value="95054"/>
    <Integer value="98036"/>
</Collection>

The key to using unnamed properties is that collections can represent tables (name=value) or lists.

Note
Do not create an unnamed property with the same value as another unnamed property in the same collection. The property will be created, but the provider will not be able to access the value because of the duplicate name.

In addition, because the Sun ONE Portal Server treats a property that has the same name and value as equivalent to an unnamed Boolean property you may unintentionally create properties with duplicated names in the same collection. This again can result in all but one being inaccessible.

Display Profile Property Propagation

You can mark all display profile properties, including Boolean, Collection, Integer, Strings, and Reference, with the propagate attribute. The propagate attribute is a Boolean attribute that can take a value of true or false (the default is true). The propagate attribute controls how properties are treated when they are read non-locally but set locally.

For example, the set of properties for a channel consists of the set that is the union of:

The set of properties existing locally in the channel's properties (<Properties>) bag

The set of properties existing locally in each descendent channel of the channel (channel's parent, channel's parent's parent, and so on)

The set of properties existing locally in the channel's provider (specified by the provider attribute on the channel)

The set of global properties existing under the display profile root object

When a channel requests a property value, it can be read from any of these "remote" locations. When a property value is set, there are two options where to store the property value:

The channel's property bag

The remote location

The propagate attribute controls the location. When you set the propagate attribute to true, a property is stored locally to the object that set the property (in most cases, a channel). When you set the propagate attribute to false, the property is set in place (wherever it was read from). That is, when set to false, the existing value is changed, but when true, a new property is created and stored locally (unless it was already local).

Consider the following display profile XML fragment:

<DisplayProfile>
  <Properties>
    <String name="color" value="blue"/>
  </Properties>
...
<Channel name="testchannel" provider="..."/>
  <Properties/>
</Channel>
...
</DisplayProfile>

The property color lives in the global properties bag. Because propagate is not set (and is true by default), the following results if channel testchannel sets property color:

<DisplayProfile>
  <Properties>
    <String name="color" value="blue"/>
  </Properties>
...
<Channel name="testchannel" provider="..."/>
  <Properties/>
    <String name="color" value="new value"/>
</Channel>
...
</DisplayProfile>

The property is propagated to the local object that set it (the channel). On the other hand, if propagate were set to false in the global properties bag, for example:

<String name="color" value="blue" propagate="false"/>

The result of channel testchannel setting property color would be:

<DisplayProfile>
  <Properties>
    <String name="color" value="new value"/>
  </Properties>
...
<Channel name="testchannel" provider="..."/>
  <Properties/>
</Channel>
...
</DisplayProfile>

In addition to individual properties, a properties bag can also be marked with the propagate attribute, for example:

<Properties propagate="false">
...
</Properties>

For a property to be considered as propagate=false, the following must be true:

The property's propagate attribute must be false, or the property's properties bag's propagate attribute must be set to false.

The above statement must be true for all mergers of the property.

For anything else, propagate is considered to be true.

You can only mark top-level properties with the propagate attribute. The display profile DTD does not disallow this but the display profile code ignores it.

Display Profile Merge Semantics

The display profile is composed of a hierarchy of XML documents. Sun ONE Portal Server could store a display profile document for the user, each role the user belongs to, and the user's organization or suborganization. At runtime, the system merges these multiple display profile documents to deliver a particular desktop to the user. This process of merging display profile documents affects the final display profile by potentially changing channel, provider, and property definitions.

The display profile data format contains syntax that defines how these documents are combined. This definition is commonly known as merge semantics.

Merge semantics control how attributes are combined as display profile documents from different LDAP nodes (base DN, DN, and role DNs) are merged to form a single representation (that is, Desktop). Merge semantics assume an ordering to display profile documents. iPlanet Directory Server Access Management Edition does not provide hierarchical structure of roles. Instead, the users' role structure is flat. All roles are peers. Because of this, Sun ONE Portal Server imposes an additional ordering on iPlanet Directory Server Access Management Edition roles to simulate a hierarchical structure.

The set of display profile documents for a user consists of: the documents that exist at the user's LDAP organization an suborganization nodes; the documents that exist at each of the user's role nodes; and the document that exists at the user's entry node. Documents do not need to be defined at each of these nodes, but there must be at least one document defined at a node. The set of documents is sorted according to a priority value that the display profile document defines. See "Display Profile Document Priorities" for more information.

You can visualize the process of document merging as laying one display profile document on top of another. A merge happens where like named channels, providers, and properties fall on top of one another. Merging is based on the name of the display profile object, not the XML structure defined in the display profile document. Like named channels can exist in different containers within the containment hierarchy in the display profile to be merged.

Note
Channel definitions in one container cannot be seen by another container. If a channel definition is inside one container, then only that container can contain that channel. To have more than one container reference the same channel, put the channel definition in the global area, or in the parent container, so that the contained container can make a reference to it.

How the Merge Process Works

When a user logs on to Sun ONE Portal Server, and after authentication takes place, the system determines the user's display profile by:

Locating all the display profile documents for that user by searching through the global display profile, and LDAP organization, suborganization, role, and user nodes that the user belongs to.

Placing the retrieved display profile documents in a temporary area, which you can visualize as a bag.

Sorting the display profile documents in the bag based on priority, starting at the lowest priority. (The node at which the document was retrieved does not influence the priority sorting. Also, the user display profile document always has the highest priority.)

Taking the documents out of the bag, lowest priority first, then placing the next higher level priority document over this document, and applying merge and lock semantics.

Continuing Step 4 until all the documents have been taken out of the bag so that the system returns a value to the user that is a merge of the objects found in the documents.

Display Profile Merge Types

The display profile uses the following three types of merges to determine how to combine display profile documents:

replace—All the display profile objects defined in the lower priority document completely override the ones defined at the higher one. If the object does not exist in the higher priority document, it is added to the merge result.

remove—The named object is removed from the merge up to this point. It no longer exists in the display profile. It can be redefined by a higher priority document.

fuse—The object from the lower priority document is combined with one from the higher priority document.

Note
The exact meaning of each merge type depends on the display profile object they are applied to.

For channels and providers, fuse has special meaning. The channels themselves are not actually fused together. Rather, fuse indicates that the channel's or provider's properties should be combined. The replace semantic replaces the entire channel or provider, including all properties. The remove semantic removes the entire channel or provider from the merge up to that point.

The display profile <DisplayProfile> root node can also have merge semantics. The replace semantic means that all the DP objects defined in the lower priority document completely override the ones defined at the higher one. All merges up to that point are negated and the lower priority document is used as the new base for merging. The remove semantic indicates that all merge results up to the point of this document are to be discarded. The merge begins with the next display profile document found in the sorted set. As with channels and providers, the fuse semantic means that the contained objects (channels and providers) should be combined.

Atomic display profile properties (those that cannot contain other properties) cannot use the fuse semantic. This includes the String, Integer, Boolean, and Reference properties.

The set of properties for a channel consists of the channel's properties plus the channel's provider's properties plus the channel's parent's properties, and so on. You can think of this total set of properties as the channel's single document properties. An implication of document merging is that the total set of properties for a document consists of the set union of the channel's single document properties for all documents in the user's merge set.

Remove Example: Using remove Merge to Modify Container's Selected Channel List

The following example shows how all users' merge set can consist of an organizational level document that has the following display profile fragment.

<Container name="TemplateTableContainer" provider="TemplateTableContainerProvider" merge="fuse">
    <Properties> ... </Properties>

    <Available> ... </Available>
    <Selected merge="fuse">
        <Reference value="UnixTipoftheDay"/>
    </Selected>
</Container>

The "unix tip of the day" describes ways to use UNIX. It is likely that users that belong to the admin role would not find this channel helpful. To remove this channel from everyone with the admin role, define the TemplateTableContainer channel in the admin role document as follows:

admin role
<Container name="TemplateTableContainer" provider="TemplateTableContainerProvider" merge="fuse">
    <Properties> ... </Properties>

    <Available> ... </Available>
    <Selected merge="fuse">
        <Reference value="Outages"/>
        <Reference value="SolarisAdmin"/>
        <Reference value="AdminTipoftheDay"/>
        <Reference value="UnixTipoftheDay" merge="remove"/>
    </Selected>
</Container>

The preceding sample snippet causes the Reference value="UnixTipoftheDay" to be removed from the admin role display profile.

Replace Example: Using replace Merge to Remove Channel from All Users' Display

The following example shows how for a particular container, a role admin can ignore all of the channels defined in the organization level. The organization definition resembles the following:

organization display profile
<Container name=...>
    ...
    ...
    <Selected>
        <Reference name="X"/>
        <Reference name="Y"/>
        <Reference name="Z"/>
    </Selected>
</Container>

Because the role admin does not want any of the users under that role to have the X, Y, or Z channels, the container is defined as follows:

admin role
<Container name=...>
    ...
    ...
    <Selected merge="replace">
        <Reference name="A"/>
        <Reference name="B"/>
        <Reference name="C"/>
    </Selected>
</Container>

The selected list in the role document's container replaces the selected list in the organization document's container.

Fuse Example: Using fuse Merge to Create Role-based Channel List

You commonly use the fuse merge semantic to combine non-atomic display profile objects. These objects include Collection and the available or selected channel lists. Here, fuse indicates that all the properties contained in the non-atomic property should also be merged. Using fuse in this way enables the final non-atomic property presented to the user to be build up from various documents.

The following example display profile documents are for a user who belongs to the admin, employee, and movieFreak roles. The selected channels for the user appear at the end.

admin role
<Container name="TemplateTableContainer" provider="TemplateTableContainerProvider" merge="fuse">
    <Properties> ... </Properties>

    <Available> ... </Available>
    <Selected merge="fuse">
        <Reference value="Outages"/>
        <Reference value="SolarisAdmin"/>
        <Reference value="AdminTipoftheDay"/>
    </Selected>
</Container>

employee role
<Container name="TemplateTableContainer" provider="TemplateTableContainerProvider" merge="fuse">
    <Properties> ... </Properties>

    <Available> ... </Available>
    <Selected merge="fuse">
        <Reference value="Benefits"/>
        <Reference value="EmployeeNews"/>
    </Selected>
</Container>

movieFreak role
<Container name="TemplateTableContainer" provider="TemplateTableContainerProvider" merge="fuse">
    <Properties> ... </Properties>

    <Available> ... </Available>
    <Selected merge="fuse">
        <Reference value="NewMoviesReleases"/>
        <Reference value="MovieShowTimes"/>
    </Selected>
</Container>

The resultant list of selected channels for the user is as follows, with the available channel list ordered in the same way that the merging was applied, from higher to lower priority:

<Container name="TemplateTableContainer" provider="TemplateTableContainerProvider" merge="fuse">
    <Properties> ... </Properties>

    <Available> ... </Available>
    <Selected merge="fuse">
        <Reference value="Outages"/>
        <Reference value="SolarisAdmin"/>
        <Reference value="AdminTipoftheDay"/>
        <Reference value="Benefits"/>
        <Reference value="EmployeeNews"/>
        <Reference value="NewMoviesReleases"/>
        <Reference value="MovieShowTimes"/>
    </Selected>
</Container>

Merge Locking

Any display profile object that is able to be merged can also be locked. When an object is locked, it cannot be affected by merge semantics in lower priority documents. This enables high-priority documents to prevent a lower-priority document from using merge semantics to change particular aspects of the display profile.

Merge Locking Example: Using lock Merge to Force Property Value for All Users

The following example shows how to ensure that for a particular organization, all users see the "employee news" channel. The users cannot remove this channel from their display. At the organization level document, the container channel's selected list is defined as follows:

<Selected merge="fuse">
    ...
    <Reference value="EmployeeNews" lock="true"/>
    ...
</Selected>

Merge Locking Example: Using lock Merge to Force-remove Channel from All Users' Display

The following example shows how to force the "online games" channel to be removed. In this scenario, users have added this channel to the selected channels list in their user document, so simply removing it from the organization level document's selected channel's list will not work. Instead, the employee and organization lists will be merged together resulting in the "online games" channel being present. To forcibly remove the channel from all users under the organization, the selected channels list is defined as follows:

<Selected merge="fuse">
    ...
    <Reference value="OnlineGames" merge="remove" lock="true"/>
    ...
</Selected>

The remove semantic removes the channel from merged result, and lock prevents lower priority documents from merging the value back in.

Display Profile Document Priorities

At runtime, when a user logs in, the system determines the set of documents that makes up the user's display profile document set. The Desktop internal implementation of the display profile (the part that interprets the display profile) determines this set by looking at all of the LDAP nodes that the user belongs to. This can be the organization DN (o=sesta.com), suborganizations, role DNs (cn=Role1,o=sesta.com), and uid (uid=jtb,ou=People,cn=Role1,0=sesta.com), as well as the global display profile. The display profile documents from each of these LDAP nodes and global display profile are then read (if it exists there), and all of the documents are put into a set. The system sorts the set according to the document priorities. A lower number represents a lower priority. For example, a 1 is a lower priority than a 2. The documents are then sorted from lower number to higher number. See "How the Merge Process Works" for more information on this process.

The user level document (uid=jtb,ou=People,...) is a special case referred to as the base document. Think of the base document as a priority equal to infinity. Thus, it is always the highest number (and hence highest priority). All of the mergers are associated with the base document in sorted order, and the priority setting on a user document is always the highest. The priority attribute used in the <DisplayProfile> tag takes the special keyword user to indicate that the current display profile is the user level display profile.

When a merge occurs, it starts at the lowest priority document (lowest number) and proceeds in increasing priority number, until it arrives at the user (base) document.

Thus, the implication of display profile document priorities is that what really matters is the priority number. For example, an organization level document can have a higher priority than a role level document, but it does not have to. It depends on how you need to prioritize these documents for your site.

You specify the display profile document priority in the XML file with the <DisplayProfile priority= syntax> tag. You can change the priority by directly editing the display profile XML by using the iPlanet Directory Server Access Management Edition admin console or by using the dpadmin command to load the display profile. See Chapter 12 "Command-Line Utilities" for more information on the dpadmin command.

Note
Do not assign the same priority to two display profile documents. Doing so causes the Desktop to not appear properly. However, the product does not check for duplicate document priorities.

Document Priority Example 1

This example uses two display profiles, one for the organization acme and one for the uid bill. When Bill logs in (uid=bill) to the Desktop, the bookmark channel titled "Bill's Bookmarks" is displayed with the following three bookmarks (in that order):

ACME

Amazon

EBay

<DisplayProfile version="1.0" priority="10">

...

  <Channel name="Bookmark" provider="BookmarkProvider" merge="fuse">

    <Properties>

<DisplayProfile version="1.0" priority="1">

Document Priority Example 2

This example uses three display profiles, the global display profile, the display profile for the organization acme, and the display profile for the role hradmin. When the user who is assigned to the hradmin role logs in to the Desktop, the TemplateTableContainer appears with the following channels:

UserInfo

MailCheck

SampleSimpleWebService

<DisplayProfile version="1.0" priority="0">

...

  <Container name="TemplateTableContainer" provider="TemplateTableContainerProvider" merge="fuse">

    <Properties>

<DisplayProfile version="1.0" priority="10">

...

  <Container name="TemplateTableContainer" provider="TemplateTableContainerProvider" merge="fuse">

    <Properties>

<DisplayProfile version="1.0" priority="5">

...

  <Container name="TemplateTableContainer" provider="TemplateTableContainerProvider" merge="fuse">

    <Properties>

Display Profile Document Priority Summary

A display profile document has a low or high priority depending on whether you consider the merge order or the ability to lock as the defining factor.

Without considering locking, the lower numbered display profile document has a lower priority. The lower numbered display profile document gets merged first so any higher numbered document overrides its entries. In this sense, the lower numbered document has a lower priority.

However, the lower numbered display profile document can also lock an object so it cannot be affected by a higher numbered document. In this sense, the lower numbered document has a higher priority.

Display Profile and iPlanet Directory Server Access Management Edition

The set of display profile documents for a user can consist of:

The document that exists at the user's LDAP organization (or suborganization) node

The documents that exist at each of the user's role nodes

The document that exists at the user's entry node

The document that exists at the global display profile

Documents do not need to be defined at each of these nodes, but there must be at least one document defined at a node. The set of documents is sorted according to a priority value that the display profile document defines. See "Display Profile Document Priorities" for more information. Merge semantics control how attributes are combined as display profile documents from different nodes are merged to form a single representation or Desktop. See "Display Profile Merge Semantics" for more information.

Administrators can edit the display profile using the iPlanet Directory Server Access Management Edition admin console. You can set up delegated administrators so that they do not see the display profile in the iPlanet Directory Server Access Management Edition admin console. You do this when you create the Desktop service template. When you create the template for the Desktop service, if you unselect the "Show Desktop Service Attributes" box, you can hide the display profile text from a delegated administrator.

Tip
The organization administrator can define a container (or container hierarchy) associated with certain roles through the Desktop service. Then, the delegated administrator (role administrator) can define the necessary channels and containers under this container through the Channel and Container Management link in the Desktop attributes page. See "Using the Channel and Container Management Link to Administer Channels" for more information.

Administering the Display Profile

You edit the display profile (and other Desktop service data) through the iPlanet Directory Server Access Management Edition admin console and dpadmin command. When you edit the display profile, you add, modify, and remove providers, containers, and channels from the display profile, and edit properties.

In addition, the iPlanet Directory Server Access Management Edition admin console provides the Channel and Container Management link in the Desktop attributes page to add channels and edit properties. This link also enables you to modify properties when a new channel is created.

Note
The Channel and Container Management link is suited for delegated administration and allows the administrator to add and modify attributes of containers and channels. The overall system administrator should be responsible for adding the container and providers available to the delegated administrator.

Table 5-2 explains the different types of display profiles and how to use the iPlanet Directory Server Access Management Edition admin console to administer them. This three column table lists the types of display profiles in the first column, how to access that display profile using the iPlanet Directory Server Access Management Edition admin console, and a brief description in the third column.

Table 5-2    Types of Display Profile Documents

Type of Display Profile Document

How to View Using the iPlanet Directory Server Access Management Edition Admin Console

Description

Global Display Profile Document

Choose View Service Management. Click the properties arrow next to Desktop. In the Desktop Global attributes section, click Edit XML.

Defines display profile elements that are inherited by all users on the system, regardless of the organization or role to which they belong. (Although currently not enforced, you might also want to use the display profile XML document to define the common providers that will be used by everyone.)

Dynamic Display Profile Document

Choose View Service Management. Click the properties arrow next to Desktop. In the Desktop Dynamic attributes section, click Edit XML.

Describes container management and properties for channels. This display profile is not `used' to generate a user's Desktop at runtime, but becomes the default for each newly created organization and role. By default, the dynamic display profile document is blank. To use the dynamic display profile, you need to first populate it.

Organization, Suborganization, or Role Display Profile

Choose View User Management. Select the appropriate organization, suborganization, and if necessary, select Roles from the Show menu. Select Services from the Show menu. Click the properties arrow next to Desktop. In the Desktop page, click Edit XML.

Shows the display profile for the selected organization, suborganization, or role. When you create a new organization, suborganization, or role, you create a template for this entity. When you create the template for the Desktop service, the initial display profile is set to the dynamic display profile document as mentioned above. Thus, if the dynamic display profile is blank, nothing is filled in.

Most likely, you use this display profile document to customize container management and channel properties to fit the needs of different organizations and roles.

When you install Sun ONE Portal Server, you create an initial organization. The installer then imports the display profile global level document, and the default display profile, based on what you specify.

After that, each time you create a new organization, suborganization, or role, the display profile is not automatically loaded. You must manually load the display profile for a newly created organization, suborganization, or role. See "To Load the Display Profile (Admin Console)" for more information.

The high-level steps to administer the display profile are:

Loading the display profile for any newly created organization, suborganization, or role. (You do not need to perform this step for the organization that is created during the installation process.)

Modifying the display profile using the dpadmin command, the Edit XML link, or as a file that has been saved and then loaded using the Download XML and Upload XML links.

Adding channels and containers, and adding, deleting, and modifying their properties using the Channel and Container Management link.

Default Display Profile Documents

Table 5-3 explains the display profile documents that the Sun ONE Portal Server Desktop supplies for the sample portal in the /opt/SUNWps/samples/desktop directory. This two column table lists the display profile documents in the first column and a brief description in the second column.

Table 5-3    Display Profile Documents Supplied with Sample Portal

Display Profile Document

Description

dp-anon.xml

Used by the authless anonymous user.

dp-org.xml

Sample display profile loaded at the default organization level. It defines all the global properties that are used for the organization and the channel definitions that are used by the organization.

dp-org-final.xml

A copy of dp-org.xml, with NetMail links defined in the Bookmark and Applications channels. This display profile document is used when the NetMail service is created.

dp-providers.xml

Sample display profile loaded at the global display profile level. This document defines all the provider definitions. Because these providers are going to be used by all organizations, the system loads this display profile at the top level, and every organization is able to use them. If a provider definition is used only by one organization, define it in the organization level display profile.

See the Sun ONE Portal Server 6.0 Desktop Customization Guide for information on customizing these sample display profiles.

Loading the Display Profile

When you first install Sun ONE Portal Server, you create an initial organization. The installer also imports the display profile global level document, and the default display profile, based on what you specify. If you decide not to install the sample portals, the sample display profile documents are not installed.

After that, when you create a new organization, suborganization or role, the display profile is not automatically loaded. You must manually load the display profile for a newly created organization, suborganization, or role.

There are three basic methods for loading the display profile:

Using the Edit XML link of the iPlanet Directory Server Access Management Edition admin console. With this method you use the Edit XML link and an existing display profile in an organization, which you copy then paste into the blank display profile of the newly created organization, suborganization, or role. See "To Load the Display Profile (Admin Console)".

Using the command line. With this method you use the dpadmin command to load the display profile. See "To Load the Display Profile (Command Line)". Before using the dpadmin command, see "Guidelines for Using the dpadmin Command".

Using the Download and Upload links of the iPlanet Directory Server Access Management Edition admin console. With this method you download a display profile to a file and then upload a display profile from a file. See "To Download and Upload a Display Profile".

Note
You cannot edit the display profile XML directly through the admin console if your browser is Netscape 4.x.

To Load the Display Profile (Admin Console)

Log in to the iPlanet Directory Server Access Management Edition admin console as administrator.

Navigate to User Management by choosing View User Management.

Select Organizations from the Show menu.

Select the organization or suborganization from which you want to copy the display profile.

Choose Services from the Show menu.

Click the properties arrow next to Desktop in the navigation pane.

The Desktop attributes appear in the data pane.

Tip
You might have to scroll down to see the Desktop service.

Copy the Display Profile.

Click Edit XML then select and copy the entire text of the display profile.

Select the organization, suborganization, or role for which you want to load the display profile.

Navigate to User Management by choosing View User Management, then select the appropriate organization or suborganization. To display a role, choose Roles from the Show menu then select the appropriate role from the list.

Choose Services from the Show menu.

Click the properties arrow next to Desktop in the navigation pane.

A list of Desktop service attributes, including the display profile XML, is displayed in the data pane.

Click Edit XML.

The display profile XML document appears in a text window.

Paste the copied display profile into the display profile window.

When done, click Save.

The changes affect only users in this particular organization.

To Load the Display Profile (Command Line)

Use the add subcommand of the dpadmin command to load a display profile.

For example, the following command loads the display profile (dp-org.xml):

dpadmin add -u "uid=amAdmin,ou=People,o=sesta.com,o=isp" -w password -d
"o=sesta.com,o=isp" dp-org.xml

Note
You can add the -r or --dryrun option to the end of the command before the file name to verify that the command will be successful before actually writing any changes to LDAP.

To Download and Upload a Display Profile

Log in to the iPlanet Directory Server Access Management Edition admin console as administrator.

Navigate to User Management by choosing View User Management.

Select Organizations from the Show menu.

Select the organization or suborganization from which you want to copy the display profile.

Choose Services from the Show menu.

Click the properties arrow next to Desktop in the navigation pane.

The Desktop attributes appear in the data pane.

Tip
You might have to scroll down to see the Desktop service.

Click Download XML in the Global attributes section and save the display profile to a file.

Select the organization, suborganization, or role for which you want to upload the display profile.

Navigate to User Management by choosing View User Management, then select the appropriate organization or suborganization. To display a role, choose Roles from the Show menu then select the appropriate role from the list.

Choose Services from the Show menu.

Click the properties arrow next to Desktop in the navigation pane.

Click Upload XML and specify the file to load.

Click Upload.

A message indicating that the display profile upload was a success appears.

Click Close.

The changes affect only users in this particular organization.

To View the Entire Display Profile

Run the dpadmin command with the list subcommand to view the entire display profile, for example:

dpadmin list -u "uid=amAdmin,ou=People,o=sesta.com,o=isp" -w password -d "o=sesta.com,o=isp"

To Remove a Display Profile

If you need to remove a display profile for some reason, for example if it is corrupted, you can use the dpadmin command with the remove subcommand.

For example, to remove the entire display profile (dp-org.xml) from the root:

dpadmin remove -u "uid=amAdmin,ou=People,o=sesta.com,o=isp" -w password -d "o=sesta.com,o=isp" -t root

If you remove a display profile from the root or from a node at which you require a display profile, you must load a new one. For example, if you removed the dp-org.xml display profile as shown above, you will have to load another similar display profile such as the dp-org-final.xml display profile. See "To Load the Display Profile (Command Line)" for information on loading a display profile.

Using the Channel and Container Management Link to Administer Channels

You use the Channel and Container Management link to administer:

Properties—You can define and add global display profile properties.

Containers—You can add or remove a content container to or from a container. You can also modify a content container's properties.

Channels—You can add or remove a channel to or from a container

You can also modify a channel's properties.

Note
Currently, you can work with channels and containers and their properties using the Channel and Container Management link. This link does not work with providers.

When using the Desktop attributes page, delegated administrators see only the Channel and Container Management link. All other display profile attributes are hidden, and thus made secure.

Note
In a display profile document, the <channels/> tag means that no channels have been specified.

Channel and Container Management Default Providers

The Desktop Channel and Container Management link displays a management screen that allows you add or remove container channels or content channels.

Add Channels

The Add link for the Channels list allows you to select a content provider to add from a list of default content providers. Table 5-4 shows the provider channels that are available to add. This two-column table lists the providers in the first column and a brief description of the provider in the second column.

Table 5-4    Default Provider Channels

Provider

Description

AppProvider

Enables a user to add or remove applications from a list of applications.

BookmarkProvider

Enables a user to add or remove URLs from a list of bookmarks.

JSPProvider

Obtains content from one or more JSP™ files.

LoginProvider

Enables the Login channel to show up in the anonymous user's Desktop so users can log in.

MailCheckProvider

Gives information about a user's mail status.

NotesProvider

Enables anyone the administrator has authorized to post a message to everyone's desktop in the Notes channel.

SearchProvider

Supplies a search function using the Sun ONE Portal Server Search Engine.

SimpleWebServiceConfigurableProvider

Makes simple web services available to an end user channel that is configurable by the end user.

SimpleWebServiceProvider

Makes simple web services available to an end user channel.

URLScraperProvider

Uses the Rewriter to construct the URL information and an XML file to describe how to display it.

UserInfoProvider

Collects information from the display profile and iPlanet Portal Server Access Management Edition. It displays a greeting, the user's name, timezone, locale and has access to the user's IMAP and SMTP data.

XMLProvider

Displays content from an XML file format that is converted into another format for viewing.

Add Container Channels

The Add link for the Container Channels list allows you to select a container provider to add from a list of default container providers. Table 5-5 shows the default container channel providers that are available. This two-column table lists the providers in the first column and a brief description of the provider in the second column.

Table 5-5    Default Provider Container Channels

Provider

Description

JSPFrameCustomTableContainerProvider

A provider used internally by the JSPTabContainer to create a new frame on a user's JSP frameset-based Desktop.

JSPSingleContainerProvider

A container building-block provider and an extension of the JSP container provider, this provider displays a single channel in it.

JSPTabContainerProvider

A container building-block provider and an extension of the JSP Provider, this provider displays a channel that is made up of a number of tabs with titles on them.

JSPTabCustomTableContainerProvider

A provider used internally by the JSPTabContainer to create a new tab on a user's JSP tab-based Desktop.

JSPTableContainerProvider

A container building-block provider and an extension of JSPProvider, this provider displays the content channels in a table.

TemplateEditContainerProvider

A provider used internally by the template-based containers (TemplateTabContainer and TemplateTableContainer) as their edit provider. If a channel's editType is edit_subset, this provider is used to draw the frame for the Edit page.

TemplateTabContainerProvider

A container building-block provider and a template-based tab container, this provider contains support for a number of tabs in it.

TemplateTabCustomTableContainerProvider

A provider used internally by the template-based containers (TemplateTabContainer and TemplateTableContainer) to create a new tab.

TemplateTableContainerProvider

A container building-block provider and a template-based table container, this provider displays the content channels in a table.

About the Notes Channel

The Notes channel (using the notes provider) reads a set of messages from a shared file, formats them then displays those messages on the user's Desktop. Optionally, the Notes channel enables users to post messages to the shared file. These messages are visible to all other users who have selected this channel. The notes data file can also be manually edited (with a text editor) to add or remove messages.

When deploying a Notes channel, consider the following issues:

Because the Notes channel does not perform error checking on the note text, users can inadvertently, or purposefully enter text, such as HTML tags, that can cause all Desktops that use this channel not to display. If this is a concern, edit privileges should be restricted to certain users or disabled completely in favor of manually editing the notes data file.

Because the notes data is on a file system, there are implications for multi-node environments. If the notes data file is not shared between the servers where Sun ONE Portal Server is running, then the Notes channel will not have the same view on the different nodes. If used in multi-node environments, and cross-server sharing of notes data is desired, the shared notes data file can be made accessible through an NFS-mounted file system. Of course, NFS sharing ties the performance of the Desktop to that of the NFS server. In most cases this should not be a problem.

Because the notes data is on a file system, there can be performance implications of its use. Reading the notes data file is an I/O operation. Exclusive access to the notes data file is ensured through file locking. This arrangement might not scale well if the Sun ONE Portal Server configuration results in heavy access to the Notes channel. NFS sharing of the notes data file across multiple nodes can worsen this situation. However, if you configure the Notes channel to have a non-zero refresh time it will access the file system much less frequently, alleviating such performance concerns.

Note
When using the Notes channel, it is envisioned that the channel will be editable only by a group of privileged users, and hence those users will belong to a role. The role display profile document should have the Notes channel isEditable property set to true.

Using Cookies with the URLScraper Channel *

To manage cookies with a URL scraper channel, you use two channel properties. The cookiesToForwardAll property, if set to true, causes all cookies to be forwarded to the target site. Otherwise, the cookiesToForwardList property can be used to forward selected cookies.

This setting is on a channel-by-channel basis. See the Sun ONE Portal Server 6.0 Developer's Guide and Sun ONE Portal Server 6.0 Desktop Customization Guide for more information.

To Add a Channel or Container Channel

Log in to the iPlanet Directory Server Access Management Edition admin console as administrator or delegated administrator.

Navigate to User Management by choosing View User Management.

Select the organization, suborganization, or role to which you want to add a channel.

When you log in as a delegated administrator, you are automatically taken to the organization, suborganization, or role to which you have administrative access.

Choose Services from the Show menu.

Click the properties arrow next to Desktop in the navigation pane.

The Desktop attributes page appears in the data pane.

In the Desktop page, click the Channel and Container Management link.

The Channels page appears, with the container path set at the root.

Click the Container that you want to add the channel or container to.

The top of the page displays the container path where the channel will be added. Defined channels and container, if any, appear in lists.

Click Add to add a container channel or channel.

To add a container channel, click Add under Container Channel. To add a channel, click Add under Channel.

The Add Channel page appears.

Type a channel name and select the type of provider from the menu.

See Table 5-4 for the available providers.

Click Create.

To Modify a Channel or Container Channel Property

Log in to the iPlanet Directory Server Access Management Edition admin console as administrator or delegated administrator.

Navigate to User Management by choosing View User Management.

Select the organization, suborganization, or role in which you want to modify a channel.

When you log in as a delegated administrator, you are automatically taken to the organization, suborganization, or role to which you have administrative access.

Choose Services from the Show menu.

Click the properties arrow next to Desktop in the navigation pane.

The Desktop attributes page appears in the data pane.

In the Desktop page, click the Channel and Container Management link.

The Channels page appears. At the top is the container path. The defined channels appear in a list.

Click the Edit link beside the channel or container channel to be modified.

The Properties page appears.

Modify the properties as needed.

See the Sun ONE Portal Server 6.0 Desktop Customization Guide for more information on channel properties.

When done, click Save.

To Remove a Channel or Container Channel

Log in to the iPlanet Directory Server Access Management Edition admin console as administrator or delegated administrator.

Navigate to User Management by choosing View User Management.

Select the organization, suborganization, or role in which you want to modify a channel.

When you log in as a delegated administrator, you are automatically taken to the organization, suborganization, or role to which you have administrative access.

Choose Services from the Show menu.

Click the properties arrow next to Desktop in the navigation pane.

The Desktop attributes page appears in the data pane.

In the Desktop page, click the Channel and Container Management link.

The Channels page appears. At the top is the container path. The defined channels appear in a list.

Click the checkbox beside the channel or container channel to be removed. Then click Delete.

The channel is deleted and the Channels list is updated to show its removal.

Administering Containers

When administering containers, you can use the iPlanet Directory Server Access Management Edition admin console to directly edit the display profile XML. You can also use the dpadmin command, which for the most part this section describes by using various examples.

These examples include:

To View a Display Profile Object

To Replace a Channel in a Container

To Replace a Property in a Channel

To Add a Channel to a Container

To Add a Property to a Collection

To Add a Collection Property

To Remove a Property from a Channel or Container

To Remove a Provider

To Remove a Channel from a Container

To Change a Display Profile Document Priority

To Make a Channel Available for a Container

To Make a Channel Unavailable for a Container

To Select a Channel from a Container's Available Channel List

To Unselect a Channel from a Containers Available Channel List

See "Using the Display Profile Text Window" for information on editing the display profile through the iPlanet Directory Server Access Management Edition admin console.

Using the dpadmin Command

The syntax of the dpadmin command is:

$ dpadmin list|modify|add|remove [command-specific options] -u uid -w password {-g|-d dn} [-l locale] [-r] [-b] [-h] [file]

See Chapter 12 "Command-Line Utilities," for the complete syntax of the dpadmin command. When running the dpadmin command, note the following:

file argument—If present, the file argument must also be the last argument on the command line. It specifies a path to an XML file that contains an XML fragment that conforms to the display profile DTD. Subcommands that require XML input include modify and add.

When adding or modifying an entire display profile, always include a proper XML header, for example

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE DisplayProfile SYSTEM "jar://resources/psdp.dtd">

list subcommand—Retrieves and displays display profile node objects. Objects are displayed in their native XML format. The object to be displayed is sent to standard out. If you do not use the -n or --name option, the entire display profile document is displayed.

modify subcommand— Changes the value of an existing display profile object. This command assumes that the object already exists in the display profile. The modify subcommand reads data for the new object from either standard input or the file specified as an argument. Data for the new object must be XML and conform to the display profile DTD. Specifically, the object data must be a well-formed XML fragment.

add subcommand—Adds a new object to the display profile. This subcommand assumes that the object to be added does not exist in the display profile. The add subcommand reads data for the new object from either standard input or the file specified as an argument. Data for the new object must be XML and conform to the display profile DTD. Specifically, the object data must be a well-formed XML fragment.

remove subcommand—Removes an existing object from the display profile.

-g option—Specifies the global level display profile document.

-r or --dryrun option—Reports whether the current command will succeed or fail, and does not write any changes into LDAP. This is useful to ensure that a particular dpadmin command is correctly formatted.

-n or --name and -p or --parent options—Require a fully qualified name of the display profile container, channel or provider object, or of the parent of the display profile object.

Guidelines for Using the dpadmin Command

Use the following guidelines when running the dpadmin command to update the display profile:

Make sure no other administrator is currently using the iPlanet Directory Server Access Management Edition admin console or dpadmin command to make display profile modifications. Such a situation could cause changes to be lost, as there is no locking mechanism to prevent dpadmin and the admin console from accessing the display profile at the same time.

The preferred sequence when using dpadmin is to put your modifications into a file as an XML "fragment" then run the dpadmin command with the add subcommand. For example,

/opt/SUNWps/bin/dpadmin add -u "uid=amAdmin,ou=People,o=sesta.com,o=isp" -w password -d "uid=anonymous,ou=people,o=sesta.com,o=isp" newtheme.xml

In this example, newtheme.xml is a file containing the XML "fragment" to be added to the display profile.

If you edit a display profile document directly, first use the dpadmin command with the list subcommand to obtain the latest contents of the display profile, make your edits, then run the dpadmin command with the modify subcommand. For example,

/opt/SUNWps/bin/dpadmin list -u"uid=amAdmin,ou=People,o=sesta.com,o=isp" -w password -d "o=sesta.com,o=isp" > dp-org.xml

(Edit the dp-org.xml file.)

/opt/SUNWps/bin/dpadmin modify -u "uid=amAdmin,ou=People,o=sesta.com,o=isp" -w password -d "o=sesta.com,o=isp" dp-org.xml

Caution

Between the time you run the dpadmin list and dpadmin modify commands, do not change the display profile document in the LDAP server in any way (by using the admin console, dpadmin, or ldapmodify commands). Otherwise, those changes will be overwritten by the latest dpadmin modify.

Modifying the Display Profile

You can modify display profile objects by performing one of the following:

Manually editing an existing display profile document then loading it at the appropriate LDAP node or global level by using the dpadmin modify command.

Running the dpadmin command with the specified changes, in XML text, on standard input. When adding a new object you use the add subcommand. When modifying an existing object, you use the modify subcommand.

Creating a new display profile document from scratch then loading it at the appropriate LDAP node or global level by using the dpadmin modify command.

Understanding Display Profile Error Messages

The system reports errors when you try and save a display profile document containing invalid XML. The error messages appear as a title, a message, and a sub-message. The title of the message box is "Invalid XML document." The message appears as one of the following:

No XML header

Error reported by parser was ...

Error at line nnn and column nnn reported by parser was ...

If you receive an "Invalid XML document" error, you need to correct the error to be able to save the XML document you are working on.

To View a Display Profile Object

Use the list subcommand to view a display profile object.

For example, the following command gets the channel, container, or provider named TemplateTableContainer and prints it to standard output.

dpadmin list -n "TemplateTableContainer" -u "uid=amAdmin,ou=people,o=sesta.com,o=isp" -w password -d "o=sesta.com,o=isp"

Note
You can view the entire display profile document by omitting the -n option.

To Replace a Channel in a Container

Use the modify subcommand to replace a channel in a container with a value specified on standard input.

For example, this command replaces the channel Test in the container TemplateTableContainer with value specified on standard input.

dpadmin modify -p TemplateTableContainer -u "uid=amAdmin,ou=People, o=sesta.com,o=isp" -w password -d "o=sesta.com,o=isp" <<EOF
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE DisplayProfile SYSTEM "jar://resources/psdp.dtd">
<Channel name="Test" provider="testprovider">
    <Properties>
        <String name="title" value="Test Channel"/>
        <String name="description" value="This channel is a test."/>
    </Properties>
</Channel>
EOF

Use the list subcommand to verify that the channel was replaced.

See "To View a Display Profile Object".

To Replace a Property in a Channel

Use the modify subcommand to replace a property in a channel with a value specified on standard input.

For example, the following command acts upon the channel NewChannel to replace the property named in the new.xml with the new object in said file, where new.xml is:

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE DisplayProfile SYSTEM "jar://resources/psdp.dtd">
<String name="welcome" value="Hi, welcome to your desktop!"/>

dpadmin modify -p TemplateTableContainer/NewChannel -u "uid=amAdmin,ou=People,o=sesta.com,o=isp" -w password -d "o=sesta.com,o=isp" new.xml

Use the list subcommand to verify that the property was replaced.

See "To View a Display Profile Object".

To Add a Channel to a Container

Modify your display profile input XML file to include only the new <Channel> definition, for example, create the following file testadd.xml:

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE DisplayProfile SYSTEM "jar://resources/psdp.dtd">
<Channel name="TestChannel" provider="testprovider">
    <Properties>
      <String name="teststring" value="sfds"/>
    </Properties>
</Channel>

Use the add subcommand to add the channel to a container.

For example, the following command adds a new channel defined in testadd.xml to the display profile. In this example, the new channel must be added in the TemplateTableContainer level. If you do not specify a parent object with the -p option, the channel is added at the root level.

dpadmin add -p "TemplateTableContainer" -u "uid=amAdmin,ou=People, o=sesta.com,o=isp" -w password -d "o=sesta.com,o=isp" testadd.xml

Note
When you add a new channel to JSPTabContainer, you actually add a new tab. JSPTabContainer requires TabProperties defined for all its available and selected tabs. Thus, for any new container or channel added to the JSTTabContainer, add the following XML snippet inside the TabProperties Collection in the JSPTabContainer for which the new channel or container is added.

:

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE DisplayProfile SYSTEM "jar://resources/psdp.dtd">
<Collection name="<New Channel Name>">
            <String name="title" value="<New Channel Title>"/>
            <String name="desc" value="<New Channel Description>"/>
            <Boolean name="removable" value="false"/>
            <Boolean name="renamable" value="true"/>
            <Boolean name="predefined" value="true"/>
</Collection>

Use the list subcommand to verify that the channel was added.

See "To View a Display Profile Object".

To Add a Property to a Collection

Use the combine (-m) option to add a new property to a collection.

For example, the following command adds a new property msg2 to the collection bar. The existing property, msg, still remains in the result. The list subcommand is used before and after to show the property values.

dpadmin list -n TemplateTableContainer -u "uid=amAdmin,ou=People, o=sesta.com,o=isp" -w password -d "o=sesta.com,o=isp
...
<Collection name="foo">
    <Collection name="bar">
        <String name="msg" value="hi"/>
    </Collection>
</Collection>
...

dpadmin modify -p TemplateTableContainer -u "uid=amAdmin,ou=People, o=sesta.com,o=isp" -w password -d "o=sesta.com,o=isp" -m <<EOF

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE DisplayProfile SYSTEM "jar://resources/psdp.dtd">
<Collection name="foo">
    <Collection name="bar">
        <String name="msg2" value="woo hoo"/>
    </Collection>
</Collection>
EOF

dpadmin list -n TemplateTableContainer -u "uid=amAdmin,ou=People, o=sesta.com,o=isp" -w password -d "o=sesta.com,o=isp"
...
<Collection name="foo">
    <Collection name="bar">
        <String name="msg" value="hi"/>
        <String name="msg2" value="woo hoo"/>
    </Collection>
</Collection>
...

To Add a Collection Property

Use the add subcommand to add a collection with a value specified on standard input.

For example, the following command adds the collection property zipCodes specified on standard input to the channel, container, or provider named Postal.

dpadmin add -p SamplesTabPanelContainer/Postal -u "uid=amAdmin,ou=People, o=sesta.com,o=isp" -w password -d "o=sesta.com,o=isp" <<EOF
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE DisplayProfile SYSTEM "jar://resources/psdp.dtd">
<Collection name="zipCodes">
    <Integer value="98012"/>
    <Integer value="98036"/>
    <Integer value="94025"/>
    <Integer value="95112"/>
</Collection>
EOF

Use the list subcommand to verify that the collection property was added.

See "To View a Display Profile Object".

To Remove a Property from a Channel or Container

Use the remove subcommand to remove a property from a channel or container.

For example, the following command removes the property locations from the Bookmarks channel (or container) at the global level.

dpadmin remove -t property -p Bookmarks -n locations -u "uid=amAdmin,ou=People, o=sesta.com,o=isp" -w password -g

Use the list subcommand to verify that the property was removed.

See "To View a Display Profile Object".

To Remove a Provider

Use the remove subcommand to remove a provider.

For example, the following command removes the provider NotesProvider.

dpadmin remove -t provider -n "NotesProvider" -u "uid=amAdmin,ou=People, o=sesta.com,o=isp" -w password -d "o=sesta.com,o=isp"

Use the list subcommand to verify that the provider was removed.

See "To View a Display Profile Object".

To Remove a Channel from a Container

Use the remove subcommand to remove a channel from a container.

For example, the following command removes the channel Test that exists in the parent container TemplateTableContainer.

dpadmin remove --type channel --parent TemplateTableContainer --name "Test" --runasdn "uid=amAdmin,ou=People,o=sesta.com,o=isp" --password password --dn "o=sesta.com,o=isp"

Use the list subcommand to verify that the channel was removed.

See "To View a Display Profile Object".

To Change a Display Profile Document Priority

Use the modify subcommand to change the priority of a display profile document.

For example, the following command changes the document priority from the original priority to 10 for the organization.

dpadmin modify -m -u "uid=amAdmin,ou=People,o=sesta.com,o=isp" -w password -d "o=sesta.com,o=isp" <<EOF
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE DisplayProfile SYSTEM "jar://resources/psdp.dtd">
<Properties/>
<Channels/>
<Providers/>
EOF

Use the list subcommand to verify that the priority change was made.

See "To View a Display Profile Object".

To Make a Channel Available for a Container

Use the modify subcommand with the combine (-m) option to add a channel specified on standard input to a container's existing Available list.

For example, the following command adds the BookMark channel to the Available list of the TemplateTableContainer.

dpadmin modify -p TemplateTableContainer -u "uid=amAdmin,ou=People, o=sesta.com,o=isp" -w password -d "o=sesta.com,o=isp" -m <<EOF

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE DisplayProfile SYSTEM "jar://resources/psdp.dtd">
<Available>
    <Reference value="BookMark">
</Available>
EOF

Use the list subcommand to verify that the priority change was made.

See "To View a Display Profile Object".

To Make a Channel Unavailable for a Container

Use the remove subcommand to remove a channel from a container's Available list.

For example, the following command removes the channel Test from the Available list in the parent container TemplateTableContainer.

dpadmin remove --type available --parent TemplateTableContainer --name "Test" --runasdn "uid=amAdmin,ou=People,o=sesta.com,o=isp" --password password --dn "o=sesta.com,o=isp"

Use the list subcommand to verify that the channel was removed.

See "To View a Display Profile Object".

To Select a Channel from a Container's Available Channel List

Use the modify subcommand with the combine (-m) option to add a channel specified on standard input to a container's existing Selected list.

For example, the following command adds the BookMark channel to the Selected list of the TemplateTableContainer.

dpadmin modify -p TemplateTableContainer -u "uid=amAdmin,ou=People, o=sesta.com,o=isp" -w password -d "o=sesta.com,o=isp" -m <<EOF

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE DisplayProfile SYSTEM "jar://resources/psdp.dtd">
<Selected>
    <Reference value="BookMark">
</Selected>
EOF

Use the list subcommand to verify that the priority change was made.

See "To View a Display Profile Object".

To Unselect a Channel from a Containers Available Channel List

Use the remove subcommand to remove a channel from a container's Selected list.

For example, the following command removes the channel Test from the Selected list of the parent container TemplateTableContainer.

dpadmin remove --type selected --parent TemplateTableContainer --name "Test" --runasdn "uid=amAdmin,ou=People,o=sesta.com,o=isp" --password password --dn "o=sesta.com,o=isp"

Use the list subcommand to verify that the channel was removed.

See "To View a Display Profile Object".

Using the Display Profile Text Window

The iPlanet Directory Server Access Management Edition provides a text window for viewing and directly editing the display profile text. As long as you have administrative access to an organization, suborganization, or role, you can use the iPlanet Directory Server Access Management Edition admin console to navigate to this text window and view or edit the display profile.

Note
You cannot edit the display profile XML directly through the admin console if your browser is Netscape 4.x.

To Access the Display Profile Text Window

Log in to the iPlanet Directory Server Access Management Edition admin console as administrator or delegated administrator.

Navigate to User Management by choosing View User Management.

Select the organization, suborganization, or role for which you want to modify the display profile document.

When you log in as a delegated administrator, you are automatically taken to the organization, suborganization, or role to which you have administrative access.

Choose Services from the Show menu.

Click on the properties arrow next to Desktop in the navigation pane.

The Desktop attributes page appears in the data pane.

In the Desktop page, click the Display Profile Edit XML link.

The display profile appears in a text window.

Note
By default, the display profile priority level is set to the keyword user,indicating that the current display profile is the user level display profile. Other allowable values are integers with lower numbers representing lower priorities. For example, a 1 is a lower priority than a 2.

Make your changes and click Save.

Note
Changes to global, organization, suborganization, or role level documents are effectively immediately. Changes to user level documents are effectively after users log out and log in.

Attribute	Definition	Example
advanced	"Hides" the display profile property from users in the iPlanet Directory Server Access Management Edition admin console Channel and Container Management link when set to true. However, the property is not hidden when using the Edit XML or Download XML links. The advanced attribute is a Boolean attribute that can take a value of true or false. The default value is false.	<String name="refreshTime" value="0" advanced="true"/>
lock	Enables high-priority documents to prevent a lower-priority document from using merge semantics to change particular aspects of the display profile. When a display profile object is locked, it cannot be affected by merge semantics in lower priority documents. The lock attribute is a Boolean attribute that can take a value of true or false. The default value is false.	<Selected merge="fuse"> ... <Reference value="EmployeeNews" lock="true"/> ... </Selected>
merge	Controls how properties are combined as display profile documents from different LDAP nodes (base DN, DN, and role DNs) are merged to form a single representation (that is, Desktop). Allowable values are replace, remove, and fuse. The default value is fuse.	See"Display Profile Merge Types"" for replace, remove, and fuse examples.
priority	Sets the priority of the display profile document. A lower number represents a lower priority. For example, a 1 is a lower priority than a 2. Allowable values are integers and the keyword user, which indicates that the current display profile is the user level display profile.	<DisplayProfile version="1.0" priority="10">
propagate	Controls how properties are treated when they are read non-locally but set locally. You can mark all display profile properties, including Boolean, Collection, Integer, Strings, and Reference, with the propagate attribute. The propagate attribute is a Boolean attribute that can take a value of true or false. The default value is true.	<String name="color" value="blue" propagate="false"/>

Type of Display Profile Document	How to View Using the iPlanet Directory Server Access Management Edition Admin Console	Description
Global Display Profile Document	Choose View Service Management. Click the properties arrow next to Desktop. In the Desktop Global attributes section, click Edit XML.	Defines display profile elements that are inherited by all users on the system, regardless of the organization or role to which they belong. (Although currently not enforced, you might also want to use the display profile XML document to define the common providers that will be used by everyone.)
Dynamic Display Profile Document	Choose View Service Management. Click the properties arrow next to Desktop. In the Desktop Dynamic attributes section, click Edit XML.	Describes container management and properties for channels. This display profile is not `used' to generate a user's Desktop at runtime, but becomes the default for each newly created organization and role. By default, the dynamic display profile document is blank. To use the dynamic display profile, you need to first populate it.
Organization, Suborganization, or Role Display Profile	Choose View User Management. Select the appropriate organization, suborganization, and if necessary, select Roles from the Show menu. Select Services from the Show menu. Click the properties arrow next to Desktop. In the Desktop page, click Edit XML.	Shows the display profile for the selected organization, suborganization, or role. When you create a new organization, suborganization, or role, you create a template for this entity. When you create the template for the Desktop service, the initial display profile is set to the dynamic display profile document as mentioned above. Thus, if the dynamic display profile is blank, nothing is filled in. Most likely, you use this display profile document to customize container management and channel properties to fit the needs of different organizations and roles.

Display Profile Document	Description
dp-anon.xml	Used by the authless anonymous user.
dp-org.xml	Sample display profile loaded at the default organization level. It defines all the global properties that are used for the organization and the channel definitions that are used by the organization.
dp-org-final.xml	A copy of dp-org.xml, with NetMail links defined in the Bookmark and Applications channels. This display profile document is used when the NetMail service is created.
dp-providers.xml	Sample display profile loaded at the global display profile level. This document defines all the provider definitions. Because these providers are going to be used by all organizations, the system loads this display profile at the top level, and every organization is able to use them. If a provider definition is used only by one organization, define it in the organization level display profile.

Previous Contents Index Next
Copyright 2002-2003 Sun Microsystems, Inc. All rights reserved.

Provider	Description
AppProvider	Enables a user to add or remove applications from a list of applications.
BookmarkProvider	Enables a user to add or remove URLs from a list of bookmarks.
JSPProvider	Obtains content from one or more JSP™ files.
LoginProvider	Enables the Login channel to show up in the anonymous user's Desktop so users can log in.
MailCheckProvider	Gives information about a user's mail status.
NotesProvider	Enables anyone the administrator has authorized to post a message to everyone's desktop in the Notes channel.
SearchProvider	Supplies a search function using the Sun ONE Portal Server Search Engine.
SimpleWebServiceConfigurableProvider	Makes simple web services available to an end user channel that is configurable by the end user.
SimpleWebServiceProvider	Makes simple web services available to an end user channel.
URLScraperProvider	Uses the Rewriter to construct the URL information and an XML file to describe how to display it.
UserInfoProvider	Collects information from the display profile and iPlanet Portal Server Access Management Edition. It displays a greeting, the user's name, timezone, locale and has access to the user's IMAP and SMTP data.
XMLProvider	Displays content from an XML file format that is converted into another format for viewing.

Provider	Description
JSPFrameCustomTableContainerProvider	A provider used internally by the JSPTabContainer to create a new frame on a user's JSP frameset-based Desktop.
JSPSingleContainerProvider	A container building-block provider and an extension of the JSP container provider, this provider displays a single channel in it.
JSPTabContainerProvider	A container building-block provider and an extension of the JSP Provider, this provider displays a channel that is made up of a number of tabs with titles on them.
JSPTabCustomTableContainerProvider	A provider used internally by the JSPTabContainer to create a new tab on a user's JSP tab-based Desktop.
JSPTableContainerProvider	A container building-block provider and an extension of JSPProvider, this provider displays the content channels in a table.
TemplateEditContainerProvider	A provider used internally by the template-based containers (TemplateTabContainer and TemplateTableContainer) as their edit provider. If a channel's editType is edit_subset, this provider is used to draw the frame for the Edit page.
TemplateTabContainerProvider	A container building-block provider and a template-based tab container, this provider contains support for a number of tabs in it.
TemplateTabCustomTableContainerProvider	A provider used internally by the template-based containers (TemplateTabContainer and TemplateTableContainer) to create a new tab.
TemplateTableContainerProvider	A container building-block provider and a template-based table container, this provider displays the content channels in a table.