+

Search Tips   |   Advanced Search

Portal Scripting Interface

Use the Portal Scripting Interface to configure the portal by running scripts from a command line.

To start the Portal Scripting Interface...

The Portal Scripting Interface returns the following response:

At the command prompt wsadmin> use the following command:


Search for a page

For example...

If a page with the specified unique name exists, the Portal Scripting Interface returns the object ID of the page as follows:

If we are not sure whether the resource is a page or a label we can specify the type "any" instead of page...


Find out information about a portal page

To display some standard information about a portal resource, use the details() command. Specify for which resource you want more detailed information. For example...

This returns the following response:

To find information about a portal resource, specify the resource. If you do not specify the resource, for example, by entering only wsadmin>Content.details(), you get a response such as the following:

Here are some more examples for requesting information about a portal page:

The following example shows the hierarchy of a page:

To get a human readable list...

With this simple loop we can print out the whole hierarchy of nodes up to our currently selected 'Getting Started' page.


Create a page

To create a page as a child page to the currently selected page:

This command creates a page for HTML markup and returns its portal object ID. We can now start adding attributes or metadata to the page.


Add a portlet to a page

To add a portlet to a page...

This adds the Information portlet to the page and places it in a horizontal container.

To find out more detail about the search types...

This returns the following help information about the search criteria:

To find out about the search criteria:

To find out which command the Content bean supports...

This returns the following help output:


Logging out of the portal

After completing working with the Portal Scripting Interface, you log out and exit the interactive scripting console.

Enter the following commands:


Work with the Portal Scripting Interface

The Portal Scripting Interface provided by IBM WebSphere Portal is based on the wsadmin scripting toon that is provided by IBM WAS. Therefore, before we use the Portal Scripting Interface, familiarize yourself with how to use the WAS wsadmin tool.


Interactive mode

Use the interactive mode to interact directly and dynamically with the portal to perform simple administrative tasks that should only be executed once.

For example, the administrator wants to modify the permissions of a page for a certain principal, or the administrator wants to add a portlet to a page. Use the interactive mode if you do not intend to repeat the operation.

Before initiating a session in interactive mode, make sure that WebSphere Portal is running. The portal script client is located in the WebSphere Portal installation directory:

Log in using the admin user ID, and invoke the portal script client:

Parameters...

Parameter Description
-lang

Language of the script file, command, or an interactive shell. Specify one of the following values for the -lang parameter:

  • jacl
  • jython

Optional and has no default value. This option overrides language determinatione that are based on script file names, profile script file names, or the com.ibm.ws.scripting.defaultLang property.

Important: If you do not specify the script language in the command line or as a parameter, and the wsadmin tool cannot determine the script language, an error occurs. If you do not specify the script language as the value for -lang, the wsadmin tool determines the script language as follows:

  • If we specify the -f script_file_name argument, the wsadmin tool determines the language from the name of the target script file.

  • If we specify the -profile profile_script_name argument, the wsadmin tool determines the language from the name of the profile script.

-conntype

The type of connection that should be established between scripting. Valid connection types include:

Default is SOAP. Optional. Use the -conntype NONE option to run in local mode. The result is that the scripting client is not connected to a running server. If the connection type NONE is selected, the scripting beans are inactive and cannot be used for administration, with the exception of the help command.

-port The connection port number. This parameter is optional.

The port number depends on values chosen during installation. We can verify the value set for the WasSoapPort property in the properties/wkplc.properties file found in the appropriate directory given here:

    WP_PROFILE/ConfigEngine

If we are running wpscript on a machine that is part of a cell managed by a dmgr, the port_number can vary depending on what ports are in use on the system when the dmgr is created. To verify the value, check the setting for SOAP_CONNECTOR_ADDRESS in serverindex.xml located in the appropriate directory given here:

    DMGR_PROFILE/config/cells/cell_name/nodes/node_name

For z/OS: The name of the connection port. This is the SOAP port of the portal server. This parameter is optional. To determine the SOAP port, access the WAS admin console, navigate to yourPortalServerName > End Points > SOAP_CONNECTOR_ADDRESS.

For example, if we are running wpscript on a machine that is part of a cell managed by a dmgr, the SOAP port might be 10033.

-user

The user ID under which you establish the connection. This parameter can be mandatary, depending on the security configuration.

-password

