XML Import FAQ

Table of Contents

1. Overview
2. XML Import Schema Basics
3. Basic Topics
   1. Deployment Options
   2. MWS Pages & Folders
   3. Content
4. Advanced Topics
   1. Aliases
   2. Renderers (Relation)
   3. Wiring
   4. Resource Bundles
   5. Includes
   6. Execute Command
   7. Delete
5. Principals
   1. (System) Users
   2. (System) Groups
   3. Adding principals to Groups and Roles
   4. (Static) Roles
   5. System Directory Service (ldif)
   6. LDAP Directory Service
   7. DB Directory Service
   8. LDAP Query Roles
   9. Dynamic Role Attributes
   10. Dynamic Role Attributes -- User Overrides
6. Security
   1. Permissions
   2. Authentication Schemes
   3. Security Realms
7. Reference
8. External Links

Overview

My webMethods Server was designed to allow the dynamic deployment of any MWS resource to occur at runtime without requiring a restart. This includes the deployment of items such as: Portlets, MWS Pages, Skins, Shells, Aliases, Rules, etc... Since Portlets are developed in the CAF Designer IDE, the technique for deploying Portlets is fairly well documented. The other resources (eg: MWS Pages) are created and configured inside the MWS itself. There are two main techniques for migrating these other types of resources from one MWS to another MWS: Content Migration Wizard and Deployer. Both of these tools are geared towards MWS Administrators running production portal installations. This document focuses on a third use case: CAF Developers who are pre-packaging MWS Pages and other MWS resources for distribution.

XML Import Schema Basics

MWS Resources are imported by xml documents. There isn't a schema or dtd for these documents, but there are some guidelines to follow.

All xml import documents must start with a <Config> Node.
The simplest possible xmlImport document (that does nothing) would look like this: <!--Does nothing--> <Config />
Location/Context: All portal resources live somewhere inside of the MWS's folder structure. In order to create your resources in the appropriate location you should use the <Context> Node to set the current 'root'. The <Context> node takes an attribute: 'alias'.
The following snippet demonstrates creating a folder inside of Public Folders. <Config> <!--Set the current 'root' to be the public folder--> <Context alias="folder.public"> <folder name="test folder" /> </Context> </Config>
Types: All instances of portal resources are identified by their type name (eg: wm_htmltext, wm_wikiobject, etc...) In order to create an instance of any type of portal resource you just use the type name as the Tag name of the xml element.
The following examples create a bunch of different types of objects with default properties. <Config> <!--Set the current 'root' to be the public folder--> <Context alias="folder.public"> <wm_bam_tree name="Business Process Tree" /> <wm_htmltext name="Empty Text" /> <wm_folderview name="Current FolderView" /> <wm_xt_wikiobject name="Wiki Page"> <wm_sessionmonitor name="Session Monitor" /> </Context> </Config>
Properties: You can set any property on a portal resource by using the appropriate property name for that type. NB: These are the portlet descriptor names of the properties and not their display names. (eg: 'Name' vs 'name')
In the previous examples, we we're already setting the name. The following examples create the some objects and also sets some properties on those resources besides just the name. <Config> <!--Set the current 'root' to be the public folder--> <Context alias="folder.public"> <wm_htmltext name="Hello World Text Portlet" HTMLText="This is some sample text for this portlet"/> <link name="Link to www.webmethods.com" URL="http://www.webmethods.com" /> <wm_xt_shortcut name="Web Page" URL="/webApp/presManager/webPageRenderer"/> <wm_portletinportlet name="Nested Portlet" proxyThingID="user.current.fabric.home" subrenderer="pageinportlet"> <wm_simplelink name="Home" newWindow="false" proxyThingID="global.navlink.home" reuseWindow="false" truncate="50" visualStyle="1" /> <wm_menubar name="My Folders" listViewTargetURI="user.current.home" sort="name" /> <wm_listoflinks name="Siblings" linkType="basic" pageSize="10" rootFolder="current.resource.parent" showSelectedItem="true" /> </Context> </Config> Furthermore, if you need some more control over setting a property, you can use a variant like the following: <Config> <!--Set the current 'root' to be the public folder--> <Context alias="folder.public"> <folder name="Folder with a description> <property name="description"> I want to add a fairly long description with "quotes" and other stuff. </property> </folder> </Context> </Config>

Basic Topics

Deployment Options

At the heart of any Importing of MWS Resources is the main xml document containing the MWS resources. As long as the xml import conforms to the guidelines above, it may be deployed in one of three types of packages:

