Command reference for Portal Scripting Interface


Overview

The WebSphere Portal Scripting Interface component provides a scripting interface to the administration functionality currently available only in the administration GUI. While working with xmlaccess.sh requires a "super administrator" user ID, the Portal Scripting Interface allows you to access the portal with any portal user ID and work within the access rights of that user ID. This topic gives a description of the available commands.


Jython

Jython is a general-purpose high-level programming language that uses code indentation as block delimiters.

Example:

# here is a comment
single_statement(with_arguments)
first_statement_in_line() ; second_statement()
outer statement [first inner] [second inner statement]

A variable can contain an object. A method of an object is invoked by using the object as the first part of a statement followed by a dot ( . ), followed by the method name, followed by arguments that you want to be passed to the method in parentheses ().

Example:

# variable 'Object' holds the object to invoke
# invoke the double argument version of the method
Object.method(arg1, arg2)

# and now the single argument version
Object.method(arg)

# there may be a version with three arguments
Object.method(arg1, arg2, arg3)

# invoke the single argument version
# the single argument is provided as a nested statement
# the nested statement invokes the double argument version
Object.method(Object.method(argInner1, argInner2)


JACL

JACL is an interpreted procedural language without strong typing, with some object oriented concepts that are used by the scripting component.

Example:

# here is a comment single statement with arguments first statement in line ; second statement outer statement [first inner] [second inner statement]

The value of a JACL variable is accessed by placing a $ in front of the variable name. A variable can contain an object. A method of an object is invoked by using the object as the first part of a statement, followed by the method name, followed by any arguments that should be passed to the method. Since there is no strong typing, a method can only be overloaded by varying the number of arguments.

Example:

# variable 'Object' holds the object to invoke
# invoke the double argument version of the method
$Object method arg1 arg2

# and now the single argument version
$Object method arg

# there may be a version with three arguments
$Object method arg1 arg2 arg3

# invoke the single argument version
# the single argument is provided as a nested statement
# the nested statement invokes the double argument version
$Object method [$Object method argInner1 argInner2]


Script Beans

The portal scripting component adds so-called Script Beans to the wsadmin tool. These are objects with methods that work on the portal data. Portal objects are not represented by Jython or JACL objects. There is no Jython or JACL object that represents a particular page or an individual portlet. Rather, there is a fixed number of Script Beans that provide access to specific areas of the portal data.

The available beans are:

Most method names are single English words, such as get or search or parent. All method names must be written in lowercase. Each bean has a help method. If invoked with a method name, it prints help for that method in the bean. If invoked without an argument, it prints general help for that bean, including a list of method names and other help topics. The general help message of the Portal bean includes an overview of the available beans and their responsibilities.

Jython example: 

# get help - for the completely lost
Portal.help()
 
# get help on a particular bean
Portlet.help()
Access.help()
 
# get help on a method of a bean
Portal.help("login")
Layout.help("select")
 
# get help on an extended help topic of a bean
Content.help("search-criteria")

JACL example: 

# get help - for the completely lost
$Portal help
 
# get help on a particular bean
$Portlet help
$Access help
 
# get help on a method of a bean
$Portal help login
$Layout help select
 
# get help on an extended help topic of a bean
$Content help search-criteria


Portal Objects

Most portal objects are represented in the script by an object identifier string which is based on the object ID in the portal. For example: _6_00KJL57F9D02H456_A

These IDs are expected by methods as arguments and returned as results. Since an ID never contains white spaces or characters that would be misinterpreted by JACL, it is a convenient handle for a portal object. If a method returns several objects, the IDs are separated by white spaces. The result can then be used directly as a JACL list. In Jython you use the method split() on the result string to create a list.

Unlike with the GUI, where geometric arrangement and a locale specific title provide information about an object, the IDs used in the script are unintelligible to the user. Most of the script beans therefore provide a details method that prints information about an object. The details method of a bean will only work for the objects handled by that bean. For example, the Content bean cannot provide details about IDs returned by the Layout bean.

Jython example: 

# 'search' returns a list of objects
for child in Content.search("all").split():
  # details get printed, they are not returned as a result
  Content.details(child)
}

JACL example: 

# 'search' returns a list of objects
foreach child  [$Content search all] {
  # details get printed, they are not returned as a result
  $Content details $child
}

The scripting component tries to generate a "common name" for the portal objects. The common name is based on a global unique name, an object name, or a title assigned to the object. The common name never contains white space, special characters, or characters outside of the US-ASCII range. Hence, it can be displayed even in a terminal window that does not support national character sets. If suitable input data is available, the generated common name may provide an indication of what an object represents.


Tree Navigation

The Content, Layout, and Portlet beans each represent a tree hierarchy. The basic navigation methods are the same for all three. A tree bean provides methods to access the root node, to look up the parent and children of a node, and to maintain a cursor which points to a selected node in the tree. The code examples in this section use the Content bean, but the same operations can be performed on the other tree beans as well.

The command root returns the ID of the root node, as a fixed starting point for navigation.
Jython: Content.root()
JACL: $Content root

You can select a node by its ID using the select command. You can clear the current selection using deselect or using select without an argument. You can return the ID of the selected node using the current command. For interactive use, csn is an alias for current.

Jython example: 

Content.select ID
Content.deselect
Content.current
Content.csn
 
# example: select the root node
Content.select(Content.root())

JACL example: 

$Content select ID
$Content deselect
$Content current
$Content csn
 
# example: select the root node
$Content select  [$Content root]

The path command returns a list of all IDs from the root to the currently selected node. The children of the selected node are returned in the same fashion by the children command. The ID of the parent of the selected node can be obtained by using parent.

Jython example: 

Content.path
Content.parent
Content.children
 
# example: select a node and print its children
Content.select(node_ID)
for child in Content.children().split():
    print child

JACL example: 

$Content path
$Content parent
$Content children
 
# example: select a node and print its children
$Content select node_ID
foreach child  [$Content children] { puts "$child" }

The commands path, parent, and children can also be used with an explicit ID instead of implicitly referring to the currently selected node.

Jython example: 

Content.path(ID)
Content.parent(ID)
Content.children(ID)

JACL example: 

$Content path ID
$Content parent ID
$Content children ID

For simplicity, there are dedicated select commands for the root node and for the parent of the currently selected node. In the following example, the first argument is a dummy, to distinguish the method from the select with an ID argument. It will not be interpreted. The second argument is a keyword, which is case insensitive. Alternative, shorter keywords are documented in the bean help.

Jython example: 

Content.select("the", "root")
Content.select("the", "parent")

JACL example: 

$Content select the root
$Content select the parent


Search

All beans with tree navigation support identical commands for searching, but the available search criteria are different for each bean. As before, the Content bean is used in the generic examples.

Searches in trees are scoped. The search scope is the subtree below the selected node, including the selected node itself. If nothing is selected, the search scope is the full tree starting at the root.

There are two different commands for searching: search will return a list of matches, whereas find only succeeds if there is a single, unique match for the search. It fails if there is more than one match, or no match at all. It can be used in cases where a script should terminate if the search result is not a unique match. If the keyword select is passed to find, the search result becomes the selected node.

Jython example: 

Content.search(type)
Content.search(type), "by", (value)
 
Content.find(type)
Content.find(type), "by", (value)
 