The password for the user ID under which you establish the connection.

  • Log on to the portal using one of the following script commands:

    Jython: Portal.login("user_ID", "password")

    JACL: $Portal login user_ID password

  • Issue portal script commands as required.

  • After you have completed all tasks by the portal scripting interface, close and exit the script processor. All changes that you committed are applied to the portal configuration.


    Script mode

    Use the script mode to apply predefined changes to the configuration of a portal.

    The wpscript tool executes a Jython or JACL script containing the administrative operations. The scripting client inherits the script processor from wsadmin, so an administrator can exploit the Jython or JACL scripting language, in order to write re-usable, extendable administration scripts. This mode is typically preferred if reproducible administration tasks are created:

    For example, the administrator can write a script that produces a complete page subtree, and adds individual page layouts and portlets on each page.

    Users who have access permission to perform xmlaccess.sh requests can change configurations of all resources. The Portal Scripting Interface is mostly consistent with the administration modes that is exposed by the Portal user interface.

    Before using script mode, make sure that WebSphere Portal is running and a portal script file is available. Be logged in using the WebSphere admin user ID. Use the following procedure:

    1. Update the script file with the appropriate credentials, if required.

    2. Use one of the following commands to launch the script processor tool:

      Jython: wpscript.sh -port port_number -f script_file_name.py

      JACL: wpscript.sh -port port_number -f script_file_name.jacl This initializes the interactive script environment of the portal JACL or Jython script processor.

    3. In the directory WP_PROFILE/PortalServer/bin to launch the script processor tool:

      Jython: wpscript.sh -port port_number -f script_file_name.py

      JACL: wpscript.sh -port port_number -f script_file_name.jacl

      This command initializes the script environment of the portal script processor. Be logged in at the z/OS console using the WAS admin user ID.

    4. Check the output from the script processor to ensure that no errors occurred during the execution of the script.

    All changes committed by the script are immediately applied to the portal configuration.

    The following script example creates a new page with the title A page. This page resides beneath the Home label. The page contains two portlets that are arranged horizontally.

      Portal Jython script example

      The following example is a Jython script file named testme.py: 
      # Scripting bean example: create a simple page (multi-column Layout)
#

# Procedure: create a multi-column page under the page that is currently
# selected, and place the given portlets into the layout.
#
# parameters:
#   name The name of the page 
#   portlet_names A list of portlet names.
# returns:
#   oid The id of the page that has been created def create_multi_col_page(name, portlet_names):
    thePage = Content.create("page", name, "html")
    Content.select(thePage)
    lyt0 = Layout.create("container", "horizontal", "select")
    for pn in portlet_names:
        pid = Portlet.find("portlet", "cn", pn)
        Layout.create("control", pid)

    return thePage


# main code starts here 
# set User ID/ pwd for portal Login command 
# Hint: User ID and passwords should normally not be placed inside a 
# configuration script; better use property files or command line arguments
user = "user_ID"
pwd = "password"
Portal.login(user, pwd)