• Simple xml file Give the document an extension of 'xml' and deploy it.
• In a Portlet Specifically name the document 'xmlImport.xml', place it into a WEB-INF/config directory of your portlet, and deploy the portlet.
• In a 'cdp' component Create a directory structure like wm_myportalpage/WEB-INF/config and place your xmlImport.xml file into the config directory. Then build and deploy the cdp file like you would any other portlet.

MWS Pages & Folders

A MWS Page is created with the <folder> tag. Because it is a container, it can contain nested child nodes of other portlets and portal resources like the following:

In the example above, there are no attributes set on the <page>, <column>, or <row>. However, you may set some attributes on both the <column>, or <row> as in the following:

If you are using the WebPage renderer which hides any Auto-Positioned Portlets, then you will want to use <hobos> tag. This is demonstrated in the example below. (Please note, the relation tag hasn't been defined yet, but will be in the Advanced Topics section)

Another common thing when modifying a MWS Page Layout is to hide the titlebars and/or the borders of portlets. This technique uses the <layout> tag as in the following example.

Content

Content (documents) can be created in the same manner as any other MWS resource. The one key thing to note is that the actual contents of the file must be available with the xml import as well (eg: the bytes of the file whether it is plain text or binary). This means that you have can need to use either the cdp or the pdp option when deploying an xmlimport with content. (see Deployment Options). When defining a content item to import you must set a special attribute 'content' which points to the location inside of your deployable component as in the following example:

Advanced Topics

Aliases

Aliases are a portable, convenient mechanism to uniquely identify MWS Resources. Every MWS Resource has a unique ID, but those ids are not portable from one MWS installation to another, where aliases are portable. Aliases come in two flavors: system aliases and non-system aliases. There is no difference in their behavior, just in whether they can be easily edited or removed. (You get a warning in the Alias Administration Portlet if you attempt to remove or modify a system alias.) The following examples demonstrate how to set multiple aliases on multiple resources.

Renderers (Relation)

Renderers are an important concept in the MWS that helps to decide how a specific MWS Page should be displayed. Some common renderers are: MWS Page Renderer, Folder Details Renderer, Web Page Renderer, Thumbnail Renderer, etc... As a MWS administrator/user you would typically set these by browsing to the Properties page of an item and modify its Display Properties. There are two main types of display properties you can set: Full Page View and Portlet View. They represent how an item will appear when it's Maximized, and how the item will appear when it is placed on a MWS Page. The following table shows some of the common renderers that are available:

Name	Type	Description	Alias	Usage
Properties	Full Page	Used to draw the properties page of a MWS Resource	renderers.properties	<folder name="Show Properties"> <relation path="renderers.properties" type="renderer"/> </folder>
Folder Details	Full Page	Used to draw the current MWS page as a detailed list	renderers.details	<folder name="Show Folder Details"> <relation path="renderers.details" type="renderer"/> </folder>
Thumbnails	Full Page	Used to draw the current MWS page as a series of thumbnails	renderers.thumbnails	<folder name="Show Folder Thumbnails"> <relation path="renderers.thumbnails" type="renderer"/> </folder>
WebPage	Full Page	Used to draw the current MWS page as a MWS page but hides any auto-positioned portlets	folder.presManager.renderers/webpagerenderer	<folder name="Show Web Page View"> <relation path="folder.presManager.renderers/webpagerenderer" type="renderer"/> </folder>
Folder Details	Portlet View	Used to draw the current folder in details on a MWS Page	portlet.pseudo.folderview	<folder name="Show Folder Details in MWS Page"> <relation path="portlet.pseudo.folderview" type="portlet.pseudo"/> </folder>
Simple FolderView Details	Portlet View	Used to draw the current folder in simple details on a MWS Page	portlet.pseudo.folderview.simple	<folder name="Show Simple Folder in MWS Page"> <relation path="portlet.pseudo.folderview.simple" type="portlet.pseudo"/> </folder>
List of Links	Portlet View	Used to draw the current folder with a simple List of Links on a MWS Page	portlet.pseudo.listoflinks	<folder name="Show List of Links in MWS Page"> <relation path="portlet.pseudo.listoflinks" type="portlet.pseudo"/> </folder>
Thumbnails	Portlet View	Used to draw the current folder with thumbnails on a MWS Page	portlet.pseudo.folderview.thumbnails	<folder name="Show Thumbnails in MWS Page"> <relation path="portlet.pseudo.folderview.thumbnails" type="portlet.pseudo"/> </folder>

Wiring

When creating Composite Applications, you typically will be wiring properties from one portal to the next. The following example demonstrates how to create an xmlImport that captures this wiring information. Please note, that all wired properties must use aliases instead of IThingIDs.

Resource Bundles

Resource Bundles are generally only used deploying HTMLText portlets with localizable strings. The following demonstrates this technique:

Includes

Occasionally, the xmlImport files get so large that you want to split them into smaller pieces. Using the include will assist with this:

Execute Command

This statement allows you to exectue MWS Verbs (aka Commands). The following examples demonstrate this technique:

Delete

This is a short cut for invoking the delete command.

Principals

(System) Users

Users can be imported into the MWS's internal System Directory Service much like you would import a folder into the MWS.

(System) Groups

Similar to users, Groups can be created in the same fashion. Notice how the following example takes care to have the same attributes for name, groupName and the cn part of the dn.

Adding principals to Groups and Roles

Now that we've created some internal users and groups, we might want to add some of these users to some of the groups or roles. The following command demonstrates this as well as why you would want to assign aliases to the previously imported users and groups and roles.

(Static) Roles

Roles come in a variety of 'flavors' depending on their implemenetation. The simplest type of role is a Static Role where the members are statically defined from any available user, group or role in the MWS Directory System. Static Roles are fairly similar to users and groups, but due to the ability to have different implementation patterns, in order to define a static role you need to define both the storage of the role and the MWS System definition of a role. In the following example we add the previous group and user to a new static role:

System Directory Service (ldif)

We've seen how to incrementally add a user and a group, but we also have the ability to perform a bulk import by using the LDIF standard. This gives us the ability to define users, groups and group membership in one file. In order to perform a bulk ldif import you will need to use two files, the xmlImport file as well as the ldif file. In order to create the simplest possible cdp for an ldif import create the following directory structure:

LDAP Directory Service

In order to automatically import a connection to an external ldap directory service you can use the following example that specifies the minimum necessary connection info. The exact parameters may vary based on your customized LDAP directory service (AD/ADAM/etc...)

DB Directory Service

The databased directory service is similiar in concept to the LDAP dir service but there are many more parameters that are highly dependent on the external database schema.

LDAP Query Roles

In a previous step we've created both static roles and created connections to an external ldap directory service. Now we can combine those techniques and create a role based upon an ldap query.

Dynamic Role Attributes

In order to assign dynamic attributes to roles, you will execute four different ModifyPrincipal commands. They will separately modify:

• displayList: This is the CSV list of Display names for the attributes
• nameList: This is the CSV list of internal names for the attributes
• typeList: This is the CSV list of types for the attributes (string,integer,boolean,long,float,double,date)
• valueList: This is the CSV list of values for the attributes

Dynamic Role Attributes -- User Overrides

In some cases, you may want to override on a per user basis the value of one of these dynamic role attributes. This is done with yet again another call to ModifyPrincipal. In the following example, we provide a different attribute value for the attributes: role1date1 and role1float1.

Security

Security information can be set like nearly any other MWS data via xmlImport as well. You can set ACLs/ACEs, GRANT and DENY privileges, add/remove items from Security realms and set authentication schemes.

Permissions

The ACL tag creates a new set of permissions exclusively for the Everyone Group and sets an alias. Later that alias can be used on any resource that you choose. The following example creates a named ACL that allows the Everyone Group READ and MODIFY access and then applies that acl to a new folder under Public Folders. Note how the aclName attribute must match the alias of the ACL. Valid values for different access rights may be found on the SDK site (http://ajax-softwareag.com/) and searching for IAccessRight.java

The more flexible tag: ACE allows you fine-grained control over the complete ACL. It allows you to specify users, groups and roles (Not just the Everyone Group). It allows you to grant and deny any available Permission, and it allows you to optinally set this ACE recursively. Finally, it also allows you to remove any existing ACEs. This tag is applied on the specific resource that you want to modify security for as a child resource. In the following example, the My webMethods Administrators Role is Granted ALL rights to the public folder recursively.

The right tag has the following boolean attributes: [delegate|grant|deny]
The ace tag has an action attribute that has the valid attributes: [add|remove|removeAll]. The add action requires the right child tag to determine what to add. The remove action just removes any security setting for the principal referenced by the uid attribute. The removeAll value will remove all of the ACEs for that resource.
The recusrive boolean attribute determines whether or not to apply this change to all descendents.
In the next example, the ability to add multiple rights together is demonstrated.

Authentication Schemes

An authentication scheme can be placed on any resource by setting the authLevel property. This allows you to designate resources as anonymous, requiring BASIC auth, NTLM auth, or whathever auth scheme you require. Valid auth schemes can be determined by looking at the English names of the auth schemes listed in the System Folder: "folder.auth.schemes" (this is an alias). In the following example, the public folder is changed to be anonymous.

Security Realms

Security Realms are a single ACL that is shared by many different resources. They are created just like any other resource and you set the security on them using the ACE tag. Configuring a resource to be part of a security realm doesn't have a unique tag, instead it is performed by using the executecommand tag. In the following example, a new Security Realm is created and configured, and then a new folder is added to the Security Realm. You should note that the security realm must have an alias in order to be able to reference it from the executecommand tag.

Reference

Name	Type	Description	Example	Relates to
alias (userAlias)	Attribute	used to identify the alias of a MWS resource	<Context alias="folder.public" />	Context, Any MWS Resource
Column	Tag	used to create a new column in a MWS Page Layout	<folder name="MWS Page with two columns"> <page> <row> <column width="40%" align="left" wrap="true"><folder name="Column 1" /></column> <column width="60%" align="left"><folder name="Column 2" /></column> </row> </page> </folder>	Any MWS Page
Config	Tag	Root Node of xml import document	<Config />
Content	Tag	Imports a document to the MWS	<Config> <!--Set the current 'root' to be the public folder--> <Context alias="folder.public"> <content content="deploytemp:/resources/PDFDocument.pdf" mimeType="application/pdf" name="Special PDF Document" origFileName="PDFDocument.pdf" /> </Context> </Config>
Context	Tag	Sets the current MWS Resource node	<Context alias="folder.public"> <folder name="new folder" /> </Context>
Executecommand	Tag	Runs a portal command	<Config> <!-- Renaming default Start Page if it exists --> <context alias="start.page"> <executecommand commandName="updateProperties" resourceURI="start.page" name="MWS Start (6.2)"/> </context> </Config>
Hobos	Tag	used to create auto positioned portlets in a MWS Page Layout	<folder name="MWS Page with two columns"> <page> <row> <column width="40%" align="left" wrap="true"><folder name="Column 1" /></column> </row> </page> <hobos> <folder name="Auto Positioned folder" /> </hobos> </folder>	Any MWS Page
Include	Tag	Includes external xml import documents	<Config> <!--Set the current 'root' to be the public folder--> <Context alias="folder.public"> <include include="deploytemp:/resources/pages/customPage.xmli"/> </Context> </Config>
Layout	Tag	used to hide titlebars and borders on any MWS Resource in a MWS Page Layout	<folder name="MWS Page with two columns"> <page> <row><column> <link name="Link with no titlebar and no border" URL="http://www.webmethods.com"> <layout name="titlebar" value="false"/> <layout name="border" value="false"/> </link> </column></row> </page> </folder>	Any MWS Resource in a MWS Page
name	Attribute	used to identify the name of a MWS resource	<folder name="My New Folder" />	Any MWS Resource
Page	Tag	Starts the layout information of a MWS Page	<folder name="MWS Page with one row and one columnumn"> <page> <row> <column> <folder name="Row 1 Column 1" /> </column> </row> </page> </folder>	Any MWS Page
Property	Tag	Sets the value of named property of a MWS Resources	<folder name="Folder with a description> <property name="description"> I want to add a fairly long description with "quotes" and other stuff. </property> </folder>	Any MWS Resource
Relation	Tag	Sets a renderer (using a relation) on a MWS Resource.	<folder name="Show Thumbnails in MWS Page"> <relation path="portlet.pseudo.folderview.thumbnails" type="portlet.pseudo"/> </folder>	Any MWS Resource
resourceBundleClass	Attribute	used to identify the location of localizable text for html text portlets	<wm_htmltext name="Localizable text"> <property name="HTMLText" resourceBundleClass="com.webmethods.portal.portlet.wm_portalcontent.resources.MWSContentResources" key="POP.012.0018.wm_portalcontent"/> </wm_htmltext>	Any MWS Resource
Row	Tag	used to create a new row in a MWS Page Layout	<folder name="MWS Page with two rows"> <page> <row> <column><folder name="Row 1 Column 1" /></column> </row> <row> <column><folder name="Row 2 Column 1" /></column> </row> </page> </folder>	Any MWS Page
Wiring	Tag	Configures wiring between any two MWS Resources	<Config> <!--Set the current 'root' to be the public folder--> <Context alias="folder.public"> <wm_htmltext name="My Wiring Source" HTMLText="98117, 98024" userAlias="my.wiring.source" /> <wm_accuweather name="My Wired Weather"> <wiring name="zipCodes" portlet="my.wiring.source" property="HTMLText"/> </wm_accuweather> </Context> </Config>	Any two MWS Resources