Content.find(type, "select")
Content.find(type, "by", (value, "select")

JACL example: 

$Content search type
$Content search type by value
 
$Content find type
$Content find type by value
 
$Content find type select
$Content find type by value select

The first argument for all searches is the type of the nodes to look for. The type is specified by a keyword, which is case insensitive. The available types and corresponding keywords depend on the bean. In all beans, the keywords all and any can be used to search regardless of the type. There is a dedicated help topic for the search types.

Jython example: 

# example: return all nodes in the search scope
Content.search all
 
# example: get help on the available type keywords
Content.help search-types

JACL example: 

# example: return all nodes in the search scope
$Content search all
 
# example: get help on the available type keywords
$Content help search-types

You can combine the type selection with an additional search criteria, which is specified by a keyword ( by ) and a value to match against ( value ). The available search criteria and corresponding keywords depend on the bean. There is a dedicated help topic for the search criteria.

Jython example: 

# example: get help on the available by keywords
Content.help("search-criteria")

JACL example: 

# example: get help on the available by keywords
$Content help search-criteria

The following are common search criteria. Alternative, shorter keywords are described in the help text on search criteria of the respective bean.

Value Description
id The value is an ID, the search is for the object with that ID.
uniquename The value is a string, the search is for the object with the string as its unique name.
commonnamehas The value is a string, the search is for objects with the string as a substring in their common name. Comparison is case insensitive.
commonnameis The value is a string, the search is for objects with the string as their common name. Comparison is case sensitive.

Jython example: 

# example: find and select by unique name
Content.find("any", "uniquename", "ibm.portal.Portlets", "select")

JACL example: 

# example: find and select by unique name
$Content find any uniquename "ibm.portal.Portlets" select


Attributes

All beans use similar commands to query and modify attributes. Attributes are identified by a name, such as "uniquename", "title", or "markup". There are different commands for the different types of attributes. Similar to the details command in Portal objects, the commands must be invoked on the bean responsible for the object type. For example, attributes of content nodes can only be accessed through the Content bean, not through the Layout or any other bean.

The set of attributes supported for an object depends on the type of the object. Many attributes are read-only. Attribute values are always represented as strings in the scripting language. They are mapped from and to portal data types by the respective script bean. Exceptions will be triggered if the mapping fails.

Plain attributes:

Plain attributes have a single value that can be queried using the get command. The object for which to query the attribute is specified by an ID, the attribute by name. If the attribute is not read-only, the value can be set using the set command, which expects the new value as the last argument. If the bean supports a current selection, the ID can be omitted for both commands to refer to the selected object.

Jython example: 

Content.get(ID, attribute)
Content.set(ID attribute value)
 
# only for beans with a current selection
Content.get(attribute)
Content.set(attribute value)
 
# example: get unique name of a content node
Content.get(ID, "uniquename")
 
# example: get type of the selected content node
Content.get("type")
 
# example: set theme of a content node
themeid = Look.find("theme", "commonameis", "Science")
Content.set(ID, "theme", themeid)

JACL example: 

$Content get ID attribute
$Content set ID attribute value
 
# only for beans with a current selection
$Content get attribute
$Content set attribute value
 
# example: get unique name of a content node
$Content get ID uniquename
 
# example: get type of the selected content node
$Content get type
 
# example: set theme of a content node
set themeid  [$Look find theme commonameis "Science"]
$Content set ID theme $themeid

The following are standard attribute names available for all objects. Names for additional attributes of individual portal object types are documented with the respective bean. Alternative or shorter names are documented in the bean help.

Value Description
id The identifier of the object.
type The type of the object.
uniquename The unique name of the object, if one is assigned.
commonname The common name of the object, if one could be generated.


List valued attributes

List valued attributes can have multiple values. They can be queried using the list command, which will return all values, separated by white space. The object for which to query the attribute is specified by an ID, the attribute by name. If the bean supports a current selection, the id can be omitted to refer to the selected object.

List valued attributes can be modified by adding or removing a particular value, or by removing all values from the list. The respective commands are add, drop, and empty. With all commands, the object is specified by ID and the attribute by name. The add and drop commands also require the value to be added or removed.

These commands are appropriate as long as the values do not contain white space and the order of the elements is not important. Currently, all list valued attributes satisfy these restrictions.

Not all list valued attributes can be modified by all of these commands. For example, some lists may not be empty, in which case the empty command is not available. However, if an operation is supported for an attribute, the operation uses the command as described here. List valued attributes may also change as a side effect of other operations. For example, if a title is set for a previously undefined locale, the new locale will show up in the list of locales. See Local specific attributes for details on titles and locales.

Jython example: 

Content.list(ID, attribute)
Content.add(ID, list, value)
Content.drop(ID, list, value)
Content.empty(ID, list)
 
# only for beans with a current selection
Content.list(attribute)
Content.add(list, value)
Content.drop(list, value)
Content.empty(list)
 
# example: add a new markup for the selected node
Content.add("markup", "wml")
 
# example: drop the american locale for the given node
Content.drop(node_ID, "locale", "en_US")
 
# example: drop all locales for the given node
Content.empty(node_ID, "locale")

JACL example: 

$Content list ID attribute
$Content add ID list value
$Content drop ID list value
$Content empty ID list
 
# only for beans with a current selection
$Content list attribute
$Content add list value
$Content drop list value
$Content empty list
 
# example: add a new markup for the selected node
$Content add markup wml
 
# example: drop the american locale for the given node
$Content drop node_ID locale en_US
 
# example: drop all locales for the given node
$Content empty node_ID locale

Locale specific attributes:

Locale-specific attributes have different values for different languages and countries. They can be queried using the nlsget command, where nls stands for National Language Support. The object for which to query the attribute is specified by an ID, the attribute by name. If the bean supports a current selection, the ID can be omitted to refer to the selected object. The usual locale-specific attributes are:

For the Content bean, only the locale-specific attributes title and description exist. For the Portlet bean, all four of the attributes exist.

The language and country is given as a so-called locale, which consists of a language identifier, an optional country identifier, and an optional variant. Language and country are specified by standard two letter abbreviations, the language in lower case and the country in upper case. The components are separated by underscore characters. Here are some example locales:

en General English
en_US American English
de_CH Swiss German
pt_BR Brazilian Portuguese

The list valued attribute named "locales" holds all locales for which a locale specific attribute may be defined. However, all locale specific attributes are optional for all locales. There is no fallback algorithm that would, for example, return the general Portuguese value if the Brazilian Portuguese value is not set. Such fallback algorithms are used when pages are assembled by the portal, but not for the administrative access provided by the portal scripting component.

Locale specific attributes that are not read-only can be set using the nlsset command. On top of the arguments for the nlsget command, it expects the new value of the attribute as the last argument. By setting an attribute for a locale that was not used before, the new locale is added to the list valued attribute "locales" mentioned above.

Jython example: 

Content.nlsget(ID, attribute, locale)
Content.nlsset(ID, attribute, locale, value)
 
Content.nlsget(attribute, locale)
Content.nlsset(attribute, locale, value)
 
# example: get american title of a specific content node
Content.nlsget(node_ID, "title", "en_US")
 
# example: set german description of current selection
Content.nlsset("description", "de_DE", "Kurze Beschreibung")
 
# example: set general english title of a specific node
Content.nlsset(node_ID, "title", "en", "English Title")

JACL example: 

$Content nlsget ID attribute locale
$Content nlsset ID attribute locale value
 
$Content nlsget attribute locale
$Content nlsset attribute locale value
 
# example: get american title of a specific content node
$Content nlsget node_ID title en_US
 
# example: set german description of current selection
$Content nlsset description de_DE "Kurze Beschreibung"
 
# example: set general english title of a specific node
$Content nlsset node_ID title en "English Title"

Since locale-specific attributes are often translated independently from script development, the nlsimport command can be used to read a separate property file that defines attribute values for a set of locales. By specifying an appropriate prefix, it is possible to load values from the same property files that are used by the XMLAccess tool.

Jython example: 

Content.nlsimport(ID, file_name)
Content.nlsimport(ID, file_name, prefix)

JACL example: 

$Content nlsimport ID file_name
$Content nlsimport ID file_name prefix

To delete all locale-specific attributes before importing a set of values, empty the list valued attribute "locales" as described in List valued attributes.


Organization

For some beans, in particular the Content and Layout beans, the order of nodes is significant. In tree beans, the parent relationship of the nodes defines the hierarchy. Only nodes with the same parent node are in a particular order in trees. The Layout bean is used in the generic examples.

Sequence:

The move command can be used to reorder nodes. The order of nodes is tracked as a non-negative integer position assigned to each node, with the first node at position 0. For tree beans, the positions compare only among the children of a common parent node. The position can be queried as a read-only plain attribute.

The order of nodes is changed by the move command. It is used on a single node to assign an absolute position or to displace by a given distance. The positions of the other affected nodes are updated automatically. In both cases, the new position of the node will always remain within bounds. The position or displacement argument will be adjusted accordingly by the bean.

The move command expects the ID of the node to be moved, a keyword indicating whether the change is absolute or relative, and the new position or distance. If the bean supports a current selection, the ID can be omitted to move the selected object.

Jython example: 

Layout.move(ID, "to", position)
Layout.move(ID, "by", distance)
 
# only for beans with a current selection
Layout.move("to", position)
Layout.move("by", distance)
 
# example: move selected node to the top position
Layout.move("to", 0)
 
# example: move given node one down in the list
# if it already is the last node, do nothing
Layout.move(node_ID, "by", 1)
 
# example: move selected node 4 up in the list
# if it is at position 0 to 4, it becomes the new head
Layout.move("by", -4)
 
# example: move given node to the last position
# negative absolute positions are interpreted as max int
Layout.move(node_ID, "to", -1)

JACL example: 

$Layout move ID to position
$Layout move ID by distance
 
# only for beans with a current selection
$Layout move to position
$Layout move by distance
 
# example: move selected node to the top position
$Layout move to 0
 
# example: move given node one down in the list
# if it already is the last node, do nothing
$Layout move node_ID by 1
 
# example: move selected node 4 up in the list
# if it is at position 0 to 4, it becomes the new head
$Layout move by -4
 
# example: move given node to the last position
# negative absolute positions are interpreted as max int
$Layout move node_ID to -1

Hierarchy

In some tree beans, it is possible to change the parent of a node in the tree, thereby moving the whole subtree below that node to another part of the tree. This is achieved by the commands transfer or adopt. With transfer, the ID of the node and new parent are specified explicitly, while adopt uses the selected layout mode as the new parent. To improve readability and avoid confusion about the interpretation of the two IDs, the arguments of the transfer command are separated by the keyword "to".

Jython example: 

Content.transfer(child_ID, "to", parent_ID)
Layout.transfer(child_ID, "to", parent_ID)
Layout.adopt(child_ID)
 
# example: move a layout node below the root component of the page
Layout.select("the", "root")
Layout.adopt(node_id)

JACL example: 

$Content transfer child_ID to parent_ID
$Layout transfer child_ID to parent_ID
$Layout adopt child_ID
 
# example: move a layout node below the root component of the page
$Layout select the root
$Layout adopt node_ID


Content Hierarchy

The content hierarchy is a tree of content nodes. Content nodes can be labels, compositions, and links. Compositions are also called pages. Links can be internal or external. In the GUI, links represent the nodes in the "Favorites" list. Internal links point to a portal page, external links can point to any URL. The content hierarchy is accessed and modified by means of the Content bean, referenced as $Content in JACL. The Content bean offers the following functionality:


Navigation

The Content bean is a tree bean.


Search

The generic search syntax is documented in Search. The Content bean supports the default search criteria, and the following keywords for node types in searches. Alternative, shorter keywords are documented in the bean help.

Jython example: 

Content.help("search-types")
 
# example: search all content nodes
Content.search("all")
 
# example: find and select page by unique name
Content.find("page", "uniquename", "ibm.portal.Portlets", "select")
 
# example: find all pages under label "Administration"
Content.find("label", "uniquename", "ibm.portal.Administration", "select")
Content.search("composition")

JACL example: 

$Content help search-types
 
# example: search all content nodes
$Content search all
 
# example: find and select page by unique name
$Content find page uniquename "ibm.portal.Portlets" select
 
# example: find all pages under label "Administration"
$Content find label uniquename ibm.portal.Administration select
$Content search composition


Plain attributes

In addition to the default attributes, content nodes have the following attributes:

Attribute Description
position The numeric position among the siblings, 0-based.
themeid The identifier of the theme for the content node.
themename The name of the theme for the content node.
allportlets A flag that indicates whether all portlets are allowed for this page or not. If this flag is set true, the list of allowed portlets is ignored. (Refer to List valued attributes.)

The themeid attribute is writable. The themename attribute is not writable, but the value depends on the themeid attribute. The position attribute is not writable either, but the value depends on the organization of the content tree.

To get attributes of a static page content node, run the following command:

Jython: 

Content.get(oid, attribute, markup)

JACL: 

$Content get oid attribute markup

Valid attributes are as follows:
filename


displayoption


Jython example: Content.get(6_CGAH47L00G2N802TJFV58Q3000, filename, html)
JACL example: /$Content get 6_CGAH47L00G2N802TJFV58Q3000 filename html

The preceding example returns the filename of the entry point for the page display.

To set attributes for a static page, run the following command:

Jython example: 

Content.set(oid, attribute, value, markup)

JACL example: 

$Content set oid attribute value markup

Valid attributes are filename and displayoption.
filename


displayoption


List valued attributes

The content nodes have three list valued attributes, locales, markups, and allowedportlets. See the bean help for alternative, shorter names for these lists.

The locales list holds the locales for which locale-specific attributes are defined (see Locale specific attributes). The commands list, drop, and empty are available for locales. New values can be added by setting a title for the respective locales.

The markups list holds the markups supported by the content node. The commands list,add, and drop are available for markups. At least one markup has to be supported.

The allowedportlets list holds the portlets that are registered as allowed portlets for that page. The total list of portlets that can be used for this page is this list, plus the lists of allowed portlets of all parent pages.

Jython example: 

# example for manipulating locales of a content node:
# select node, list locales, remove and re-create a locale
# "locale" is an alternative name for the "locales" list
Content.select(ID)
Content.list("locales")
Content.drop("locale", "en")
Content.nlsset("title", "en", "New English Title")
 
# example for manipulating markups of a content node:
# select node, list markups, replace wml by chtml
# "markup" is an alternative name for the "markups" list
Content.select(ID)
Content.list("markups")
Content.add("markup", "chtml")
Content.drop("markup", "wml")
Content.list("allowedportlets")

JACL example: 

# example for manipulating locales of a content node:
# select node, list locales, remove and re-create a locale
# "locale" is an alternative name for the "locales" list
$Content select ID
$Content list locales
$Content drop locale en
$Content nlsset title en "New English Title"
 
# example for manipulating markups of a content node:
# select node, list markups, replace wml by chtml
# "markup" is an alternative name for the "markups" list
$Content select ID
$Content list markups
$Content add markup chtml
$Content drop markup wml
$Content list allowedportlets


Locale specific attributes

The content nodes have two locale specific attributes, title and description. See the bean help for alternative, shorter names for these attributes. The title has to be defined for each locale, though it can be set to the empty string. A new locale is defined by setting the title for it.

Jython example: 

# example for manipulating locales of a content node:
# select node, remove all, import, add one manually
Content.select(ID)
Content.empty("locales")
Content.nlsimport("nls/content.nls", "page.visualization")
Content.nlsset("title", "en_GB", "Visualisation")
Content.nlsset("description", "en_GB", "A page for...")

JACL example: 

# example for manipulating locales of a content node:
# select node, remove all, import, add one manually
$Content select ID
$Content empty locales
$Content nlsimport nls/content.nls page.visualization
$Content nlsset title en_GB "Visualisation"
$Content nlsset description en_GB "A page for..."


URL attributes

For a URL content node, the urlget command obtains the URLs. It requires the markup name as an argument. If an ID is given, the requested URL of that content URL node is returned. If the ID is omitted, the requested URL of the currently selected URL node is returned.

Jython example: 

Content.urlget(markup)
Content.urlget(ID, markup)
# example: get WML URL of a specific content URL node
Content.urlget(node_ID, "wml")

JACL example: 

$Content urlget markup
$Content urlget ID markup
 
# example: get WML URL of a specific content URL node
$Content urlget node_ID wml


Metadata attributes

Content nodes can own metadata, which are name/value pairs of data that are associated with the content node. Metadata are used by the portal itself (to set display attributes for example) or by the user. However, ensure that none of the metadata information that is set by the portal is overridden.

Jython example: 

Content.parmget(ID, name)
Content.parmset(ID, name, value)
Content.drop(ID, "parm", name)
Content.list(ID, "parm")
 
# only for beans with a current selection
Content.parmget(name)
Content.parmset(name, value)
Content.drop("parm", name)
Content.list("parm")
 
# example: set the metadata for an instance property named #
"MyUserData" on the selected node
Content.parmset("MyUserData", "A_User_Value")
 
# example: get the metadata for an instance property named #
"MyUserData" (should return "A_User_Value")
print Content.parmget("MyUserData")
 
# example: list all metadata names
for pname in Content.list("parm").split():
    print pname
 
#example: Drop the metadata with the name "MyUserData"
Content.drop("parm", "MyUserData")
Organization

JACL example: 

$Content parmget ID name
$Content parmset ID name value
$Content drop ID parm name
$Content list ID parm
 
# only for beans with a current selection
$Content parmget name
$Content parmset name value
$Content drop parm name
$Content list parm
 
# example: set the metadata for an instance property named 
# "MyUserData" on the selected node 
$Content parmset MyUserData A_User_Value 
 
# example: get the metadata for an instance property named 
# "MyUserData" (should return "A_User_Value") 
puts " [$Content parmget MyUserData]" 
 
# example: list all metadata names 
foreach pname  [$Content list parm] { 
  puts "$pname"  
} 
 
#example: Drop the metadata with the name "MyUserData" 
$Content drop parm "MyUserData"


Organization

The sequence of nodes can be modified as described in Sequence. It is currently not possible to reorganize the content hierarchy.


Life Cycle

The create command creates a new content node. The derive command creates a new content node for a page that is derived from another page. The delete command removes a content node.

When creating a new content node, the parent for the new node has to be selected. The first argument for creating is the type of the new node. Supported types are label, page, and externalurl. See the bean help for alternative and shorter names. It is currently not possible to create a node of type internalurl from a script. The second argument is a name for the new node. It will be set as the provisional English title, and the common name of the new node is computed from it. The last argument is one markup that will be supported by this nodes. Additional markups can be enabled by manipulating the list of markups (see List valued attributes). The create command returns the ID of the newly created node. If the keyword select is appended to the command, the created node becomes the current selection.

Optionally, the script can specify a shared-flag, which indicates if the new page is a shared page (shared) or a non-shared page(nonshared). The optional flag private-flag indicates if the new page is private or public (possible values are private and public). This flag is only valid if a the content node type is page.

When you derive a page, the parent for the new page in the content tree has to be selected. Only pages that are flagged as shared and public can be used as base pages for derivation. The first argument is the name of the new page. The type of the node is implicit, since only pages can be derived. The second argument is the keyword from, the third is the identifier of the page to derive from. The supported markups are the same as for the base page. The derive command returns the ID of the newly created node. If the keyword select is appended to the command, the created node becomes the current selection.

Do not rely on the name being set as the English title, since this behavior might change in the future. Set the English title explicitly if you plan to support the "en" locale. However, the common name will be computed from the name argument.

Jython example: 

Content.create(type, name, markup)
Content.create(type, name, markup, "select")
Content.create(type, name, markup,  [shared_flag,]
 [private_flag,] "select")
 
Content.derive(name, "from", ID)
Content.derive(name, "from", ID, "select")
 
# example: create and select a label at the top level,
#          then create a derived page below the new label
Content.select("the", "root")
Content.create("label", "Leisure", "html", "select")
Content.derive("Movies", "from", node_ID)

JACL example: 

$Content create type name markup
$Content create type name markup select
$Content create type name markup  [shared_flag]  [private_flag] 
select
 
$Content derive name from ID
$Content derive name from ID select
 
# example: create and select a label at the top level,
#          then create a derived page below the new label
$Content select the root
$Content create label "Leisure" html select
$Content derive "Movies" from node_ID

To create a static page, run the following command:

Jython: 

Content.create(staticpage, title, markup, zip_file_name, filename, displayoption, "select")

For example, Content.create(staticpage, MyStaticPageTitle, html, c:/tmp/StaticContentPage.zip, index.html, inline, "select")

JACL: 

$Content create staticpage title markup zip_file_name filename  [displayoption]  [select]

For example, $Content create staticpage MyStaticPageTitle html c:/tmp/StaticContentPage.zip index.html [inline] [select]

The preceding example creates a static page beneath the currently selected content node for the HTML markup with the page title MyStaticPageTitle. The content of the page is read from c:/tmp/StaticContentPage.zip. The entry point for the page display is read from index.html, which must be contained in the ZIP archive. To specify the display method, you can use the optional parameter displayoption. This parameter takes one of the following values inline, iframe, or ajax. The default value is inline. To make the newly created static page the currently selected content node, use the optional parameter select.

To get the static page content in the format of a ZIP archive, run the following command:

Jython: 

Content.pageget(oid, markup, zip_file_name)

For example, Content.pageget(6_CGAH47L00G2N802TJFV58Q3000, html, c:/tmp/MyStaticContentPage.zip)

JACL: 

$Content pageget oid  markup  zip_file_name

For example, $Content pageget 6_CGAH47L00G2N802TJFV58Q3000 html c:/tmp/MyStaticContentPage.zip

The preceding example writes the content of the specified static page to c:/tmp/MyStaticContentPage.zip.

To set the static page content by specifying a ZIP filename, use the following command:

Jython: 

Content.pageset(oid, markup, zip_file_name, filename)

For example, Content.pageset(6_CGAH47L00G2N802TJFV58Q3000, html, c:/tmp/NewStaticContentPage.zip, index.html)

JACL: 

$Content pageset oid markup zip_file_name filename

For example, $Content pageset 6_CGAH47L00G2N802TJFV58Q3000 html c:/tmp/NewStaticContentPage.zip index.html

The preceding example updates the specified static page content with the content of c:/tmp/NewStaticContentPage.zip. The entry point for the page display is read from index.html, which must be contained in the ZIP archive.

The command delete removes a content node that has no children. Nodes that have children cannot be deleted. To reduce the risk of accidental deletion, this command always requires the ID as an argument, even if the node to be deleted is selected.

When deleting a page, all pages derived from that page will also be deleted. This also affects other users that have pages derived from that base page. If the currently selected node is deleted, either directly or by deleting a base page, the bean clears.

Jython example: 

Content.delete(ID)

JACL example: 

$Content delete ID


Component Hierarchy

The component hierarchy is a tree of components on a page. Components can be containers and controls. A container holds other components, a control displays a portlet. The component hierarchy is accessed and modified by means of the Layout bean, referenced as $Layout in JACL.

Only pages have a component hierarchy. The Layout bean always refers to the page that is currently selected in the Content bean (see Content Hierarchy). When the Content bean has no current selection, or the current selection is not a page, the Layout bean cannot be used. Whenever a node is selected in the Content bean, the current selection of the Layout bean is cleared.

In the GUI, the component hierarchy of a page is manipulated by the customizer. The operations of the Layout bean allows for the definition of component hierarchies that can not be handled by the customizer. Care has to be taken by the script developer if the customizer is to be used alongside scripting.

The Layout bean offers the following functionality:


Navigation

The Layout bean is a tree bean.

The Layout bean provides the index command to obtain and resolve so-called index paths (see Index paths. When invoked with an ID as argument, the command returns the absolute index path for that component. When invoked without an argument, it returns the absolute index path for the currently selected component.

When invoked with an index path and a keyword, the index command resolves the argument path. If the keyword is find, it returns the ID of the addressed component. If the keyword is select, it also selects it. The keyword is case insensitive. If the index path is not absolute, it will be resolved relative to the selected component.

Jython example: 

Layout.index()
Layout.index(ID)
 
Layout.index(ipath, "find")
Layout.index(ipath>, "select")
 
# example: resolve an absolute index path
Layout.index("/1/0/3", "find")
 
# example: select first child of current container
Layout.index("0", "select")

JACL example: 

$Layout index
$Layout index ID
 
$Layout index ipath find
$Layout index ipath select
 
# example: resolve an absolute index path
$Layout index /1/0/3 find
 
# example: select first child of current container
$Layout index 0 select


Search

The generic search syntax is documented in Search. The Layout bean supports the following keywords for node types in searches. Alternative, shorter keywords are documented in the bean help.

In addition to the default search criteria, the Layout bean supports the following criteria. Alternative, shorter names are documented in the bean help.


Plain attributes

In addition to the default attributes, components have the following attributes. Alternatively, shorter names are documented in the bean help.

Attribute Description
position The numeric position among the siblings, 0-based.
skinid The identifier of the skin for the component.
skinname The name of the skin for the component.
modifiable A flag indicating whether the component can be modified.
deletable A flag indicating whether the component can be deleted.
width The width of the component, in pixel or percent.

The skinid, modifiable, deletable, and width attributes are writable. The boolean value of the flag attributes can be given as true/false, t/f, 1/0, or on/off. It is returned as true/false by the get command. The flag values are local values of the component. On derived pages, a component is modifiable or deletable only if the flag is also set on all base pages where that component is defined. The value of the width attribute can be given as a number of pixels, or as a numeric percentage followed by the percent sign.

The skinname attribute is not writable, but the value depends on the skinid attribute. The position attribute is not writable either, but the value depends on the organization of the component tree (see Organization).

Jython example: 

# examples for setting attributes of the selected node
Layout.set("modifiable", "true")
Layout.set("deletable", "0")
Layout.set("width", "350")

JACL example: 

# examples for setting attributes of the selected node
$Layout set modifiable true
$Layout set deletable 0
$Layout set width "350"

Containers have the following additional attribute:

Attribute Description
orientation The orientation of the container.

The orientation attribute is writable. The value is returned as "horizontal" or "vertical". It can be set as horizontal/vertical or as row/column or as row/col.

Controls have the following additional attributes:

Attribute Description
portletdefinition The ID of the portlet shown in the control.
portletentity The ID of the portlet entity shown in the control.

These attributes are not writable.


Global flags

A composition hierarchy has several global flags. These are similar to attributes of the content page node, except that they are associated with the composition hierarchy rather than the content node. In consequence, they have to be accessed through the Layout bean after selecting the page in the Content bean.

The global flags can be queried with the getflag and modified with the setflag command. The getflag command expects the name of the flag as the first argument. If the keywordnumeric is added, it returns the value of the flag as a boolean 1 or 0. Without the keyword, it returns a string "true" or "false", respectively. The setflag command expects the name of the flag as the first argument, the new value as the second. The new value can be specified as any boolean value recognized by the BSF, like 1/0, true/false, t/f, on/off.

Jython example: 

Layout.getflag(flag)
Layout.getflag(flag, "numeric")
 
Layout.setflag(flag, value)
 
# query a flag in a condition
if Layout.getflag("active", "numeric"):
  ...
else:
  ...

JACL example: 

$Layout getflag flag
$Layout getflag flag numeric
 
$Layout setflag flag value
 
# query a flag in a condition
if  [$Layout getflag active numeric] then {...} else {...}

The following global flags are supported. The bean help documents alternative and shorter names.

Attribute Description
active, a Whether the page is active.
bookmarkable, bookmark, b Whether an internal link to this page can be created.
shareable, share, s Whether this page can be used as a base for derived pages.

A page is not shown in the navigation if the active flag is false. Pages can be inactivated temporarily while they are modified, to prevent user from seeing an inconsistent view of the page. The bookmarkable flag is not writable.


Organization

The component hierarchy can be modified as described in Sequence and Hierarchy.


Life Cycle

The create command creates a new component. The parent container for the new component has to be selected. The first argument is a keyword indicating whether a container or control is to be created. Alternative, shorter keywords are documented in the bean help. The interpretation of the second argument depends on the type of object to create. When creating a container, it is the initial value for the orientation attribute. When creating a control, it is the value for the portletdefinition attribute. See Plain Attributes for both attributes. If the keyword select is appended, the newly created node becomes the current selection.

A page that has just been created, or from which all components have been deleted, does not have a root container. Only in that case, it is possible to create a container without selecting a parent. The new container becomes the root container for the page. It is not possible to create a page with a root control.

Jython example: 

Layout.create("container", orientation)
Layout.create("container", orientation, "select")
 
Layout.create("control", portlet_ID)
Layout.create("control", portlet_ID, "select")
 
# example: append a column to the second row
Layout.index("/1", "select")
Layout.create("container", "column")
 
# example: create a new control in the first row or column
Layout.index("/0", "select")
Layout.create("control", portlet_ID)
 
# example: create a page with a control in a row
Content.create("page", "New Page", "html", "select")
 
# no deselect required, since nothing can be selected
Layout.create("container", "row", "select")
Layout.create("control", portlet_ID)

JACL example: 

$Layout create container orientation
$Layout create container orientation select
 
$Layout create control portlet_ID
$Layout create control portlet_ID select
 
# example: append a column to the second row
$Layout index /1 select
$Layout create container column
 
# example: create a new control in the first row or column
$Layout index /0 select
$Layout create control portlet_ID
 
# example: create a page with a control in a row
$Content create page "New Page" html select
# no deselect required, since nothing can be selected
$Layout create container row select
$Layout create control portlet_ID

The only argument required for the delete command is the ID of the node to delete. To prevent accidental deletion, explicitly specify the ID even if the node is selected. You can only delete a container if it is empty. If the selected node is deleted, the bean automatically clears.

Jython example: 

Layout.delete ID

JACL example: 

$Layout delete ID


Portlet Repository

The portlet repository provides access to portlets, portlet applications, and web modules. To provide easy access to the relations between the repository objects, the repository is modeled as a tree. Unlike with the content and component hierarchies, the repository tree is not arbitrarily nested.

At the root of the repository is a dummy node. Children of the root are the web modules. web modules are the deployment units of the portal, they correspond to WAR files. The children of a web module are portlet applications.

The portlet repository is accessed by means of the Portlet bean, referenced as $Portlet in JACL. Modification of the portlet repository from a script is currently not supported.

The Portlet bean provides the following functions:


Navigation

The Portlet bean is a tree bean. The navigation is documented in Tree Navigation.

There is one dedicated select command to select the web module of the currently selected portlet application or portlet.

Jython example: 

Portlet.select("the", "root")
Portlet.select("the", "parent")
Portlet.select("the", "webmodule")

JACL example: 

$Portlet select the root
$Portlet select the parent
$Portlet select the webmodule


Search

The generic search syntax is documented in Search. The Portlet bean supports the following keywords for node types in searches. Alternative, shorter keywords are documented in the bean help.

In addition to the default search criteria, the Portlet bean supports two criteria that match on the name of the objects. The name is similar to a common name, except that there are no restrictions on the character set. The name is a real attribute of the repository objects, not a synthesized one like the common name.

Attribute Description
namehas The value is a string, the search is for objects with the string as a substring in their name. Comparison is case insensitive.
nameis The value is a string, the search is for objects with the string as their name. Comparison is case sensitive.

Jython example: 

# example: search all applications related to news
Portlet.deselect()
Portlet.search("application", "namehas", "News")
 
# example: find and select unique news portlet
#          will fail if none or several are found
Portlet.find("portlet", "nameis", "NewsPortlet", "select")

JACL example: 

# example: search all applications related to news
$Portlet deselect
$Portlet search application namehas "News"
 
# example: find and select unique news portlet
#          will fail if none or several are found
$Portlet find portlet nameis "NewsPortlet" select


Plain attributes

In addition to the default attributes, repository objects have some of the following attributes. Alternative, shorter names are documented in the bean help.

Attribute Description
name The name, for all object types.
version The version number, for web modules only.
contextroot The absolute path URI, for web modules only.
resourceroot The relative directory, for web modules only.
defaultlocale The default locale, for applications and portlets.

These attributes are also available:

Attribute Description
id, oid, guid The identifier of the node. Suitable input for 'select'.
uniquename, uname, un The global unique name of the node, if it has one.
type The type of the node. Options: repository, webmodule, application, portlet
name The name of the node.
commonname, cname, cn The common name generated for the node.
version The version number. Only for web modules.
contextroot, context, uri The relative URI for addressing the web module. Only for web modules.
resourceroot, resdir, dir, war The subdirectory where the web module resources can be found.
defaultlocale, dlocale, defloc The default locale. Only for portlet applications and portlets.
servlet The id of the associated servlet. Only for portlets.
cachescope, cs The remote cache scope of this repository node. Only portlet nodes can have this read-only flag. The attribute value can be empty. Valid attribute values are 'shared' or 's' for a shared remote cache scope, respectively 'nonshared' or 'ns' for a non-shared remote cache scope.
cacheexpiration, cacheexp, cexp The expiration value of the remote cache, in seconds. Only portlet nodes can have this read-only flag. The attribute value must be a numeric expression, where -1 means the cache never expires, 0 means the cache expires at each request.
remotecachedynamic, rcd Indicates if the remote cache is dynamic or static. Only portlet nodes can have this read-only flag. A value of true indicates that the remote cache is dynamic. false indicates that the remote cache is a static cache.

All attributes are read-only, there is no set command. The resourceroot attribute typically is the name of the WAR file of the web module.


List valued attributes

The portlet nodes have two list valued attributes, locales and parameters. See the bean help for alternative, shorter names for these lists. Only the list command is supported, the lists cannot be modified. The locales list is available for portlets and portlet applications. It holds the locales for which locale specific attributes are defined in Locale specific attributes. The parameters list holds the init parameter setting names that are associated with the specified portlet.


Locale specific attributes

Portlets and portlet applications have the following locale specific attributes. All attributes are optional. The list of locales for which attributes are defined can be queried using the list command (List valued attributes).

Only the nlsget command is available for locale specific attributes.


Portlet Metadata

Portlet nodes can own metadata, which are name/value pairs of data that are associated with the content node. Metadata are used by the portal itself (for example, to set display attributes), or by the user. The portal bean allows a read-only access on portlet metadata. Metadata can only be assigned with portlet-type or application-type repository objects.

Jython example: 

Portlet.parmget(ID, name)
Portlet.list(ID, "parm")
 
# only for beans with a current selection
Portlet.parmget(name)
Portlet.list("parm")
 
# example: get the metadata for an instance property named #
"MyPortletConfig"
print Portlet.parmget("MyPortletConfig")
 
# example: list all metadata names for the selected portlet
for pname in Portlet.list("parm").split():
    print pname

JACL example: 

$Portlet parmget ID name
$Portlet list ID parm
 
# only for beans with a current selection
$Portlet parmget name
$Portlet list parm
 
# example: get the metadata for an instance property named # "MyPortletConfig"
puts " [$Portlet parmget MyPortletConfig]"
 
# example: list all metadata names for the selected portlet
foreach pname  [$Portlet list parm] {
puts "$pname" 
}


Portlet Preferences

It is possible to get and set preferences to portlet instances. Because portlet beans specify a static portlet only, and not a portlet instance that resides on a page, portlet instances must be identified by two ID values: The ID of the portlet that specifies the portlet itself, plus the ID of the portlet entity piid that anchors an instance of the portlet in a page.

The command prefnames can be used to obtain a list of available preference names. Portlet preferences may have multiple values. The command getpref therefore accepts a numeric index attribute, that denotes the number of the value to be obtained (0 means to return the first preference value, 1 means to return the second value, and so on). The total number of available preference values for a specific preference name is returned by the prefcount command.

The addpref command can be used to add a new portlet preference value to the portlet preference list. Portlet preferences can be set to read-only. This can be controlled by the commands spprof ("Set Portlet Preference Read-only Flag") and gpprof ("Get Portlet Preference Read-only Flag"), respectively.

Jython example: 

Portlet.prefnames(ID, piid)
Portlet.getpref(ID, piid, name, "at", index)
Portlet.addpref(ID, piid, name, value)
Portlet.gpprof(ID, piid, name,  ["numeric"])
Portlet.spprof(ID, piid, name, readonly_flag)

JACL example: 

$Portlet prefnames ID piid
$Portlet getpref ID piid name at index
$Portlet addpref ID piid name value
$Portlet gpprof ID piid name  [numeric] 
$Portlet spprof ID piid name readonly_flag

The portlet is identified by two ID values: The ID of the portlet itself, and the ID of the portlet entity. The ID of the portlet entity can be obtained by the command $Layout get piid or Layout.get("piid").

Jython example: 

# example: set a portlet preference
# 1. locate the control where the portlet resides
# 2. obtain its the portlet instance id
# 3. set the portlet preference accordingly
ctl = Layout.find("all", "pid", Portlet.csn(), "select")
piid = Layout.get(ctl, "piid")
Portlet.addpref(piid, "MYKEY", "Value")
 
# example: list portlet preference values for key "MYKEY"
# the control ID is stored in the variable ctrl
for ix in range($Portlet.prefcount(piid, "MYKEY")):
  print Portlet.getpref(piid, "MYKEY", "at", ix)
 
# example: drop all portlet preferences on a certain key
Portlet.droppref(piid, "MYKEY")

JACL example: 

# example: set a portlet preference
# 1. locate the control where the portlet resides
# 2. obtain its the portlet instance id
# 3. set the portlet preference accordingly
set ctl  [$Layout find all pid  [$Portlet csn] select] 
set piid  [$Layout get $ctl piid]
$Portlet addpref $piid MYKEY "SomeValue"
 
# example: list portlet preference values for key "MYKEY"
# the control ID is stored in the variable ctrl
for {set ix 0} {$ix <  [$Portlet prefcount $piid MYKEY]} {incr ix} {
  puts " [$Portlet getpref $piid MYKEY at $ix]"
}
 
# example: drop all portlet preferences on a certain key
$Portlet droppref $piid  MYKEY

Dependent on the standard that the portlet complies with, there are differences in the handling of portlet preferences. Standard portlets allow to set multiple preference values on a preference key, while IBM portlets only support single values on each portlet preference key.


Themes and Skins

Themes and skins are two distinct sets of objects with a matrix relation, where each skin can be tied to any number of themes. The sets of themes and skins are accessible through the Look bean, which is referenced as $Look in JACL.

The Look bean provides access to the portal theme and skin objects:


Navigation

The Look bean currently is a simple lookup mechanism to access name and ID of the available themes and skins. It does not support a current selection, nor navigation of the matrix relation between both sets. Since that may change in the future, the deselect command is implemented. It can be used before searches to ensure that the search is global, even if a current selection is introduced in the future.

Jython example: 

Look.deselect()

JACL example: 

$Look deselect


Search

The syntax for searching is similar to the generic tree search described in Search. Since the Look bean does not support a current selection, the search is not scoped and the keyword select is not supported for the find command. The command deselect (Navigation) can be used to ensure that a search is global, even if a search scope is introduced in the future.

The Look bean supports the default search criteria, and the following keywords for node types in searches. Alternative keywords are documented in the bean help.

Since the sets of themes and skins are distinct, there is no option to search for both type of nodes at the same time.


Plain attributes

Themes and skins support the default attributes. Only the get command is available. Since there is no current selection, the ID of the node for which to obtain an attribute value has to be given explicitly.


Global lists

For ease of use, there are two global lists that hold the common name of all themes and skins, respectively. They can be accessed with the listall command, which expects the list name as an argument. The following list names are supported. See the bean help for alternative list names.

Jython example: 

# example: list the names of all themes
Look.listall("themes")
 
# example output:
Admin WebSphere Engineering Science Finance Corporate

JACL example: 

# example: list the names of all themes
$Look listall themes
 
# example output:
Admin WebSphere Engineering Science Finance Corporate


Portal Access Control

The scripting operations for access control differ fundamentally from those for content, layout or the portlet repository. The reason is that access control data is not transparently cached on the client. To avoid a huge number of round trips and annoying response times for every simple lookup operation, a different programming model has been adopted for access control data.

The collected access control data for a resource is represented on the client by an object. These objects are explicitly created, locally modified, and written back to the portal. All local modifications become effective at the time the object is written back.

Two script beans are provided for access control data. The Access bean, referenced as $Access in a script, is for reading and writing of the access control objects. The PAC List bean, referenced as $PacList, provides operations to view and edit access control objects.

The Access bean and PacList bean provide the following functionality:


Access control objects

The complete access control data for a resource is represented on the client by a so-called PacList object. PAC stands for "Portal Access Control". PacList objects are opaque, they can not be manipulated directly. Instead, they are loaded into the PacList bean, which provides the operations to view and edit the objects. PacList objects are obtained from and written back using the Access bean.

The access control data for a resource is split in similar data groups for several action sets, also referred to as role types in the information center. The term action sets will be used here, as it has the smaller potential for misinterpretation. The portal uses predefined action sets, which combine the actions for the following types of portal users. One name for each action set is given in parentheses. Alternative names are documented in the help of the PacList bean.

For each action set, there is a list of principals that are explicitly allowed to execute the corresponding actions. A principal is a group or user, which are specified by a name or distinguished name (DN). There are three special principals, which represent an anonymous user, all authenticated users, and all user groups.

In addition to the list of principals, there are two flags that control the implicit distribution of permissions through resource hierarchies. The inheritance flag controls distribution of permissions from parent to child nodes. If inheritance is not blocked, a principal that has permission on the parent will have permission on the child, too. That is particularly useful for administrative actions. The propagation flag controls the other direction. If propagation is not blocked, a principal that has permission on at least one child will have permission on the parent as well. That is useful for simple actions, like viewing a page, which requires view access to all parents.

Although the flags can be manipulated for each action set, they will be ignored for security administrators and administrators. For these two action sets, inheritance and propagation is never blocked.


Life cycle

PacList objects are read from and written back to the portal using getacl and setacl in the Access bean. The command getacl returns the PacList object for a resource. It expects the category and identifier of the resource as arguments. The category identifies the script bean that is responsible for the resource. It is given as a keyword, which can be the bean name or the type of the resource. The supported keywords are documented in the help for the Access bean. PacList objects can only be obtained for resources handled by the Content and Portlet beans. For the root node of the portlet repository, there are no PacList objects.

The command setacl writes a PacList object back to the portal. That is only necessary if the PacList object has been modified. The only argument to the command is the PacList object itself. Each PacList object is tied to a particular resource and can not be written for any other resource.

Jython example: 

Access.getacl(category, ID)
Access.setacl(paclist)
 
# example: get PacList object for a particular page
#          the object is stored in variable "acl"
Content.find("label", "uniquename",
"ibm.portal.Administration", "select")
acl = Access.getacl("Content", Content.current())
 
# example: write back PacList object in variable "acl"
Access.setacl(acl)

JACL example: 

$Access getacl category ID
$Access setacl paclist
 
# example: get PacList object for a particular page
#          the object is stored in variable "acl"
$Content find label uniquename ibm.portal.Administration select
set acl  [$Access getacl Content  [$Content current]]
 
# example: write back PacList object in variable "acl"
$Access setacl $acl

To access or manipulate a PacList object, it has to be loaded in the PacList bean. The operations of the PacList bean always refer to the PacList object currently loaded. An object can be loaded for viewing only using view, or for manipulation using edit. Both commands expect the PacList object as an argument. The PacList bean can only be loaded if it is unloaded, or if it is loaded with an object that has not been modified.

Jython example: 

PacList.view(paclist)
PacList.edit(paclist)
 
# example: load PacList object for content root, view only
PacList.view(Access.getacl("Content", Content.root()))
 
# example: load PacList object for a particular page
Content.find("label", "uniquename",
"ibm.portal.Administration", "select")
acl = Access.getacl("Content", Content.current())
PacList.edit(acl)

JACL example: 

$PacList view paclist
$PacList edit paclist
 
# example: load PacList object for content root, view only
$PacList view  [$Access getacl Content  [$Content root]]
 
# example: load PacList object for a particular page
$Content find label uniquename ibm.portal.Administration select
set acl  [$Access getacl Content  [$Content current]]
$PacList edit $acl

The command current returns the name of the loaded object, which includes the identifier of the resource. The command done unloads the PacList bean and returns the object that was loaded. If the PacList bean is already unloaded, done still returns the PacList object that was loaded before, which is useful for dealing with errors.

The command modified returns whether the currently loaded PacList object has been modified since it was loaded. If the keyword numeric is added, it returns the value of the flag as a boolean 1 or 0. Without the keyword, it returns a string "true" or "false", respectively.

Jython example: 

PacList.current()
PacList.done()
 
PacList.modified()
PacList.modified("numeric")
 
# example: write back and unload PacList object
#          only if it was modified
if PacList.modified("numeric"):
  Access.setacl(PacList.done()
 
# example: recover the last loaded PacList object
PacList.view(PacList.done())

JACL example: 

$PacList current
$PacList done
 
$PacList modified
$PacList modified numeric
 
# example: write back and unload PacList object
#          only if it was modified
if  [$PacList modified numeric] {
  $Access setacl  [$PacList done]
}
 
# example: recover the last loaded PacList object
$PacList view  [$PacList done]


Global lists

There is a global list that holds the names of the predefined action sets. It can be accessed with the listall command in the Access bean. The command expects the list name as an argument. The only supported list name is actionsets. See the bean help for alternative list names.

Jython example: 

# example: list the names of all predefined action sets
Access.listall("actionsets")
 
# example output:
Admin SecurityAdmin Delegator Manager Editor PrivilegedUser User

JACL example: 

# example: list the names of all predefined action sets
$Access listall actionsets
 
# example output:
Admin SecurityAdmin Delegator Manager Editor PrivilegedUser User


Principals

The list of principals for an action set can be access using the list command. The first argument is the name of an action set. If the second argument is the keyword all, the command returns all principals in the list, separated by newlines. A regular principal is listed with its name. A special principal is listed with a dedicated name embraced by special characters, which makes the special principals easy to spot. Since principal names can include white space, the complete list should not be parsed into items.

The principals in the list can be accessed individually. The keyword at as the second argument indicates that the third argument is an index. Alternative keywords are documented in the bean help. The command returns the principal at the given position in the list, where 0 is the index of the first position. If the index is out of range, the command returns empty. The number of principals can be obtained usingcount, which expects the name of the action set as the only argument.

Jython example: 

PacList.list(actionset, "all")
PacList.list(actionset, "at", index)
PacList.count(actionset)
 
# example: get first principal in list of administrators
PacList.list("Administrator", "at", 0)
 
# example: list all principals in all lists
for as in Access.listall("actionsets").split():
  print "Principals for " + as:" + PacList.list(as, "all")

JACL example: 

$PacList list actionset all
$PacList list actionset at index
$PacList count actionset
 
# example: get first principal in list of administrators
$PacList list Administrator at 0
 
# example: list all principals in all lists
foreach as  [$Access listall actionsets] {
  puts "/nPrincipals for $as:"
  puts  [$PacList list $as all]
}

The command grant adds a principal to a list of principals. The first argument is the name of the action set for which to add a principal. The second argument is a keyword that indicates whether a regular or special principal is to be added, as described below. The third argument specifies the principal to add. The PacList bean help documents alternative keywords for the second argument.

If the keyword name is given as the second argument, a regular principal is added. The third argument is the name of the principal, either as a fully qualified distinguished name, or as a short name. The name will only be resolved to a canonical form at the time the PacList object is written back to the portal. Therefore, it is possible to have duplicates in the list, which will be removed by the portal.

If the keyword special is given as the second argument, a special principal is added to the list. The third argument is a keyword indicating which special principal shall be added. The following special principals are supported. Alternative keywords are documented in the help for the PacList bean.

The grant command returns a success message if a principal was added to the list. It returns empty if the principal to be added was spotted as a duplicate. As mentioned above, duplicates can not be spotted by the PacList bean if names in non-canonical form are used.

Jython example: 

PacList.grant(actionset, "name", name)
PacList.grant(actionset, "special", keyword)
 
# example: grant user access to anyone authenticated
PacList.grant("User", "special", "Authenticated")
 
# example: grant editor access to John Doe - twice
PacList.grant("Editor", "name", "johndoe")
PacList.grant("Editor", "name", "uid=johndoe,dc=example_1,dc=com")

JACL example: 

$PacList grant actionset name name
$PacList grant actionset special keyword
 
# example: grant user access to anyone authenticated
$PacList grant User special Authenticated
 
# example: grant editor access to John Doe - twice
$PacList grant Editor name "johndoe"
$PacList grant Editor name "uid=johndoe,dc=example_1,dc=com"

The command revoke deletes principals from the list for an action set. The first argument is the name of the action set. The second argument is a keyword that indicates how the principal to delete is specified, as described below. Alternative keywords are documented in the help for the PacList bean. In most cases, there is a third argument that specifies the principal to be removed. The command returns a success message if a principal was removed from the list, or empty if the principal to be removed was not found.

If the second argument is the keyword all, the command deletes all principals from the list. This is the only case where more than one principal is removed. It is also the only case without a third argument.

If the second argument is the keyword at, the third argument is the index of the principal to be deleted. This addressing style is similar to the list command. It can be used to delete regular and special principals. Note that the indices of the succeeding principals are changed by this operation.

If the second argument is the keyword name, the third argument is the name of the regular principal to delete. This addressing style is similar to the grant command. Since the PacList bean can not resolve names into canonical form, the name must be given in the exact same form in which it is present in the list. If the principal was read from the portal, that will be the canonical form. If the principal was added by a previous grant command, the name in the list will be unchanged from the argument given to that command.

If the second argument is the keyword special, the third argument is a keyword for the special principal to delete. This addressing style is similar to the grant command and uses the same keywords for the special principals.

Jython example: 

PacList.revoke(actionset, "all")
PacList.revoke(actionset, "at", index)
PacList.revoke(actionset, "name", name)
PacList.revoke8actionset, "special", keyword)

JACL example: 

$PacList revoke actionset all
$PacList revoke actionset at index
$PacList revoke actionset name name
$PacList revoke actionset special keyword


Permission blocks

The command show is used to access the flags that control distribution of permissions. The first argument is the name of the action set, the second is the name of the flag to obtain. The optional keyword numeric indicates whether the flag value should be returned as a human readable string, or as a numeric value suitable for programmatic evaluation. Since the string value is subject to translation into different locales, only the numeric value can reliably be used in conditional statements. Note that the numeric value 0 indicates a block, while 1 stands for allowed distribution. The following names are supported for the two flags. Alternative names are documented in the help for the PacList bean.

Jython example: 

PacList.show(actionset, flag)
PacList.show(actionset, flag, "numeric")
 
# example: evaluate manager inheritance flag
if PacList.show("Manager", "inheritance", "numeric"):
  print "inheritance is permitted"
else:
  print "inheritance is blocked"

JACL example: 

$PacList show actionset flag
$PacList show actionset flag numeric
 
# example: evaluate manager inheritance flag
if  [$PacList show Manager inheritance numeric] then {
  puts "inheritance is permitted"
} else {
  puts "inheritance is blocked"
}

The commands block and unblock can be used to change the flags that control distribution of permissions. They expect the name of the action set and the name of the flag as the first and second argument. The block command will prevent the corresponding distribution of permissions, unblock will allow it. The commands return a success message if the flag value has changed, or empty if the flag already had the required value.

Jython example: 

PacList.block(actionset, flag)
PacList.unblock(actionset, flag)
 
# example: prevent propagation of delegator permissions
PacList.block("Delegator", "propagation");
 
# example: allow inheritance of user permissions
PacList.unblock("User", "inheritance")

JACL example: 

$PacList block actionset flag
$PacList unblock actionset flag
 
# example: prevent propagation of delegator permissions
$PacList block Delegator propagation
 
# example: allow inheritance of user permissions
$PacList unblock User inheritance


Portal authentication

The Portal bean handles functionality that is outside of the responsibility of the other beans. This includes global data as well as technical aspects of scripting, such as the scripting session with the portal. The Portal bean is referenced as $Portal in JACL.

The Portal bean provides the following functionality:


Authentication

Before any data can be accessed from a script, the user identity for script execution has to be established. The login command authenticates the scripting engine against the portal and creates a user session for the subsequent commands. There are several different options for logging in, which can be distinguished by the number of arguments. They are discussed separately in the following.

The login command with two arguments expects a user name and a password as the first and second argument, respectively. The user name identifies the portal user. It can be given as a fully qualified distinguished name, or as a login name. The portal will look up the user name and verify the password.

Jython example: 

Portal.login(user_ID, password)
 
# example: login as Portal user
Portal.login(user_ID, password)

JACL example: 

$Portal login user_ID password
 
# example: login as Portal user
$Portal login user_ID password

The login command without arguments can only be used if security is enabled in the portal. In that case, a user name and password had to be given to the application server in order to connect to the portal. The portal will accept the user identity from the connection without a second password check. This requires that the application server user is also a portal user.

Jython example: 

Portal.login()

JACL example: 

$Portal login

The login command with a single argument can only be used if security is enabled in the portal. Like the version without argument, the user identity from the connection is accepted by the portal. In addition, that user requires manage permission on the portal itself. That is the same permission required to use the XMLAccess tool.

If these preconditions are satisfied, the user name given as argument, which is different from the user name of the connection, will be looked up and taken as the portal user identity. There is no second password check. This is similar to the su command found in many OSs, which allows the super user to act as any other user, without knowing the user password.

Jython example: 

Portal.login(user_ID)
 
# example: login and change to Portal user
Portal.login("johndoe")

JACL example: 

$Portal login user_ID
 
# example: login and change to Portal user
$Portal login johndoe

The logout command terminates the scripting session and allows the portal to free the resources allocated for that session. It should always be used before the scripting client exits. The logout command also invalidates the portal data cached in the client. It is therefore possible to re-authenticate as a different user without starting a new scripting client.

Logout and re-authentication as the same user should always be performed if the connection from the scripting client to the portal is re-established using the AdminControl bean of the wsadmin tool. The portal may have lost the user session in that case, which lets subsequent operations fail.

Jython example: 

Portal.logout()

JACL example: 

$Portal logout

In a deployment scenario, the authentication should not be handled by the deployment script itself. Use a wrapper script for the authentication instead, so the deployment script can be executed under different user identities without changes. Here is an example for a wrapper script, which assumes that the deployment script defines a run_deployment procedure.

Jython example: 

# keep the user identity of the connection
Portal.login()
# execute the deployment procedure
run_deployment()
# clean up before exit
Portal.logout()

JACL example: 

# keep the user identity of the connection
$Portal login
# execute the deployment procedure
run_deployment
# clean up before exit
$Portal logout

Alternatively, the deployment script can use procedures defined in a profile script for login and logout. Profile scripts are executed on startup of the scripting client.

Jython example: 

# login function
def portal_login(user_ID, password):
  Portal.login(user_ID, password)
  # other startup operations, like logging the access
# logout function
def portal_logout():
  Portal.logout()
  # other shutdown operations

JACL example: 

# procedure for login
proc portal_login { } {
  $Portal login user_ID password
 # other startup operations, like logging the access
}
 
# procedure for logout
proc portal_logout { } {
  $Portal logout
  # other shutdown operations
}


Virtual Portal selection

The $Portal setvp or Portal.setvp() command allows you to set a virtual portal for a login or Portal.login() command. It is possible to set the virtual portal during a session, but the session only becomes effective during the $Portal login command.The virtual portal is specified by the URL context. This is the part of the home URL that identifies the virtual portal. If $Portal setvp or Portal.setvp() is invoked without a URL context, the default virtual portal is set.

Jython example: 

# example: set the virtual portal and execute a portal login
# in the example, the virtual portal URL context is employees,
# which would correspond with a base URL of
'/wps/myportal/employees'
 
Portal.setvp("employees")
 
Portal.login()

JACL example: 

# example: set the virtual portal and execute a portal login
# in the example, the virtual portal URL context is employees,
# which would correspond with a base URL of '/wps/myportal/employees'
 
$Portal setvp employees
 
$Portal login


Examples


Delete portlets

Jython example: 

# delete all welcome-portlets from all pages of a user
# see the Authentication section for portal_login and
portal_logout
portal_login(user_ID, password)
for page in Content.search("pages").split():
  Content.select(page)
  for c in Layout.search("control", "commonnamehas",
"Welcome").split():
    Layout.delete(c)
 
portal_logout()

JACL example: 

# delete all welcome-portlets from all pages of a user
# see the Authentication section for portal_login and portal_logout
portal_login
foreach page  [$Content search pages] {
  $Content select $page
  foreach c  [$Layout search control commonnamehas Welcome] {
    $Layout delete $c
   }
 }
portal_logout


Add portlets

Jython example: 

# add a FunPortlet next to each WeatherPortlet
 
# procedure: add a portlet next to a control
# this changes the current selection of the Layout bean
def add_portlet(control, portlet):
  Layout.select(control)
  pos = Layout.get("position")
  pos = pos + 1
  Layout.select("the", parent)
  Layout.create("control", portlet, "select")
  Layout.move("to", pos)
 
# main program
# see the Authentication section for portal_login and
portal_logout
 
portal_login(user_ID, password)
fun = Portlet.find("portlet", "nameis", "FunPortlet")
 
for page in Content.search("pages").split():
  Content.select(page)
  for c in Layout.search("control", "commonnamehas",
"Weather").split():
    add_portlet(c, fun)
 
portal_logout()

JACL example: 

# add a FunPortlet next to each WeatherPortlet
 
# procedure: add a portlet next to a control
# this changes the current selection of the Layout bean
proc add_portlet { control portlet } {
  global Layout
  $Layout select $control
  set pos  [$Layout get position]
  set pos  [expr $pos + 1]
  $Layout select the parent
  $Layout create control $portlet select
  $Layout move to $pos
}
 
# main program
# see the Authentication section for portal_login and portal_logout
 
portal_login
set fun  [$Portlet find portlet nameis FunPortlet]
 
foreach page  [$Content search pages] {
  $Content select $page
  foreach c  [$Layout search control commonnamehas Weather] {
    add_portlet $c $fun
  }
}
portal_logout


Troubleshooting


Property File Format

Locale specific attributes for a set of locales can be provided in a Java property file. The generic format of Java property files is described in the Java API documentation for method load in class java.util.Properties. The description here covers the particular properties that will be interpreted when locale specific attributes are loaded from a portal script.

The property files are loaded by the script interpreter. They have to be located on the client machine where the script is run. A property file must be encoded in the ISO 8859-1 character encoding format.

Here is an example of a property file with no prefix.

Jython example: 

locales = en de
 
en.title = English Title
en.description = A description, in English.
 
de.title = Deutscher Titel
de.description = Eine Beschreibung auf Deutsch.

At the core of the file is the property locales, which holds a white space separated list of the locales for which attributes are defined in the file. Only the locales listed here will be interpreted when the property file is loaded.

The actual attribute values for each locale are defined as separate properties. The key for these properties is composed of the locale and the attribute name, separated by a dot. The attribute name is title or description, the locale must match the string listed in the locales property. Case is significant for property keys.

There is no fallback algorithm when loading locale specific attributes. If a property title.en is defined, it will not be considered when the title for locale en_US is required.

To combine different sets of localized data into a single property file, prefixes can be used. All properties of a set have to use the same prefix, which is separated from the property name by a dot. Here is an example of a property file with two sets, using the prefixes leisure and finance, respectively.

Jython example: 

leisure.locales = en fr
leisure.en.title = Leisure Page
leisure.fr.title = Page de Loisir
 
finance.locales = en de
finance.en.title = Finance Page
finance.en.description = Holds financial info portlets.
finance.de.title = Finanzseite

You can also load property files in the scripting format by using the XML configuration interface. To do this, specify the locale as part of the prefix in a localedata tag.


Index paths

Index paths are used to refer to components in the component hierarchy. They are based on the index or position of a component in the surrounding container. An index path is a multi-dimensional index of a component, where the number of dimensions is equal to the depth of the component in the tree. Index paths can be absolute or relative, depending on whether there is a leading slash. Absolute paths start with a leading slash and are resolved from the root component. Relative paths start with a number and are resolved from the selected component. Trailing slashes are irrelevant.
/


/0


/1


...
/0/0


/0/1


...
/5/1/3


...
0


1


...
1/0


...


Parent

Portal Scripting Interface
About the Portal Scripting Interface
Work with the Portal Scripting Interface


Related tasks


Get started with the Portal Scripting Interface

 


+

Search Tips   |   Advanced Search