# determine and select the parent of the page to be created.
# In this example, This is the "Home" label.
Content.select(Content.find("all", "uniquename", "ibm.portal.Home")

# Invoke the page creation procedure. The label of the page is "My test page", 
# portlets to be added are the reminder portlet and the welcome portlet.
newbie = create_multi_col_page("A Page", ["Reminder", "Welcome_to_WebSphere_Portal"])

print "ok, we are done."

      Portal JACL script example

      The following example is a JACL script file named testme.jacl: 
      # Scripting bean example: create a simple page (multi-column Layout)           
#                                                                              

# Procedure: create a multi-column page under the page that is currently       
# selected, and place the given portlets into the layout.                      
#                                                                              
# parameters:                                                                  
#   name              The name of the page                                     
#   portlet_names     A list of portlet names.                                 
# returns:
#   oid               The id of the page that has been created                 
proc create_multi_col_page { name portlet_names } {                            
  global Content Layout Portlet                                                
    set thePage [$Content create page $name html]                              
    $Content select $thePage                                                   
    set lyt0 [$Layout create container horizontal select]                      
    foreach pn $portlet_names {                                                
      set pid [$Portlet find portlet cn $pn]                                   
      $Layout create control $pid                                              
    }                                                                          
  return $thePage                                                              
}                                                                              
                                                                               
# main code starts here                                                        
                                                                               
# set User ID/ pwd for portal Login command                                    
# Hint: User ID and passwords should normally not be placed inside a          
# configuration script; better use property files or command line arguments    
set user user_ID                                                           
set pwd  password                                                              
$Portal login $user $pwd                                                       
                                                                               
# determine and select the parent of the page to be created.                   
# In this example, This is the "Home" label.                              
$Content select [$Content find all uniquename "ibm.portal.Home"]                 
                                                                               
# Invoke the page creation procedure. The label of the page is "My test page", 
# portlets to be added are the reminder portlet, and the welcome portlet.   
set newbie [create_multi_col_page "A Page" { "Reminder" "Welcome_to_WebSphere_Portal" } ]
                                                                               
puts "ok, we are done."

    The scripts can receive parametric information externally, using one of the following features:

    • Profiles.
    • Command line arguments.

    Scripts can access command line arguments with the following variables:

      argc

      Use this variable in JACL scripts to specify the number of command line arguments.

      argv

      Use this variable in Jython and JACL scripts to specify the command line arguments.

    Jython: In the preceding example script, testme.py, delete the following statements: 

    user = "portaladmin"
pwd = "adminpwd"

    ...and replace them with the following... 

    if len(sys.argv) != 2:
   print "invocation syntax: wpscript testme.py <user> <pwd>"
   sys.exit(1)

user = argv[0]
pwd = argv[1]

    JACL: In the preceding example script, testme.jacl, delete the following statements: 

    set user portaladmin                                                           
set pwd  adminpwd

    ...and replace them with the following... 

    if { $argc != 2 }  {
    puts "invocation syntax: wpscript testme.jacl <user> <pwd>"
   exit
  }
  set user [lindex $argv 0]
  set pwd [lindex $argv 1]

    The security-sensitive username and password are removed from the script. The modified code expects the user ID and password to be specified as command line arguments, for example:

    Jython: wpscript.sh -port port_number -f testme.py user_IDpassword
    JACL: wpscript.sh -port port_number -f testme.jacl user_ID password


    Run scripting commands in a profile

    A profile is a script that runs before the main script, or before entering interactive mode. Profiles can be used to set up environment specific behavior or user specific data. Profiles are specified when invoking wpscript, using the -profile parameter.

    For example, the login command can be placed in a profile.

      Jython profile script example

      The following example is a Jython profile script named mylogin.py: 

      # scripting profile 
# contains log-in procedure on portal with disabled security if len(sys.argv) != 2:
   print "invocation syntax: wpscript -f testme.jacl -profile
mylogin.py user_ID password"
   sys.exit(1)

user = argv[0]
pwd = argv[1]
Portal.login(user, pwd)

      Remove or comment out the following statements in the testme.py script file: 

      if len(sys.argv) != 2:
   print "invocation syntax: wpscript testme.py user_ID password"
   sys.exit(1)

user = argv[0]
pwd = argv[1]
Portal.login(user, pwd)

      To invoke mylogin.py command: wpscript.sh -port port_number -profile mylogin.py -f testme.py user_ID password

      JACL profile script example

      The following example is a JACL profile script named mylogin.jacl: 

      # scripting profile 
  # contains log-in procedure on portal with disabled security   if { $argc != 2 }  {
    puts "invocation syntax: wpscript -f testme.jacl -profile mylogin.jacl user_ID password"
   exit
  }
  set user [lindex $argv 0]
  set pwd [lindex $argv 1]
  $Portal login $user $pwd

      Remove or comment out the following statements in the testme.jacl script file: 

        if { $argc != 2 }  {
    puts "invocation syntax: wpscript testme.jacl user_ID password"
    exit
  }
  set user [lindex $argv 0]
  set pwd [lindex $argv 1]
  $Portal login $user $pwd

      To invoke mylogin.jacl command: wpscript.sh -port port_number -profile mylogin.jacl -f testme.jacl user_ID password

    The benefit of this change is that the environment-specific login procedure is removed from the administration script. For systems with enabled WAS security, the login procedure is as follows:

      Jython scripts

        # scripting profile 
  # contains log-in procedure on portal with enabled security   Portal.login()

      JACL scripts

        # scripting profile 
  # contains log-in procedure on portal with enabled security   $Portal login


    Command reference for Portal Scripting Interface


    The IBM 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 us to access the portal with any portal user ID and work within the access rights on that user ID. This topic gives a description of the available commands.

    For the scripting syntax we can use Jython or JACL; these are the two scripting languages supported by the wsadmin tool of the WAS.


    Jython

    Jython is a general-purpose high-level programming language. It uses code indentation as block delimiters. This section provides a basic overview of Jython so that you will understand the examples used in this section.

    • The character # starts a commenu that extends to the end of the line.
    • By default, each line is interpreted as one statement.
    • We can write multiple statements on one line by separating the statements with semicolons.
    • Jython is case-sensitive.

    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 using the object as the first part of a statement followed by a dot ( . ), followed by the method name, followed by argumento 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 language without strong typing. It is a procedural language with some object oriented concepto used by the scripting component. This section provides a basic overview of JACL so that you will understand the examples used in this section.

    • The hash sign character ( # ) starts a comment that extends to the end of the line.

    • By default, each line is interpreted as one statement.

    • We can write multiple statements on one line by separating the statements with semicolons.

    • We can nest statements using brackets [] , which are interpreted like back quotes in most UNIX shells: the statement within is executed, and its result substituted in place of the bracketed statement before interpreting the surrounding statement.

    • JACL is case-sensitive.

    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 using the object as the first part of a statement, followed by the method name, followed by any argumento 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 Beand that provide access to specific areas of the portal data.

    The available beans are:

    • Portal
    • Content
    • Layout
    • Portlet
    • Look
    • Access
    • PacList
    • Application
    • ArchivedApplication
    • ApplicationCategory
    • TemplateCategory
    • Publish

    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 we 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 bthat 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 windows 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

    We can select a node by its ID using the select command. We can clear the current selection using deselect or using select without an argument. We 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 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 under 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

    We 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 wito 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:

    • title
    • description
    • shorttitle
    • keywords

    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 lowercase and the country in uppercase letters. The components are separated by underscore characters. Here are some example locales:

    Locale Description
    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 algoriththat 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. Additional to the arguments for the nlsget command, specify the new value of the attribute as the last argument. By setting an attribute for a locall that was not used before, the new locale is added to the list valued attribute "locales" mentioned previously.

    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 has a set of locales. By specifying an appropriate prefix, we can load values from the same property file used by xmlaccess.sh (XMLAccess).

    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 has 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, we can change the parent of a node in the tree, thereby moving the whole subtree under 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, whereas 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 under 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 under 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:

    • Methods that allow to navigate in the content tree hierarchy, refer to Navigation.

    • Methods to locate a content node , or to search for particular content nodes, refer to Search.

    • Methods for getting and setting attributes or metadata. The following attribute types are supported by the Content bean.

      • Plain attributes
      • List valued attributes
      • Locale specific attributes
      • URL attributes
      • Metadata attributes

    • Methods to create or delete pages, labels, or URL links, or to derive pages, refer to Life Cycle.

    • Methods to move pages, labels, or URL links, Refer to Organization.


    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.

    • label
    • composition or page
    • internalurl
    • externalurl
    • url (either internal or external)
    • all or any

    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 flas 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:

    Jython: 

    Content.get(oid, attribute, markup)

    JACL: 

    $Content get oid attribute markup

    Valid attributes are as follows:

      filename

      Gets the file name of the static page layout file contained in the ZIP archive.

      displayoption

      Specifies markup languages such as HTML.

    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:

    Jython example: 

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

    JACL example: 

    $Content set oid attribute value markup

    Valid attributes are filename and displayoption.

      filename

      Gets the file name of the static page layout file contained in the ZIP archive.

      For example, to set the entry point to display anotherindex.html for the specified markup:

      Jython: Content.set(6_CGAH47L00G2N802TJFV58Q3000, filename, anotherindex.html, html)
      JACL: $Content set 6_CGAH47L00G2N802TJFV58Q3000 filename anotherindex.html html

      displayoption

      Specifies markup languages such as HTML. Valid options for displayoption are: inline, iframe, and ajax.

      For example, to set the display option to iframe for the specified markup:

      Jython: Content.set(6_CGAH47L00G2N802TJFV58Q3000, displayoption, iframe, html)
      JACL: $Content set 6_CGAH47L00G2N802TJFV58Q3000 displayoption iframe html


    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 on 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 datag 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 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 under 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 under the new label 

$Content select the root 
$Content create label "Leisure" html select 
$Content derive "Movies" from node_ID

    To create a static page:

    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, we can use the optional parameter displayoption. This parameter takes one of the following values inline, iframe, or ajaxDefault 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:

    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:

    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. Nodethat 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 hierarchiethat 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:

    • Navigate in the layout hierarchy, refer to Navigation.

    • Locate a layout node, or to search for particular layout nodes, refer to Search.

    • Getting and setting attributes or flags. The following attribute types are supported by the Layout bean:

      • Plain attributes.
      • Global flags

    • Methods to create or delete layout objects, refer to Life Cycle.

    • Methods to move or transfer layout objects, refer to Organization.


    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.

    • container
    • control
    • all or any

    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 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. 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 is 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, you must explicitly specify the ID even if the node is selected. We 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:

    • Methods to navigate in the portlet repository tree, refer to Navigation

    • Methods to locate a portlet, application, or web module, or to search for particular repository objects, refer to Search.

    • Methods for getting attributes, metadata, or portlet preferences.

      The following attribute types are supported by the Layout bean:

      • Plain attributes
      • List valued attributes
      • Locale specific attributes
      • Portlet metadata
      • Portlet preferences


    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.

    • webmodule, webmodules, module, modules, wm, w, m
    • application, applications, app, apps, a
    • portlet, portlets, p
    • concrete (portlet or application)
    • abstract (webmodule)
    • all or any

    In addition to the default search criteria, the Portlet bean supports two criteris 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 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).

    • title
    • shorttitle
    • keywords
    • description

    Only the nlsget command is available for locale specific attributes.


    Portlet Metadata

    Portlet nodes can own metadata, which are name/value pairs of datag 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 piis 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 attributes 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 standare 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:

    • Search on themes, refer to Search.
    • Get attributes, refer to Plain attributes.
    • Retrieve theme and skin lists, refer to Global lists.


    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. Sincthat may change in the future, the deselect command is implemented. It can be used before searches to ensures 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.

    • theme
    • skin

    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 listo 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.

    • themes
    • skins

    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 large number of requests and slow 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 when 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 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:

    • Methods to request or release access list objects, and to load the permission set for view, edit, or manage permissions, refer to Life cycle.
    • Methods to get a list of available action sets, refer to Global lists.
    • Methods to grant or revoke access for principals on the portal resource, or to view the permissiondefined for the portal resource, refer to Principals.
    • Methods to set or clear permission blocks, refer to Permission blocks.


    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 principalthat are explicitly allowed to execute the corresponding actions. A principal is a group or user, which are specified by a name or 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 flagthat 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 principas that has permission on the parent will have permission on the child as well. This is particularly useful for administrative actions. The propagation flag controls the other direction. If propagation is not blocked, a principas that has permission on at least one child will have permission on the parent as well. This is useful for simple actions, such as 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 using count, 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 keyworthat indicates whether a regular or special principal is to be added, as described later. 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.

    • anonymous - a user that is not logged in
    • authenticated - any user logged in
    • allgroups - any group of a user logged in. This virtual user group contains all non-virtual user groups.

    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 earlier, duplicates cannot 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 keyworthat indicates how the principal to delete is specified, as described later. Alternative keywords are documented in the help for the PacList bean. In most cases, there is a third argumenu 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 portals 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 flagthat 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.

    • inheritance - from the parent to this node
    • propagation - from the children to this node

    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 flagthat 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:

    • Methods to perform a login and logout. For details refer to the section about Authentication.
    • Methods to set a virtual portal.


    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. Ithat 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 operating systems, 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 is 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 us 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

    • connectivity problem / MBean not found -> connected to wrong application server
    • bean not enabled -> not logged in
    • Layout bean not enabled -> no page selected in Content bean
    • PacList bean not enabled -> no PacList object loaded
    • no method named "xxx" -> typo or capitalization in method name, check bean help
    • no method named "xxx" with y arguments -> wrong syntax, check bean help


    Property File Format

    Locale specific attributes for has 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

    We can also load property files in the scripting format using xmlaccess.sh. 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.

      /
      The root component.
      /0
      The first child of the root component.
      /1
      The second child of the root component.
      ...
      /0/0
      The first child of the first child of the root component.
      /0/1
      The second child of the first child of the root component.
      ...
      /5/1/3
      The fourth child of the second child of the sixth child of the root component.
      ...
      0
      The first child of the current component.
      1
      The second child of the current component.
      ...
      1/0
      The first child of the second child of the current component.
      ...


    Parent: Portal Scripting Interface
    Related:
    About the Portal Scripting Interface
    Work with the Portal Scripting Interface
    Related:
    Get started with the Portal Scripting Interface