WebSphere IBM WebSphere XML Document Management Server

Transcription

1 WebSphere IBM WebSphere XML Document Management Server Version 6.2 IBM WebSphere XML Document Management Server SC

2

3 WebSphere IBM WebSphere XML Document Management Server Version 6.2 IBM WebSphere XML Document Management Server SC

4 Note Before using this information and the product that it supports, read the information in Notices on page 163. First Edition (October 2007) This edition applies to IBM WebSphere XML Document Management Server, Version 6.2 and to all subsequent releases and modifications until otherwise indicated in new editions. A form for readers comments appears at the back of this publication. If the form has been removed, address your comments to: International Business Machines Corporation Department 6R4A P.O. Box Research Triangle Park, North Carolina When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you. Copyright International Business Machines Corporation All rights reserved. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

5 Contents Chapter 1. Introduction Introducing the IBM WebSphere XML Document Management Server Component IBM XDMS features Chapter 2. Planning Evaluating your hardware environment Basic Aggregation Proxy routing Advanced Aggregation Proxy routing Planning for security Planning authentication security using the Trust Association Interceptor Chapter 3. Installing Hardware and software requirements Hardware requirements Software requirements Creating authentication users and groups Preparing the WebSphere Application Server environment Preparing the Trust Association Interceptor for use 24 Preparing the installation files Configuring the Trust Association Interceptor for IBM XDMS Installing and configuring the Aggregation Proxy interceptor Creating XDMS clusters Creating the Shared List cluster Creating the Presence Rules cluster Configuring ports Preparing the databases Creating the Shared List XDMS DB2 database..32 Creating a Presence Rules XDMS DB2 database 33 Creating the Service Integration Bus DB2 database Creating the Usage Records database and tables for DB Creating the Usage Records database and tables for Oracle Configuring data sources Creating WebSphere variables Creating an authentication alias Configuring datasources for the Shared List XDMS and Presence Rules XDMS databases..41 Configuring a data source for the Service Integration Bus database Connecting to the Usage Records database...43 Configuring the Service Integration Bus and JMS..45 Configuring the Service Integration Bus and JMS for Shared List Configuring the Service Integration Bus and JMS for Presence Rules Preparing the Shared List XDMS Deploying Shared List Configuring the resource provider for the Shared List XDMS Starting the Shared List XDMS Preparing the Presence Rules XDMS Deploying Presence Rules Configuring the resource provider for the Presence Rules XDMS Starting the Presence Rules XDMS Installing Aggregation Proxy Creating the Aggregation Proxy cluster Configuring Aggregation Proxy ports Deploying the Aggregation Proxy Uninstalling IBM XDMS Uninstalling the Shared List XDMS enterprise application Uninstalling the Presence Rules XDMS enterprise application Removing Resource Environment Providers..64 Uninstalling the Service Integration Bus and JMS from the Shared List cluster Uninstalling the Service Integration Bus and JMS from the Presence Rules cluster Dropping the Service Integration Bus and JMS database Uninstalling the Aggregation Proxy enterprise application Removing Aggregation Proxy Resource Environment Providers Uninstalling core IBM XDMS components...70 Chapter 4. Administering IBM XDMS.. 73 Stopping and starting the server Stopping a cluster Stopping a server (console) Stopping a server (command line) Stopping the node agent (console) Stopping the node agent (command line)...75 Stopping the deployment manager (console)..75 Stopping the deployment manager (command line) Starting the deployment manager Starting the node agents Starting a cluster Starting a server (console) Starting a server (command line) Policy based authorization Adding new policy documents Granting a single identity admin access to a specific document Granting many identities read access to all documents in a directory Granting a group of identities write access to all documents in a domain Using IBM Tivoli License Manager Copyright IBM Corp iii

6 Chapter 5. Managing documents Using IBM XDMS to store and manage documents 87 Using XCAP to store and manage documents...88 Using the Node Selector Adding and editing documents Adding and editing elements Adding and editing attributes Retrieving documents Deleting documents Searching documents Chapter 6. Managing Document Subscriptions SUBSCRIBE and NOTIFY SUBSCRIBE flow using rls-services documents..99 SUBSCRIBE headers Chapter 7. Developing for XDMS Chapter 8. Troubleshooting IBM XDMS 107 IBM Support Assistant Installing ISA plug-ins Enabling Performance Monitoring Infrastructure (PMI) logging Audit logging Monitoring log messages Modifying log properties Enabling trace Trace loggers Faults and alarms Messages Messages Messages Messages Chapter 9. Reference Standards and specifications Presence Rules Resource Environment Providers 133 Shared List Resource Environment Providers Aggregation Proxy Resource Environment Providers Example Policy documents Example Resource List document Javadoc for IBM XDMS Notices Trademarks iv XML Document Management Server

7 Chapter 1. Introduction Welcome to the IBM WebSphere XML Document Management Server Component (IBM XDMS) information center. The following links will help you access the available information. Introducing the IBM WebSphere XML Document Management Server Component The IBM WebSphere XML Document Management Server Component (IBM XDMS) provides network accessible storage, retrieval, and management of XML documents that are owned by entities within your IMS-based solution. IBM XDMS is based on the Open Mobile Alliance (OMA) standards for the OMA XDM v1.0.1 specification along with some aspects of the draft of OMA XDM v2.0 specification. The OMA XDM specification describes the usage of two primary network protocols for interactions with the XDMS: v XML Configuration Access Protocol (XCAP): An IETF specification that defines how XML documents are transported over HTTP. It allows the retrieval or manipulation of either the whole document or specific parts of the document (element or attribute) by use of a node selector, a subset of XPath. v Session Initiation Protocol (SIP): Another IETF specification that defines how subscriptions and notifications can occur. An XDMS uses SIP to allow entities to subscribe to document change notifications so that any updates to a document are signaled to the subscribed entities. Two enablers are provided that enable applications to store XML content based on the application usages as described for IBM XDMS: v A SharedList XDMS for managing resource-lists and rls-services documents that are common to other IMS components v A PresenceRules XDMS for handling presence rules associated with protecting presence information In addition, you can use the IMS Enablement Feature to customize each IBM XDMS by inserting custom code needed to add additional constraints or interact with third party servers. Custom properties can also be inserted to toggle or affect the function of the new customized code. This flexibility allows IBM XDMS to be tailored for specific needs that are required in various telecommunication environments. Finally, an Aggregation Proxy is provided to route requests based on the application usage to the corresponding IBM XDMS enablers. It can also aggregate capabilities and directory information from multiple IBM XDMS enablers. The Aggregation Proxy is considered the client facing service that is a single point of entry to access all IBM XDMS enablers. Digest authentication using a WebSphere Trust Association Interceptor (TAI) and standard support for Transport Layer Security (TLS) are provided to enhance security when accessing the Aggregation Proxy. IBM Corporation

8 IBM XDMS features The IBM WebSphere XML Document Management Server Component is highly extensible and has many useful features. IBM XDMS includes the following features: v Aggregation Proxy support Domain partitioning v Security support P-Asserted identity Digest authentication Transport Layer Security (TLS) Policy-based authorization v Shared List XDMS resource-lists rls-services v Presence Rules XDMS org.openmobilealliance.pres-rules v OMA XDM v2.0 partial support Search using XQuery v Extensibility Framework Custom XDMS creation using IBM XDMS and SIP extensibility frameworks v Usage logging and Monitoring Usage records logging Audit logging Performance Monitoring Infrastructure (PMI) 2 XML Document Management Server

9 Chapter 2. Planning You should plan your IBM XDMS deployment ahead of time. You have several deployment considerations and choices to make. This section outlines the various planning elements. System requirements The end-to-end system consists of two cooperating components, both of which are specified by the OMA XDM v2.0 specification. The components are the Aggregation Proxy and the IBM WebSphere XML Document Management Server Component (IBM XDMS). Both component subsystems run in a WebSphere Application Server Network Deployment environment and can be configured on separate physical machines and clusters for reasons of scaling flexibility. IBM XDMS requires a DB2 9.1 FixPak 2 database for storage of user documents. IBM XDMS also requires a JMS-based messaging engine for communication within the cluster. Note: You can deploy a standalone XDMS subsystem if you do not require the functionality of the Aggregation Proxy. Database capacity You need to plan the amount of database space to dedicate to user document storage. Several factors enter into this calculation: v The number of expected subscribers Ns, both initial and additional considering growth over time. v The average document size for each type of stored document, resource list Zr, authorization Za, presence rules Zp, and global documents Zg. v The average number of documents per subscriber per document type Dr and Dp. There is typically only a single authorization document per subscriber. v The number of physical global documents Ng. As an example, these factors can be combined in a simple formula to provide a rough assessment of the storage requirement: Ns*(Dr*Zr+Za+Dp*Zp)+Ng*Zg You also need to plan the database-serving capacity as a function of I/O instructions per second (IOPS). To size your I/O serving capacity requirement, you need to ascertain the workload that each disk in the array supporting the IBM XDMS database can support. Assume that each 15K RPM disk in the array can sustain 120 IOPS. Use this rate combined with the expected workload on the database to derive the number and types of disks required to support the database. Information about the relationship of number of XCAP requests to I/O requests for typical workloads is documented in the IMS 6.2 Capacity Planning Guide, which you can obtain from the IBM Support Web site. You can also configure IBM XDMS to generate usage records (audit/billing records) for all activity that it processes. As such, you should plan for enough database capacity to handle the expected billing traffic within the limits and Copyright IBM Corp

10 constraints imposed by your usage record processing policy (archival, extraction, and so forth). More details and recommendations are available in the IMS 6.2 Capacity Planning Guide. High availability and scaling The IBM XDMS components use WebSphere Application Server clustering technology to achieve a highly available and scalable architecture. The Aggregation Proxy and the IBM XDMS are both independently scalable because they are both deployed in separate clusters. In addition to WebSphere Application Server, both the Aggregation Proxy and the IBM XDMS provide core functionality that can enhance the scalability of the end-to-end solution. You can deploy clusters for the IBM XDMS in different combinations of domain and AUID (Application Usage Indentifier). Cluster management As clusters, both the IBM XDMS and the Aggregation Proxy must be fronted with some network element that performs routing to these clusters and handles request processing. For SIP traffic, the XDMS cluster must have a highly available set of WebSphere Application Server proxies to do the request routing. This set of proxies is itself clustered and is fronted by some type of IP sprayer or load balancer. For HTTP traffic destined for the Aggregation Proxy or the IBM XDMS, either the WebSphere Application Server Proxy or some equivalent HTTP router such as IBM HTTP Server or an IP sprayer can be used. In addition, the proxy/router fronting the Aggregation Proxy cluster must be configured to ensure affinity based on client IP or similar if retry counts on failed authentication attempts are used. The following diagrams depict typical highly available configurations for Aggregation Proxy and IBM XDMS: Aggregation Proxy Cluster XCAP Client XCAP/HTTP Load Balancer or IP Sprayer Pair XCAP/HTTP XCAP/HTTP Aggregation Proxy Server WebSphere Application Server Clustering XDMS Cluster 1 XDMS Cluster 2 Aggregation Proxy Server Figure 1. High availability Aggregation Proxy 4 XML Document Management Server

11 XDMS Cluster SIP SIP Client XCAP Client XCAP/HTTP XCAP/HTTP SIP, XCAP/HTTP Load Balancer or IP Sprayer Pair SIP, XCAP/HTTP SIP, XCAP/HTTP WebSphere Application Server Proxy WebSphere Application Server Clustering XDM Server WebSphere Application Server Clustering SIP, XCAP/HTTP HA DB2 Complex WebSphere Application Server Proxy XDM Server Aggregation Proxy Figure 2. High availability XDMS Application Usage Identifier partitioning The AUID supported by the system can be hosted all on the same IBM XDMS or subsets of them can be hosted on a dedicated IBM XDMS or IBM XDMS cluster. By partitioning to separate clusters, the overall scalability and supportable throughput as a whole is improved. For example, you can use a separate high-availability cluster and database for your resource-lists documents from your presence rules documents. Aggregation Proxy request forwarding and routing is used to control to which IBM XDMS requests are sent. Domain partitioning Using Aggregation Proxy request forwarding, you can configure different IBM XDMS instances to support or be dedicated to certain subscriber domains. This capability enables supporting multiple user space partitions when the total user population is too large for a single IBM XDMS cluster, or when there are different security requirements for different domains. AUID partitioning can be used in conjunction with domain partitioning whereby the Aggregation Proxy first determines the subset of XDMSs supporting the AUID and then discriminates between that subset for the domain matching the XUI of the requested user. Here is a diagram of a typical deployment that uses both partitioning techniques for scaling: Chapter 2. Planning 5

12 SIP SIP Client (resource-lists) XCAP/HTTP SharedList XDMS Cluster ( default XCAP_URI) resource-lists/ XCAP/HTTP XCAP/HTTP XCAP Client Aggregation Proxy Cluster XCAP/HTTP SharedList XDMS Cluster (XCAP_URI! us.example.com) resource-lists/ SIP SIP Client (pres-rules) PresRules XDMS Cluster (default XCAP_URI) org.openmobilealliance.pres-rules/ Figure 3. Subscriber and AUID partitioning In this example, pres-rules and resource-lists are partitioned across three different clusters, where resource-lists are additionally partitioned across two domains (a default domain and a specific domain us ). Note: SIP clients, which can be the same physical device as the XCAP client are aware of the specific IBM XDMS cluster endpoint address, whereas the XCAP client is aware of the Aggregation Proxy endpoint only. Remember that the clustering techniques for high-availability and scaling can also be combined with the partitioning techniques. Related tasks Preparing the databases on page 32 IBM XDMS requires databases for storing usage records, for storing XML documents managed by IBM XDMS, and for the service integration bus. Evaluating your hardware environment IBM XDMS installs and runs as an application on WebSphere Application Server. It can be deployed in various hardware configurations. Before starting the installation process, review the planning information to develop a deployment strategy that will meet your network needs. WebSphere Application Server supports numerous deployment topologies. It is beyond the scope of this documentation to provide detailed steps for each topology. Therefore deployment information has been grouped into a number of broad categories. Throughout the documentation the categories are used to provide 6 XML Document Management Server

13 a reference point. Each component has a unique deployment strategy. Prior to deployment, review all of the planning and installation information. The commonly used topologies for WebSphere Application Server fall into the following categories. Note: For IBM XDMS, only clustered environments are supported. Vertical scaling topology With vertical clustering techniques, members of a cluster exist on a single physical server. In cases where very long packets might be exchanged, vertical scaling can help alleviate head-of-line blocking problems. Vertical scaling also allows you to make better use of your multiprocessor server. HTTP redirector products can also be used to implement vertical scaling because each application server in the vertical cluster will have its own HTTP Transport. Horizontal scaling topology Members of a cluster exist on multiple physical servers, effectively and efficiently distributing the workload of a single instance. HTTP redirector products can also be used to implement horizontal scaling. Clustering is most effective in environments that use horizontal scaling because of the ability to build in redundancy and failover, to easily add new horizontal cluster members to increase capacity, and to improve scalability by adding heterogeneous systems into the cluster. You can combine vertical and horizontal scaling techniques to increase efficiency in the environment. Development topology An IBM WebSphere Telecom Toolkit development environment can help you rapidly develop and deploy IMS Application Server applications. This toolkit is available as a free download. It is designed to reduce the time to develop applications that use IBM XDMS and other IBM WebSphere products for Telecom. The toolkit includes sample applications that demonstrate how to invoke the Diameter Enabler Web services. Basic Aggregation Proxy routing Basic routing uses the list of IBM XDMS enablers configured in the resource environment providers to route requests to specific AUIDs. The Aggregation Proxy provides a single point of entry to access multiple IBM XDMS enablers that are configured in the backend. Therefore it can be considered to have the superset of capabilities for all IBM XDMS enablers. This simplifies the client configuration in that all XCAP communication is sent to a single entity which is the Aggregation Proxy. During the installation and configuration of the Aggregation Proxy, the list of IBM XDMS enablers is configured in the Resource Environment Provider (REP) property called XDMS_URI. The list must contain a unique set of IBM XDMS enablers in that no two XDMS enablers can support the same AUID (except for two common AUIDs, xcap-caps and org.openmobilealliance.xcap-directory, which all IBM XDMS enablers must implement). This is required so that for each AUID, there is a unique route to a specific IBM XDMS enabler. If two IBM XDMS enablers Chapter 2. Planning 7

14 are defined to support the same AUID, then the Aggregation Proxy cannot determine which IBM XDMS enabler to forward requests to. The AUID, therefore, is rendered unserviceable. Typically, the IBM XDMS enablers in the backend are secured by a firewall and should be considered trusted. However, if higher security is required and HTTPS is enabled for the IBM XDMS enablers, then you can set the REP property HTTPS_PROXY_XDMS to true, which indicates the use of encryption. Then, instead of defining your list of IBM XDMS enablers in the REP property XDMS_URI, define the list of XDMS enablers in the REP property XDMS_URI_HTTPS. Optionally, the advanced routing topic discusses usage of domain partitioning to support multiple XDMS enablers with the same AUID but separated by domain. This allows the segregation of certain client populations to be routed to a specific IBM XDMS enabler for a specific domain. See the topic Advanced Aggregation Proxy routing for more information. Basic routing example Aggregation Proxy REP Configuration used for the examples below: 1. PROXY_ROOT = 2. HTTPS_PROXY_XDMS= false 3. XDMS_URI = presrules1.com:9081/services The SharedList IBM XDMS enabler sharedlist1.com supports the AUID resource-lists. The PresenceRules IBM XDMS enabler presrules1.com supports the AUID org.openmobilealliance.pres-rules. Example XCAP Request: org.openmobilealliance.pres-rules/users/sip:[email protected]/mydoc.xml SharedList XDMS XCAP Client Aggregation Proxy PresRules XDMS org.openmobilealliance.pres-rules/ Figure 4. Basic routing diagram Related tasks 8 XML Document Management Server

15 Deploying the Aggregation Proxy on page 56 Perform a default installation of the Aggregation Proxy EAR (IBMXdmsAggregationProxy.ear) from the WebSphere Application Server console. Configuring basic routing on page 58 Configure just the basic routing when domain partitioning and routing are not required. Configuring advanced routing on page 60 Configure advanced routing when domain partitioning and matching are required. Starting the Aggregation Proxy cluster on page 62 After you have deployed the Aggregation Proxy, start the cluster. Related reference Aggregation Proxy Resource Environment Providers on page 157 Several Resource Environment Providers exist for the Aggregation Proxy. Advanced Aggregation Proxy routing Advanced routing uses domain partitioning and matching to determine the routing of XCAP requests. Basic routing is simply based on the AUID in order to determine the unique IBM XDMS enabler that the request is routed to. However, there may be situations where the user population is too large for a single IBM XDMS enabler to support or where there are security requirements to partition the users. Therefore, besides defining the default IBM XDMS enablers, an administrator may choose to define additional IBM XDMS enablers that support the same AUID but for different domains. During the installation and configuration of the Aggregation Proxy, the list of IBM XDMS enablers for a specific domain is configured in the Resource Environment Provider (REP) property XDMS_URI!<domain> where the <domain> portion of the name defines the domain for which the list of IBM XDMS enablers is supported. The implication here is that two IBM XDMS enablers supporting the same AUID can be defined in the Aggregation Proxy if they reside in different domains. If for each AUID and domain combination, the request matches only one IBM XDMS enabler, then there is no ambiguity in routing. The portion of the request that is used for domain matching is found in the XCAP User Identifier (XUI). The XUI is typically a URI such as a SIP URI. The URI may contain a domain which is parsed and then used to match on the appropriately configured XDMS enabler to route the request to. Matching is done first by the most qualified domain towards least qualified. If no domain is matched, then the default XDMS enabler is used as specified during basic routing configuration. If the XCAP request is for a global document (no XUI), then no domain is specified and consequently the request is routed to the default XDMS. Advanced routing examples These examples illustrate the various routes given the domain and AUID matching done by the Aggregation Proxy. Aggregation Proxy REP Configuration used for the examples below: 1. PROXY_ROOT = Chapter 2. Planning 9

16 2. HTTPS_PROXY_IBM XDMS = false 3. XDMS_URI = presrules1.com:9081/services 4. XDMS_URI!us.example.com = The SharedList IBM XDMS enablers sharedlist1.com and sharedlist2.com both support the AUID resource-lists. The PresenceRules IBM XDMS enabler presrules1.com supports the AUID org.openmobilealliance.pres-rules. Example XCAP Request: resource-lists/users/sip:user1@ ca.example.com/mydoc.xml SharedList XDMS ( default XCAP_URI) resource-lists/ XCAP Client Aggregation Proxy SharedList XDMS (XCAP_URI! us.example.com) resource-lists/ PresRules XDMS (default XCAP_URI) org.openmobilealliance.pres-rules/ Figure 5. Advanced routing example one The Aggregation Proxy routes to the default domain because it did not find a closer match to the XCAP Request XUI. 10 XML Document Management Server

17 Example XCAP Request: us.example.com/mydoc.xml SharedList XDMS (default XCAP_URI) XCAP Client Aggregation Proxy SharedList XDMS (XCAP_URI! us.example.com) resource-lists/ PresRules XDMS (default XCAP_URI) Figure 6. Advanced routing example two The Aggregation Proxy routes to the domain us.example.com because it matches the XUI in the request. Chapter 2. Planning 11

18 Example XCAP Request: nc.us.example.com/mydoc.xml SharedList XDMS (default XCAP_URI) XCAP Client Aggregation Proxy SharedList XDMS (XCAP_URI! us.example.com) resource-lists/ PresRules XDMS (default XCAP_URI) Figure 7. Advanced routing example three The Aggregation Proxy routes to the us.example.com domain because it most closely matches the XUI in the request. 12 XML Document Management Server

19 Example XCAP Request: resource-lists/global/mydoc.xml SharedList XDMS ( default XCAP_URI) resource-lists/ XCAP Client Aggregation Proxy SharedList XDMS (XCAP_URI! us.example.com) resource-lists/ PresRules XDMS (default XCAP_URI) org.openmobilealliance.pres-rules/ Figure 8. Advance routing example four The Aggregation Proxy routes all global requests to the default XCAP URI. Related tasks Deploying the Aggregation Proxy on page 56 Perform a default installation of the Aggregation Proxy EAR (IBMXdmsAggregationProxy.ear) from the WebSphere Application Server console. Configuring basic routing on page 58 Configure just the basic routing when domain partitioning and routing are not required. Configuring advanced routing on page 60 Configure advanced routing when domain partitioning and matching are required. Starting the Aggregation Proxy cluster on page 62 After you have deployed the Aggregation Proxy, start the cluster. Related reference Aggregation Proxy Resource Environment Providers on page 157 Several Resource Environment Providers exist for the Aggregation Proxy. Chapter 2. Planning 13

20 Planning for security To plan for security, consider factors such as requester authentication, requester authorization, confidentiality, and integrity. Requester authentication The Aggregation Proxy performs HTTP Digest Authentication using a Trust Association Interceptor, which requires the provisioning and configuration of an LDAP repository containing the subscriber identity and passwords of all users needing access to the system. The Aggregation Proxy can also reject authentication attempts after a pre-configured number of failed attempts. This function requires maintaining user session affinity with the initial Aggregation Proxy instance using techniques such as source IP address affinity. IBM XDMS uses a Trust Association Interceptor (TAI), which is included with the IBM WebSphere IP Multimedia Subsystem Connector and which enables consumption of the private extension security headers for both HTTP and SIP traffic. This TAI consumes the headers created by the HTTP Digest TAI that runs with the Aggregation Proxy. If the Aggregation Proxy is not used in the environment and authentication security is still required, then authentication mechanisms can be configured directly on the WebSphere Application Server that is running IBM XDMS. These mechanisms can include a Digest authentication (using a custom TAI), or the built-in WebSphere Application Server global security. Any IBM-supplied TAI can be replaced with a custom version if the function does not suit your environment. Requester authorization For authorization access to user documents, IBM XDMS provides a default behavior that gives each user automatic universal access to all documents that user creates and read access to all global documents. This behavior can be changed through comprehensive or selective provisioning of document authorization documents for affected users. Confidentiality and integrity OMA relies on Transport-Level Security (TLS) for ensuring confidentiality on transmitted information and for integrity on information, at least in context of the connection with the previous network element. TLS is supported by WebSphere Application Server. Note: Security can be turned off when running in a test or pre-production mode. If this mode is used, you will need to configure a default authorization policy in IBM XDMS for anonymous access. 14 XML Document Management Server

21 Planning authentication security using the Trust Association Interceptor The Trust Association Interceptor (TAI) security component is intended to enhance the overall authentication security for the IBM WebSphere products for Telecom. An implementation scenario describes how you can deploy the TAI for IBM XDMS. About the scenario IBM XDMS is an extensible framework that also provides shipped support for two Application Unique ID (AUID) extensions: Shared lists (includes rls-services and resource-lists) and Presence rules (pres-rules). Other AUIDs could be deployed similarly. The constituent components are deployed and scaled separately from each other, so there are different cluster descriptions for the XDMS configuration. The following section depicts a common system configuration in which components are deployed in a production scenarios. The scenario is presented with the following conditions: v The scenario does not illustrate all of the possible valid combinations of the IBM WebSphere products for Telecom. v WebSphere Application Server Administrative node deployment is not shown. It is assumed that all components described in this section belonging in a cluster also belong to a WebSphere Application Server-administered core group for purposes of administration and management. v While the scenario depicts the standard deployment of the IBM Tivoli Composite Application Management (ITCAM) for J2EE operations component that is co-located with the IBM WebSphere products for Telecom, the required remote ITCAM for J2EE components (or other SNMP-based monitors) are not shown. In all cases for interaction with the ITCAM for J2EE operations performance Servlet, it is expected that the cluster load balancer or proxy is not invoked to route requests. v Session data replication details are not shown. v The configuration does not address high-availability in an end-to-end sense, nor does it address interactions with required databases. v Issues of development-to-deployment using the IBM WebSphere Telecom Toolkit are not addressed. v The example illustrates the components and nodes in a cluster, in the WebSphere Application Server scaling sense consisting of two or more nodes providing identical service. These nodes may or may not cooperate at some level to guarantee high availability. Three nodes are shown as a convention, but other configurations are possible. Note: The Network Deployment high availability (HA) schemes require an even number of nodes in order to support pair-wise replication Chapter 2. Planning 15

22 XDMS Node XDMS auid1...auidn ALM IMS TAI ITCAM CONVERGED PROXY pair/ LOAD BALANCER pair XCAP/HTTP XCAP/HTTP XCAP/HTTP SIP SOAP/HTTP XDMS Node XDMS auid1...auidn ALM SIP SOAP/HTTP IMS TAI ITCAM CONVERGED PROXY pair SIP XDMS Node SOAP/HTTP XDMS auid1...auidn ALM IMS TAI ITCAM Note: v The WebSphere Application Server Converged Proxy or any third-party load balancer may be deployed pair-wise (for HA reasons). v The Converged Proxy must be used for SIP traffic to maintain session affinity, but the same instance could also be used for HTTP traffic. v The ALM service is a separately-deployed Parlay X Address List management service that is configured to not require TWSS Web service implementations. v The Trust Association Interceptor detects authenticated user identity from inbound messages. v IBM Tivoli Composite Application Management (ITCAM) users communicate directly with the IBM XDMS node for purposes of collecting PMI data from that node. v An aggregation proxy is the reverse proxy security server (RPSS) that performs user authentication before Trust Association Interceptor/XDMS is invoked. v The aggregation proxy adds an X-XCAP-Asserted-Identity header in the HTTP request. 16 XML Document Management Server

23 v The Trust Association Interceptor searches for the asserted identity header. Related reference Configuring the Trust Association Interceptor The Trust Association Interceptor implementation contains two interceptors to process the incoming requests: HttpInterceptor and SipInterceptor. Each interceptor has properties associated with it. Use the WebSphere Integrated Solutions Console to set the properties. Chapter 2. Planning 17

24 18 XML Document Management Server

25 Chapter 3. Installing The installation of IBM XDMS involves several different file entities, and it requires administrative access to the application server and a database server. IBM WebSphere XML Document Management Server Component version 6.2 consists of the following installable entitles: v com.ibm.ws.xdms_6.2.0.jar: An OSGI bundle that contains the IBM XDMS core and it must be installed in the plugins directory of each WebSphere installation. v IBMSharedListXdms.ear: An enterprise application that is deployed to support the Open Mobile Alliance (OMA) SharedList IBM XDMS enabler. v IBMPresenceRulesXdms.ear: An enterprise application that is deployed to support the OMA Presence Rules IBM XDMS enabler. v IBMXdmsAggregationProxy.ear: An enterprise application that is deployed to support the OMA Aggregation Proxy service. Installing IBM XDMS requires administrative access to WebSphere Application Server and to a database server (DB2 for XDMS-specific databases; DB2 or Oracle for a Usage Records database). You will follow these tasks to install IBM XDMS: Related tasks Preparing the databases on page 32 IBM XDMS requires databases for storing usage records, for storing XML documents managed by IBM XDMS, and for the service integration bus. Hardware and software requirements Hardware Specific hardware and software is required before you can begin the installation process. requirements Hardware requirements vary, depending on the operating system on which you plan to deploy. The following hardware should be installed and configured before you begin the installation process: AIX Linux on pseries on page 20 Linux on Intel on page 20 The information below represents the minimum requirements. For greater performance and scalability, additional hardware may be needed. AIX Processor Power 4 or Power 5 Physical memory 4 GB minimum, 2 GB per JVM recommended Copyright IBM Corp

26 Software Disk space 2 GB of free space (minimal) 4 GB of free space recommended Other: CD-ROM or access to shared network drive where CD images are available Linux on pseries Processor Power 4 or Power 5 L2 cache L2 cache for 2.8 GHz processor must be 512 KB L2 cache for 3.4 GHz processor must be 1 M Physical memory 4 GB minimum, 2 GB per JVM recommended Disk Linux on Intel space 2 GB of free space (minimal) 4 GB of free space recommended The following configuration is supported for Intel x86 platforms: Processor Pentium 4, a minimum of 2 processors is required L2 2.8 GHz (32- and 64-bit) cache L2 cache for 2.8 GHz processor must be 512 KB L2 cache for 3.4 GHz processor must be 1 M Physical memory 4 GB minimum, 2 GB per JVM recommended Disk space 2 GB of free space (minimal) 4 GB of free space recommended Other CD-ROM or access to shared network drive where CD images are available Hyper-threading should be enabled requirements Required software includes the operating system, WebSphere Application Server, Java, and a database component. IBM XDMS also requires an LDAP server. The information provided here is intended for a basic installation that is not scaled or fully deployed. The following software should be installed and configured before you begin the installation process: Supported operating systems on page XML Document Management Server

27 Supported application servers Supported Java version Supported databases LDAP server Supported operating systems The following operating systems are supported: v Red Hat Enterprise Linux AS 4.0 Update 5 v SUSE Linux Enterprise Server 9 SP 3 v AIX 5L 5.3 TL 05 SP 6 Supported application servers The following application server offerings are required: v WebSphere Application Server Network Deployment, Version For a list of required WebSphere Application Server fixes, refer to the readme file, WebSphereProductsForTelecomReadme.html, on the QuickStart CD. Supported Java version WebSphere Application Server Network Deployment includes the correct JDK version. The following JDK is required: v JDK, Version SR 5 For WebSphere Enterprise Service Bus, the correct JDK version is also included. The following JDK is required: v JDK, Version Supported databases Each component has different database needs. Refer to the planning section for each component to understand the database needs for that component. IBM XDMS does not require a database. v IBM DB2 Universal Database Version 9.1 FixPak 2 v Oracle Database Version LDAP server IBM XDMS retrieves users from an LDAP server. It has been tested with the following LDAP server: v IBM Tivoli Directory Server, Version A license to download IBM Tivoli Directory Server, Version 6.0 is included with this product. You can download Fix Pack 1 ( ) from the IBM Tivoli Directory Server support page. Chapter 3. Installing 21

28 Creating authentication users and groups Using the deployment manager profile, prepare for the installation by creating users and groups with the appropriate privileges. Before you begin, the following steps should be completed: v A WebSphere user account repository is created. A federated LDAP repository is recommended. See WebSphere Application Server Information Center for more instructions. v Started the application server. v Connected to the database. Follow these steps to create your users and groups. 1. Log in to the Integrated Solutions Console. a. Open a browser and navigate to the following URL: ibm/console. Where: host_name is the fully qualified host name of the server where the application or the network deployment manager is deployed. port is the secured port used to access the console. The default is Note: The default unsecured port is If you use 9060, you must have http instead of https in the URL. b. Enter an administrator user ID and password. If security is not enabled leave the password field blank. c. Click Log in. 2. In the navigation panel, click Users and Groups Manage Users. 3. Create a user with super administrative privileges. a. Click Create. b. Type a User ID. For example, type superadmin. c. Type the First name and Last name for the user. d. Optional: Type the for the user. Use the standard format. For example, [email protected] e. Type the Password for the user. For example superadmin, password superadminpassword f. Confirm the password. g. Click Create. The following success message displays: The user was created successfully. h. Click Close. i. In the navigation panel, click Users and Groups Administrative User Roles. j. Click Add. k. Type the User ID for the user you created. For example, type superadmin. l. Press Ctrl and click Administrator and Configurator for the Roles of the user. m. Click OK. n. Click Save to save to the master configuration 4. Create an anonymous user to use IBM XDMS. a. Click Create. 22 XML Document Management Server

29 b. Type a User ID. For example, type anonymous.invalid c. Type the First name and Last name for the user. d. Optional: Type the for the user. Use the standard format. For example, [email protected] e. Type the password for the user. f. Confirm the password. g. Click Create. The following success message displays: The user was created successfully. h. Click Close. Preparing the WebSphere Application Server environment You must preparewebsphere Application Server for the installation of IBM XDMS. Before installing IBM XDMS you must have the following prerequisites met: v WebSphere Application Server Network Deployment Version has been installed with a deployment manager with at least one managed node. v You have federated all nodes into the deployment manager cell v A WebSphere user account repository is created. A federated LDAP repository is recommended. See WebSphere Application Server Information Center for more instructions. v IBM DB2 Universal Database9.1 FixPak 2 has been installed along with the license for purexml. v IBM DB2 Universal Database9.1 FixPak 2 client in the same path on every WebSphere Application Server node in the cluster. This allows the WebSphere Variables for the JDBC driver to be declared at the Cell level. Unpack the installation tar file in the was_root directory. Note: was_root is the installation root directory for WebSphere Application Server Network Deployment. By default, this directory is: /usr/ibm/websphere/appserver /opt/ibm/websphere/appserver Complete the following steps to prepare WebSphere Application Server Network Deployment, Version for the IBM XDMS installation: 1. Log in to the Integrated Solutions Console. a. Open a browser and navigate to the following URL: ibm/console. Where: host_name is the fully qualified host name of the server where the application or the network deployment manager is deployed. port is the secured port used to access the console. The default is Note: The default unsecured port is If you use 9060, you must have http instead of https in the URL. b. Enter an administrator user ID and password. If security is not enabled leave the password field blank. c. Click Log in. 2. Verify that you have the correct version of WebSphere Application Server Network Deployment installed: Chapter 3. Installing 23

30 a. In the navigation panel, click Welcome. b. Click WebSphere Application Server. c. Under About your WebSphere Application Server, you should see the following line of text indicating the version: WebSphere Application Server Network Deployment, Configure security: a. In the navigation panel, click Security Secure administration, applications, and infrastructure. b. Under Administrative security, select Enable administrative security. When you enable administrative security, you must configure user repositories. For additional information about user repositories, refer to the WebSphere Application Server Information Center. c. Under Application security, select Enable application security. d. Under Java 2 security, deselect Use Java 2 security to restrict application access to local resources. e. Click Apply. f. Click Save to save changes to master configuration. 4. Configure WebSphere Application Server Web security. a. From the admin console click, Security Secure administration applications, and infrastructure Web Security. b. Click General settings. c. Select Authenticate only when URI is protected and the sub heading, Use available authentication data when an unprotected URI is accessed. 5. Verify that the console preferences are set to synchronize changes across the nodes: a. In the navigation panel, click System administration Console Preferences. b. Select Synchronize changes with Nodes. c. Click Apply. 6. Stop all application servers, node agents, and the deployment manager. a. Stop all application servers. b. Stop all node agents. c. Stop the deployment manager. 7. Copy the IBM XDMS tar file, IBMXdmsInstallPackage_6.2.0.tar, to the was_root directory on each physical WebSphere Application Server node. 8. Unpack the file on each node including the Aggregation Proxy server, by typing the following command: tar -xvf IBMXdmsInstallPackage_6.2.0.tar 9. The servers will be restarted in a subsequent section. Related tasks Stopping and starting the server on page 73 After making changes to the server configuration, you must restart the application server. Preparing the Trust Association Interceptor for use Follow these procedures to install the Trust Association Interceptor and make it ready for use by the IBM WebSphere XML Document Management Server Component. 24 XML Document Management Server

31 Preparing the installation files Before you install the Trust Association Interceptor, the WebSphere IMS Connector installation file must be unpacked on the server where WebSphere Application Server is installed. Unpacking the WebSphere IMS Connector installation file, DHAImsConnectorInstallPackage_6.2.0.tar, which is found on the WebSphere IMS Connector CD, places all of the files for the WebSphere IMS Connector and for the TAI into their appropriate directories. It is necessary to perform this step only once, even if you plan to use the TAI for several different components. On the server where WebSphere Application Server is installed, unpack the installation tar file to the was_root directory: Note: was_root is the installation root directory for WebSphere Application Server Network Deployment. By default, this directory is: /usr/ibm/websphere/appserver /opt/ibm/websphere/appserver 1. Copy the installation file from the CD (IBM_WebSphere_IMS_Connector/ DHAImsConnectorInstallPackage_6.2.0.tar) to the was_root directory. 2. Change (cd) to the was_root directory. 3. Unpack the file by typing the following command: tar -pxvf DHAImsConnectorInstallPackage_6.2.0.tar Configuring the Trust Association Interceptor for IBM XDMS Before you begin, make sure that: v WebSphere Application Server Network Deployment, Version v The file DHAIMSConnectorTai.jar is located in the following directory: was_root/lib/ext. Note: was_root is the installation root directory for WebSphere Application Server Network Deployment. By default, this directory is: /usr/ibm/websphere/appserver /opt/ibm/websphere/appserver Launch the WebSphere Application Server Integrated Solutions Console and perform the following steps to configure the interceptor. 1. Click Security Secure administration, applications, and infrastructure and enable global security. For detailed instructions about enabling security, refer to the topic Securing applications and their environment in the WebSphere Application Server Information Center. 2. Click Security Secure administration, applications, and infrastructure Web Security General Settings. 3. Select Authenticate only when the URI is protected and Use available authentication data when an unprotected URI is accessed. 4. Click Apply. 5. Click Save to the master configuration. 6. Click Security Secure administration, applications, and infrastructure. Chapter 3. Installing 25

32 7. Under Authentication Web Security, select Trust Association. 8. Select Enable trust association. 9. Under Additional Properties, click Interceptors. 10. Delete all default connector interceptors that are currently defined. 11. Add the HTTP interceptor. a. Click New b. Type the class name: com.ibm.imsconnector.tai.httpinterceptor 12. Click Apply. 13. Click Save. 14. Double click on com.ibm.imsconnector.tai.httpinterceptor to return to the edit screen. 15. Click Custom properties 16. Click New to add new custom properties a. Type a Name, Value, and Description for the custom property. b. Click Apply. c. Return to the Custom properties window. Repeat this step to add all custom properties. For a complete list of these properties and associated information, refer to the topic Configuring the IMS Trust Association Interceptor. The following properties may not use the default installation values: Name: enablemultipleidmapping Value: false Description: Enables stripping the protocol scheme from the SIP URI, to obtain an ID that may ma Note: If you are configuring the WebSphere IMS Connector for both SIP and HTTP TAIs in test environments, change the allowedsenderlist property value to x.x.x.x. This allows you to send requests from any host via asserted identity. For production environments, please configure trusted servers such as the Aggregation Proxies, Presence Servers, XDMS Enablers, and TWSS servers. 17. Click Save. 18. Return to the Interceptors page. 19. Add the SIP interceptor. a. Click New. b. Type the class name: com.ibm.imsconnector.tai.sipinterceptor 20. Click Apply. 21. Click Save. 22. Double click on com.ibm.imsconnector.tai.httpinterceptor to return to the edit screen. 23. Click Custom properties 24. Click New to add new custom properties a. Type a Name, Value, and Description for the custom property. b. Click Apply. c. Return to the Custom properties window. Repeat this step to add custom properties. For a complete list of these properties and associated information, refer to the topic Configuring the IMS Trust Association Interceptor. The following properties may not use the default installation values: 26 XML Document Management Server

33 Name: enablemultipleidmapping Value: false Description: Enables stripping the protocol scheme from the SIP URI, to obtain an ID that may Note: If you are configuring the WebSphere IMS Connector for both SIP and HTTP TAIs in test environments, change the allowedsenderlist property value to x.x.x.x. This allows you to send requests from any host via asserted identity. For production environments, please configure trusted servers such as the Aggregation Proxies, Presence Servers, XDMS Enablers, and TWSS servers. Installing and configuring the Aggregation Proxy interceptor Install the Trust Association Interceptor (com.ibm.glm.http.security.tai.httpdigesttai) for Aggregation Proxy in order for it to pass proper credentials to IBM XDMS. Before you proceed, make sure that: v The file AggProxyTai.jar is located in the following directory: was_root/lib/ext. Note: was_root is the installation root directory for WebSphere Application Server Network Deployment. By default, this directory is: /usr/ibm/websphere/appserver /opt/ibm/websphere/appserver v WebSphere Application Server Network Deployment security is properly configured as either standalone or federated IBM Directory Server on a separate standalone machine. Launch the WebSphere Application Server Administration Console and perform the following steps to install the interceptor: 1. Click Security Secure administration, applications, and infrastructure Web Security Trust Association Interceptors New. 2. Type the class name: com.ibm.glm.http.security.tai.httpdigesttai 3. Type the following custom properties: Note: Each of the following properties is an example taken from a working WebSphere/LDAP configuration. Parameter: LdapAuthDn Example Value: cn=root Explanation: Pulled from configuration for a Stand-alone LDAP. Most implementations typically u Parameter: LdapAuthPw Example Value: LDAPAUTH_PASSWORD Explanation: LDAP password of the user specified by the LdapAuthDn parameter Parameter: LdapBaseDn Example Value: dc=wasusers Explanation: Root entry for users matching the value specified by the LdapUserFilter parameter. Parameter: LdapHost Example Value: LDAP_HOST Explanation: Host name of LDAP server Parameter: LdapPort Example Value: 389 Explanation: The port on which the LDAP server is listening Parameter: LdapUserFilter Chapter 3. Installing 27

34 Creating XDMS clusters Example Value: (&(uid=%v)(objectclass=inetorgperson)) Explanation: Used to search for a specific user identified by the %v. In this case, it searches f Parameter: RetryCount Example Value: 3 Explanation: Number of times a user is challenged for valid credentials before a 401 Unauthorized Parameter: auth.int.enable Example Value: false Explanation: Specifies the auth-int quality of protection (QOP) for digest authentication. Digest 4. Click Save to save changes to the master configuration. Begin the installation by creating a cluster for each XDMS enabler, Shared List and Presence Rules. The Shared List, Presence Rules, and other custom AUIDs run on their own clusters. Using the default names provided will prevent you from having to do further configuration in the resource environment providers. Note: The procedure for creating a cluster for the Aggregation Proxy is provided elsewhere in this information center. Related tasks Creating the Aggregation Proxy cluster on page 54 Create a cluster for the Aggregation Proxy in the WebSphere Application Server Network Deployment console, and use the default values that WebSphere Application Server provides. Creating the Shared List cluster Before installing applications, you can create a cluster and add cluster members for Shared List using the Integrated Solutions Console. Before installing Shared List XDMS application, you must create a cluster: v WebSphere Application Server Network Deployment, Version In addition, you should have: v Created a deployment manager profile v Federated all nodes into the deployment manager cell v Prepared the environment Create the Shared List Cluster, and add members by completing the following steps: 1. Start the deployment manager. 2. Start the node agent. 3. Log in to the Integrated Solutions Console. a. Open a browser and navigate to the following URL: host_name:port/ibm/console. Where: host_name is the fully qualified host name of the server where the application or the network deployment manager is deployed. port is the secured port used to access the console. The default is XML Document Management Server

35 Note: The default unsecured port is If you use 9060, you must have http instead of https in the URL. b. Enter an administrator user ID and password. If security is not enabled leave the password field blank. c. Click Log in. 4. In the navigation panel, click Servers Clusters. 5. Click New. 6. Type the cluster name, for example SharedListCluster. 7. Select Prefer local. 8. Click Next. 9. Type server_name in the Member name field. This is the fully qualified host name of additional WebSphere Application Server servers being added as cluster members. For example, SharedList0 10. Select Generate unique HTTP ports. 11. Select the appropriate option for Select basis for first cluster member for your environment. For example, select Create the member using an application server template to create a new application server using the existing default template. 12. Click Next. 13. Optional: If your environment requires more than one cluster member, add additional cluster members. Repeat the following steps for each cluster member you would like to add. a. Type server_name in the Member name field. This is the fully-qualified host name of additional WebSphere Application Server servers being added as cluster members for example, SharedList1 b. Select the node for the cluster member. c. Select Generate unique HTTP ports. d. Click Add Member to add the cluster member. 14. Click Next, and click Finish. 15. Click Save to save changes to the master configuration. 16. Click OK. 17. Start the SharedListCluster cluster: a. If the cluster started automatically, select the check box corresponding to the SharedListCluster, then click Stop. b. Select the check box corresponding to SharedListCluster. c. Click Start. Verify that the status for the SharedListCluster cluster is Started. You must create a proxy server and associate the proxy server with the cluster that you have created. Because IBM XDMS supports both SIP and HTTP, you will need a WebSphere Application Server proxy server that supports HTTP and SIP requests. Refer to the WebSphere Application Server Information Center for additional information on setting up the proxy server. Note: Once you have created the proxy server you need to disable page caching for the HTTP proxy. Related tasks Stopping and starting the server on page 73 After making changes to the server configuration, you must restart the application server. Chapter 3. Installing 29

36 Creating the Presence Rules cluster Before installing applications, you can create a cluster and add cluster members for Presence Rules using the Integrated Solutions Console. Before you begin, the following software should be installed: v WebSphere Application Server Network Deployment, Version In addition, you should have: v Created a deployment manager profile v Federated all nodes into the deployment manager cell v Prepared the environment Create the PresenceRulesCluster cluster, and add members by completing the following steps: 1. Start the deployment manager. 2. Start the node agent. 3. Log in to the Integrated Solutions Console. a. Open a browser and navigate to the following URL: host_name:port/ibm/console. Where: host_name is the fully qualified host name of the server where the application or the network deployment manager is deployed. port is the secured port used to access the console. The default is Note: The default unsecured port is If you use 9060, you must have http instead of https in the URL. b. Enter an administrator user ID and password. If security is not enabled leave the password field blank. c. Click Log in. 4. In the navigation panel, click Servers Clusters. 5. Click New. 6. Type the cluster name, for example PresenceRulesCluster. 7. Select Prefer local. 8. Click Next. 9. Type server_name in the Member name field. This is the fully qualified host name of additional WebSphere Application Server servers being added as cluster members. For example, PresenceRules Select Generate unique HTTP ports. 11. Select the appropriate option for Select basis for first cluster member for your environment. For example, select Create the member using an application server template to create a new application server using an existing template. 12. Click Next. 13. Optional: If your environment requires more than one cluster member, add additional cluster members. Repeat the following steps for each cluster member you would like to add. a. Type server_name in the Member name field. This is the fully-qualified host name of additional WebSphere Application Server servers being added as cluster members for example, PresenceRules1. 30 XML Document Management Server

37 b. Select the node for the cluster member. c. Select Generate unique HTTP ports. d. Click Add Member to add the cluster member. 14. Click Next, and click Finish. 15. Click Save to save changes to the master configuration. 16. Click OK. 17. Start the PresenceRulesCluster cluster: a. If the cluster started automatically, select the check box corresponding to the PresenceRulesCluster, then click Stop. b. Select the check box corresponding to PresenceRulesCluster. c. Click Start. Verify that the status for the PresenceRulesCluster cluster is Started. You must create a proxy server and associate the proxy server with the cluster that you have created. Because IBM XDMS supports both SIP and HTTP, you will need a WebSphere Application Server proxy server that supports HTTP and SIP requests. Refer to the WebSphere Application Server Information Center for additional information on setting up the proxy server. Note: Once you have created the proxy server you need to disable page caching for the HTTP proxy. Related tasks Stopping and starting the server on page 73 After making changes to the server configuration, you must restart the application server. Configuring ports The HTTP transport ports and virtual hosts must be properly defined for the clusters. You can verify and correct the port configuration using the Integrated Solutions Console. Before you begin, the following software should be installed: v WebSphere Application Server Network Deployment, Version In addition, you should have: v Completed the environment preparation steps v Created the cluster you wish to install the IBM XDMS EAR files on To ensure that the ports are configured correctly, complete the following steps: 1. Log in to the Integrated Solutions Console. a. Open a browser and navigate to the following URL: ibm/console. Where: host_name is the fully qualified host name of the server where the application or the network deployment manager is deployed. port is the secured port used to access the console. The default is Note: The default unsecured port is If you use 9060, you must have http instead of https in the URL. Chapter 3. Installing 31

38 b. Enter an administrator user ID and password. If security is not enabled leave the password field blank. c. Click Log in. 2. Verify that the HTTP transport ports are properly defined. a. In the navigation panel, click Servers Application servers. b. Click server_name for the cluster member you want to verify. c. On the right side of the page, in the Communication section, Expand Ports. d. Verify that the correct ports are listed. Two ports must be included in the virtual host definition: 1) WC_defaulthost (typically 9080) 2) SIP_DEFAULTHOST (typically 5060) Note: You need to remember the port numbers, because in the next step you will verify that the ports are correct for each virtual host 3. Verify that the virtual hosts are properly defined. a. In the navigation panel, click Environment Virtual Hosts. b. Click the virtual_host_name that you are using typically default_host. c. Under Additional Properties, click Host Aliases. d. Verify that all ports are correct. 4. If the information is not correct, make necessary changes. a. To change an existing port, click host_name and modify as necessary. b. To add a missing port, click New. Supply values for Host Name and Port, and click OK. c. Click Apply. d. Click Save to save changes to the master configuration. e. Click OK. Preparing the databases IBM XDMS requires databases for storing usage records, for storing XML documents managed by IBM XDMS, and for the service integration bus. Follow these instructions to prepare DB2 and create the required databases: Related concepts Chapter 3, Installing, on page 19 The installation of IBM XDMS involves several different file entities, and it requires administrative access to the application server and a database server. Prerequisites The following prerequisites must be installed prior to installation of IBM XDMS. Chapter 2, Planning, on page 3 You should plan your IBM XDMS deployment ahead of time. You have several deployment considerations and choices to make. This section outlines the various planning elements. Creating the Shared List XDMS DB2 database Create the database for the Shared List XDMS using the the IBMSharedListXdms.sh script. 32 XML Document Management Server Follow these instructions to prepare DB2:

39 1. Copy the IBMSharedListXdms.sh script from one of the WebSphere Application Server nodes to a location on the DB2 server that can be accessed by the instance owner. The script is located in the Installable Application directory of your WebSphere Application Server. For example, was_root/installableapps/ xdms/scripts/dbscripts/xdms/ Note: was_root is the installation root directory for WebSphere Application Server Network Deployment. By default, this directory is: /usr/ibm/websphere/appserver /opt/ibm/websphere/appserver 2. Log in to DB2 as the DB2 instance owner, for example db2inst1 3. Start the DB2 instance. 4. Make the script executable by typing the following: chmod 755 IBMSharedListXdms.sh 5. Run the following command:./ibmsharedlistxdms.sh db_name db_user db_password. For example,./ibmsharedlistxdms.sh XDMS db2inst1 password. 6. Verify that the XDMS database was created properly by typing the following command: db2 connect to db_name user db_user using db_password For example, type: db2 connect to XDMS user db2inst1 using password. You should see the following results: Database Connection Information. Database server = DB2/LINUX SQL authorization ID = DB2INST1 Local database alias = XDMS 7. Verify that all tables were properly created by typing the following command: db2 list tables You should see the following results: Table/View Schema Type Creation time RESOURSELISTS DB2INST1 T RESOURSELISTSACLS DB2INST1 T RLSSERVICES DB2INST1 T RLSSERVICESACLS DB2INST1 T record(s) selected. 8. Retain the following information needed to install and configure Shared List XDMS and connect to the database. v Database name v Connection port v DB2 Instance server hostname v DB2 instance userid and password Creating a Presence Rules XDMS DB2 database Create the database for the Shared List XDMS using the IBMSharedListXdms.sh script. After the IBMXdmsInstallPackage_6.2.0.tar has been unpacked, follow these instructions to prepare DB2: Chapter 3. Installing 33

40 1. Copy the IBMSharedListXdms.sh script from one of the WebSphere Application Server nodes to a location on the DB2 server that can be accessed by the instance owner. The script is located in the Installable Application directory of your WebSphere Application Server. For example, was_root /installableapps/xdms/scripts/dbscripts/xdms/ Note: was_root is the installation root directory for WebSphere Application Server Network Deployment. By default, this directory is: /usr/ibm/websphere/appserver /opt/ibm/websphere/appserver 2. Log in to DB2 as the DB2 instance owner (db2inst1). 3. Start the DB2 instance. 4. Make the script executable by typing the following: chmod 755 IBMPresenceRulesXdms.sh 5. Run the following command:./ibmpresencerulesxdms.sh db_name db_user db_password. For example,./ibmpresencerulesxdms.sh XDMS db2inst1 password. 6. Verify that the XDMS database was created properly by typing the following command: db2 connect to db_name user db_user using db_password For example, type: db2 connect to XDMS user db2inst1 using password You should see the following results: Database Connection Information. Database server = DB2/LINUX SQL authorization ID = DB2INST1 Local database alias = XDMS 7. Verify that all tables were properly created by typing the following command: a. db2 list tables You should see the following results: Table/View Schema Type Creation time PRESRULES DB2INST1 T PRESRULESACLS DB2INST1 T record(s) selected. Note: You will see four additional tables here if you have already created tables for Shared List XDMS. 8. Retain the following information needed to install and configure Presence Rules XDMS and connect to the database. v Database name v Connection port v DB2 instance server hostname v DB2 instance userid and password Creating the Service Integration Bus DB2 database Create the Service Integration Bus database using the createxdmssibus.sh script. 34 XML Document Management Server

41 After the IBMXdmsInstallPackage_6.2.0.tar has been unpacked, follow these instructions to prepare the Service Integration Bus DB2 database: 1. Copy the createxdmssibus.sh script from one of the WebSphere Application Server nodes to the DB2 server. The script can be located on WebSphere Application Server nodes in the following directory: was_root/ installableapps/xdms/scripts/dbscripts/xdms/ Note: was_root is the installation root directory for WebSphere Application Server Network Deployment. By default, this directory is: /usr/ibm/websphere/appserver /opt/ibm/websphere/appserver 2. Log in to DB2 as the DB2 instance owner, for example db2inst1. 3. Run the following command:./createxdmssibus.sh db_name user db_user db_password. For example,./createxdmssibus.sh XDMSSIB db2inst1 password. 4. Verify that the XDMSSIB database was created properly by typing the following command: a. db2 connect to db_name user db_user using db_password. For example, type db2 connect to XDMSSIB user db2inst1 using password. You should see the following results: Database Connection Information. Database server = DB2/LINUX SQL authorization ID = DB2INST1 Local database alias = XDMSSIB 5. Retain the following information needed to install and configure XDMSSIB and connect to the database. v Database name v Connection port v DB2 server hostname v DB2 userid and password Related concepts Configuring the Service Integration Bus and JMS on page 45 Two Jython scripts are provided to help you create and delete the Service Integration Bus and JMS artifacts such as connection factories and topics. Creating the Usage Records database and tables for DB2 Configure a DB2 Usage Records database using the crtsrvdb2.sh script. Before you begin, the following software should be installed: v IBM DB2 Universal Database, Version 9.1 FixPak 2 Verify that the following files have been copied to the database server in was_root/installableapps/xdms/scripts/dbscripts/usagerecords: v v crtsrvdb2.sh UsageDbDB2.ddl Note: was_root is the installation root directory for WebSphere Application Server Network Deployment. By default, this directory is: /usr/ibm/websphere/appserver Chapter 3. Installing 35

42 /opt/ibm/websphere/appserver 1. Log in to the DB2 server as a database administrator. 2. Create a directory that has write and execute permission, for example DB_dir. 3. Switch to the following directory: was_root/installableapps/xdms/scripts/ dbscripts/usagerecords. 4. Run the crtsrvdb2.sh script, providing the following inputs: Sequence No. Parameter Description Default value 1 dbserver Name of the database server 2 dbport Number for the listening port on the database server hostname dbname Name of the database XDMSUR 4 dbalias Alias by which the database is known 5 dblocale Territory code that identifies your DB2 locale, for example US or JP 6 dbinstance Name of the database instance 7 dbinstancepw Password for the database instance 8 dbuser User ID for the authorized user (the ID with which you are logged in) 9 dbuserpw Password for the authorized user 10 ddlfile Path to the data definition language (ddl) file used to define the database s attributes 11 dbcreate Boolean value specifying whether the database should be recreated 12 dblocal Boolean value specifying whether the database should be created in the local catalog. Recommended value: TRUE 13 dbnodename Remote database server node name (if dblocale is not TRUE). Recommended value: RDBSRV XDMSUR US db2inst pw db2inst pw UsageDbDb2.ddl TRUE TRUE RDBSRV 36 XML Document Management Server

43 5. Verify that the database tables were created properly by typing the following command, where database_alias is the alias you provided when running the crtsrvdb2.sh script: db2 connect to database_alias user database_administrator_id Where: database_alias represents the database alias you assigned in step 7 database_administrator_id represents the administrator user ID For example: db2 connect to XDMSUR user db2inst If the script ran properly, the following results display: Database Connection Information Database server = DB2/LINUX 9.1 SQL authorization ID = database_administrator_id Local database alias = database_alias 6. Verify that all tables were created properly by typing the following command: db2 list tables If the script ran properly, the USAGERECORDS table is listed. Note: If errors occur when you run the database preparation script, refer to the topic Troubleshooting the database script. Creating the Usage Records database and tables for Oracle Configure an Oracle Usage Records database using the crtsrvora.sh script. Before you begin, the following software should be installed: v Oracle Database, Version Verify that the following files exist on the database server in was_root/ installableapps/xdms/scripts/dbscripts/usagerecords: v crtsrvora.sh v UsageDbOra.ddl Note: was_root is the installation root directory for WebSphere Application Server Network Deployment. By default, this directory is: /usr/ibm/websphere/appserver /opt/ibm/websphere/appserver 1. Log in to the Oracle server as a database administrator. 2. Create a directory that has write and execute permission, for example DB_dir. 3. Switch to the following directory: was_root/installableapps/xdms/scripts/ dbscripts/usagerecords. 4. Run the crtsrvora.sh script, providing the following inputs: Sequence No. Parameter Description Default value 1 dbname Name of the database XDMSUR 2 dbuser User ID for the authorized user (the ID with which you are logged in) user name Chapter 3. Installing 37

44 Configuring data sources Sequence No. Parameter Description Default value 3 dbuserpw Password for the authorized user 4 ddlfile Path to the data definition language (ddl) file used to define the database s attributes pw UsageDbOra.ddl 5. Verify that the database tables were created properly by running a command similar to the following: select USAGERECORDS from user_tables If the script ran properly, the USAGERECORDS table is shown in the display. After WebSphere Application Server Network Deployment has been installed, and you have prepared your databases, you must create data sources for IBM XDMS to interact with the databases. To connect to the databases, you must create a JAAS authentication alias for the database, create the JDBC provider, and define data sources using the Integrated Solutions Console. The database client allows the database server and the application server to communicate. When the database is not on the same server as WebSphere Application Server Network Deployment, the database client must be installed on each WebSphere Application Server Network Deployment server. This applies to all nodes and the deployment manager, when the deployment manager has an application server. Creating WebSphere variables WebSphere variables define parameters for the system. To enable communication between the application server and the database, you must create a WebSphere variables to specify the path to the database client JAR files. Before you begin, the following software should be installed: v WebSphere Application Server Network Deployment, Version v One of the following supported databases: IBM DB2 Universal Database, 9.1 FixPak 2 v Database client to communicate with the database server Before you begin, the following steps should be completed: v Started the deployment manager v Started the node agents v Created the database After you have installed the database client on the server where you installed WebSphere Application Server, you must create a WebSphere variable to enable communication between the application server and the database server. Important: Install the database client in the same location on each physical server. 1. Log in to the Integrated Solutions Console. 38 XML Document Management Server

45 a. Open a browser and navigate to the following URL: ibm/console. Where: host_name is the fully qualified host name of the server where the application or the network deployment manager is deployed. port is the secured port used to access the console. The default is Note: The default unsecured port is If you use 9060, you must have http instead of https in the URL. b. Enter an administrator user ID and password. If security is not enabled leave the password field blank. c. Click Log in. 2. In the navigation panel, click Environment WebSphere Variables. 3. Select cell_name from the Scope drop-down list. The cell name has the following convention hostnamecell01 4. Create the JDBC driver path variable. a. Click New. b. In the Name text box type DB2UNIVERSAL_JDBC_DRIVER_PATH c. In the Value field, type the path to the database client JAR files: For the path, use the following format where db_client_root is the path where you installed the database client: /db_client_root/java This path is where you would find the following JAR files: db2jcc.jar and db2jcc_license_*.jar For example, type: /home/db2inst1/sqllib/java d. Click OK. 5. Create the DB2 JDBC driver path variable. a. Click New. b. In the Name text box type UNIVERSAL_JDBC_DRIVER_PATH c. In the Value field, type the path to the database client JAR files: For the path, use the following format where db_client_root is the path where you installed the database client: /db_client_root/java This path is where you would find the following JAR files: db2jcc.jar and db2jcc_license_*.jar For example, type: d. Click OK. /home/db2inst1/sqllib/java 6. Create the Universal JDBC driver native path variable. a. Click New: b. In the Name field type: Chapter 3. Installing 39

46 DB2UNIVERSAL_JDBC_DRIVER_NATIVEPATH c. In the Value field, type the path to the database client JAR files: For the path, use the following format where db_client_root is the path where you installed the database client: /db_client_root/lib This path is where you would find the following JAR files: libdb2.so and libdb2cfg.so For example, type: /home/db2inst1/sqllib/lib d. Click OK. 7. At the node scope, remove the variables you just defined at the cell scope. a. Select each node one at a time b. Select the variables you are deleting. c. Click Delete. 8. Click Save to save changes to the master configuration. Related tasks Stopping and starting the server on page 73 After making changes to the server configuration, you must restart the application server. Creating an authentication alias Use an authentication alias to define authentication data used to access the databases.the authentication alias is created using the Integrated Solutions Console. Before you begin, the following steps should be completed: v Started the deployment manager v Started the node agents v Created the database v Created WebSphere variables Complete the following steps to create an authentication alias for the IBM XDMS database: 1. In the navigation panel, click Security Secure administration, applications, and infrastructure. 2. Expand Java Authentication and Authorization Service, and click J2C authentication data. 3. Click New. 4. In the Alias field, type XDMS. 5. In the User ID field, type the user_id For example, db2inst1 that can be used to access the database. 6. In the Password field, type the password that corresponds to the user_id. 7. Optional: In the Description field, type the description of the alias. 8. Click OK 9. Click Save to save changes to the master configuration. Related tasks 40 XML Document Management Server

47 Stopping and starting the server on page 73 After making changes to the server configuration, you must restart the application server. Configuring datasources for the Shared List XDMS and Presence Rules XDMS databases Use the WebSphere Application Server s Connecting to a database guided activity to connect to the Shared List XDMS and Presence Rules XDMS databases. Before you begin, the following prerequisites must be met: v The XDMS database is configured for the Shared List and Presence Rules AUIDs v TheWebSphere Application Server JDBC environment variables and authentication alias have been configured. environment variables and Alias have been configured. Before you begin, the following steps should be completed: v Started the deployment manager v Started the node agents v Created the databases Connect to the database using the guided activity. 1. Click Guided Activities. 2. Click Connecting to a Database. 3. Click, Configure a JDBC provider. 4. Click, Click to Perform. 5. Select cell_name from the Scope drop-down list. For example:hostnamecell01 6. Create the New JDBC Provider. a. Click New b. Click Database type and select DB2 c. Click Provider type and select DB2 Universal JDBC Driver Provider. d. Click Implementation type and select XA data source. e. Click Next. f. Keep defaults for paths and other variables on this page. g. Click Next. h. Click Finish 7. Click Save to save changes to the master configuration. 8. Click on DB2 Universal JDBC Driver Provider (XA). 9. Click Data sources under Addtional Properties a. Click New. b. Type a meaningful data source name. For example, XDMS Datasource. c. Type the JNDI name of the XDMS database. For example jdbc/xdms Note: It is recommended that you use the example configurations given here as this will prevent having to change Resource Environment Provider default configurations. However, if you have multiple databases for each IBM XDMS then you must create multiple datasources with unique JNDI names. The Resource Environment Provider for each AUID must be updated with the JNDI names of these datasources. Chapter 3. Installing 41

48 d. From the drop down for Component-managed authentication alias and XA recovery authentication alias, select the authentication alias created earlier. e. Click Next. f. Type the database name. The database name to which this data source connects. For example, XDMS g. Select the driver type. The default driver type is 4. h. Type the fully qualified hostname or IP of the database server. i. Select a port number. The port number is part of the information you gathered and saved after creating the databases j. Unselect the Use this data source in the container managed persistence (CMP) checkbox. 10. Click Next. 11. Click Finish. 12. Click Save. 13. Test the database connection. 14. Restart the node agents and deployment manager. Note: If you have chosen to use two separate databases for the Shared List and Presence Rules applications you must repeat these steps for the each database. Related tasks Stopping and starting the server on page 73 After making changes to the server configuration, you must restart the application server. Configuring a data source for the Service Integration Bus database Use the WebSphere Application Server guided activity to create data source for the Service Integration Bus database. v The IBM XDMS Service Integration Bus database has been created and configured. v The WebSphere Application Server environment variables and Alias have been configured. Before you begin, the following steps should be completed: v Started the deployment manager v Started the node agents v Created the database Connect to the database using the guided activity. Note: Perform this activity only if you are using data stores for the bus members of the Service Integration Bus. If you are using file stores, you can skip this activity. 1. Click Guided Activities. 2. Click Connecting to a Database. 3. Click, Configure a JDBC provider. 4. Click, Click to Perform. 42 XML Document Management Server

49 5. Select cell_name from the Scope drop-down list. 6. Create the New JDBC Provider. a. Click New b. Click Database type and select DB2 c. Click Provider type and select DB2 Universal JDBC Driver Provider. d. Click Implementation type and select Connection Pool data source. Keep the default com.ibm.db2.jcc.db2connectionpooldatasource. e. Click Next. f. Type DB2 Directory locations for driver paths. These are taken from the WebSphere Environment variables, so keep the defaults. g. Click Next. h. Click Finish 7. Click Save to save changes to the master configuration. 8. Click on DB2 Universal JDBC Driver Provider. 9. Click Data sources under Addtional Properties a. Click New. b. Type the JNDI name of the Service Integration Bus database. For example jdbc/xdmssib Note: It is recommended that you use the example configurations given here as this will prevent having to change Resource Environment Provider default configurations. c. From the drop down for Component-managed authentication alias and XA recovery authentication alias, select the authentication alias created earlier. d. Click Next. e. Type the database name. For example, XDMSSIB f. Select the driver type. The default driver type is 4. g. Type the fully qualified host name or IP of the database server. h. Select a port number. The port number is part of the information you gathered and saved after creating the databases i. Un-select the Use this data source in the container managed persistence (CMP) checkbox. 10. Click Next. 11. Click Finish. 12. Click Save. 13. Test the database connection. 14. Restart the node agents and deployment manager. Related tasks Stopping and starting the server on page 73 After making changes to the server configuration, you must restart the application server. Connecting to the Usage Records database Use the WebSphere Application Server guided activity to connect to the Usage Records database. v The usage record database has been created and configured. Chapter 3. Installing 43

50 v The WebSphere Application Server environment variables and Alias have been configured. Before you begin, the following steps should be completed: v Started the deployment manager v Started the node agents v Created the database Connect to the database using the guided activity. 1. Click Guided Activities. 2. Click Connecting to a Database. 3. Click, Configure a JDBC provider. 4. Click, Click to Perform. 5. Select cell_name from the Scope drop-down list. 6. Create the New JDBC Provider. a. Click New b. Click Database type and select DB2 c. Click Provider type and select DB2 Universal JDBC Driver Provider. d. Click Implementation type and select Connection Pool data source. Keep the default com.ibm.db2.jcc.db2connectionpooldatasource. e. Click Next. f. Type DB2 Directory locations for driver paths. These are taken from the WebSphere Environment variables, so keep the defaults. g. Click Next. h. Click Finish 7. Click Save to save changes to the master configuration. 8. Click on DB2 Universal JDBC Driver Provider. 9. Click Data sources under Additional Properties. a. Click New. b. Type the JNDI name of the usage record database. For example jdbc/xdmsur Note: It is recommended that you use the example configurations given here as this will prevent having to change Resource Environment Provider default configurations. c. From the drop down for Component-managed authentication alias and XA recovery authentication alias, select the authentication alias created earlier. d. Click Next. e. Type the name of the database you created for Usage Records, for example XDMSUR. f. Select the driver type. The default driver type is 4. g. Type the fully qualified hostname or IP address of the database server. h. Select a port number. The default is i. Unselect Use this data source in the container managed persistence (CMP). 10. Click Next. 11. Click Finish. 44 XML Document Management Server

51 12. Click Save 13. Test the database connection. 14. Restart WebSphere Application Server. Related tasks Stopping and starting the server on page 73 After making changes to the server configuration, you must restart the application server. Configuring the Service Integration Bus and JMS Two Jython scripts are provided to help you create and delete the Service Integration Bus and JMS artifacts such as connection factories and topics. Messaging engines use a message store for keeping its operating information and message recovery. In a clustered environment, the message store is the Service Integration Bus database, which you created earlier in the installation process. A Service Integration Bus and JMS must be installed on each XDMS cluster. The following scripts are provided: v createxdmsmessaging.py: This script creates the Service Integration Bus and JMS artifacts used by IBM XDMS This script does not currently enable security. v deletexdmsmessaging.py: This script removes Service Integration Bus and JMS artifacts used by IBM XDMS. Note: Refer to the topics for uninstalling the Service Integration Bus and JMS for details about using the deletexdmsmessaging.py script. Related tasks Creating the Service Integration Bus DB2 database on page 34 Create the Service Integration Bus database using the createxdmssibus.sh script. Uninstalling the Service Integration Bus and JMS from the Shared List cluster on page 65 Run the Service Integration Bus and JMS uninstall scripts to remove the Sibus JMS from the Shared List cluster. Uninstalling the Service Integration Bus and JMS from the Presence Rules cluster on page 66 Run the Service Integration Bus and JMS uninstall scripts to remove the Sibus JMS from the Presence Rules cluster. Configuring the Service Integration Bus and JMS for Shared List Use the XDMS WS Admin Jython Script to install and configure the Service Integration Bus and JMS. The XDMS Jython script must be run once for each cluster in your XDMS. Instructions and examples assume that default cluster configurations for the SharedList and PresenceRules components have been used in installation. If you have not followed the defaults or are installing Service Integration Bus and JMS for a custom XDMS application, the parameters may vary. Follow these instructions to run the createxdmsmessaging.py script and configure the Service Integration Bus and JMS. Chapter 3. Installing 45

52 1. Go to the Deployment Manager bin directory. From a command line interface type: cd was_root/profiles/dmgr01/bin/ Note: was_root is the installation root directory for WebSphere Application Server Network Deployment. By default, this directory is: 2. Type /usr/ibm/websphere/appserver /opt/ibm/websphere/appserver./wsadmin.sh -user user_id -password password -lang jython -f script_name { -cluster cluster_name node_name -server server_name} [-busname bus_name] [-busdest bus_destination] [-usebusfilestore [ Where: user_id The administrative user ID. It is required when WebSphere Application Server administrative security is enabled. password The administrative user password. It is required when WebSphere Application Server administrative security is enabled. script_name The path to this script. was_root/installableapps/xdms/scripts/ jmsscripts/createxdmsmessaging.py cluster_name The name of the XDMS cluster. SharedListCluster for Shared List and PresenceRulesCluster for Presence Rules. JNDI_name The JNDI name of the datasource. jdbc/xdmssib is the default JNDI name. node_name Name of the node on which IBM XDMS is installed. Applicable only in single server environments. server_name Name of the server on which IBM XDMS is installed. Applicable only in single server environments. bus_name Name of the bus to be created. The default recommendation for this is XDMSBus. bus_destination Name of bus destination (topic space) to create. This is generated based on the cluster name. usebusfilestore Set this flag in order to use File. file_store_base_dir Override the default filestore location. Only used if -usebusfilestore is also set. The following directories will be used: v Log directory: file_store_base_dir/node_name.server_name-bus_name/ log v Permanent and temporary store directory: file_store_base_dir/ node_name.server_name-bus_name/store Note: The node and server names are not required if a cluster name has been defined. For a cluster, a bus member will be created on each cluster member. By default, the bus members will use a data stores as their message stores. The schema names for each message store will be generated by the script, using the algorithm of NodeName_ServerName, then using the last 30 characters as the schema name. Because all schema names must be unique, if this algorithm will not yield unique names, either create the bus members manually, or edit the script to use a different algorithm in the function generateschemaname. If you wish to use a filestore, rather than a data store for the bus members, pass the flag -usebusfilestore and the message store will be a file store with the default settings. 46 XML Document Management Server

53 Script examples FileStore example Here is an example of what a script command for an XDMS Shared List clustered environment might look like when using FileStore: Go to the Deployment Manager bin directory. From a command line interface type: cd was_root/profiles/dmgr01/bin/ Then type: /wsadmin.sh -user user_id -password password -lang jython -f was_root/installableapps/xdms/scripts DataStore example Note: Recommended for production environments and requires datasource creation Here is an example of what a script command for an XDMS Shared List clustered environment might look like when using DataStore: Go to the Deployment Manager bin directory. From a command line interface type: cd was_root/profiles/dmgr01/bin/ /wsadmin.sh -user user_id -password password -lang jython -f was_root/installableapps/xdms/scripts Configuring the Service Integration Bus and JMS for Presence Rules Use the XDMS WS Admin Jython Script to install and configure the Service Integration Bus and JMS Follow these instructions to run the createxdmsmessaging.py script and configure the Service Integration Bus and JMS. 1. Go to the Deployment Manager bin directory. From a command line interface type: cd was_root/profiles/dmgr01/bin/ Note: was_root is the installation root directory for WebSphere Application Server Network Deployment. By default, this directory is: 2. Type /usr/ibm/websphere/appserver /opt/ibm/websphere/appserver./wsadmin.sh -user user_id -password password -lang jython -f script_name { -cluster cluster_na node_name -server server_name} [-busname bus_name] [-busdest bus_destination] [-usebusfilestore Where: user_id The administrative user ID. It is required when WebSphere Application Server administrative security is enabled. password The administrative user password. It is required when WebSphere Application Server administrative security is enabled. script_name The path to this script. was_root/installableapps/xdms/scripts/ jmsscripts/createxdmsmessaging.py cluster_name The name of the XDMS cluster. SharedListCluster for Shared List and PresenceRulesCluster for Presence Rules. Chapter 3. Installing 47

54 JNDI_name The JNDI name of the datasource. jdbc/xdmssib is the default JNDI name. node_name Name of the node on which IBM XDMS is installed. Applicable only in single server environments. server_name Name of the server on which IBM XDMS is installed. Applicable only in single server environments. bus_name Name of the bus to be created. The default recommendation for this is XDMSBus. bus_destination Name of bus destination (topic space) to create. This is generated based on the cluster name. usebusfilestore Set this flag in order to use File. file_store_base_dir Override the default filestore location. Only used if -usebusfilestore is also set. The following directories will be used: v Log directory: file_store_base_dir/node_name.server_name-bus_name/ log v Permanent and temporary store directory: file_store_base_dir/ node_name.server_name-bus_name/store Note: The node and server names are not required if a cluster name has been defined. For a cluster, a bus member will be created on each cluster member. By default, the bus members will use a data stores as their message stores. The schema names for each message store will be generated by the script, using the algorithm of NodeName_ServerName, then using the last 30 characters as the schema name. Because all schema names must be unique, if this algorithm will not yield unique names, either create the bus members manually, or edit the script to use a different algorithm in the function generateschemaname. If you wish to use a filestore, rather than a data store for the bus members, pass the flag -usebusfilestore and the message store will be a file store with the default settings. Script examples FileStore example Here is an example of what a script command for an XDMS Presence Rules clustered environment might look like when using FileStore: Go to the Deployment Manager bin directory. From a command line interface type: cd was_root/profiles/dmgr01/bin/ Then type: /wsadmin.sh -user user_id -password password -lang jython -f was_root/installableapps/xdms/scripts/jm DataStore example 48 XML Document Management Server Note: Recommended for production environments and requires datasource creation Here is an example of what a script command for an XDMS Presence Rules clustered environment might look like when using DataStore: Go to the Deployment Manager bin directory. From a command line interface type:

55 cd was_root/profiles/dmgr01/bin/ /wsadmin.sh -user user_id -password password -lang jython -f was_root/installableapps/xdms/scripts Preparing the Shared List XDMS In order to use the Shared List XDMS, you must deploy the application (EAR), perform configuration using the Integrated Solutions Console, and then start the application. Deploying Shared List Deploy the Shared List XDMS application (EAR) using the Integrated Solutions Console. Before you begin, the following steps should be completed: v Created the XDMS database and Shard List tables v Created a data source for Shared List XDMS 1. Start the deployment manager. 2. Start the node agent. 3. Log in to the Integrated Solutions Console. a. Open a browser and navigate to the following URL: ibm/console. Where: host_name is the fully qualified host name of the server where the application or the network deployment manager is deployed. port is the secured port used to access the console. The default is Note: The default unsecured port is If you use 9060, you must have http instead of https in the URL. b. Enter an administrator user ID and password. If security is not enabled leave the password field blank. c. Click Log in. 4. Use the Install New Application task to deploy the IBMSharedListXdms.ear. a. Click Applications Enterprise Applications Install New Application. b. Browse to the location of the IBMSharedListXdms.ear file. The default location is was_root/installableapps/xdms/ Note: was_root is the installation root directory for WebSphere Application Server Network Deployment. By default, this directory is: c. Leave the context root blank. d. Click Next. /usr/ibm/websphere/appserver /opt/ibm/websphere/appserver e. Accept the defaults on the Select installation options panel f. Click Next. g. Select the SharedListXDMS and SIPNotify modules. h. Select SharedListCluster from the Clusters and Severs list. i. Click Apply. Verify that the server name for both modules should deploy to the SharedListCluster. j. Click Next. Chapter 3. Installing 49

56 k. Click Finish. 5. Click Save to save changes to the master configuration. Related tasks Stopping and starting the server on page 73 After making changes to the server configuration, you must restart the application server. Configuring the resource provider for the Shared List XDMS If you have not used the default configurations described in this information center, you will need to configure the resource provider for the Shared List XDMS. 50 XML Document Management Server To configure the resource provider, follow these steps: 1. Log in to the Integrated Solutions Console. a. Open a browser and navigate to the following URL: ibm/console. Where: host_name is the fully qualified host name of the server where the application or the network deployment manager is deployed. port is the secured port used to access the console. The default is Note: The default unsecured port is If you use 9060, you must have http instead of https in the URL. b. Enter an administrator user ID and password. If security is not enabled leave the password field blank. c. Click Log in. 2. Click Resources Resource Environment Resource Environment Providers. 3. Select the Cluster=SharedListCluster scope in the drop-down list. 4. Click the Resource Provider Environment for the global ibm-xdms properties and set the superadmin and xcaproot: a. Click ibm-xdms. b. Under Additional Properties, click Custom Properties. You will see the following properties: v superadminuser: A user configured with the super-admin role v superadminpassword: The password for the user defined as superadminuser. You should change the superadminpassword so that it is password. v xcaproot: The XCAP Root of the Aggregation Proxy (if installed) or the XCAP Root of the local server c. Change the value of superadminpassword to password, and leave the default values for the other two properties 5. Go to the Resource Provider Environment for each AUID and configure the data source and table name. a. Click an AUID such as resource-lists, rls-services, com.ibm.resource-listsacls, or com.ibm.rls-services-acls. b. Under Additional Properties, click Custom Properties. c. If you kept all defaults and examples, nothing should need to be configured here. Otherwise, you can configure your custom properties here. Note: At minimum these two properties, db!default!datasource and db!default!table, must match the properties gathered when you

57 created the database. The properties reference the WebSphere AUID variables for data source and data table. You can now start the Shared List cluster. Related tasks Stopping and starting the server on page 73 After making changes to the server configuration, you must restart the application server. Starting the Shared List XDMS After the Shared List XDMS has been deployed, it can be started. Follow these steps to start the Shared List XDMS cluster. 1. Log in to the Integrated Solutions Console. a. Open a browser and navigate to the following URL: ibm/console. Where: host_name is the fully qualified host name of the server where the application or the network deployment manager is deployed. port is the secured port used to access the console. The default is Note: The default unsecured port is If you use 9060, you must have http instead of https in the URL. b. Enter an administrator user ID and password. If security is not enabled leave the password field blank. c. Click Log in. 2. Click Servers Clusters SharedListCluster. 3. Select SharedListCluster. 4. Click Start. Related tasks Stopping and starting the server on page 73 After making changes to the server configuration, you must restart the application server. Preparing the Presence Rules XDMS In order to use the Presence Rules XDMS, you must deploy the application (EAR), perform configuration using the Integrated Solutions Console, and then start the application. Deploying Presence Rules Deploy the Presence Rules XDMS application (EAR) using the Integrated Solutions Console. Before you begin, the following steps should be completed: v Created the XDMS database and Presence Rules tables v Created a data source for Presence Rules XDMS 1. Start the deployment manager. 2. Start the node agent. 3. Log in to the Integrated Solutions Console. Chapter 3. Installing 51

58 a. Open a browser and navigate to the following URL: ibm/console. Where: host_name is the fully qualified host name of the server where the application or the network deployment manager is deployed. port is the secured port used to access the console. The default is Note: The default unsecured port is If you use 9060, you must have http instead of https in the URL. b. Enter an administrator user ID and password. If security is not enabled leave the password field blank. c. Click Log in. 4. Log into the Deployment Manager Web Admin Console. 5. Use the Install New Application task to deploy the IBMPresenceRulesXdms.ear. a. Click Applications Enterprise Applications Install New Application. b. Browse to the location of the IBMPresenceRulesXdms.ear file. The default location is was_root/installableapps/xdms/ Note: was_root is the installation root directory for WebSphere Application Server Network Deployment. By default, this directory is: c. Leave the context root blank. d. Click Next. /usr/ibm/websphere/appserver /opt/ibm/websphere/appserver e. Accept the defaults on the Select installation options panel f. Click Next. g. Select the PresenceRulesXDMS and SIPNotify modules. h. Select PresenceRulesCluster from the Clusters and Severs list. i. Click Apply. Verify that the server name for both modules should deploy to the PresenceRulesCluster. j. Click Next. k. Click Finish. 6. Click Save to save changes to the master configuration. Related tasks Stopping and starting the server on page 73 After making changes to the server configuration, you must restart the application server. Configuring the resource provider for the Presence Rules XDMS If you have not used the default configurations described in this information center, you will need to configure the resource provider for the Presence Rules XDMS. 52 XML Document Management Server To configure the resource provider, follow these steps: 1. Log in to the Integrated Solutions Console. a. Open a browser and navigate to the following URL: ibm/console.

59 Where: host_name is the fully qualified host name of the server where the application or the network deployment manager is deployed. port is the secured port used to access the console. The default is Note: The default unsecured port is If you use 9060, you must have http instead of https in the URL. b. Enter an administrator user ID and password. If security is not enabled leave the password field blank. c. Click Log in. 2. Click Resources Resource Environment Resource Environment Providers. 3. Select thecluster=presencerulescluster scope in the drop-down list. 4. Click Resource Provider Environment for the global ibm-xdms properties and set the superadmin and xcaproot: a. Click ibm-xdms. b. Under Additional Properties, click Custom Properties. You will see the following properties: v superadminuser: A user configured with the super-admin role v superadminpassword: The password for the user defined as superadminuser. You should change the superadminpassword so that it is password. v xcaproot: The XCAP Root of the Aggregation Proxy (if installed) or the XCAP Root of the local server c. Change the value of superadminpassword to password, and leave the default values for the other two properties 5. Go to the Resource Provider Environment for each AUID and configure the data source and table name. a. Click on an AUID such as org.openmobilealliance.pres-rules or com.ibm.pres-rules-acls. b. Under Additional Properties, click Custom Properties. c. If you kept all defaults and examples, nothing should need to be configured here. Otherwise, you can configure your custom properties here. Note: At minimum these two properties, db!default!datasource and db!default!table, must match the properties gathered when you created the database. The properties reference the WebSphere AUID variables for data source and data table. You can now start the Presence Rules cluster. Related tasks Stopping and starting the server on page 73 After making changes to the server configuration, you must restart the application server. Starting the Presence Rules XDMS After the Presence Rules XDMS has been deployed, it can be started. Follow these steps to start the Presence Rules XDMS cluster. 1. Log in to the Integrated Solutions Console. Chapter 3. Installing 53

60 a. Open a browser and navigate to the following URL: ibm/console. Where: host_name is the fully qualified host name of the server where the application or the network deployment manager is deployed. port is the secured port used to access the console. The default is Note: The default unsecured port is If you use 9060, you must have http instead of https in the URL. b. Enter an administrator user ID and password. If security is not enabled leave the password field blank. c. Click Log in. 2. Click Servers Clusters PresenceRulesCluster. 3. Select PresenceRulesCluster. 4. Click Start. Related tasks Installing Aggregation Proxy Stopping and starting the server on page 73 After making changes to the server configuration, you must restart the application server. Aggregation Proxy must be installed on a separate server from the IBM XDMS. Creating the Aggregation Proxy cluster Create a cluster for the Aggregation Proxy in the WebSphere Application Server Network Deployment console, and use the default values that WebSphere Application Server provides. Before you begin, the following software should be installed: v WebSphere Application Server Network Deployment, Version In addition, you should have: v Created a deployment manager profile v Federated all nodes into the deployment manager cell v Configured security Create the AggProxyCluster cluster, and add members, by completing the following steps: 1. Log in to the Integrated Solutions Console. a. Open a browser and navigate to the following URL: host_name:port/ibm/console. Where: host_name is the fully qualified host name of the server where the application or the network deployment manager is deployed. port is the secured port used to access the console. The default is Note: The default unsecured port is If you use 9060, you must have http instead of https in the URL. 54 XML Document Management Server

61 b. Enter an administrator user ID and password. If security is not enabled leave the password field blank. c. Click Log in. 2. In the navigation panel, click Servers Clusters. 3. Click New. 4. Type AggProxyCluster for the Cluster name. 5. Select Prefer local. 6. Click Next. 7. Type the Member name. This is the fully qualified host name of additional WebSphere Application Server servers being added as cluster members. 8. Select the appropriate option for Select basis for first cluster member for your environment. v Select Create the member using an application server template to create a new application server using an existing template. v Select Create the member using an existing application server as a template to create a new application server using another application server as a template. v Select Create the member by converting an existing application server to select an application server from a federated node as the first cluster member. 9. Click Next. 10. Optional: If your environment requires more than one cluster member, add additional cluster members. Repeat the following steps for each cluster member you would like to add. a. Type server_name the member you would like to create. For federated nodes with multiple cluster members, you will need to know the names of each of the members. b. Select the node for the cluster member. c. Select Generate unique HTTP ports. d. Click Add member to add the cluster member. 11. Click Next, and click Finish. 12. Click Save to save changes to the master configuration. 13. Click OK. 14. Start the AggProxyCluster cluster: a. Select the check box corresponding to the AggProxyCluster cluster. b. Click Start. Verify Status for the AggProxyCluster cluster is Started. You must create a proxy server and associate the proxy server with the cluster that you have created. Because IBM XDMS and Aggregation Proxy support both SIP and HTTP, you will need a WebSphere Application Server proxy server that supports HTTP and SIP requests. Refer to the WebSphere Application Server Information Center for additional information on setting up the proxy server. Note: Once you have created the proxy server you need to disable page caching for the HTTP proxy. Related concepts Creating XDMS clusters on page 28 Begin the installation by creating a cluster for each XDMS enabler, Shared List and Presence Rules. Chapter 3. Installing 55

62 Configuring Aggregation Proxy ports Verify that the virtual host assigned to the Aggregation Proxy application has the correct port definition for the HTTP port on you want incoming requests to be accepted. 1. From the WebSphere Application Server console, select Applications Enterprise Applications AggregationProxy Virtual hosts. Note the name of the virtual host assigned to the AggProxyWeb module. For example default_host. 2. Verify that default_host is accessible outside of WebSphere Application Server. 3. From the WebSphere Application Server console select Servers clusters Aggregation Proxy= AggProxyCluster Cluster members Application server(s) name Ports. Note the port number of the WC_defaulthost which must be defined in the virtual host. 4. Verify that virtual host found in the previous step resides (default_host). Closest match is WC_defaulthost Go to Virtual Hosts virtual host= default_host Virtual Hosts Host Aliases and ensure that the port number found in the previous step has been added to the list of ports. If not, add it. Deploying the Aggregation Proxy Perform a default installation of the Aggregation Proxy EAR (IBMXdmsAggregationProxy.ear) from the WebSphere Application Server console. Install the Aggregation Proxy to using the WebSphere Application Server console. Make sure that the EAR is installed to the Aggregation Proxy Cluster, not another server or cluster on the node. Once the Aggregation Proxy is installed configure the security role and resource environment provider. 1. Start the deployment manager. 2. Start the node agent. 3. Log in to the Integrated Solutions Console. a. Open a browser and navigate to the following URL: ibm/console. Where: host_name is the fully qualified host name of the server where the application or the network deployment manager is deployed. port is the secured port used to access the console. The default is Note: The default unsecured port is If you use 9060, you must have http instead of https in the URL. b. Enter an administrator user ID and password. If security is not enabled leave the password field blank. c. Click Log in. 4. Log into the Deployment Manager Web Admin Console. 5. Use the Install New Application task to deploy the IBMXdmsAggregationProxy.ear. a. Click Applications Enterprise Applications Install New Application. b. Browse to the location of the IBMXdmsAggregationProxy.ear file. The default location is was_root/installableapps/xdms/ Note: was_root is the installation root directory for WebSphere Application Server Network Deployment. By default, this directory is: 56 XML Document Management Server

63 c. Leave the context root blank. d. Click Next. /usr/ibm/websphere/appserver /opt/ibm/websphere/appserver e. Accept the defaults on the Select installation options panel f. Click Next. g. Select the AggProxy module. h. Select AggProxyCluster from the Clusters and Severs list. i. Click Apply. Verify that the server name should deploy to the AggProxyCluster. j. Click Next. k. Click Finish. 6. Once the EAR is properly installed you should see that REP values have been created for the Aggregation Proxy to read at its initialization time. From the WebSphere Application Server console go to Resources Resource Environment Resource Environment Providers. 7. Select AggProxyREP from the list of REPs to edit the values. Related concepts Aggregation Proxy Aggregation Proxy is the contact point for the XDM Client implemented access XML documents stored in any XDMS. Aggregation Proxy Aggregation Proxy is the contact point for the XDMS client implemented in an IBM XDMS system to access XML documents stored in any IBM XDMS. Basic Aggregation Proxy routing on page 7 Basic routing uses the list of IBM XDMS enablers configured in the resource environment providers to route requests to specific AUIDs. Advanced Aggregation Proxy routing on page 9 Advanced routing uses domain partitioning and matching to determine the routing of XCAP requests. Related reference Aggregation Proxy Resource Environment Providers on page 157 Several Resource Environment Providers exist for the Aggregation Proxy. Configuring the resource providers for the Aggregation Proxy If you have not used the default configurations used in this information cente,r you will need to configure the resource provider for the Aggregation Proxy XDMS. 1. Log in to the Integrated Solutions Console. a. Open a browser and navigate to the following URL: ibm/console. Where: host_name is the fully qualified host name of the server where the application or the network deployment manager is deployed. port is the secured port used to access the console. The default is Note: The default unsecured port is If you use 9060, you must have http instead of https in the URL. b. Enter an administrator user ID and password. If security is not enabled leave the password field blank. c. Click Log in. Chapter 3. Installing 57

64 2. Click Resources Resource Environment Resource Environment Providers. 3. Select the Cluster=AggProxyCluster scope in the drop-down list. 4. Select AggProxyREP from the list of REPs to edit the values. Example Resource Environment Provider values: Table 1. Aggregation Proxy properties Property name Property value HTTPS_PROXY_XDMS false Property type Required? Property description java.lang.boolean Required Whether or not this Aggregation Proxy s backend XDMS instances are accessed by an https URL PROXY_ROOT java.lang.string Required The portion of the Aggregation proxy.com:9082 Proxy s URL ending with the context root THREEGPP_IMS false java.lang.boolean Required Whether or not the 3GPP-GAA is present. If false, Xdms-Asserted- Identity is used XCAP_CACHE_TIMEOUT 180 java.lang.integer Required Time in seconds that the XCAP-CAPS of each backend XDMS instance should remain in WebSphere s dynamic cache superadminuser superadmin java.lang.string Required ID used by the Aggregation Proxy during initialization and for sending an initial XCAP-CAPS request to each backend XDMS instance superadminpassword password java.lang.string Required Password used by the Aggregation Proxy during initialization XDMS_URI java.lang.string Required XCAP root of XDMS, per domain hostname1:9080/services# XDMS_URI!<domain> java.lang.string Required Defines the domain for which the list sharedlist2.com:9080/services/resource-lists of XDMS enablers is supported XDMS_URI_HTTPS java.lang.string Not The XUIs of the backend XDMS sharedlist1.com:9080/services# required clusters serviced by the Aggregation Proxy. List all XUIs here, separated by a # symbol XDMS_URI_HTTPS!<domain> java.lang.string Not Defines the secure domain for which sharedlist2.com:9080/services/resource-lists required the of XDMS enablers is supported alarminterval 15 java.lang.string Not Time in minutes between alarm required notifications for the same alarm (recommended value: 15) BAD_XDMS_POLLING_INTERVAL 20 java.lang.integer Required Time in seconds for polling XDMS instances that have never been online MAX_PROXY_THREAD_POOL_SIZE 60 java.lang.integer Required Maximum number of threads in the thread pool used to send proxy requests to XDMSes 58 XML Document Management Server Configuring basic routing Configure just the basic routing when domain partitioning and routing are not required. Configuration is performed using the Integrated Solutions Console.

65 1. Log in to the Integrated Solutions Console. a. Open a browser and navigate to the following URL: ibm/console. Where: host_name is the fully qualified host name of the server where the application or the network deployment manager is deployed. port is the secured port used to access the console. The default is Note: The default unsecured port is If you use 9060, you must have http instead of https in the URL. b. Enter an administrator user ID and password. If security is not enabled leave the password field blank. c. Click Log in. 2. Click Resources Resource Environment Resource Environment Providers. 3. Go to the Resource Provider Environment for the Aggregation Proxy, and configure the basic routing. a. Click Custom Properties under additional properties b. Click New. If you are not using HTTPS then create the following minimum custom properties: Table 2. Minimum Resource Environment Provider Custom Properties for Basic Routing Property Example Value Description Notes PROXY_ROOT services Context root of Aggregation Proxy HTTPS_PROXY_XDMS false Enable/disable HTTPS XDMS_URI The list of the List all enablers here, sharedlist1.com:9080/services# backend XDMS separated by a # enablers serviced by the Aggregation Proxy. symbol. Enablers listed here are also known as the Default route. If you are using HTTPS you need to add the following custom properties instead: Table 3. Minimum Resource Environment Provider Custom Properties for Secure HTTPS Basic Routing Property Example Value Description Notes PROXY_ROOT services Context root of Aggregation Proxy HTTPS_PROXY_XDMS true Must be enabled when using HTTPS XDMS_URI_HTTPS Related concepts The XUIs of the List all XUIs here, sharedlist1.com:9080/services# backend XDMS separated by a # clusters serviced by symbol. the Aggregation Proxy. Aggregation Proxy Aggregation Proxy is the contact point for the XDM Client implemented access XML documents stored in any XDMS. Chapter 3. Installing 59

66 Aggregation Proxy Aggregation Proxy is the contact point for the XDMS client implemented in an IBM XDMS system to access XML documents stored in any IBM XDMS. Basic Aggregation Proxy routing on page 7 Basic routing uses the list of IBM XDMS enablers configured in the resource environment providers to route requests to specific AUIDs. Advanced Aggregation Proxy routing on page 9 Advanced routing uses domain partitioning and matching to determine the routing of XCAP requests. Related tasks Configuring advanced routing Configure advanced routing when domain partitioning and matching are required. Related reference Aggregation Proxy Resource Environment Providers on page 157 Several Resource Environment Providers exist for the Aggregation Proxy. Configuring advanced routing Configure advanced routing when domain partitioning and matching are required. Configuration is performed using the Integrated Solutions Console. 1. Log in to the Integrated Solutions Console. a. Open a browser and navigate to the following URL: ibm/console. Where: host_name is the fully qualified host name of the server where the application or the network deployment manager is deployed. port is the secured port used to access the console. The default is Note: The default unsecured port is If you use 9060, you must have http instead of https in the URL. b. Enter an administrator user ID and password. If security is not enabled leave the password field blank. c. Click Log in. 2. Click Resources Resource Environment Resource Environment Providers. 3. Go to the Resource Provider Environment for Aggregation Proxy and configure the basic routing. a. Click Custom Properties under additional properties b. Click New. If you are not using HTTPS then create the following minimum custom properties: Table 4. Minimum Resource Environment Provider Custom Properties for Advanced Routing Property Example Value Description Notes PROXY_ROOT services Context root of Aggregation Proxy HTTPS_PROXY_XDMS false Enable/disable HTTPS 60 XML Document Management Server

67 Table 4. Minimum Resource Environment Provider Custom Properties for Advanced Routing (continued) Property Example Value Description Notes XDMS_URI XDMS_URI!<domain> The list of the List all enablers here, sharedlist1.com:9080/services# backend XDMS separated by a # enablers serviced by the Aggregation Proxy. symbol. Enablers listed here are also known as the Default route. sharedlist2.com:9080/ services/resourcelists Defines the domain for which the list of XDMS enablers is supported Add one property per domain you are serving. Example Property name : 4. XDMS_URI!us.example.com If you are using HTTPS you need to add the following custom properties instead: Table 5. Minimum Resource Environment Provider Custom Properties for Secure HTTPS Advanced Routing Property Example Value Description Notes PROXY_ROOT services Context root of Aggregation Proxy HTTPS_PROXY_XDMS true Must be enabled when using HTTPS XDMS_URI_HTTPS XDMS_URI_HTTPS!<domain> sharedlist2.com:9080/ services/resourcelists Related concepts The XUIs of the List all XUIs here, sharedlist1.com:9080/services# backend XDMS separated by a # clusters serviced by symbol. the Aggregation Proxy. Defines the secure domain for which the list of XDMS enablers is supported Aggregation Proxy Aggregation Proxy is the contact point for the XDM Client implemented access XML documents stored in any XDMS. Aggregation Proxy Aggregation Proxy is the contact point for the XDMS client implemented in an IBM XDMS system to access XML documents stored in any IBM XDMS. Basic Aggregation Proxy routing on page 7 Basic routing uses the list of IBM XDMS enablers configured in the resource environment providers to route requests to specific AUIDs. Advanced Aggregation Proxy routing on page 9 Advanced routing uses domain partitioning and matching to determine the routing of XCAP requests. Related tasks Configuring basic routing on page 58 Configure just the basic routing when domain partitioning and routing are not required. Related reference Chapter 3. Installing 61

68 Aggregation Proxy Resource Environment Providers on page 157 Several Resource Environment Providers exist for the Aggregation Proxy. Starting the Aggregation Proxy cluster After you have deployed the Aggregation Proxy, start the cluster. Follow these steps to start the AggProxyCluster cluster. 1. Log in to the Integrated Solutions Console. a. Open a browser and navigate to the following URL: ibm/console. Where: host_name is the fully qualified host name of the server where the application or the network deployment manager is deployed. port is the secured port used to access the console. The default is Note: The default unsecured port is If you use 9060, you must have http instead of https in the URL. b. Enter an administrator user ID and password. If security is not enabled leave the password field blank. c. Click Log in. 2. Click Servers Clusters AggProxyCluster. 3. Select AggProxyCluster. 4. Click Start. Uninstalling IBM XDMS Related concepts Aggregation Proxy Aggregation Proxy is the contact point for the XDM Client implemented access XML documents stored in any XDMS. Aggregation Proxy Aggregation Proxy is the contact point for the XDMS client implemented in an IBM XDMS system to access XML documents stored in any IBM XDMS. Basic Aggregation Proxy routing on page 7 Basic routing uses the list of IBM XDMS enablers configured in the resource environment providers to route requests to specific AUIDs. Advanced Aggregation Proxy routing on page 9 Advanced routing uses domain partitioning and matching to determine the routing of XCAP requests. Related reference Aggregation Proxy Resource Environment Providers on page 157 Several Resource Environment Providers exist for the Aggregation Proxy. To uninstall IBM XDMS, you must uninstall associated applications and other entities before you install core IBM XDMS components. You will follow these tasks to uninstall IBM XDMS: Uninstalling the Shared List XDMS enterprise application If you are uninstalling IBM XDMS and the Shared List XDMS enterprise application is installed, you must uninstall it. 62 XML Document Management Server

69 To uninstall the Shared List application, perform the following steps: 1. Log in to the Integrated Solutions Console. a. Open a browser and navigate to the following URL: ibm/console. Where: host_name is the fully qualified host name of the server where the application or the network deployment manager is deployed. port is the secured port used to access the console. The default is Note: The default unsecured port is If you use 9060, you must have http instead of https in the URL. b. Enter an administrator user ID and password. If security is not enabled leave the password field blank. c. Click Log in. 2. Uninstall the IBMSharedListXdms_EAR application. a. Click Applications Enterprise Application b. Click to select IBMSharedListXdms_EAR. c. Click Uninstall. d. Click OK to verify that you want to uninstall the application. e. Click Save to save the change to the master configuration. You must now remove the associated resource environment providers. Uninstalling the Presence Rules XDMS enterprise application If you are uninstalling IBM XDMS and the Presence Rules XDMS enterprise application is installed, you must uninstall it. To uninstall the Presence Rules application, perform the following steps: 1. Log in to the Integrated Solutions Console. a. Open a browser and navigate to the following URL: ibm/console. Where: host_name is the fully qualified host name of the server where the application or the network deployment manager is deployed. port is the secured port used to access the console. The default is Note: The default unsecured port is If you use 9060, you must have http instead of https in the URL. b. Enter an administrator user ID and password. If security is not enabled leave the password field blank. c. Click Log in. 2. Uninstall the IBMPresenceRulesXdms_EAR application. a. Click Applications Enterprise Application b. Click to select IBMPresenceRulesXdms_EAR. c. Click Uninstall. d. Click OK to verify that you want to uninstall the application. e. Click Save to save the change to the master configuration. You must now remove the resource environment providers. Chapter 3. Installing 63

70 Removing Resource Environment Providers Remove the Resource Environment Providers. Before you begin: Uninstall the Shared List XDMS and Presence Rules XDMS Enterprise Applications. To remove the Resource Environment Provider: 1. Log in to the Integrated Solutions Console. a. Open a browser and navigate to the following URL: ibm/console. Where: host_name is the fully qualified host name of the server where the application or the network deployment manager is deployed. port is the secured port used to access the console. The default is Note: The default unsecured port is If you use 9060, you must have http instead of https in the URL. b. Enter an administrator user ID and password. If security is not enabled leave the password field blank. c. Click Log in. 2. From the administrative console of the deployment manager go to Resource Environment Resource Environment Provider a. Select the cluster from the scope drop down menu. For example, SharedListCluster or PresenceRulesCLuster. b. Select the AUIDs for the components you are removing. For Shared List select: com.ibm.resource-lists-acls com.ibm.rls-services-acls ibm-xdms resource-lists rls-services For Presence Rules select: com.ibm.pres-rules-acls ibm-xdms org.openmobilealliance.pres-rules c. Click Delete. 3. Save to the master configuration. a. Go to System administration Save Changes to Master Repository. b. Select Synchronize changes with Nodes and click Save. 4. Stop the node agents and deployment manager. a. Stop all node agents. b. Stop the deployment manager. Remove the XDMS core files. Related tasks 64 XML Document Management Server

71 Stopping and starting the server on page 73 After making changes to the server configuration, you must restart the application server. Uninstalling the Service Integration Bus and JMS from the Shared List cluster Run the Service Integration Bus and JMS uninstall scripts to remove the Sibus JMS from the Shared List cluster. To uninstall the JMS artifacts, you need to run two scripts: v deletexdmsmessaging.py: Deletes the objects in WebSphere Application Server v deletexdmssibus.sh: Deletes the schema from the database 1. Start the deployment manager, if it is not already started. 2. From a command-line interface, type:./wsadmin.sh -usernameuser_id -password user_password -lang jython -f script name {-cluster cluster name -node node name -server server name}[-schemasfile schemas file name][-deletebus][debug] -f script name The path to this script. was_root/installableapps/xdms/scripts/ jmsscripts/deletexdmsmessaging.py Note: was_root is the installation root directory for WebSphere Application Server Network Deployment. By default, this directory is: /usr/ibm/websphere/appserver /opt/ibm/websphere/appserver -cluster cluster name The name of the XDMS cluster. SharedListCluster for Shared List and PresenceRulesCluster for Presence Rules. -node node name Name of the Node XDMS is installed on. Only applicable in single server environments. -server server name Name of the server XDMS is installed on. Only applicable in single server environments. -schemasfile schemas file name Name of the output file where generated schemas are to be saved. By default, the schema names will be saved in a file in the current directory with the name cluster nameschemas.lst. You can change this name by using the -schemafile flag. This file will be used as input to into by the schema/table deletion script, deletexdmssibus.sh, in order to delete the schemas and tables for the Service Integration Bus members of this cluster. The file will only be generated if there are bus members that use a data store. deletebus Delete the entire bus, optional. If this parameter is set, then the service integration bus is deleted. Only use this parameter if you wish to delete all artifacts of the bus. Every cluster will have its bus objects deleted. An example of the uninstall script command for Shared List might look like this: First, change to the WebSphere Application Server root directory by running the command: cd was_profile_root/dmgr01/bin Note: was_profile_root is the directory for a WebSphere Application Server Network Deployment profile called profile_name. By default, this directory is: Chapter 3. Installing 65

72 /usr/ibm/websphere/appserver/profiles/profile_name /opt/ibm/websphere/appserver/profiles/profile_name Then, run:./wsadmin.sh -lang jython -f was_root/installableapps/xdms/ scripts/jmsscripts/deletexdmsmessaging.py db_name schema list file name -deletebus db_user db_password 3. Remove the SharedListCluster bus member schemas from the XDMSSIB database. This script will remove the bus member schemas listed in the schema list file and all tables associated with them. Only run it if you do not have any other tables associated with these schemas. This script does not need to be run if there were no bus members which used a data store. a. Copy the was_root/installableapps/xdms/scripts/dbscripts/xdms/ deletexdmssibus.sh to the database server. b. Copy the schema list file to the database server. This file was generated by the deletexdmsmessaging.py script when the XDMS JMS/bus artifacts were uninstalled. c. Log into the database as the DB2 instance owner such as db2inst1 d. Remove the schema used by the SharedListCluster bus members from the XDMSIB database by typing:./deletexdmssibus.sh db_name schema list file name db_user db_password Where: Variable Description db_name Name of the database where the schema for the bus members are located. For example, XDMSSIB. schema list file name File name of input file. This was generated by the deletexdmsmessaging.py script when the XDMS JMS/bus artifacts were uninstalled. This file contains the list of schemas to remove. db_user User name for the DB2 instance owner. db_password DB2 instance owner password. An example of the deletexdmssibus.sh command for Shared List might look like this:./deletexdmssibus.sh XDMSSIB SharedListClusterschemas.lst db2inst1 db_password Related concepts Configuring the Service Integration Bus and JMS on page 45 Two Jython scripts are provided to help you create and delete the Service Integration Bus and JMS artifacts such as connection factories and topics. Uninstalling the Service Integration Bus and JMS from the Presence Rules cluster Run the Service Integration Bus and JMS uninstall scripts to remove the Sibus JMS from the Presence Rules cluster. To uninstall the JMS artifacts, you need to run two scripts: v deletexdmsmessaging.py: Deletes the objects in WebSphere Application Server v deletexdmssibus.sh: Deletes the schema from the database 1. Start the deployment manager, if it is not already started. 66 XML Document Management Server

73 2. From a command line interface type:./wsadmin.sh -usernameuser_id -password user_password -lang jython -f script name {-cluster cluster name -node node name -server server name}[-schemasfile schemas file name][-deletebus][debug] -f script name The path to this script. was_root/installableapps/xdms/scripts/ jmsscripts/deletexdmsmessaging.py Note: was_root is the installation root directory for WebSphere Application Server Network Deployment. By default, this directory is: /usr/ibm/websphere/appserver /opt/ibm/websphere/appserver -cluster cluster name The name of the XDMS cluster. SharedListCluster for Shared List and PresenceRulesCluster for Presence Rules. -node node name Name of the Node XDMS is installed on. Only applicable in single server environments. -server server name Name of the server XDMS is installed on. Only applicable in single server environments. -schemasfile schemas file name Name of the output file where generated schemas are to be saved. By default, the schema names will be saved in a file in the current directory with the name cluster nameschemas.lst. You can change this name by using the -schemafile flag. This file will be used as input to into by the schema/table deletion script, deletexdmssibus.sh, in order to delete the schemas and tables for the Service Integration Bus members of this cluster. The file will only be generated if there are bus members that use a data store. deletebus Delete the entire bus, optional. If this parameter is set, then the service integration bus is deleted. Only use this parameter if you wish to delete all artifacts of the bus. Every cluster will have its bus objects deleted. An example of the uninstall script command for Presence Rules might look like this: First, change to the WebSphere Application Server root directory by running the command: cd was_profile_root/dmgr01/bin Note: was_profile_root is the directory for a WebSphere Application Server Network Deployment profile called profile_name. By default, this directory is: /usr/ibm/websphere/appserver/profiles/profile_name /opt/ibm/websphere/appserver/profiles/profile_name Then, run:./wsadmin.sh -lang jython -f was_root/installableapps/xdms/ scripts/jmsscripts/deletexdmsmessaging.py db_name schema list file name -deletebus db_user db_password 3. Remove the PresenceRulesCluster bus member schemas from the XDMSSIB database. This script will remove the bus member schemas listed in the schema list file and all tables associated with them. Only run it if you do not have any other tables associated with these schemas. This script does not need to be run if there were no bus members which used a data store. a. Copy the was_root/installableapps/xdms/scripts/dbscripts/xdms/ deletexdmssibus.sh to the database server. Chapter 3. Installing 67

74 b. Copy the schema list file to the database server. This file was generated by the deletexdmsmessaging.py script when the XDMS JMS/bus artifacts were uninstalled. c. Log into the database as the DB2 instance owner such as db2inst1 d. Remove the schema used by the PresenceRulesCluster bus members from the XDMSIB database by typing:./deletexdmssibus.sh db_name schema list file name db_user db_password Variable Where: Description db_name Name of the database where the schema for the bus members are located. For example, XDMSSIB. schema list file name File name of input file. This was generated by the deletexdmsmessaging.py script when the XDMS JMS/bus artifacts were uninstalled. This file contains the list of schemas to remove. db_user User name for the DB2 instance owner. db_password DB2 instance owner password. An example of the deletexdmssibus.sh command for Presence Rules might look like this:./deletexdmssibus.sh XDMSSIB PresennceRulesClusterSchemas.lst db2inst1 password Related concepts Configuring the Service Integration Bus and JMS on page 45 Two Jython scripts are provided to help you create and delete the Service Integration Bus and JMS artifacts such as connection factories and topics. Dropping the Service Integration Bus and JMS database After you have uninstalled other Service Integration Bus and JMS components, drop the database. From the DB2 command line, follow these instructions to drop the JMS Sibus database (XDMSSIB). 1. Log into DB2 as the instance owner. 2. Issue the following command: db2 drop database XDMSSIB Uninstalling the Aggregation Proxy enterprise application If you are uninstalling IBM XDMS and the Aggregation Proxy enterprise application is installed, you must uninstall it. To uninstall the Aggregation Proxy application, perform the following steps: 1. Log in to the Integrated Solutions Console. a. Open a browser and navigate to the following URL: ibm/console. Where: host_name is the fully qualified host name of the server where the application or the network deployment manager is deployed. port is the secured port used to access the console. The default is XML Document Management Server

75 Note: The default unsecured port is If you use 9060, you must have http instead of https in the URL. b. Enter an administrator user ID and password. If security is not enabled leave the password field blank. c. Click Log in. 2. Uninstall the IBMXdmsAggregationProxy.ear application. a. Click Applications Enterprise Application b. Click to select IBMXdmsAggregationProxy.ear. c. Click Uninstall. d. Click OK to verify that you want to uninstall the application. e. Click Save to save the change to the master configuration. You must now remove the associated resource environment providers. Removing Aggregation Proxy Resource Environment Providers Remove the Resource Environment Providers. Before you begin: Uninstall the Shared List XDMS and Presence Rules XDMS Enterprise Applications. To remove the Resource Environment Provider: 1. Log in to the Integrated Solutions Console. a. Open a browser and navigate to the following URL: ibm/console. Where: host_name is the fully qualified host name of the server where the application or the network deployment manager is deployed. port is the secured port used to access the console. The default is Note: The default unsecured port is If you use 9060, you must have http instead of https in the URL. b. Enter an administrator user ID and password. If security is not enabled leave the password field blank. c. Click Log in. 2. From the administrative console of the deployment manager go to Resource Environment Resource Environment Provider a. Select the cluster from the scope drop down menu. For example, AggProxyCluster. b. Select AggProxyREP. c. Click Delete. 3. Save to the master configuration. a. Go to System administration Save Changes to Master Repository. b. Select Synchronize changes with Nodes and click Save. 4. Stop the node agents and deployment manager. a. Stop all node agents. b. Stop the deployment manager. Chapter 3. Installing 69

76 Uninstalling core IBM XDMS components After removing associated applications and other entities, remove the core IBM XDMS components from the system. Before you begin: v Uninstall the enterprise application EAR files for installed XDMS applications. v Remove the Resource Environment Provider(s). v Shut down the deployment manager and nodes. To uninstall the core components ofibm XDMS, follow the instructions in the following sections: Uninstalling IBM XDMS core Remove the core IBM XDMS files from the system. Before you begin: v Uninstall the enterprise application EAR files for installed XDMS applications. v Remove the Resource Environment Provider(s). v Shut down the deployment manager and nodes. To uninstall the core files foribm XDMS, perform the following steps. 1. Access the uninstall script directory by changing to thewas_root /installableapps/xdms/scripts/uninstall directory. Note: was_root is the installation root directory for WebSphere Application Server Network Deployment. By default, this directory is: /usr/ibm/websphere/appserver /opt/ibm/websphere/appserver a. On a command line, run the following command: was_root/installableapps/xdms/scripts/uninstall 2. To uninstall IBM XDMS files, run the uninstall.sh script. a. On a command line, run one of the following commands:./uninstall.sh or./sh uninstall.sh Note: This script must be run from thewas_root/installableapps/xdms/ scripts/uninstall directory. It cannot be moved. After running this script, removal of IBM XDMS core files from the WebSphere Application Server installation is complete 3. Clear the OSGI Bundle cache by executing the following commands on each profile node: a. Reinitialize the OSGI configuration by running osgicfginit: was_profile_root/profile/bin/osgicfginit.sh Note: was_profile_root is the directory for a WebSphere Application Server Network Deployment profile called profile_name. By default, this directory is: /usr/ibm/websphere/appserver/profiles/profile_name /opt/ibm/websphere/appserver/profiles/profile_name 70 XML Document Management Server

77 b. Clear the OSGI class cache by running clearclasscache: was_profile_root/profile/bin/clearclasscache.sh Note: It is important that the above two commands are run for each profile. Thus if you have AppSrv01 and AppSrv02 then you must run the osgicfginit.sh and clearclasscache.sh twice for each profile. 4. Drop the IBM XDMS database: a. Log into DB2, using the databases that were created in previous steps in the topics Creating the IBM Shared List XDMS database and Creating the IBM Presence Rules XDMS database as the instance owner. b. Run the command db2 drop database XDMS. Uninstalling the Trust Association Interceptor Security Component The Trust Association Interceptor feature is uninstalled from the WebSphere Application Server Administration Console. Perform the following steps to uninstall the interceptor: 1. Delete the DHAIMSConnectorTAI.jar from the was_root/lib/ext. Note: was_root is the installation root directory for WebSphere Application Server Network Deployment. By default, this directory is: /usr/ibm/websphere/appserver /opt/ibm/websphere/appserver 2. Launch the WebSphere Application Server Administration Console. 3. Click Security Secure administration, applications, and infrastructure. 4. Under Authentication Web Security, select Disable trust association. Note: You can keep the trust association enabled and then uninstall the interceptors using the following instructions. 5. Click OK. 6. Click Save. 7. Return to Authentication Web Security Trust Assocation. 8. Under Additional Properties, click Intercepters. 9. Select com.ibm.imsconnector.tai.httpinterceptor and com.ibm.imsconnector.tai.sipinterceptor. 10. Click Delete. 11. Click Save. 12. Restart the server. Uninstalling the Aggregation Proxy interceptor security component The Aggregation Proxy interceptor feature is uninstalled from the WebSphere Application Server Administration Console. Perform the following steps to uninstall the interceptor: 1. Delete the AggProxyTai.jar from the was_root/lib/ext. Note: was_root is the installation root directory for WebSphere Application Server Network Deployment. By default, this directory is: /usr/ibm/websphere/appserver Chapter 3. Installing 71

78 /opt/ibm/websphere/appserver 2. Launch the WebSphere Application Server Administration Console. 3. Click Security Secure administration, applications, and infrastructure. 4. Under Authentication Web Security, unselect Enable trust association. Note: You can keep the trust association enabled and then uninstall the Aggregation Proxy intercepter per instructions below. 5. Click OK. 6. Click Save. 7. Return to Authentication Web Security Trust Assocation. 8. Under Additional Properties, click Intercepters. 9. Select com.ibm.glm.http.security.tai.httpdigesttai. 10. Click Delete. 11. Click Save. 12. Restart the server. 72 XML Document Management Server

79 Chapter 4. Administering IBM XDMS From the command-line interface, you can perform administrative tasks for IBM XDMS such as adding, deleting, and modifying policy documents. Related tasks Adding new policy documents on page 80 Add new policy documents using the xcap_put.sh request. Adding and editing documents on page 90 Use the xcap_put.sh request to add or edit documents from the command line interface. Retrieving documents on page 93 Use the xcap_get.sh request to retrieve stored documents. Deleting documents on page 94 Use the xcap_delete.sh request to delete XDMS documents. Searching documents on page 95 Use the xcap_post.sh request to search documents from the command line interface. Related reference Example Policy documents on page 159 Examples of XDMS Policy documents Stopping and starting the server After making changes to the server configuration, you must restart the application server. In a clustered environment, some tasks require you to restart the deployment manager for changes to take effect. To stop the deployment manager, you must stop all application servers, all node agents, and then the deployment manager. To restart the deployment manager, you must start the deployment manager, all node agents, and then the cluster (which starts all application servers). The following instructions describe how to stop and restart resources both from the Integrated Solutions Console and from a command-line prompt. Note: was_profile_root is the directory for a WebSphere Application Server Network Deployment profile called profile_name. By default, this directory is: /usr/ibm/websphere/appserver/profiles/profile_name /opt/ibm/websphere/appserver/profiles/profile_name Stopping a cluster When you stop a cluster, all application servers on the cluster are stopped. 1. Log in to the Integrated Solutions Console. a. Open a browser and navigate to the following URL: ibm/console. Where: host_name is the fully qualified host name of the server where the application or the network deployment manager is deployed. port is the secured port used to access the console. The default is Copyright IBM Corp

80 Note: The default unsecured port is If you use 9060, you must have http instead of https in the URL. b. Enter an administrator user ID and password. If security is not enabled leave the password field blank. c. Click Log in. 2. Stop the cluster: a. In the Integrated Solutions Console, click Servers Clusters. b. Select the checkbox associated with the name of the cluster. c. Click Stop. Stopping a server (console) Stopping an application server stops all applications automatically. 1. Log in to the Integrated Solutions Console. a. Open a browser and navigate to the following URL: ibm/console. Where: host_name is the fully qualified host name of the server where the application or the network deployment manager is deployed. port is the secured port used to access the console. The default is Note: The default unsecured port is If you use 9060, you must have http instead of https in the URL. b. Enter an administrator user ID and password. If security is not enabled leave the password field blank. c. Click Log in. 2. Stop the application server: a. In the Integrated Solutions Console, click Servers Application Servers. b. Select the checkbox associated with the name of the server. c. Click Stop. Stopping a server (command line) Run the following command: was_profile_root/bin/stopserver.sh server_name -username user_name -password password Where: profile_name within the was_profile_root path is the name of the application server profile server_name is name of the application server user_name represents your WebSphere Application Server administrator user ID. password represents the password associated with your user_name. Stopping the node agent (console) When stopping the deployment manager and application servers, you must also stop the node agents. If you are stopping a cluster, you must stop all node agents. 1. Log in to the Integrated Solutions Console. a. Open a browser and navigate to the following URL: ibm/console. 74 XML Document Management Server

81 Where: host_name is the fully qualified host name of the server where the application or the network deployment manager is deployed. port is the secured port used to access the console. The default is Note: The default unsecured port is If you use 9060, you must have http instead of https in the URL. b. Enter an administrator user ID and password. If security is not enabled leave the password field blank. c. Click Log in. 2. Stop one or more nodes: a. In the Integrated Solutions Console, click System Administration Node Agents. b. Select the checkboxes associated with each node. c. Click Stop. Stopping the node agent (command line) Run the following command: was_profile_root/bin/stopnode.sh -username user_name -password password Where: profile_name within the was_profile_root path is the name of a federated node profile user_name represents your WebSphere Application Server administrator user ID. password represents the password associated with your user_name. Stopping the deployment manager (console) When stopping the servers and node agents in a cluster, you must also stop the deployment manager. When the deployment manager is stopped, you will not be able to access the Integrated Solutions Console. 1. Log in to the Integrated Solutions Console. a. Open a browser and navigate to the following URL: ibm/console. Where: host_name is the fully qualified host name of the server where the application or the network deployment manager is deployed. port is the secured port used to access the console. The default is Note: The default unsecured port is If you use 9060, you must have http instead of https in the URL. b. Enter an administrator user ID and password. If security is not enabled leave the password field blank. c. Click Log in. 2. Stop the deployment manager: a. In the Integrated Solutions Console, click System Administration Deployment Manager. b. Click Stop. Chapter 4. Administering 75

82 Stopping the deployment manager (command line) Run the following command: was_profile_root/bin/stopmanager.sh -username user_name -password password Where: profile_name within the was_profile_root path is the name of the deployment manager profile user_name represents your WebSphere Application Server administrator user ID. password represents the password associated with your user_name. Starting the deployment manager Start the deployment manager before starting the node agents and application servers. When the deployment manager is started, you will have access to the Integrated Solutions Console. Run the following command: was_profile_root/bin/startmanager.sh -username user_name -password password Where: profile_name within the was_profile_root path is the name of the deployment manager profile user_name represents your WebSphere Application Server administrator user ID. password represents the password associated with your user_name. Starting the node agents After starting the deployment manager, you must start the node agents before you can start the cluster or the application server. Run the following command: was_profile_root/bin/startnode.sh -username user_name -password password Where: profile_name within the was_profile_root path is the name of a federated node profile user_name represents your WebSphere Application Server administrator user ID. password represents the password associated with your user_name. Starting a cluster When you start a cluster, all application servers on the cluster are started. 1. Log in to the Integrated Solutions Console. a. Open a browser and navigate to the following URL: ibm/console. Where: host_name is the fully qualified host name of the server where the application or the network deployment manager is deployed. port is the secured port used to access the console. The default is XML Document Management Server

83 Note: The default unsecured port is If you use 9060, you must have http instead of https in the URL. b. Enter an administrator user ID and password. If security is not enabled leave the password field blank. c. Click Log in. 2. Start the cluster: a. In the Integrated Solutions Console, click Servers Clusters. b. Select the checkbox associated with the name of the cluster. c. Click Start. Starting a server (console) When you start a server, the applications will start automatically. 1. Log in to the Integrated Solutions Console. a. Open a browser and navigate to the following URL: ibm/console. Where: host_name is the fully qualified host name of the server where the application or the network deployment manager is deployed. port is the secured port used to access the console. The default is Note: The default unsecured port is If you use 9060, you must have http instead of https in the URL. b. Enter an administrator user ID and password. If security is not enabled leave the password field blank. c. Click Log in. 2. Start the application server: a. In the Integrated Solutions Console, click Servers Application Servers. b. Select the checkbox associated with the name of the server. c. Click Start. Starting a server (command line) Run the following command: was_profile_root/bin/startserver.sh server_name -username user_name -password password Where: Policy based authorization profile_name within the was_profile_root path is the name of the application server profile server_name is name of the application server. user_name represents your WebSphere Application Server administrator user ID. password represents the password associated with your user_name. Policy based authorization allows users to specify authorization rules by sending XCAP requests to create, update, or delete authorization documents. Chapter 4. Administering 77

84 The authorization policy documents are based on the IETF common policy specification draft-ietf-geopriv-common-policy-11 and the OMA common policy extensions documented in section of the XDM_Core_V2 specification. The common policy documents contain a set of rules. Each rule contains three elements: conditions, transformations (not used in IBM XDMS), and actions (also not supported by IBM XDMS). The IETF geopriv common policy provides ways to specify the following identities: v one: One specific authenticated identity. An identity element can specify multiple one elements. v many: Matches all authenticated identities including the anonymous identity. Can include except elements to exclude specific identities. The OMA XDM Core extends the conditions element to allow references besides the identity element: v external-list: A reference to a resource-list that contains multiple authenticated identities. v anonymous-request: A reference to an anonymous identity. This may or may not refer to unauthenticated users. It is determined by the Trust Association Interceptor (TAI) to create the special anonymous.invalid principal when receiving a request from a requester. The IBM XDMS provides a way to specify authorization policies at various levels of the XCAP URI path hierarchy. The URI and name of the document will determine the access type that it grants. The AUID for authorization policy documents will depend on the AUID of the document being protected. Here are the various levels where authorization policies can be applied: Table 6. Access levels for authorization policies Access type Description Policy Document XCAP URI Global directory Who has access to all documents in the global directory. Global file Who has access to a specific document in the global directory. XUI domain XUI directory Who has access to all documents that match an XUI domain/subdomain. The XUI for the domain is specified with the domain scheme such as domain:<subdomain>. This prevents name collisions with a real user within the XUI. Who has access to all documents in the XUI directory XML Document Management Server

85 Table 6. Access levels for authorization policies (continued) Access type Description Policy Document XCAP URI XUI file Who has access to a specific document in the XUI directory. The AUID for authorization policy documents will depend on the AUID of the document being protected. The suggested naming convention is com.ibm.auid-acls. The name of the authorization policy AUID for the resource-lists AUID is com.ibm.resource-lists-acls. The IBM authorization policy includes a schema that describes the special authorization rules that are allowed for an authorization policy. The rule attribute id describes the access levels and can contain the following attribute values: v read: Grants the read permission to read the contents of the target document or element. Also includes the ability to subscribe to the document. v write: Grants the write permission to write to the contents of the target document or element. v delete: Grants the delete permission to delete the contents of the target document or element. v admin: Grants the admin permission which encompasses the above read, write, and delete permissions as well as allows the ability to modify the authorization policy document. The following elements are listed in the Open Mobile Alliance specifications for policy documents but are not supported by the IBM XDMS: v sphere: No context-specific rules allowed for authorization rules v validity: No time-based conditions allowed for authorization rules v actions: No special actions needed because permissions are defined in the rule ID v transformations: No special transformations allowed for authorization rules v media: No special media characteristics affect authorization rules You can create policy documents using any editor you choose. Related tasks Adding new policy documents on page 80 Add new policy documents using the xcap_put.sh request. Adding and editing documents on page 90 Use the xcap_put.sh request to add or edit documents from the command line interface. Retrieving documents on page 93 Use the xcap_get.sh request to retrieve stored documents. Deleting documents on page 94 Use the xcap_delete.sh request to delete XDMS documents. Searching documents on page 95 Use the xcap_post.sh request to search documents from the command line interface. Related reference Example Policy documents on page 159 Examples of XDMS Policy documents Chapter 4. Administering 79

86 Adding new policy documents Add new policy documents using the xcap_put.sh request. Before using the XDMS client and XCAP requests, make sure that you have JDK1.5.0 SR 5 installed and configured in your system path variables. Create or edit an XDM policy document and post it to the XDMS. 1. Reach the command client by typing the following from the command-line directory: cd was_root/installableapps/xdms/client/ Note: was_root is the installation root directory for WebSphere Application Server Network Deployment. By default, this directory is: 2. Type the XCAP Put request. /usr/ibm/websphere/appserver /opt/ibm/websphere/appserver./xcap_put.sh -user user_id -password password -filename file_name -content_type application/auth For example, to post a Resource List policy document name resourcelistspolicy.xml to the XDMS server for example.com, type the following parameters on a single line../xcap_put.sh -user admin -password adminpassword -filename path/resourcelistspolicy.xml -content 3. Press Enter to send the request. The new policy document is posted to the XDMS in the specified location in this case, the global directory to protect the document named resourcelistspolicy.xml. Policy documents can be retrieved or deleted using the XCAP Get and XCAP Delete commands. Related concepts Chapter 4, Administering IBM XDMS, on page 73 From the command-line interface, you can perform administrative tasks for IBM XDMS such as adding, deleting, and modifying policy documents. Policy based authorization on page 77 Policy based authorization allows users to specify authorization rules by sending XCAP requests to create, update, or delete authorization documents. Related reference Example Policy documents on page 159 Examples of XDMS Policy documents Granting a single identity admin access to a specific document The following task illustrates how a user can grant a single identity with administrative permission access to a specific document in their home directory. Preconditions: 1. User John Doe (sip:[email protected]) owns a buddy list document in his home directory with the following XCAP URI: sip:[email protected]/buddylist.xml 2. John has a friend Bob (sip:[email protected]) who would like admin access to John s buddy list. 80 XML Document Management Server

87 In order for John to provide Bob access, John must create an authorization policy document that complies with the IETF common policy specification. The authorization policy document must look like this to provide Bob admin access. <?xml version="1.0" encoding="utf-8"?> <ruleset xmlns="urn:ietf:params:xml:ns:common-policy"> <rule id="admin"> <conditions> <identity> <one /> </identity> </conditions> </rule> </ruleset> The above authorization policy document must be created with the exact XCAP URI as the original resource-lists document except the AUID is substituted with the access control list (ACL) AUID which is com.ibm.resource-lists-acls. This defines the authorization policy document that grants admin access to Bob for the corresponding buddy list document that is stored in the resource-lists AUID. Create or edit an XDM policy document and post it to the XDMS. 1. Reach the command client by typing the following from the command line: cd was_root/installableapps/xdms/client/ Note: was_root is the installation root directory for WebSphere Application Server Network Deployment. By default, this directory is: 2. Type the XCAP Put request. /usr/ibm/websphere/appserver /opt/ibm/websphere/appserver./xcap_put.sh -user user_id -password password -filename file_name -content_type application/au For example, to put the example above to the XDMS server for xdms.example.com, type the following parameters on a single line:./xcap_put.sh -user sip:[email protected] -password password -filename samples/authpolicy 3. Press Enter to send the request. The new policy document is put to the XDMS in the specified location in this case, for the XCAP URI that corresponds to the authorization policy document that protects John s buddy list document. Policy documents can be retrieved or deleted using the XCAP Get and XCAP Delete commands. Granting many identities read access to all documents in a directory The following task illustrates how a user can grant multiple identities read access to all documents in their home directory. Preconditions: 1. John would like to share all documents in his directory except with hacker Sam (sip:[email protected]). Chapter 4. Administering 81

88 In order for John to provide everyone read access except for Sam, John must create an authorization policy document that complies with the IETF common policy specification. The authorization policy document must look like this to provide everyone read access except for Sam. <?xml version="1.0" encoding="utf-8"?> <ruleset xmlns="urn:ietf:params:xml:ns:common-policy"> <rule id="read"> <conditions> <identity> <many> <except </many> </identity> </conditions> </rule> </ruleset> The authorization policy document must be created with the XCAP URI to a special directory.xml in John s home directory with the access control list (ACL) AUID which is com.ibm.resource-lists-acls. services/com.ibm.resource-lists-acls/users/sip:[email protected]/ directory.xml This defines the authorization policy document that grants read access to everyone (many) except for Sam to read any document stored in John s home directory for the corresponding resource-lists AUID. Before using the XDMS client and XCAP requests, make sure that you have JDK1.5.0 SR 5 installed and configured in your system path variables. Create or edit an XDM policy document and post it to the XDMS. 1. Reach the command client by typing the following from the command line:cd was_root/installableapps/xdms/client/ Note: was_root is the installation root directory for WebSphere Application Server Network Deployment. By default, this directory is: 2. Type the XCAP Put request. /usr/ibm/websphere/appserver /opt/ibm/websphere/appserver./xcap_put.sh -user user_id -password password -filename file_name -content_type application/auth For example, to put the example above to the XDMS server for xdms.example.com, type the following parameters on a single line: /xcap_put.sh -user sip:[email protected] -password password -filename samples/authpolicyman 3. Press Enter to send the request. The new policy document is put to the XDMS in the specified location in this case, for the XCAP URI that corresponds to the authorization policy document that protects all documents in John s home directory. Policy documents can be retrieved or deleted using the XCAP Get and XCAP Delete commands. 82 XML Document Management Server

89 Granting a group of identities write access to all documents in a domain The following task illustrates how a user can grant a group of identities write access to all documents in a domain. Preconditions: 1. User SuperAdmin (superadmin) owns a domain user list document in his home directory with the following XCAP URI: services/resource-lists/users/superadmin/domainuserlist.xml 2. The domain user list document above contains a list named ServicesForUSDomain. This special list contains a list of service IDs that the SuperAdmin will provision to grant write access to all documents within a certain user domain. <?xml version="1.0" encoding="utf-8"?> <resource-lists xmlns="urn:ietf:params:xml:ns:resource-lists" <list name="servicesforusdomain"> <entry uri="sip:[email protected]"/> <entry uri="sip:[email protected]"/> </list> </resource-lists> In order for the SuperAdmin to provide write access to service IDs listed in the domain user list document, the SuperAdmin user must create an authorization policy document that complies with the IETF common policy specification. The authorization policy document must look like this to reference the external list ServicesForUSDomain defined in the domain user list document above. <?xml version="1.0" encoding="utf-8"?> <ruleset xmlns="urn:ietf:params:xml:ns:common-policy" xmlns:oma="urn:oma:xml:xdm:common-policy"> <rule id="write"> <conditions> <oma:external-list> <oma:entry anc=" </oma:external-list> </conditions> <actions /> <transformations /> </rule> </ruleset> Note: Take note of the following: v The <oma:external-list> element contains an oma prefix because the element is defined in the OMA schema for common-policy. v The <oma:entry> element contains an anc attribute which is an anchor to a fully qualified resource-lists element. The Node Selector references the specific ServicesForUSDomain list. v The anc attribute must be percent encoded therefore the latter portion of the Node Selector list[@name= ServicesForUSDomain ] is percent encoded into list%5b@name=%22servicesforusdomain%22%5d. The authorization policy document must be created with the XCAP URI to a special directory.xml within a special users XUI named domain:us.example.com with the access control list (ACL) AUID which is com.ibm.resource-lists- Chapter 4. Administering 83

90 acls. users/domain:us.example.com/directory.xml This defines the authorization policy document that grants write access to all service IDs,within the domain user list document, to write to any document stored in any users directory that is under the domain us.example.com (including sub-domains) for the corresponding resource-lists AUID. Before using the XDMS client and XCAP requests, make sure that you have JDK1.5.0 SR 5 installed and configured in your system path variables. Create or edit an XDM policy document and post it to the XDMS. 1. Reach the command client by typing the following from the command line: cd was_root/installableapps/xdms/client/ Note: was_root is the installation root directory for WebSphere Application Server Network Deployment. By default, this directory is: 2. Type the XCAP Put request: /usr/ibm/websphere/appserver /opt/ibm/websphere/appserver./xcap_put.sh -user user_id -password password -filename file_name -content_type application/auth For example, to put the file to the XDMS server for xdms.example.com, type the following parameters on a single line../xcap_put.sh -user superadmin -password password -filename samples/authpolicyexternallistwrite.x 3. Press Enter to send the request. The new policy document is posted to the XDMS in the specified location in this case, for the XCAP URI that corresponds to the special directory.xml authorization policy document that protects the us.example.com domain. Policy documents can be retrieved or deleted using the XCAP Get and XCAP Delete commands. Using IBM Tivoli License Manager The IBM Tivoli License Manager (ITLM) product is used to detect where IBM products are both installed and running. ITLM is installed with each of the IBM WebSphere products for Telecom. Compatibility This release of IBM WebSphere XML Document Management Server Component runs with ITLM server version 2.2. Note: The ITLM agent version 2.2 might not be compatible with all versions of the operating systems supported by IBM XDMS. Review the ITLM documentation carefully to determine which operating systems, maintenance levels, and Linux kernel versions are supported. Installation During the installation of IBM XDMS, the inventory signatures for ITLM are installed in the was_profile_root/installedapps directory. 84 XML Document Management Server

91 Inventory Signature The ITLM inventory signature file uniquely identifies the product and is installed with the IBM XDMS EAR into WebSphere Application Server. Its name is IMSXDM0602.SYS2. License file IBM XDMS comes with a license file that is not associated with ITLM enablement, but is still important for licensing purposes. This text file specifies the customer s entitlement of installation and use of the product. Usage Signature The ITLM usage signature, generated by the Software Catalogue Signature team, is used to identify each component as a J2EE product. Chapter 4. Administering 85

92 86 XML Document Management Server

93 Chapter 5. Managing documents You can view, add, edit and delete documents from the XDMS using XCAP requests. Before using the XDMS client and XCAP requests, make sure that you have JDK1.5.0 SR 5 from IBM, installed and configured in your system path variables. Note: You must be authorized to access the XCAP servlet or be an authenticated WebSphere Application Server user, depending on the selection made for the Security role mapping to the user/group option during the installation process. If security is enabled, IBM WebSphere XDMS Component will authenticate your user ID and password. If you do not specify the password, and security is enabled, then XDMS will prompt you and hide the text during input. If security is not enabled, you may still enter a user ID and password, but IBM XDMS will not authenticate them. Follow the instructions in the following sections to manage documents: Using IBM XDMS to store and manage documents IBM WebSphere XML Document Management Server Component enables storage, access, and manipulation of XML documents stored in a central repository. IBM XDMS stores documents in central DB2 databases. The XDMS databases contain tables identified and named by an Application Unique Identifier (AUID). The stored documents can then be accessed and manipulated using one of two protocols: v XML Configuration Access Protocol (XCAP) over HTTP v Session Initiation Protocol (SIP) IBM XDMS reduces overhead and bandwidth by enabling the selection and manipulation of specific elements within an XML document instead of the entire document. The XCAP specification allows the specification of a node selector, which is a subset of XPath. Related tasks Adding and editing documents on page 90 Use the xcap_put.sh request to add or edit documents from the command line interface. Retrieving documents on page 93 Use the xcap_get.sh request to retrieve stored documents. Deleting documents on page 94 Use the xcap_delete.sh request to delete XDMS documents. Adding and editing elements on page 91 Using a node selector statement in the XCAP URI you can select elements to be added or edited in an existing document. Adding and editing attributes on page 92 Using a node selector statement in the XCAP URI you can select attributes to be added or edited in an existing document. Copyright IBM Corp

94 Related reference Example Resource List document on page 160 Example Resource List document. TestResourceList.xml Using XCAP to store and manage documents The XCAP specification defines how an HTTP Web address can identify the way XML documents are stored on an XCAP server. It also defines how the URI can be used to identify entire XML documents, individual elements, or XML attributes that can be retrieved, updated, or deleted The XML documents are stored on an XCAP server, which acts as a repository for documents with each application having access to multiple documents for each user. Each XCAP resource on an XCAP server has an associated application. For the associated application to use the XCAP resources, the application must have the following usage information: v An Application Unique ID (AUID), which uniquely identifies the application usage, must be created. v An XML schema must be defined. v The default namespace binding, which maps the namespace prefixes to the namespace URIs, must be set. v The MIME type of the document must be defined. v The XCAP server must be able to validate the content of each XCAP document that is being modified. v The XML documents to be managed for an application must be well-formed. v Naming conventions for XCAP client URIs must be set. v Resource interdependencies, how changes to one resource will affect other resources, have to be determined. XCAP URI The XCAP URI identifies the type of XML that is being stored or accessed, a unique identification of the XML document, and optionally, an XPath expression that can identify a specific XML node which is to be stored, deleted, or retrieved. The general form of an XCAP URI used to access an XML document is as follows: XCAP Root/AUID/Document Selector/~~/Node Selector v XCAP Root: identifies the HTTP request host, port, and context root. Example: v AUID is the XCAP Application Unique ID. This identifies the type of XML document. Some AUIDs are defined within XCAP Usage specifications, user defined AUIDs can be developed using the XDMS toolkit. Examples: resource-lists or rls-services v Document Selector is the portion of the URI which identifies the specific document to be stored or accessed. XCAP documents are segregated into two tree branches. The global branch contains documents which can only be created by administrators, but accessed by anybody. The users branch contains user-specific documents. v /~~/ is a separator between the document selector, and an optional Node Selector. 88 XML Document Management Server

95 v Node Selector is a limited XPath expression that can be used to identify a specific XML element or attribute which is to be updated, retrieved, or deleted. A complete XCAP URI might look like this: sip:[email protected]/exampdoc.xml/~~/exampelement Related tasks Adding and editing documents on page 90 Use the xcap_put.sh request to add or edit documents from the command line interface. Retrieving documents on page 93 Use the xcap_get.sh request to retrieve stored documents. Deleting documents on page 94 Use the xcap_delete.sh request to delete XDMS documents. Adding and editing elements on page 91 Using a node selector statement in the XCAP URI you can select elements to be added or edited in an existing document. Adding and editing attributes on page 92 Using a node selector statement in the XCAP URI you can select attributes to be added or edited in an existing document. Related reference Using the Node Selector Example Resource List document on page 160 Example Resource List document. TestResourceList.xml Node Selector is a subset of the XPath expression, used to identify a specific element or attribute of the XML document. Node Selector enables the selection of XML document elements from the document, element, or attribute level. Using Node Selector you can specify the desired element you want to retrieve, store, or alter. Example A document is stored in the XDMS with the following XCAP URI: <?xml version="1.0" encoding="utf-8"?> <resource-lists xmlns="urn:ietf:params:xml:ns:resource-lists"> <list name="friends"> <entry uri="sip:[email protected]"> <display-name>my Friend1</display-name> </entry> <entry uri="sip:[email protected]"> <display-name>my Friend2</display-name> </entry> <entry uri="sip:[email protected]"> <display-name>my Friend3</display-name> </entry> <entry uri="sip:[email protected]"> <display-name>my Friend4</display-name> </entry> <entry uri="sip:[email protected]"> <display-name>my Friend5</display-name> </entry> <entry uri="sip:[email protected]"> Chapter 5. Managing documents 89

96 <display-name>my Friend6</display-name> </entry> <entry <display-name>my Friend7</display-name> </entry> <entry <display-name>my Friend8</display-name> </entry> <entry <display-name>my Friend9</display-name> </entry> </list> </resource-lists> In bold, the example shows the document root resource-lists with the name space urn:ietf:params:xml:ns:resource-lists. Following the document root statement is an element called list, and the attribute name with the value friends. Nested elements named entry with the attribute uri, in the bolded instance the uri attribute has the Node selector example A full node selector statement will have the following format: XCAP_URL/~~/element[@name="attributevalue"] From the example document above you can construct a node selector statement to select uri=sip:[email protected] from the resource-list friends: /resource-lists/list[@name="friends"]/entry[@uri="sip:[email protected]"] Related tasks Adding and editing documents Use the xcap_put.sh request to add or edit documents from the command line interface. Retrieving documents on page 93 Use the xcap_get.sh request to retrieve stored documents. Deleting documents on page 94 Use the xcap_delete.sh request to delete XDMS documents. Adding and editing elements on page 91 Using a node selector statement in the XCAP URI you can select elements to be added or edited in an existing document. Adding and editing attributes on page 92 Using a node selector statement in the XCAP URI you can select attributes to be added or edited in an existing document. Related reference Adding and editing documents Example Resource List document on page 160 Example Resource List document. TestResourceList.xml Use the xcap_put.sh request to add or edit documents from the command line interface. Before using the XCAP client to submit XCAP request to IBM XDMS, make sure that you have JDK1.5.0 SR 5 from IBM, installed and configured in your system path variables. 90 XML Document Management Server

97 Create or edit an XML document that is of a type managed by one of the AUIDs on your IBM XDMS, or use of the example documents located in the was_root/installableapps/xdms/client/ folder. Note: was_root is the installation root directory for WebSphere Application Server Network Deployment. By default, this directory is: /usr/ibm/websphere/appserver /opt/ibm/websphere/appserver 1. Reach the command client by typing the following from the command line:cd was_root/installableapps/xdms/client/ 2. To use the XCAP client to submit a Put request, issue the following command:./xcap_put.sh -user user_id -password password -filename file_name -content_type mime-type XCAP or example, to put the sample TestResourceList.xml to the XDMS server for the user [email protected], type the following parameters on a single line:./xcap_put.sh -user admin -password adminpassword -filename samples/testresourcelist.xml -conte 3. Run the command to send the request. If the request was to put a new document, it now appears in the specified directory. If the request used a Node Selector to send an update to a document, the new content now appears in the specified document. Related concepts Using IBM XDMS to store and manage documents on page 87 IBM WebSphere XML Document Management Server Component enables storage, access, and manipulation of XML documents stored in a central repository. Using XCAP to store and manage documents on page 88 The XCAP specification defines how an HTTP Web address can identify the way XML documents are stored on an XCAP server. It also defines how the URI can be used to identify entire XML documents, individual elements, or XML attributes that can be retrieved, updated, or deleted Using the Node Selector on page 89 Node Selector is a subset of the XPath expression, used to identify a specific element or attribute of the XML document. Related reference Adding and editing elements Example Resource List document on page 160 Example Resource List document. TestResourceList.xml Using a node selector statement in the XCAP URI you can select elements to be added or edited in an existing document. Before using the XDMS client and XCAP requests, make sure that you have JDK1.5.0 SR 5 installed and configured in your system path variables. Create or edit an XDM document of your choice, or use the TestListElement.xml document located in the was_root/installableapps/xdms/clients/samples directory and add it to the system using the xcap_put.sh command. Note: was_root is the installation root directory for WebSphere Application Server Network Deployment. By default, this directory is: /usr/ibm/websphere/appserver Chapter 5. Managing documents 91

98 /opt/ibm/websphere/appserver 1. Create an xml document containing a new element and save it. For example: <?xml version="1.0" encoding="utf-8"?> <list name="coworkers" xmlns="urn:ietf:params:xml:ns:resource-lists" xmlns:oau="urn:oma:xml:xdm:r <display-name>co-workers</display-name> <entry uri="sip:[email protected]"> <display-name>employee #1</display-name> </entry> <entry uri="sip:[email protected]"> <display-name>employee #2</display-name> </entry> </list> 2. From the command line type: cd was_root/installableapps/xdms/client/ to reach the command client. 3. Type the XCAP PUT request../xcap_put.sh -user user_id -password password -filename file_name -content_type application/xcap Note: This is one example of a Node Selector. Refer to IETF RFC 4825 for information about other ways to specify a Node Selector for an element. For example: To post the sample TestListElement.xml into the TestResourceList.xml document on the XDMS server for [email protected], type the following parameters on a single line:./xcap_put.sh -filename samples/testlistelement.xml -user sip:[email protected] -password xdms1pa 4. Run the command to send the request. The new content will now appear in the specified document. Related concepts Using IBM XDMS to store and manage documents on page 87 IBM WebSphere XML Document Management Server Component enables storage, access, and manipulation of XML documents stored in a central repository. Using XCAP to store and manage documents on page 88 The XCAP specification defines how an HTTP Web address can identify the way XML documents are stored on an XCAP server. It also defines how the URI can be used to identify entire XML documents, individual elements, or XML attributes that can be retrieved, updated, or deleted Using the Node Selector on page 89 Node Selector is a subset of the XPath expression, used to identify a specific element or attribute of the XML document. Related reference Adding and editing attributes Example Resource List document on page 160 Example Resource List document. TestResourceList.xml Using a node selector statement in the XCAP URI you can select attributes to be added or edited in an existing document. Before using the XDMS client and XCAP requests, make sure that you have JDK1.5.0 SR 5 installed and configured in your system path variables. 92 XML Document Management Server

99 Create or edit an XDM document of your choice, or use the TestAttributeExample.xml document located in the was_root/installableapps/ xdms/clients/samples directory and add it to the system using the xcap_put.sh command. Note: was_root is the installation root directory for WebSphere Application Server Network Deployment. By default, this directory is: /usr/ibm/websphere/appserver /opt/ibm/websphere/appserver 1. Modify the TestLangAttrValue.txt document and change the lang attribute value to en or any other language value and save it. 2. Switch to the was_root directory. 3. Reach the command client by typing the following from the command line:cd was_root/installableapps/xdms/client/ 4. Type the XCAP Put request../xcap_put.sh -user user_id -password password -filename file_name -content_type mime-type XCAP Note: This is one example of a Node Selector. Refer to IETF RFC 4825 for information about other ways to specify a Node Selector for an attribute. For example, to post the sample TestLangAttrValue.txt to the XDMS server for example.com, type the following parameters on a single line../xcap_put.sh -user sip:[email protected] -password password -filename samples/testlangattrv 5. Press Enter to send the request. The new content now appears in the specified document. Related concepts Using IBM XDMS to store and manage documents on page 87 IBM WebSphere XML Document Management Server Component enables storage, access, and manipulation of XML documents stored in a central repository. Using XCAP to store and manage documents on page 88 The XCAP specification defines how an HTTP Web address can identify the way XML documents are stored on an XCAP server. It also defines how the URI can be used to identify entire XML documents, individual elements, or XML attributes that can be retrieved, updated, or deleted Using the Node Selector on page 89 Node Selector is a subset of the XPath expression, used to identify a specific element or attribute of the XML document. Related reference Example Resource List document on page 160 Example Resource List document. TestResourceList.xml Retrieving documents Use the xcap_get.sh request to retrieve stored documents. Before using the XDMS client and XCAP requests, make sure that you have JDK1.5.0 SR 5 installed and configured in your system path variables. Determine the name and location of an XDM document you would like to retrieve. 1. Reach the command client by typing the following from the command line:cd was_root/installableapps/xdms/client/ Chapter 5. Managing documents 93

100 Note: was_root is the installation root directory for WebSphere Application Server Network Deployment. By default, this directory is: 2. Type the XCAP Get request. /usr/ibm/websphere/appserver /opt/ibm/websphere/appserver./xcap_get.sh -user user_id -password password -output file_name XCAP_URL For example, to retrieve the sample TestResourceList.xml from the XDMS server for example.com, type the following parameters on a single line../xcap_get.sh -user admin -password adminpassword -output samples/testresourcelist.xml 3. Press Enter to send the request. The document specified in the XCAP_URL for retrieval is stored locally as <file_name>. In the example provided, the file is stored locally as samples/testresourcelist.xml. Related concepts Using IBM XDMS to store and manage documents on page 87 IBM WebSphere XML Document Management Server Component enables storage, access, and manipulation of XML documents stored in a central repository. Using XCAP to store and manage documents on page 88 The XCAP specification defines how an HTTP Web address can identify the way XML documents are stored on an XCAP server. It also defines how the URI can be used to identify entire XML documents, individual elements, or XML attributes that can be retrieved, updated, or deleted Using the Node Selector on page 89 Node Selector is a subset of the XPath expression, used to identify a specific element or attribute of the XML document. Related reference Example Resource List document on page 160 Example Resource List document. TestResourceList.xml Deleting documents Use the xcap_delete.sh request to delete XDMS documents. Before using the XDMS client and XCAP requests, make sure that you have JDK1.5.0 SR 5 installed and configured in your system path variables. Determine the name and location of an XDM document you would like to retrieve. 1. Reach the command client by typing the following from the command line:cd was_root/installableapps/xdms/client/ Note: was_root is the installation root directory for WebSphere Application Server Network Deployment. By default, this directory is: 2. Type the XCAP Delete request. /usr/ibm/websphere/appserver /opt/ibm/websphere/appserver./xcap_delete.sh -user user_id -password password XCAP_URL For example, to delete the sample TestResourceList.xml from the XDMS server for example.com, type the following parameters on a single line../xcap_delete.sh -user admin -password adminpassword 94 XML Document Management Server

101 3. Press Enter to send the request. The document specified in the XCAP_URL is deleted. In the provided example provided, the document TestResourceList.xml is deleted. Related concepts Using IBM XDMS to store and manage documents on page 87 IBM WebSphere XML Document Management Server Component enables storage, access, and manipulation of XML documents stored in a central repository. Using XCAP to store and manage documents on page 88 The XCAP specification defines how an HTTP Web address can identify the way XML documents are stored on an XCAP server. It also defines how the URI can be used to identify entire XML documents, individual elements, or XML attributes that can be retrieved, updated, or deleted Using the Node Selector on page 89 Node Selector is a subset of the XPath expression, used to identify a specific element or attribute of the XML document. Related reference Example Resource List document on page 160 Example Resource List document. TestResourceList.xml Searching documents Use the xcap_post.sh request to search documents from the command line interface. Before using the XDMS client and XCAP requests, make sure that you: v Have IBM JDK1.5.0 SR 5 installed and configured in your system path variables. As defined in the OMA XDM v2.0 specification, IBM XDMS supports the ability to search within stored documents using XQuery. To perform an XQuery search, the client sends a search document to an OMA XDM v2.0 capable search proxy or directly to IBM XDMS by means of an HTTP POST. Before performing the search, IBM XDMS extracts the AUID from the search document. If the AUID is supported, it verifies if the XQuery in the search document matches XQuery templates defined by the application usage. If the XQuery matches a defined template, the search is then performed. It is important to note that URIs used for XCAP and XQuery differ. XQuery URIs have the following form: XCAP Root/org.openmobilealliance.search XCAP Root: identifies the HTTP request host, port, and context root. Create or edit an XDM document of your choice, or use one of the documents located in the was_root/installableapps/xdms/client/ directory. Note: was_root is the installation root directory for WebSphere Application Server Network Deployment. By default, this directory is: /usr/ibm/websphere/appserver /opt/ibm/websphere/appserver Chapter 5. Managing documents 95

102 1. Reach the command client by typing the following from the command line:cd was_root/installableapps/xdms/client/ 2. Type the XCAP Post request../xcap_post.sh -user user_id -password password -filename file_name -content_type mime-type XCAP_ For example, to post the sample TestSearchResourceList.xml to the XDMS server for example.com, type the following parameters on a single line. Note: In order for this sample to work, insert the TestResourceList.xml file by following the steps in the topic Adding and editing documents../xcap_post.sh -user admin -password adminpassword -filename samples/testsearchresourcelist.xml - 3. Press Enter to send the request. The TestSearchResourceList.xml search file is sent as an HTTP Post to IBM XDMS. The search results are then returned to the XDMS client. 96 XML Document Management Server

103 Chapter 6. Managing Document Subscriptions SUBSCRIBE and NOTIFY Use SIP subscription requests for users to want to subscribe to change notifications on XDMS documents. Follow the instructions in these topics: The XCAP component provides a SIP SUBSCRIBE and NOTIFY interface into IBM WebSphere XML Document Management Server Component. The interface is used to provide subscribers notification when a group definition is modified in an XCAP document which they own, or have sufficient rights to view or modify. Overview The SIP SUBSCRIBE and NOTIFY interface is described in the draft RFC 3265 Session Initiation Protocol (SIP)-Specific Event Notification. The IBM XDMS implementation of subscription and notification is based on the specifications described in the XML Document Manager Specification OMA-TS-XDM_Core-V1_0_1. The IBM XDMS responds to a SIP SUBSCRIBE request with one of the following responses: Table 7. Common Event header returned in response to the SUBSCRIBE request. Code Description 200 OK The SUBSCRIBE request was accepted and a subscription has been created or updated. A NOTIFY response is returned to the requester with the duration of the initial connection (unless the request is being refreshed). If the response class is not a 200 level response, the NOTIFY response will be a final response indicating there will be no further NOTIFY messages. If a subscription already exists for the group, and the intended endpoint of the notification is specified in the SUBSCRIBE request, the subscription will be updated. 403 Forbidden The SUBSCRIBE request failed due to an authorization failure. 404 Not Found The document specified in the header was not found at the specified URI. 423 Interval Too Brief The duration in the SUBSCRIBE message was too short. 489 Bad Event The Event header format is incorrect. 500 Internal Server Error The SUBSCRIBE request failed due to some internal error (not header related). The SIP NOTIFY method is used to notify a SIP client (also known as an end point) about an event change or changes to a document that the SIP application had earlier requested notification about through an earlier SIP SUBSCRIBE request. In the case of IBM XDMS, the SIP NOTIFY is sent when a change is made to an XCAP document that has been subscribed to. The SIP NOTIFY generated contains an xcap-diff document when the initial SIP SUBSCRIBE has the header accept: application/xcap-diff+xml. The following is an example of an xcap-diff document that is sent in a SIP NOTIFY back to the client: Copyright IBM Corp

104 <?xml version="1.0" encoding="utf-8"?> <xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff" xcap-root=" <document new-etag="7ahggs" previous-etag="8a77f8d"/> </xcap-diff> Note: By combining the xcap-root and doc-selector values, the full XCAP URI can be formed to send an XCAP GET request for the latest updates to the document. The following conditions will cause a SIP NOTIFY request to be sent: v If SIP SUBSCRIBE request results in a successful 200 response code then a SIP NOTIFY request is sent to the requester with the state of the subscription. If the response to the SIP SUBSCRIBE is not a 200 response code then no SIP NOTIFY is sent v If the subscribed document has been modified or deleted a SIP NOTIFY is sent to the SIP client. Subscription-State headers provided in the SIP NOTIFY requests include the following: v ACTIVE: indicates that the subscription has been accepted. v TERMINATED: the subscription is not active. A reason tag will be included with the following information: Timeout: The subscription expired or was canceled. Noresource: The document which was subscribed to has been deleted. Restrictions 1. In IBM XDMS an XCAP SUBSCRIBE is only performed against an XCAP XML document. It is important to understand that the interface does not allow a subscribe request against a specific group (<list> element). The interface only identifies the document which has been modified and does not identify internal elements or attributes of the document which have been modified. 2. Because the xcap-caps is a generated document, the SUBSCRIBE interface does not accept subscriptions to it.. 3. The directory.xml file can only be subscribed to in Access Control List (ACLS) AUIDs. This file does not exist in standard AUIDs and is not available for subscriptions.. Security The XCAP interface supports authentication to ensure that a requestor has the appropriate privilege to perform the requested operation. In order to issue a SIP SUBSCRIBE request, the requester must have read permission on the target document being subscribed to. If no read permission has been granted then a 403 Forbidden response will be returned. The p-asserted-identity header field is used to contain the identity of the user sending a SIP message that will be used for verify by authentication. The asserted identity header is parsed by the WebSphere IMS Connector Trust Association Interceptor (TAI). Refer to the TAI topics in this information center for more information about how to configure the TAI for handling asserted identities. 98 XML Document Management Server

105 SUBSCRIBE flow using rls-services documents The way in which IBM XDMS processes a SUBSCRIBE request depends on what is found in the Event header. If the document tag exists in the Event header of the SUBSCRIBE request, then the process flow is simple. However, if no auid tag and no document tag exists in the Event header, then IBM XDMS assumes the subscription will use an rls-services document flow. The following topic gives an example of how to convert the SIP URI provided in the TO header to that of a resource-list referenced by a service URI defined in a rls-services document. If the Event header in the SUBSCRIBE request does not contain an auid tag and document tag, then IBM XDMS assumes the subscription is based upon the SIP URI provided in the TO header. To: <sip:[email protected]@ibm.com> In order to be able to return an XCAP URI in the NOTIFY response, a mapping is required from a user-defined SIP URI, to an XCAP URI of a document stored in IBM XDMS. This mapping is provided through the use of the rls-services document.. In order for a subscription to complete properly, there are multiple documents and document elements that must be created properly to reference one another. The SIP URI provided in the TO header of the SUBSCRIBE request must be defined in a URI attribute of a <service> element of an rls-services document. That <service> element must contain a resource-list element which contains the XCAP URI that was used to create the resource-lists document (group definition) that is being subscribed to. The following information shows the required process to create the appropriate documents for a subscription that provides only a SIP URI:: Create the resource-lists document 1. Create a resource-lists document containing your group list. <?xml version="1.0" encoding="utf-8"?> <resource-lists xmlns="urn:ietf:params:xml:ns:resource-lists"> <list name="friends"> <entry uri="sip:[email protected]"> <display-name>my Friend1</display-name> </entry> <entry uri="sip:[email protected]"> <display-name>my Friend2</display-name> </entry> </list> </resource-lists> 2. Store the document in IBM XDMS using an XCAP PUT request. The URL used for the PUT should be something like the following: Create the rls-services document 1. Create an rls-services document that references the friends list within the MyBuddies.xml document which was just stored in the previous step. <?xml version="1.0" encoding="utf-8"?> <rls-services xmlns:rl="urn:ietf:params:xml:ns:resource-lists" xmlns="urn:ietf:params:xml:ns:rls-services"> <service uri="sip:sip:[email protected]@ibm.com"> <resource-list> Chapter 6. Managing Document Subscriptions 99

106 </resource-list> <packages> <package>presence</package> </packages> </service> </rls-services> 2. Be sure to check that the following sections of the rls-services document are coded correctly: v The document selector portion of the XCAP URI (everything before the /~~/ separator) specified in the resource-list element is exactly the same as it was used to create your resource lists. The XCAP spec requires this to point to a list element within that document which is why the XPath extension was added to that URI. Because a subscription is against a document rather than a list, the XPath extension will be ignored for subscription, but it must be there to be a valid rls-services document. v The uri tag specified in the service element is the SIP URI which is to be used in the TO header of the SUBSCRIBE request. v When you store this rls-services document in IBM XDMS, the tree/xui portion of the XCAP URI that is used to store the rls-services document must be the same as the tree/xui portion of the XCAP URI that is specified in the resource-list element. In this case, users/sip:[email protected] would be the tree/xui. For this example, the URL used for the PUT of the rls-services document should be something like the following: Create the SUBSCRIBE Request After the resource-lists and rls-services documents are stored in IBM XDMS, it is possible to perform a SUBSCRIBE request as show below: SUBSCRIBE sip:service@ :5060 SIP/2.0 Via: SIP/2.0/TCP :5060 From: <sip:user1@ :5060>;tag=1 To: <sip:sip:[email protected]@ibm.com> Call-ID: @call.id Event: ua-profile;profile-type="application" Max-Forwards: 70 CSeq: 1 SUBSCRIBE P-Asserted-Identity: "John Doe" <sip:[email protected]> Privacy: none Expires: 3600 Accept: application/xcap-diff+xml Contact: sip:user1@ :5060 Content-Length: 0 NOTIFY response 100 XML Document Management Server Here is an example of the NOTIFY response from the previous SUBSCRIBE request: NOTIFY sip:user1@ :5060 SIP/2.0 Event: ua-profile;profile-type="application" From: <sip:sip:[email protected]@ibm.com>;tag= _local _2_2 To: <sip:user1@ :5060>;tag=1 Call-ID: @call.id Max-Forwards: 70 CSeq: 1 NOTIFY Content-Type: application/xcap-diff+xml Content-Length: 285 Via: SIP/2.0/TCP :5060;branch=z9hG4bK

107 Contact: <sip: :5060;transport=tcp> Subscription-State: active <?xml version="1.0" encoding="utf-8"?> <xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff" xcap-root=" <document new-etag="mte0otu0mzixnjkxnq==" previous-etag="mte0otu0mzixnjkxnq=="/> </xcap-diff> Verification If you successfully created the resource-lists and rls-services document, and correctly coded the SUBSCRIBE request, you should receive a 200 response from NOTIFY. If you do not receive a 200 response you may want to examine some of the following: v If the URI specified in the To header is not found in any rls-services document, a 404 Not found response is returned in response to the SUBSRCIBE request. Ensure that the URI defined in the rls-services <service> element is the same as the URI defined TO header. Also the referenced <resource-list> element must reference an existing resource-lists document. v If the <service> element contains a <list> element rather than a <resource-list> element then a 404 Not Found response is returned. IBM XDMS does not allow a requester to subscribe directly to a local list. v If the URI specified in the <resource-list> element does not point to a valid document stored within IBM XDMS, a 404 Not Found response is returned. v The xcap-root value used in the xcap-diff is the configuration parameter defined for the global ibm-xdms Resource Environment Provider property xcaproot. In a production environment the xcaproot property should be the address of the Aggregation Proxy or edge proxy server depending on which server the XCAP client is configured to communicate directly with. SUBSCRIBE headers A SIP application can issue a SUBSCRIBE request for notification of a future change or changes to a document. The XCAP XML document header information for the SUBSCRIBE request is checked by the XCAP server to determine whether the request should be honored or rejected. The following is a sample SUBSCRIBE request code snippet showing the format of SUBSCRIBE request. The Event header consists of specific tags, separated by a semi-colon, which provide detailed information for the SUBSCRIBE request. Event: ua-profile;profile-type="application";vendor="ibm";model="xdms";version="6.2"; auid="optional_auid";document="optional_docselector" The following is an example SIP Event header to subscribe to a resource-lists (AUID) document within a user sip:[email protected] home directory: Event: ua-profile;profile-type="application";vendor="ibm";model="xdms";version="6.2"; auid="resource-lists";document="users/sip:[email protected]/mydocument.xml" Event header When IBM XDMS receives a SUBSCRIBE request it scans the document header for the required ua-profile Event. If the Event header format is incorrect, a 489 Bad Event response will be returned Chapter 6. Managing Document Subscriptions 101

108 ua-profile tag The Event that is used for XDMS SIP SUBSCRIBE is ua-profile. profile-type tag The profile-type tag is mandatory and must be set to application as defined by the SIP ua-profile specification. vendor model tag The vendor tag is mandatory. IBM XDMS ensures that the tag exists, but it can be set to any value. tag The model tag is mandatory. IBM XDMS ensures that the tag exists, but it can be set to any value. version tag The version tag is mandatory. IBM XDMS ensures that the tag exists, but it can be set to any value. auid tag The auid tag is optional if you intend to specify the auid in the document tag otherwise you must specify the AUID of the target document with the auid tag. document tag The value of the document tag is used to identify the document that is being subscribed to. v If the auid tag and document tag do not exist the request URI in the TO header of the SUBSCRIBE request is used. This URI should represent a service URI in a rls-services document. The rls-services definition is retrieved and the associated resource-lists XCAP URI is used for the subscription. v If the service URI does not exist in an rls-services document, or if the document represented by the XCAP URI associated with that service URI does not exist in IBM XDMS, a 404 Not Found response will be returned. v If the auid tag is rls-services and the document tag is global/index, then the rls-services is again used to retrieve the associated resource-lists XCAP URI used for the subscription. However, the Request-URI is used to match the service URI instead of the TO header. v If the auid tag is specified but the document header is not specified, then a user home directory for that AUID is being subscribed to. The XUI for the user s home directory is specified in the Request-URI. v The document URI may be in the form of: AUID/users/XUI/document AUID/global/document users/xui/document global/document In order to process the document URI, IBM XDMS checks to see if the document URI starts with either global or users. If it does, IBM XDMS requires an AUID which must be specified using the auid tag Expires header The Expires header is an optional value for IBM XDMS. The value of this header field specifies the time in seconds that the subscription request is valid. 102 XML Document Management Server

109 v If the Expires header does not exist, the value from the subscribeexpiresdefault configuration parameter is used. v If the Expires value is zero the subscription is cancelled. Even if a subscription does not exist in IBM XDMS, a 200 OK response will be returned to the requestor. This will trigger a NOTIFY with a Subscription-State of terminated. v If the Expires value is non-zero, the value will be checked against the Min-Expires and Max-Expires values. The actual expiration time values are set using a minute boundary, which means the time value after being read into the system is then reduced to the next lower minute value. For example, if the Expires time value was 80 seconds the next lower minute value of 60 seconds will be used. If the time value was 170 seconds the next lower minute value would be 120 seconds. v If the Expires value is less than zero, the value is considered malformed and is set to the default value. v If the Expires value is greater than zero, but less than the minimum time defined in the configuration property subscribeexpiremin, a 423 Interval Too Brief response will be returned. v If the Expires value is greater than the configured maximum value as defined in the configuration property subscibeexpiremax it is set to the maximum value defined in the property subscibeexpiremax. Header return codes Table 8. Common Event header returned in response to the SUBSCRIBE request. Code Description 200 OK The SUBSCRIBE request was accepted and a subscription has been created or updated. A NOTIFY response is returned to the requester with the duration of the initial connection (unless the request is being refreshed). If the response class is not a 200 level response, the NOTIFY response will be a final response indicating there will be no further NOTIFY messages. If a subscription already exists for the group, and the intended endpoint of the notification is specified in the SUBSCRIBE request, the subscription will be updated. 403 Forbidden The SUBSCRIBE request failed due to an authorization failure. 404 Not Found The document specified in the header was not found at the specified URI. 423 Interval Too Brief The duration in the SUBSCRIBE message was too short. 489 Bad Event The Event header format is incorrect. 500 Internal Server Error The SUBSCRIBE request failed due to some internal error (not header related). Chapter 6. Managing Document Subscriptions 103

110 104 XML Document Management Server

111 Chapter 7. Developing for XDMS Use the IBM Telecom Web Services toolkit to develop IBM XDMS clients and custom XDMS applications. Copyright IBM Corp

112 106 XML Document Management Server

113 Chapter 8. Troubleshooting IBM XDMS IBM Support Assistant Logs store information that can help you troubleshoot problems that might occur as you install, configure, and use IBM XDMS..To help you communicate with IBM Support, an IBM Support Assistant (ISA) product plug-in is available on the Web foribm WebSphere XML Document Management Server Component. You can use ISA plug-ins to open electronic service requests. If you want to send log files associated with the service request, you must install and use the plug-in for WebSphere Application Server Version It collects logs, trace files, and configuration information to send to IBM Support. Installing ISA plug-ins IBM Support Assistant (ISA) plug-ins help you communicate with IBM Support. You can install the plug-ins for selected products and features using the ISA graphical user interface. Before you begin, you must have installed IBM Support Assistant. The IBM Support Assistant Web site has instructions for downloading and installing ISA, and for installing the product plug-ins. To install the product plug-ins: 1. Open IBM Support Assistant. 2. Select the Updater tab. 3. Select the New Products and Tools tab. 4. Select the WebSphere product family. The plug-ins are categorized by product family. 5. Check the feature or features to install and click Install. Read the license and description information. 6. Restart IBM Support Assistant. Enabling Performance Monitoring Infrastructure (PMI) logging Performance Monitoring Infrastructure (PMI) logging is available for the various XDMS metrics. Use the Integrated Solutions Console to enable PMI logging. For each AUID, the PMI logs the number of PUT, GET, DELETE, POST, SUBSCRIBE requests and their latency in milliseconds, as well as the success rate of all requests for that AUID. The success rate is the number of requests that receive a successful response, that is, a 2XX response code, out of the total number of requests. To view these metrics, perform the following steps: 1. Log in to the Integrated Solutions Console. a. Open a browser and navigate to the following URL: host_name:port/ibm/console. IBM Corporation

114 Where: host_name is the fully qualified host name of the server where the application or the network deployment manager is deployed. port is the secured port used to access the console. The default is Note: The default unsecured port is If you use 9060, you must have http instead of https in the URL. b. Enter an administrator user ID and password. If security is not enabled leave the password field blank. c. Click Log in. 2. Click Monitoring and Tuning PMI (Performance Monitoring Infrastructure). 3. Select the server you want to enable PMI on. 4. Select Enable PMI (Performance Monitoring Infrastructure). 5. Under Currently Monitored Statistic Set, make sure at least Basic monitoring is enabled. 6. Click OK. 7. Click Save to save changes to the master configuration. 8. Click Monitoring and Tuning Performance Viewer Current Activity. 9. Click Start Monitoring for the server you want to monitor. 10. Click server name. 11. Expand Performance Modules IMS. 12. Select Xdms_AUID where Xdms_AUID is the XDMS application you want to monitor. 13. Click View Modules. The following variables are displayed: Table 9. Monitored XDMS variables Variable Description PUT Requests Number of PUT requests GET Requests Number of GET requests DELETE Requests Number of DELETE requests POST Requests Number of POST requests SUBSCRIBE Requests Number of SUBSCRIBE requests Success rate Percentage of successful responses PUT Latency Average latency time for PUT requests GET Latency Average latency time for GET requests. DELETE Latency Average latency time for DELETE requests POST Latency Average latency time for POST requests SUBSCRIBE Latency Average latency time for SUBSCRIBE requests Audit logging It is possible to log http and sip requests from specific users and/or roles. The audit logger will log HTTP PUT, GET, DELETE, POST requests and SIP SUBSCRIBE requests. 108 XML Document Management Server

115 To specify the users/roles to log, change the REPs auditlogbyuser and auditlogbyrole for the AUID you want to monitor. 1. Log in to the Integrated Solutions Console. a. Open a browser and navigate to the following URL: ibm/console. Where: host_name is the fully qualified host name of the server where the application or the network deployment manager is deployed. port is the secured port used to access the console. The default is Note: The default unsecured port is If you use 9060, you must have http instead of https in the URL. b. Enter an administrator user ID and password. If security is not enabled leave the password field blank. c. Click Log in. 2. Click Resources Resource Environment Resource Environment Providers. 3. Click AUID Custom Properties. 4. Click auditlogbyuser or auditlogbyrole and change values to desired value. Option Description auditlogbyuser Default is empty. If specified, then log the users listed in this property (comma separated list of users). auditlogbyrole Default role to log is superadmin. If specified, then only log requests/responses for principals with the given role. If both REPs are null or empty, then everyone will be logged if the trace level is set to Fine, Finer, or Finest. If either one or both are specified then matching is done by either the role(s) or by the user(s). Both do not need to match the request in order to log. Only a single match by either the role(s) or by the user(s) is needed. For example: a. If auditlogbyrole and auditlogbyuser is null or not specified and the trace level is Fine, then everybody s request and response will be traced. b. If auditlogbyrole is set to super-admin, auditlogbyuser is null or not specified, and the trace level is Finest, then only users with the super-admin role will have request and response traced. c. If auditlogbyrole is null or not specified, auditlogbyuser is set to sip:[email protected], and the trace is Finer, then only the sip:[email protected] will have request and response traced. d. If auditlogbyrole is anonymous-request, auditlogbyuser is set to sip:[email protected], and the trace is Fine, then both all users with the anonymous-request role or sip:[email protected] will have request and response traced The output is logged in the trace.log for the server of the specified AUID. The trace.log can be found at: was_profile_root/logs/server_name Note: was_profile_root is the directory for a WebSphere Application Server Network Deployment profile called profile_name. By default, this directory is: Chapter 8. Troubleshooting 109

116 /usr/ibm/websphere/appserver/profiles/profile_name /opt/ibm/websphere/appserver/profiles/profile_name To enable trace, refer to the Trace Logging section of this Information Center. The required audit logging classes are com.ibm.xmds.sip.filter.impl.auditloggersipfilter com.ibm.xmds.xcap.filter.impl.auditloggerxcapfilter The audit logging trace levels are: Fine Logs the HTTP method, XCAP URI, principal making the request, and the response code going back.. Finer Logs HTTP headers for both the request and response, along with the elements in Fine tracing. Finest Logs the content from the request and content in the returned response, along with the elements in Finer tracing. Related tasks Modifying log properties on page 111 Using the administration console, you are able to modify the properties of several logs. Enabling trace on page 112 Trace logs show trace events such as function entries and exits, component events, and debugging activities. Use the administration console to enable trace for a process. Related reference Monitoring log messages Trace loggers on page 113 The level of tracing is determined by the log level details you select for the loggers. Loggers are organized hierarchically. The children of the logger will inherit the parent log level by default, but it can be changed by defining the level of tracing on each specific logger. IBM WebSphere XML Document Management Server Component can write system messages to several general purpose logs. Logging provides information about important lifecycle events, warnings, and errors that should be addressed by an administrator. By default, IBM WebSphere XML Document Management Server Component logs its messages to the WebSphere Application Server JVM log (SystemOut.log) and its trace messages to the WebSphere Application Server trace log (trace.log). Both log files are located in the logs directory: was_profile_root/logs/server_name Note: was_profile_root is the directory for a WebSphere Application Server Network Deployment profile called profile_name. By default, this directory is: /usr/ibm/websphere/appserver/profiles/profile_name /opt/ibm/websphere/appserver/profiles/profile_name In a standalone environment, profile_name is the name of the application server profile. In a clustered environment, profile_name is the name of a federated node profile. 110 XML Document Management Server

117 Each error, warning, or informational log message should include a message code which is used to identify the message. Additionally, each message can be identified by the date, timestamp, thread number, and severity. For example: [3/14/06 10:45:28:004 CST] GroupListImpl E GLSR0006E: Unable to connect to the repository adapter web service endpoint for the following reason: null Comprehensive information about working with message logs may be found in the WebSphere Application Server Network Deployment information center. Modifying log properties Using the administration console, you are able to modify the properties of several logs. You can modify the general properties of each log, which specifies the output type or location of the log. Use the following steps to adjust the properties for each log type: 1. Log in to the Integrated Solutions Console. a. Open a browser and navigate to the following URL: ibm/console. Where: host_name is the fully qualified host name of the server where the application or the network deployment manager is deployed. port is the secured port used to access the console. The default is Note: The default unsecured port is If you use 9060, you must have http instead of https in the URL. b. Enter an administrator user ID and password. If security is not enabled leave the password field blank. c. Click Log in. 2. Click server_name. 3. Click Troubleshooting Logging and Tracing. 4. To make a static change to the system log configuration, click the Configuration tab. To change the configuration dynamically, click the Runtime tab. 5. Click the appropriate log type and change the configuration according to your needs: Note: Separate logs for each log type exist for all Java virtual machines (JVMs) on a node, including all application servers and their node agent, if present, as well as for a deployment manager in its own logs directory. Option Description Diagnostic Trace Provides information in the trace.log about how the WebSphere Application Server components run. Chapter 8. Troubleshooting 111

118 Enabling Option Description JVM Logs Used to view and modify the settings for the Java Virtual Machine (JVM). The System.out log (SystemOut.log) is used to monitor the health of the WebSphere Application Server. The System.err log (SystemErr.log) contains exception stack trace information used to perform problem analysis. Process Logs Created when redirecting the standard out and standard error streams of a process to independent log files, the native_stdout.log and native_stderr.log, respectively. IBM Service Logs Also known as the activity log. Records the WebSphere Application Server messages that are written to the System.out stream and special messages that contain extended service information that you can use to analyze problems. Change Log Details Level Use log levels to control which events are processed by Java logging. 6. Click Apply. 7. Click OK. 112 XML Document Management Server trace Trace logs show trace events such as function entries and exits, component events, and debugging activities. Use the administration console to enable trace for a process. You can configure the IBM WebSphere XML Document Management Server Component to start in a trace-enabled state by setting the appropriate configuration properties. You can control how much detail each logger records by adjusting the log level details. Because the loggers are grouped hierarchically, setting the trace level on one logger also sets all subsequent loggers to the same level. Altering the tracing levels impact the performance of the system. Enable and configure trace by completing the following steps: 1. Log in to the Integrated Solutions Console. a. Open a browser and navigate to the following URL: ibm/console. Where: host_name is the fully qualified host name of the server where the application or the network deployment manager is deployed. port is the secured port used to access the console. The default is Note: The default unsecured port is If you use 9060, you must have http instead of https in the URL. b. Enter an administrator user ID and password. If security is not enabled leave the password field blank. c. Click Log in. 2. In the navigation panel, click Troubleshooting Logs and Trace.

119 3. Click server_name in the Server column of the table. 4. Click Diagnostic Trace. 5. Configure your trace options: a. Display the Configuration tab. b. Select Enable log. c. Click Change Log Level Details. d. Click Components to view all loggers for the individual components. e. Click + to show the children of the logger. f. Click logger_name to change the log details. To enable tracing on specific components of IBM WebSphere XML Document Management Server Component, use com.ibm.xdms.*=all as a logger group name. com.ibm.xcap.* com.ibm.xdms.agp.* com.ibm.xdms.common.* com.ibm.xdms.function.* com.ibm.xdms.install.* com.ibm.xdms.osgi.* com.ibm.xdms.sip.* com.ibm.xdms.utils.* com.ibm.xdms.xcap.* g. Choose the appropriate level of tracing. Remember: When you change the level for a logger, the change is propagated to the children of the logger. For additional information regarding trace levels, click? in the title bar of the panel to open the help page. 6. Click OK. 7. Click Save. 8. Restart the server_name server. Trace loggers The level of tracing is determined by the log level details you select for the loggers. Loggers are organized hierarchically. The children of the logger will inherit the parent log level by default, but it can be changed by defining the level of tracing on each specific logger. To control the trace level for all of Trust Association Interceptor, use the options on the com.ibm.imsconnector.* trace group. For more specific levels of tracing, use the following trace groups, which are relevant to Trust Association Interceptor: com.ibm.imsconnector.tai.* com.ibm.imsconnector.tai.baseimsinterceptor com.ibm.imsconnector.tai.httpinterceptor com.ibm.imsconnector.tai.sipinterceptor To control the trace level for all of IBM WebSphere XML Document Management Server Component, usse the options on the com.ibm.xdms.* and com.ibm.xcap.* trace group. For more specific levels of tracing, use the following trace groups, which are relevant to IBM WebSphere XML Document Management Server Component: Chapter 8. Troubleshooting 113

120 com.ibm.glm.http.security.* com.ibm.xcap.* com.ibm.xcap.client.* com.ibm.xcap.xml.* com.ibm.xdms.agp.* com.ibm.xdms.agp.* com.ibm.xdms.agp.common.* com.ibm.xdms.agp.exception.* com.ibm.xdms.agp.install.* com.ibm.xdms.agp.servlet.* com.ibm.xdms.* com.ibm.xdms.common.* com.ibm.xdms.common.impl.* com.ibm.xdms.exception.* com.ibm.xdms.exception.sip.* com.ibm.xdms.exception.xcap.* com.ibm.xdms.function.* com.ibm.xdms.function.impl.* com.ibm.xdms.install.* com.ibm.xdms.osgi.* com.ibm.xdms.utils.* com.ibm.xdms.version.* com.ibm.xdms.sip.* com.ibm.xdms.sip.filter.* com.ibm.xdms.sip.filter.impl.* com.ibm.xdms.sip.impl.* com.ibm.xdms.sip.servlet.* com.ibm.xdms.sip.utils.* com.ibm.xdms.xcap.* com.ibm.xdms.xcap.filter.* com.ibm.xdms.xcap.filter.impl.* com.ibm.xdms.xcap.impl.* com.ibm.xdms.xcap.servlet.* Tracing a SIP container To control the trace level for the SIP container, use the options on the com.ibm.ws.sip.* trace group. For more detailed information about tracing a SIP container or CEI, refer the WebSphere Application Server Network Deployment Information Center. 114 XML Document Management Server

121 Faults and alarms Messages IBM XDMS provides notification of application-critical events through the WebSphere Telecom Web Services Server Faults and Alarm notification service. Within the ibm-xdms Resource Environment Provider for each IBM XDMS application, the entry alarminterval allows the system administrator to declare the interval on which to receive duplicate alarms. The default value for this entry is 15 minutes. An alarm is logged for any of the following events: v Initialization of a server fails. v DB2 is not accessible for accessing document AUID tables or usage records. v JMS is not accessible to log notification events. v The Aggregation Proxy cannot connect with a configured IBM XDMS. v The Aggregation Proxy is configured with more than one IBM XDMS supporting the same AUID for the same domain. v IBM XDMS cannot access Resource Environment Providers for configuration settings. A fault is logged for any of the following events: v An <external> list cannot be resolved during an access control check from an authorization policy. v An IBM XDMS server shuts down (a fault for each of the AUIDs served by IBM XDMS is logged). A message explains a problem and suggests a user action. In addition, each message ID includes a component ID, a number, and a letter that indicates the type of message: Informational, warning, or error. Messages DHAT0001E: Pre-hop sender is not a valid host name or IP: {0} Explanation: The pre-hop sender is not included in the list of allowed pre-hop senders. User response: Make sure the proper IP addresses and hostnames are listed in the interceptor property: allowedsenderslist. DHAT0002E: RuntimeException occurred in method: {0} Explanation: RuntimeException occurred. User response: Gather tracing information and contact IBM support. DHAT0003E: NamingException occurred in method: {0} Explanation: NamingException occurred. User response: Gather tracing information and contact IBM support. Chapter 8. Troubleshooting 115

122 DHAT0004E: Initialization failed. Explanation: Error occurred while processing list property. User response: Gather tracing information and contact IBM support. DHAT0005E: NumberFormatException occurred when parsing subnet mask. Explanation: NumberFormatException occurred when parsing subnet mask. User response: Gather tracing information and contact IBM support. DHAT0006E: Exception when parsing {0} header. Explanation: ServletParseException verifying From header in SIP message. User response: Gather tracing information and contact IBM support. DHAT0007E: RuntimeException verifying SIP scheme: {0} Explanation: RuntimeException verifying SIP scheme. User response: Gather tracing information and contact IBM support. Messages GLSU0001E: File {0} was not found Explanation: File specified was not found User response: Rerun the command by specifying a file that exists GLSU0002E: Cannot read or write to the file {0} Explanation: Cannot read or write to the file specified User response: Rerun the command by specifying a different file GLSU0003E: Connection problem when attempting to contact the XCAP Server Explanation: Problem during connection with the XCAP server User response: Contact your system administrator GLSU0004E: The XCAP URI provided {0} was malformed Explanation: The XCAP URI provided was malformed User response: Rerun the command with a well formed XCAP URI 116 XML Document Management Server

123 GLSU0005E: The XCAP URI provided {0} was malformed, invalid xcap root Explanation: The XCAP URI provided was malformed, the XCAP Root in the XCAP request is expected to be of the form http(s)://hostname:port/contextroot/ User response: Rerun the command with a well formed XCAP URI GLSU0006E: The XCAP URI provided {0} was malformed, XCAP Application Unique Identifier (AUID) missing Explanation: The XCAP URI provided was malformed, the URI must specify the XCAP Application Unique Identifier (AUID) missing User response: Rerun the command with a well formed XCAP URI GLSU0007E: The XCAP URI provided {0} was malformed, XCAP filename missing Explanation: The XCAP URI provided was malformed, the URI must specify the XCAP filename User response: Rerun the command with a well formed XCAP URI GLSU0008E: The XCAP URI provided {0} was malformed, missing XCAP global or users tree Explanation: The XCAP URI provided was malformed, the URI must specify the XCAP global or users tree User response: Rerun the command with a well formed XCAP URI GLSU0009E: The XCAP URI provided {0} was malformed, XCAP User Identifier in the users tree missing Explanation: The XCAP URI provided was malformed, the URI must specify the XCAP user identifier User response: Rerun the command with a well formed XCAP URI GLSU0010E: The XCAP URI provided {0} was malformed, invalid separator Explanation: The XCAP URI provided was malformed, the URI contains an invalid separator User response: Rerun the command with a well formed XCAP URI GLSU0011E: The Content-Type is missing for the HTTP PUT or POST request. Explanation: The Content-Type is missing for the HTTP PUT or POST request. User response: Rerun the command with a Content-Type header specified containing the proper mime-type of the document. Chapter 8. Troubleshooting 117

124 GLSU0012E: The XML is missing for the HTTP PUT request. Explanation: The XML is missing for the HTTP PUT request. User response: Rerun the command and specify the XML content to put. GLSU0013E: The XML is missing for the HTTP POST request. Explanation: The XML is missing for the HTTP POST request. User response: Rerun the command and specify the XML content to post. GLSU0014E: The XCAP URI is missing from the request. Explanation: The XCAP URI is missing from the request. User response: Rerun the command and specify the XCAP URI. GLSU0015E: The HTTP METHOD is invalid or missing from the request. Explanation: The HTTP METHOD is invalid or missing from the request. User response: Rerun the command and specify a correct HTTP METHOD. GLSU0016E: This portion of the node selector in the XCAP URI is invalid {0}. Explanation: A portion of the node selector in the XCAP URI is invalid. User response: Rerun the command and specify a well formed node selector for the XCAP URI. GLSU0100E: The HTTP method is either invalid or missing for the -http_method option. Explanation: The HTTP method is either invalid or missing for the -http_method option. User response: Specify the -http_method parameter with either GET, PUT, POST, or DELETE. GLSU0101E: A header is incorrectly specified. It must be of the form -header:<header_name> <VALUE>. Explanation: A header is incorrectly specified. It must be of the form -header:<header_name> <VALUE>. User response: Specify the header in the form -header:<header_name> <VALUE> GLSU0102E: The XCAP URI is either invalid or missing. Explanation: The XCAP URI is either invalid or missing. User response: The last parameter must be a valid XCAP URI. 118 XML Document Management Server

125 GLSU0103E: The XCAP PUT requires XML content as specified by the -filename option. Explanation: The XCAP PUT requires XML content as specified by the -filename option. User response: Specify the -filename <FILENAME> parameter that references an XML file containing content to PUT. GLSU0104E: The XCAP PUT requires a content type for the XML as specified by the -content_type option. Explanation: The XCAP PUT requires a content type for the XML as specified by the -content_type option. User response: Specify the -content_type <MIME_TYPE> parameter that specifies the mime-type of the XML document. GLSU0105E: The XCAP POST requires XML content as specified by the -filename option. Explanation: The XCAP POST requires XML content as specified by the -filename option. User response: Specify the -filename <FILENAME> parameter that references an XML file containing content to POST. GLSU0106E: The XCAP POST requires a content type for the XML as specified by the -content_type option. Explanation: The XCAP POST requires a content type for the XML as specified by the -content_type option. User response: Specify the -content_type <MIME_TYPE> parameter that specifies the mime-type of the XML document. GLSU0107E: Missing the input value for the option {0}. Explanation: The option requires an input value as a 2nd parameter. User response: Enter the input value for the given option. GLSU0108E: Missing the output filename value for the option {0}. Explanation: The option requires an output filename value as a 2nd parameter. User response: Enter the output filename value for the given option. Messages GLSX0001I: {0} OSGI Bundle has started Explanation: OSGI Bundle has started User response: None Chapter 8. Troubleshooting 119

126 GLSX0002E: Error parsing parsing AUID Descriptor File {0} Explanation: The AUID Descriptor File could not be parsed User response: Please ensure the AUID Descriptor File is correct GLSX0003E: Error parsing XCAP-CAPS file {0} Explanation: The XCAP-CAPS file could not be parsed either because the XML file is not well formed or the schemas have a loading order dependency. User response: Please ensure the XCAP-CAPS file is correct or the /WEB-INF/schema/schema_order.properties lists the correct schema loading order. GLSX0004E: Cannot load helper functions defined in AUID Descriptor File {0} Explanation: An error was encountered loading the helper functions User response: Please ensure the AUID Descriptor File is correct GLSX0005E: Exception encountered loading the XCAP Filters Explanation: An error was encountered loading the XCAP Filters User response: Please ensure the AUID Descriptor File is correct and the XCAP Filter classes defined in it exist GLSX0006E: Exception encountered initializing XML Schema Files Explanation: An error was encountered initializing XML Schema Files User response: Please ensure your schemas are valid and if necessary, insure the ordering is correct in schema_order.properties GLSX0007E: XCAP-CAPS file {0} was not found in the web module Explanation: The XCAP-CAPS file could not be found User response: Please ensure the XCAP-CAPS file exists in your web module GLSX0008E: AUID Descriptor File {0} was not found in the web module Explanation: The AUID Descriptor File could not be found User response: Please ensure the AUID Descriptor File exists in your web module GLSX0009E: Exception parsing base Error XML Document Explanation: The base Error XML Document could not be parsed User response: Please contact IBM Support 120 XML Document Management Server

127 GLSX0010E: Unable to perform PUT of document with Document Selector {0} Explanation: PUT failed while interacting with the database User response: Please ensure your database settings are correct GLSX0011E: Unable to perform DELETE of document with Document Selector {0} Explanation: DELETE failed while interacting with the database User response: Please ensure your database settings are correct GLSX0012E: Unable to perform GET of document with Document Selector {0} Explanation: GET failed while interacting with the database User response: Please ensure your database settings are correct GLSX0013E: The content-type header must contain {0} for this XCAP request. Explanation: The content-type header is either missing or invalid. User response: Please ensure that the content-type header is correctly specified. GLSX0014E: The root element namespace must contain {0} within the document. Explanation: The root element does not comply with namespace of the application usage. User response: Please ensure that the parent element namespace within the document is correctly specified. GLSX0015E: The XML content is missing from the request. Explanation: The XCAP PUT or POST request requires XML content. User response: Please ensure that XML content is sent in the XCAP request. GLSX0016E: Unable to obtain the configured datasource {0} for AUID {1}. Explanation: Datasource or the Resource Provider Enviroment configuration is not valid. User response: Please ensure the datasource and Resource Provider Environment is valid for your AUID. GLSX0017E: List {0} exceeds the maximum number of entries. Explanation: The list contains more entries than the maximum allowed. Chapter 8. Troubleshooting 121

128 User response: Please ensure the list does not contain more entries than are specified in the listmaximummembers property. GLSX0018E: List {0} does not contain enough entries. Explanation: The list contains fewer entries than the minimum allowed. User response: Please ensure the list does not contain fewer entries than are specified in the listminimummembers property. GLSX0019I: No AUID properties file exists for AUID {0}, no Resource Provider Environment will be created for this AUID. Explanation: No AUID properties file exists in the WAR file for this AUID. User response: None if no Resource Environment Provider is required for this AUID. If a Resource Environment Provider should be created, then ensure the properities file is in the WAR file with the path /WEB-INF/auids/ <AUID>.properties. GLSX0020E: No global XDMS properties file exists, installation will be aborted. Explanation: No AUID properties file exists in the WAR file for this AUID. User response: None if no Resource Environment Provider is required for this AUID. If a Resource Environment Provider should be created, then ensure the properities file is in the WAR file with the path /WEB-INF/auids/ <AUID>.properties. GLSX0021E: Unable to obtain a database connection for configured datasource {0} for AUID {1}. Explanation: Datasource or the Resource Provider Enviroment configuration is not valid. User response: Please ensure the datasource and Resource Provider Environment is valid for your AUID. GLSX0022W: Unable to close a database connection for configured datasource {0} for AUID {1}, will retry to close the connection. Explanation: Datasource or the Resource Provider Enviroment configuration may not be valid. User response: Please ensure the datasource and Resource Provider Environment is valid for your AUID. GLSX0023E: Unable to close a database connection for configured datasource {0} for AUID {1}. Explanation: Datasource or the Resource Provider Enviroment configuration is not valid. 122 XML Document Management Server

129 User response: Please ensure the datasource and Resource Provider Environment is valid for your AUID. GLSX0024E: Unable to perform XQuery {0} Explanation: XQuery failed while interacting with the database User response: Please ensure your database settings are correct GLSX0025E: Unable to retrieve the Datastore helper function for AUID {0} Explanation: AUID descriptor file is incorrect or the helper function is not available on the application server s classpath User response: Please ensure the AUID Descriptor File is correct and the helper function is in the application server s classpath GLSX0026E: The xcaproot property has not been defined for the ibm-xdms Resource Environment Provider. Explanation: The xcaproot property is required for successful operation of XCAP and SIP for the XDMS. User response: Please ensure that the xcaproot is defined for the ibm-xdms Resource Environment Provider. GLSX0027W: A subscription cannot be removed for the following reason: {0} Explanation: A subscription was not removed because it may have been previously removed. User response: No user action required. GLSX0028E: An rls-services document contains service URI {0} which is not unique. Explanation: All rls-services document must have unique service URIs. User response: Remove the redundant rls-services document service URI to ensure uniqueness. GLSX0029W: Error refreshing configuration cache for {0}. Explanation: An error occurred while refreshing the configuration settings for an REP. User response: Ensure super admin user is setup correctly in global REP, also examine log file for more information. GLSX0030E: Unable to get properties for Resource Environment Provider {0} Explanation: Failed retrieving configuration settings for Resource Environment Provider Chapter 8. Troubleshooting 123

130 User response: Ensure the Resource Environment Provider exists and as Custom Properties defined. Ensure nodes have been synchronized with latest configuration. GLSX0031E: Unable to authenticate with WebSphere server using given username and password Explanation: An error occurred while trying to log into WebSphere. User response: Ensure the super admin username and password are set correctly in the ibm-xdms Resource Environment Provider. Ensure nodes have been synchronized with latest configuration. GLSX0032E: Unable to encode or decode a REP custom propery Explanation: An error occurred while encoding or decoding a Resource Environment Provider s custom property. User response: Ensure the super admin username and password are set correctly in the ibm-xdms Resource Environment Provider. Ensure nodes have been synchronized with latest configuration. GLSX0033E: Cannot delete or modify existing namespaces specified with a Node Selector Explanation: The IETF simple-xcap specification does not allow XCAP modifications of element namespaces. User response: Do not delete or modify existing namespaces specified with a Node Selector GLSX0034E: Cannot reference a namespace as an attribute with a Node Selector Explanation: The IETF simple-xcap specification does not allow a namespace referenced as an element attribute. User response: Do not reference a namespace as an attribute with a Node Selector GLSX0035E: Unable to obtain the configured usage record datasource {0} for AUID {1}. Explanation: Usage record datasource or the Resource Provider Enviroment configuration is not valid. User response: Please ensure the usage record datasource and Resource Provider Environment is valid for your AUID. GLSX0036E: Unable to obtain a UserTransaction Explanation: The XDMS was unable to retreive a UserTransaction object from the Application Server User response: Please contact IBM Support 124 XML Document Management Server

131 GLSX0037E: Unable to commit the transaction for the request, exception to follow Explanation: The XDMS was unable to commit the UserTransaction object from the Application Server User response: Please contact IBM Support GLSX0038E: Unable to begin the UserTransaction for the request, exception to follow Explanation: The XDMS was unable to begin the UserTransaction object from the Application Server User response: Please contact IBM Support GLSX0039E: Unable to rollback the transaction for the request, exception to follow Explanation: The XDMS was unable to rollback the UserTransaction object from the Application Server User response: Please contact IBM Support GLSX0040W: Can not PUT a global index document Explanation: The HTTP PUT method was called on the global index document. This operation is restricted. User response: Do not attempt to PUT a global index document GLSX0041W: Name attribute cannot be changed. Explanation: An attempt was made to change the name attribute of a list element. User response: Do not change the name attribute GLSX0042W: List element does not contain the required attribute name Explanation: Constraint validation failed because the request would have resulted in a list element which does not contain the required attribute name User response: Always include the name attribute in a list element GLSX0043W: List name {0} does not conform to OMNA_ListUsageNames Explanation: The request failed because the name attribute of a top-level does not conform to the OMNA URI List Usage Name Registry User response: See the registry specification to create a valid name Chapter 8. Troubleshooting 125

132 GLSX0044W: resource-list element does not contain an absolute HTTP URI Explanation: The resource-list element must contain an absolute HTTP URI User response: Change the resource-list element to contain an absolute HTTP URI GLSX0045W: resource-list element contains a malformed URI Explanation: The resource-list element must contain a valid URI User response: Change the resource-list element to contain a valid URI GLSX0046W: resource-list element has an AUID which is not resource-lists Explanation: The resource-list element URI must have the AUID resource-lists User response: Change the resource-list element to have an AUID of resource-lists GLSX0047W: resource-list element contains an XUI which does not match the RLS services document Explanation: The resource-list element must contains an XUI which matches the RLS services document User response: Change the resource-list element to have an XUI to match the RLS services document GLSX0048W: entry element missing the required attribute uri Explanation: The entry element must have the uri attribute User response: Add a uri attribute to the entry element GLSX0049W: entry-ref element missing the required attribute ref Explanation: The entry-ref element must have a ref attribute User response: Add a ref attribute to the entry-ref element GLSX0050W: The entry-ref element s ref attribute is not a relative path Explanation: The entry-ref element s ref attribute must be a relative path User response: Change the entry-ref element s ref attribute to be a relative path GLSX0051W: The external element s anchor attribute is not an absolute HTTP URI Explanation: The external element s anchor attribute must be an absolute HTTP URI User response: Change the external element s anchor attribute to be an absolute HTTP URI 126 XML Document Management Server

133 GLSX0052W: Can not DELETE a global index document Explanation: The HTTP DELETE method was called on the global index document. This operation is restricted. User response: Do not attempt to DELETE a global index document GLSX0053W: Client is attempting to create a recursive list with document {0} Explanation: enableexternalelementvalidation is enabled, therefore the client must not have <external> elements which cause circular references User response: Client should remove any circular references and retry their request GLSX0054W: Error detecting external list recursion in document {0} due to an invalid XCAP URI in an <external> element Explanation: An <external> element in the document or a referenced document contains an invalid XCAP URI User response: The client should insure all <external> elements contain valid XCAP URIs GLSX0055W: Node selector for a global index HTTP GET must be qualified by an attribute Explanation: The node selector must be qualified by an attribute when performing a HTTP GET on the global index User response: Retry the request using a node selector qualified by an attribute GLSX0056W: Global Index is not enabled for AUID {0}, or node selector {1} does not match the configured one Explanation: Either the global-index-nodeselector is not configured for this AUID, or the client sent a node selector which does not match the global-indexnodeselector pattern User response: Insure the global-index-nodeselector element is configured in the AUID XML file or the client is sending a node selector which corresponds to the global-index-nodeselector pattern GLSX0057W: Found {0} element after appusages Explanation: The specified element was found after the appusages element in an OMA resource-list index document User response: Rearrange the document so that the appusages element comes after other list, entry, entry-ref, and external elements at the same level GLSX0058W: Cannot have more than one appusages element in a list Explanation: More than one appusages element was found in a list. Each list should only have one appusages element Chapter 8. Troubleshooting 127

134 User response: Retry the request with only one appusages element GLSX0059W: The external element is missing the mandatory anchor attribute Explanation: The anchor attribute is mandatory for the external element in a resource list document User response: Retry the request with an anchor attribute in the external element GLSX0060W: The entry-ref element s ref attribute does not resolve to an <entry> element within a resource-lists document Explanation: The entry-ref element s ref attribute must be a relative URI which resolves to an <entry> element with a resource-lists document User response: Correct the entry-ref element s ref attribute to resolve to an <entry> element with a resource-lists document GLSX0061E: Failed to publish a message on our JMS Queue Explanation: Failed to publish a JMS message about a change to a document User response: Please ensure you Service Integration Bus was properly created and that your JMS messaging engine is running GLSX0062W: Can not GET a global index document without a node selector Explanation: The HTTP GET method was called on the global index document. This operation is restricted. User response: Do not attempt to GET a global index document without a node selector GLSX0063W: The {0} element s domain attribute is not a valid domain name Explanation: The domain attribute must be a valid domain name User response: Correct the domain attribute to be a valid domain name GLSX0064W: resource-list element {0} does not exist under a user s home directory in the resource-lists application usage Explanation: A resource-list element in a global RLS services document must exist underneath any user s home directory in the resource-lists application usage User response: Change the resource-list element to have an XUI GLSX0065W: resource-list element {0} has an XCAP root which does not match the XCAP root for the RLS services document Explanation: A resource-list element must have an XCAP root which is the same as the XCAP root of the RLS services document 128 XML Document Management Server

135 User response: Change the resource-list element to have an XCAP root which matches the XCAP root for the RLS services document GLSX0066W: The anchor attribute of the external element contains a malformed URI Explanation: The anchor attribute of the external element must contain a valid URI User response: Change the anchor attribute of the external element to contain a valid URI GLSX0067W: The anchor attribute of the external element has an AUID which is not resource-lists Explanation: The anchor attribute of the external element URI must have the AUID resource-lists User response: Change the anchor attribute of the external element to have an AUID of resource-lists GLSX0068W: The anchor attribute of the external element does not resolve to a list element Explanation: The anchor attribute of the external element must resolve to a list element User response: Change the anchor attribute of the external element to resolve to a list element GLSX0069W: The resource-list element does not resolve to a list element Explanation: The resource-list element must resolve to a list element User response: Change the resouce-list element to resolve to a list element GLSX0070W: The anchor attribute of the external element does not resolve to a <list> element within a resource-lists document Explanation: The anchor attribute of the external element must be a URI which resolves to a <list> element with a resource-lists document User response: Correct the anchor attribute of the external element to resolve to a <list> element with a resource-lists document GLSX0071W: The <conditions> element does not support <sphere>, <validity>, or <other-identity> elements. Explanation: The <conditions> element does not support <sphere>, <validity>, or <other-identity> elements. User response: Please remove the unsupported <sphere>, <validity>, or <other-identity> elements. Chapter 8. Troubleshooting 129

136 GLSX0072W: The <rule> element must contain an id attribute of read, write, delete, or admin. Explanation: The <rule> element must contain an id attribute of read, write, delete, or admin. User response: Please specify only read, write, delete, or admin for the <rule> element id attribute. GLSX0073W: The <conditions> element must not contain more than one of each <external-list>, <anonymous-request>, or <identity> element. Explanation: The <conditions> element must not contain more than one of each <external-list>, <anonymous-request>, or <identity> element. User response: Please specify no more than one of each <external-list>, <anonymous-request>, or <identity> element for a <conditions> element. GLSX0074W: The SIP Servlet serving AUID {0} is shutting down. Explanation: The SIP Servlet is terminating. User response: To restart the servlet, access the IBM Administrative Console and restart the XDMS application. GLSX0075W: The HTTP Servlet serving AUID {0} is shutting down. Explanation: The HTTP Servlet is terminating. User response: To restart the servlet, access the IBM Administrative Console and restart the XDMS application. GLSX0076W: The uri attribute of the service element is invalid. Explanation: The uri attribute of a service element failed a constraint provided by a custom UriHelper.validate() method. User response: Specify a value for the uri attribute of the service element which will pass the custom validate method. GLSX0077W: The uri attribute of the service element failed to parse. Explanation: The uri attribute of a service element failed to parse into a URI object. The uri attribute is malformed. User response: Correct the value of the uri attribute of the service element to contain a well formed URI. GLSX0078W: The requested DELETE operation could not be performed because it would not be idempotent Explanation: The Node Selector selected another portion of the document after performing the delete, this is in violation of the XCAP specification 130 XML Document Management Server

137 User response: The client should adjust its Node Selector accordingly, and retry the request GLSX0079W: The requested PUT operation could not be performed because a GET of that resource after the PUT would not yeild the content of the PUT Explanation: The Node Selector selected another portion of the document after performing the PUT, this is in violation of the XCAP specification User response: The client should adjust its Node Selector accordingly, and retry the request GLSX0080E: The Alarm Interval REP is not a valid integer. Explanation: When trying to parse the alarminterval REP, an exception occurred. User response: Please check the REP and ensure it is a valid integer. GLSX0081W: The <conditions> element must not contain more than one of each <identity>, <external-list>, <other-identity>, or <anonymous-request> element. Explanation: The <conditions> element must not contain more than one of each <identity>, <external-list>, <other-identity>, or <anonymous-request> element. User response: Please specify no more than one of each <identity>, <external-list>, <other-identity>, or <anonymous-request> element for a <conditions> element. GLSX0082W: Search request not allowed Explanation: The XQuery request the client sent violates the Application Usage User response: The client should ensure their search request adheres to the application usage, or not send one if the application usage does not support search. GLSX0084W: The document {0} contains an external authorization list or entry {1} which could not be retrieved because it is either malformed or the SharedList XDMS is unavailable. Explanation: The URL for the external authorization list or entry is either malformed or the SharedList XDMS is unavailable. User response: Verify the accuracy of the URL and the availability of the SharedList XDMS. Until resolved authorization is denied for users defined in the list or entry. GLSX0085W: The directory.xml document is reserved for authorization purposes. Please choose another document name. Explanation: The request AUID is protected by authorization policies that make use of the directory.xml. Chapter 8. Troubleshooting 131

138 User response: Please choose another document name besides directory.xml. The document name directory is acceptable without the.xml file extension. GLSX0086W: The node selector used for the Global Index is invalid Explanation: A portion of the node selector used for Global Index is invalid. User response: Ensure the node selector template defined in the global-index-nodeselector element of your AUID descriptor file is correct GLSX0087W: Can not resolve a WebSphere configuration object for the containment path {0} Explanation: XDMS tried to get configuration data from WebSphere, but the configuration object was not found. User response: Ensure the super admin username and password are set correctly in the ibm-xdms Resource Environment Provider. Ensure nodes have been synchronized with latest configuration. 132 XML Document Management Server

139 Chapter 9. Reference Standards and specifications The IBM Websphere XML Document Management Server is primarily based on the OMA XDM Core specification. However, the OMA XDM Core specification references other specifications both from other OMA specifications and IETF specifications. The below tables list the standards organizations and the various specifications used in building the IBM implementation. Open Mobile Alliance Table 10. OMA specifications Specification title Version Notes OMA-TS-XDM_Core Full compliance OMA-TS-XDM_Core 2.0 Partial implementation for XDMS POST for search. No Search Proxy. OMA-TS-XDM_Shared_List Partial implementation for URI List only OMA-TS- Presence_SIMPLE_XDM Full compliance IETF Table 11. IETF specifications Specification title Version Notes ietf-simple-xcap-list-usage 05 Full compliance ietf-geopriv-common-policy 11 Full compliance ietf-simple-xcap 12 Full compliance ietf-sip-xcap-config 00 Full compliance ietf-simple-xcap-diff 04 Partial implementation. No patch operations provided. ietf-sipping-config-framework 09 Full compliance Presence Rules Resource Environment Providers Several Resource Environment Providers exist for Presence Rules applications. Copyright IBM Corp

140 Presence Rules Resource Environment Providers Table 12. Presence Rules Resource Environment Providers Property name Property value Property type Required? Property description enableschemavalidation true java.lang.boolean Required Enables or disables XML schema validation (recommended value: true) listminimummembers -1 java.lang.integer Not required Can be changed dynamically at runtime Minimum number of members in a list (recommended range: ) If not specified or a negative number, the minimum members policy is disabled listmaximummembers -1 java.lang.integer Not required Can be changed dynamically at runtime Maximum number of members in a list (recommended range: ) If not specified or a negative number, the maximum members policy is disabled Can be changed dynamically at runtime db!default!datasource jdbc/xdms java.lang.string Required Data source used for communicating with the XDMS database (recommended value: jdbc/xdms) Cannot be changed dynamically at runtime The application must be restarted for this setting to take effect db!default!table presrules java.lang.string Required Database table to use for storing documents (recommended value: rlsservices) Cannot be changed dynamically at runtime The application must be restarted for this setting to take effect 134 XML Document Management Server

141 Table 12. Presence Rules Resource Environment Providers (continued) Property name Property value Property type Required? Property description enablestandardauthorization true java.lang.boolean Required Enables or disables standard authorization (recommended value: true) Users with standard authorization have admin permission to their own home directory and read permission to global documents authorizationpolicyauid com.ibm.presulesacls Can be changed dynamically at runtime java.lang.string Required AUID for authorization policy rules that represents ACLs for rls-services. (recommended value: com.ibm.presrules-acls) Cannot be changed dynamically at runtime siprespondpending false java.lang.boolean Required Whether to respond immediately to SIP SUBSCRIBE requests with a 202 status code meaning accepted but pending (recommended value: false) Can be changed dynamically at runtime sipdefaultexpire 3600 java.lang.integer Required Default expire time in seconds if no expire time is specified in the SIP SUBSCRIBE request (recommended value: 3600) Can be changed dynamically at runtime Chapter 9. Reference 135

142 Table 12. Presence Rules Resource Environment Providers (continued) Property name Property value Property type Required? Property description sipminimumexpire -1 java.lang.integer Not required Minimum required expire time in seconds that is specified in the SIP SUBSCRIBE request (recommended range: ) If not specified or a negative number, the minimum expires policy is disabled sipmaximumexpire -1 java.lang.integer Not required Can be changed dynamically at runtime Maximum allowed expire time in seconds that is specified in the SIP SUBSCRIBE request (recommended range: ) If not specified or a negative number, the maximum expires policy is disabled usagerecorddatasource jdbc/xdmsur java.lang.string Not required Can be changed dynamically at runtime Data source used for communicating with the XDMSUR database that is used to store usage records (recommended value: jdbc/xdmsur) Cannot be changed dynamically at runtime enablexcapputusagerecordlogging false java.lang.boolean Not required The application must be restarted for this setting to take effect Enables or disables usage record logging for XCAP PUT requests (recommended value: false) If enabled, the usagerecorddatasource must be configured Can be changed dynamically at runtime 136 XML Document Management Server

143 Table 12. Presence Rules Resource Environment Providers (continued) Property name Property value Property type Required? Property description enablexcapgetusagerecordlogging false java.lang.boolean Not required Enables or disables usage record logging for XCAP GET requests (recommended value: false) If enabled, the usagerecorddatasource must be configured enablexcapdeleteusagerecordlogging false java.lang.boolean Not required Can be changed dynamically at runtime Enables or disables usage record logging for XCAP DELETE requests (recommended value: false) If enabled, the usagerecorddatasource must be configured enablexcappostusagerecordlogging false java.lang.boolean Not required Can be changed dynamically at runtime Enables or disables usage record logging for XCAP POST requests (recommended value: false) If enabled, the usagerecorddatasource must be configured enablesipsubscribeusagerecordlogging false java.lang.boolean Not required Can be changed dynamically at runtime Enables or disables usage record logging for SIP SUBSCRIBE requests (recommended value: false) If enabled, the usagerecorddatasource must be configured Can be changed dynamically at runtime Chapter 9. Reference 137

144 Table 12. Presence Rules Resource Environment Providers (continued) Property name Property value Property type Required? Property description enableexternalelementvalidation false java.lang.boolean Not required Whether newly inserted external elements should be validated to ensure that there are no recursive references (recommended value: false) auditloglogbyrole super-admin java.lang.string Not required maxsearchresults 0 java.lang.integer Not required Can be changed dynamically at runtime Comma-separated list of users If specified, requests and responses are logged only for these users Number of search results to return from the query (default value: 0) If equal to or less than 0, all search results are returned Can be changed dynamically at runtime Presence Rules ACLS Resource Environment Providers Table 13. Presence Rules ACLS Resource Environment Providers Property name Property value Property type Required? Property description enableschemavalidation true java.lang.boolean Required Enables or disables XML schema validation (recommended value: true) listminimummembers -1 java.lang.integer Not required Can be changed dynamically at runtime Minimum number of members in a list (recommended range: ) If not specified or a negative number, the minimum members policy is disabled Can be changed dynamically at runtime 138 XML Document Management Server

145 Table 13. Presence Rules ACLS Resource Environment Providers (continued) Property name Property value Property type Required? Property description listmaximummembers -1 java.lang.integer Not required Maximum number of members in a list (recommended range: ) If not specified or a negative number, the maximum members policy is disabled Can be changed dynamically at runtime db!default!datasource jdbc/xdms java.lang.string Required Data source used for communicating with the XDMS database (recommended value: jdbc/xdms) Cannot be changed dynamically at runtime The application must be restarted for this setting to take effect db!default!table presrules-acls java.lang.string Required Database table to use for storing documents (recommended value: rlsservices) Cannot be changed dynamically at runtime The application must be restarted for this setting to take effect enablestandardauthorization true java.lang.boolean Required Enables or disables standard authorization (recommended value: true) Users with standard authorization have admin permission to their own home directory and read permission to global documents Can be changed dynamically at runtime Chapter 9. Reference 139

146 Table 13. Presence Rules ACLS Resource Environment Providers (continued) Property name Property value Property type Required? Property description siprespondpending false java.lang.boolean Required Whether to respond immediately to SIP SUBSCRIBE requests with a 202 status code meaning accepted but pending (recommended value: false) Can be changed dynamically at runtime sipdefaultexpire 3600 java.lang.integer Required Default expire time in seconds if no expire time is specified in the SIP SUBSCRIBE request (recommended value: 3600) sipminimumexpire -1 java.lang.integer Not required Can be changed dynamically at runtime Minimum required expire time in seconds that is specified in the SIP SUBSCRIBE request (recommended range: ) If not specified or a negative number, the minimum expires policy is disabled sipmaximumexpire -1 java.lang.integer Not required Can be changed dynamically at runtime Maximum allowed expire time in seconds that is specified in the SIP SUBSCRIBE request (recommended range: ) If not specified or a negative number, the maximum expires policy is disabled Can be changed dynamically at runtime 140 XML Document Management Server

147 Table 13. Presence Rules ACLS Resource Environment Providers (continued) Property name Property value Property type Required? Property description usagerecorddatasource jdbc/xdmsur java.lang.string Not required Data source used for communicating with the XDMSUR database that is used to store usage records (recommended value: jdbc/xdmsur) Cannot be changed dynamically at runtime enablexcapputusagerecordlogging false java.lang.boolean Not required The application must be restarted for this setting to take effect Enables or disables usage record logging for XCAP PUT requests (recommended value: false) If enabled, the usagerecorddatasource must be configured enablexcapgetusagerecordlogging false java.lang.boolean Not required Can be changed dynamically at runtime Enables or disables usage record logging for XCAP GET requests (recommended value: false) If enabled, the usagerecorddatasource must be configured enablexcapdeleteusagerecordlogging false java.lang.boolean Not required Can be changed dynamically at runtime Enables or disables usage record logging for XCAP DELETE requests (recommended value: false) If enabled, the usagerecorddatasource must be configured Can be changed dynamically at runtime Chapter 9. Reference 141

148 Table 13. Presence Rules ACLS Resource Environment Providers (continued) Property name Property value Property type Required? Property description enablexcappostusagerecordlogging false java.lang.boolean Not required Enables or disables usage record logging for XCAP POST requests (recommended value: false) If enabled, the usagerecorddatasource must be configured enablesipsubscribeusagerecordlogging false java.lang.boolean Not required Can be changed dynamically at runtime Enables or disables usage record logging for SIP SUBSCRIBE requests (recommended value: false) If enabled, the usagerecorddatasource must be configured enableexternalelementvalidation false java.lang.boolean Not required auditloglogbyrole super-admin java.lang.string Not required maxsearchresults 0 java.lang.integer Not required Can be changed dynamically at runtime Whether newly inserted external elements should be validated to ensure that there are no recursive references (recommended value: false) Can be changed dynamically at runtime Comma-separated list of users If specified, requests and responses are logged only for these users Number of search results to return from the query (default value: 0) If equal to or less than 0, all search results are returned Can be changed dynamically at runtime 142 XML Document Management Server

149 Example property enableschemavalidation=true enableschemavalidation.type=java.lang.boolean enableschemavalidation.req=false enableschemavalidation.desc=enables or disables XML schema validation [Recommended value: true]. Shared List Resource Environment Providers Complete list of Resource Environment Providers for Shared List applications. Resource Lists Environment Provider properties Table 14. Resource Lists properties Property name Property value enableschemavalidation true Property type Required? Property description java.lang.boolean Required Enable or disable XML schema validation (recommended value: true) Can be changed dynamically at runtime listminimummembers -1 java.lang.integer Not required Minimum number of members in a list (recommended range: ) If not specified or a negative number, the minimum members policy is disabled Can be changed dynamically at runtime listmaximummembers -1 java.lang.integer Not required Maximum number of members in a list (recommended range: ) If not specified or a negative number, the maximum members policy is disabled Can be changed dynamically at runtime db!default!datasource jdbc/xdms java.lang.string Required Data source used for communicating with the XDMS database (recommended value: jdbc/xdms) Cannot be changed dynamically at runtime The application must be restarted for this setting to take effect Chapter 9. Reference 143

150 Table 14. Resource Lists properties (continued) Property name Property value Property type Required? Property description db!default!table resourcelists java.lang.string Required Database table to use for storing documents (recommended value: resourcelists) Cannot be changed dynamically at runtime enablestandardauthorization true The application must be restarted for this setting to take effect java.lang.boolean Required Enables or disables standard authorization (recommended value: true) Users with standard authorization have admin permission to their own home directory and read permission to global documents Can be changed dynamically at runtime authorizationpolicyauid com.ibm.resource-lists-acls java.lang.string Required The AUID for authorization policy rules that represent ACLs for rls-services. (recommended value: com.ibmresource-lists-acls) siprespondpending false Cannot be changed dynamically at runtime java.lang.boolean Required Whether to respond immediately to SIP SUBSCRIBE requests with a 202 status code meaning accepted but pending (recommended value: false) Can be changed dynamically at runtime sipdefaultexpire 3600 java.lang.integer Required Default expire time in seconds if no expire time is specified in the SIP SUBSCRIBE request (recommended value: 3600) sipminimumexpire -1 java.lang.integer Not required Can be changed dynamically at runtime Minimum required expire time in seconds that is specified in the SIP SUBSCRIBE request (recommended range: ) If not specified or a negative number, the minimum expires policy is disabled Can be changed dynamically at runtime 144 XML Document Management Server

151 Table 14. Resource Lists properties (continued) Property name Property value sipmaximumexpire -1 java.lang.integer Not required Property type Required? Property description Maximum allowed expire time in seconds that is specified in the SIP SUBSCRIBE request (recommended range: ) If not specified or a negative number, the maximum expires policy is disabled usagerecorddatasource jdbc/xdmsur java.lang.string Not required Can be changed dynamically at runtime Data source used for communicating with the XDMSUR database that is used to store usage records (recommended value: jdbc/xdmsur) Cannot be changed dynamically at runtime enablexcapputusagerecordlogging false java.lang.boolean Not required The application must be restarted for this setting to take effect Enables or disables usage record logging for XCAP PUT requests (recommended value: false) If enabled, the usagerecorddatasource must be configured enablexcapgetusagerecordlogging false java.lang.boolean Not required Can be changed dynamically at runtime Enables or disables usage record logging for XCAP GET requests (recommended value: false) If enabled, the usagerecorddatasource must be configured enablexcapdeleteusagerecordlogging false java.lang.boolean Not required Can be changed dynamically at runtime Enables or disables usage record logging for XCAP DELETE requests (recommended value: false) If enabled, the usagerecorddatasource must be configured Can be changed dynamically at runtime Chapter 9. Reference 145

152 Table 14. Resource Lists properties (continued) Property name Property value enablexcappostusagerecordlogging false java.lang.boolean Not required Property type Required? Property description Enables or disables usage record logging for XCAP POST requests (recommended value: false) If enabled, the usagerecorddatasource must be configured enablesipsubscribeusagerecordlogging false java.lang.boolean Not required Can be changed dynamically at runtime Enables or disables usage record logging for SIP SUBSCRIBE requests (recommended value: false) If enabled, the usagerecorddatasource must be configured enableexternalelementvalidation false java.lang.boolean Not required auditlogbyuser username, username, username... java.lang.string Not required maxsearchresults 0 java.lang.integer Not required Can be changed dynamically at runtime Whether newly inserted external elements should be validated to ensure that there are no recursive references (recommended value: false) Can be changed dynamically at runtime Comma-separated list of users If specified, requests and responses are logged only for these users Number of search results to return from the query (default value: 0) If equal to or less than 0, all search results are returned Can be changed dynamically at runtime RLS services Resource Environment Provider properties Table 15. RLS service properties Property name Property value enableschemavalidation true Property type Required? Property description java.lang.boolean Required Enable or disable XML schema validation (recommended value: true) Can be changed dynamically at runtime 146 XML Document Management Server

153 Table 15. RLS service properties (continued) Property name Property value listminimummembers -1 java.lang.integer Not required Property type Required? Property description Minimum number of members in a list (recommended range: ) If not specified or a negative number, the minimum members policy is disabled listmaximummembers -1 java.lang.integer Not required Can be changed dynamically at runtime Maximum number of members in a list (recommended range: ) If not specified or a negative number, the maximum members policy is disabled db!default!datasource jdbc/ xdms Can be changed dynamically at runtime java.lang.string Required Data source used for communicating with the XDMS database (recommended value: jdbc/xdms) Cannot be changed dynamically at runtime The application must be restarted for this setting to take effect db!default!table rlsservices java.lang.string Required Database table to use for storing documents (recommended value: rlsservices) Cannot be changed dynamically at runtime enablestandardauthorization true The application must be restarted for this setting to take effect java.lang.boolean Required Enables or disables standard authorization (recommended value: true) Users with standard authorization have admin permission to their own home directory and read permission to global documents Can be changed dynamically at runtime Chapter 9. Reference 147

154 Table 15. RLS service properties (continued) Property name Property value Property type Required? Property description authorizationpolicyauid com.ibm.rls-services-acls java.lang.string Required AUID for authorization policy rules that represents ACLs for rls-services. (recommended value: com.ibm.rls-services-acls) Cannot be changed dynamically at runtime siprespondpending false java.lang.boolean Required Whether to respond immediately to SIP SUBSCRIBE requests with a 202 status code meaning accepted but pending (recommended value: false) Can be changed dynamically at runtime sipdefaultexpire 3600 java.lang.integer Required Default expire time in seconds if no expire time is specified in the SIP SUBSCRIBE request (recommended value: 3600) sipminimumexpire -1 java.lang.integer Not required Can be changed dynamically at runtime Minimum required expire time in seconds that is specified in the SIP SUBSCRIBE request (recommended range: ) If not specified or a negative number, the minimum expires policy is disabled sipmaximumexpire -1 java.lang.integer Not required Can be changed dynamically at runtime Maximum allowed expire time in seconds that is specified in the SIP SUBSCRIBE request (recommended range: ) usagerecorddatasource jdbc/ xdmsur java.lang.string Not required If not specified or a negative number, the maximum expires policy is disabled Can be changed dynamically at runtime Data source used for communicating with the XDMSUR database that is used to store usage records (recommended value: jdbc/xdmsur) Cannot be changed dynamically at runtime The application must be restarted for this setting to take effect 148 XML Document Management Server

155 Table 15. RLS service properties (continued) Property name Property value enablexcapputusagerecordlogging false java.lang.boolean Not required Property type Required? Property description Enables or disables usage record logging for XCAP PUT requests (recommended value: false) If enabled, the usagerecorddatasource must be configured enablexcapgetusagerecordlogging false java.lang.boolean Not required Can be changed dynamically at runtime Enables or disables usage record logging for XCAP GET requests (recommended value: false) If enabled, the usagerecorddatasource must be configured enablexcapdeleteusagerecordlogging false java.lang.boolean Not required Can be changed dynamically at runtime Enables or disables usage record logging for XCAP DELETE requests (recommended value: false) If enabled, the usagerecorddatasource must be configured enablexcappostusagerecordlogging false java.lang.boolean Not required Can be changed dynamically at runtime Enables or disables usage record logging for XCAP POST requests (recommended value: false) If enabled, the usagerecorddatasource must be configured enablesipsubscribeusagerecordlogging false java.lang.boolean Not required Can be changed dynamically at runtime Enables or disables usage record logging for SIP SUBSCRIBE requests (recommended value: false) If enabled, the usagerecorddatasource must be configured Can be changed dynamically at runtime Chapter 9. Reference 149

156 Table 15. RLS service properties (continued) Property name Property value enableexternalelementvalidation false java.lang.boolean Not required Property type Required? Property description Whether newly inserted external elements should be validated to ensure that there are no recursive references (recommended value: false) auditlogbyuser username, java.lang.string Not username, required username... maxsearchresults 0 java.lang.integer Not required Can be changed dynamically at runtime Comma-separated list of users If specified, requests and responses are logged only for these users Number of search results to return from the query (default value: 0) If equal to or less than 0, all search results are returned Can be changed dynamically at runtime Resource Lists ACLS Resource Environment Provider properties Table 16. Resource Lists ACLS properties Property name Property value Property type Required? Property description enableschemavalidation true java.lang.boolean Required Enables or disables XML schema validation (recommended value: true) listminimummembers -1 java.lang.integer Not required listmaximummembers -1 java.lang.integer Not required Can be changed dynamically at runtime Minimum number of members in a list (recommended range: ) If not specified or a negative number, the minimum members policy is disabled Can be changed dynamically at runtime Maximum number of members in a list (recommended range: ) If not specified or a negative number, the maximum members policy is disabled Can be changed dynamically at runtime 150 XML Document Management Server

157 Table 16. Resource Lists ACLS properties (continued) Property name Property value Property type Required? Property description db!default!datasource jdbc/xdms java.lang.string Required Data source used for communicating with the XDMS database (recommended value: jdbc/xdms) Cannot be changed dynamically at runtime db!default!table The application must be restarted for this setting to take effect resourcelistssacls java.lang.string Required Database table to use for storing documents (recommended value: resourcelistsacls) Cannot be changed dynamically at runtime enablestandardauthorization true The application must be restarted for this setting to take effect java.lang.boolean Required Enables or disables standard authorization (recommended value: true) Users with standard authorization have admin permission to their own home directory and read permission to global documents Can be changed dynamically at runtime siprespondpending false java.lang.boolean Required Whether to respond immediately to SIP SUBSCRIBE requests with a 202 status code meaning accepted but pending (recommended value: false) Can be changed dynamically at runtime sipdefaultexpire 3600 java.lang.integer Required Default expire time in seconds if no expire time is specified in the SIP SUBSCRIBE request (recommended value: 3600) sipminimumexpire -1 java.lang.integer Not required Can be changed dynamically at runtime Minimum required expire time in seconds that is specified in the SIP SUBSCRIBE request (recommended range: ) If not specified or a negative number, the minimum expires policy is disabled Can be changed dynamically at runtime Chapter 9. Reference 151

158 Table 16. Resource Lists ACLS properties (continued) Property name Property value Property type sipmaximumexpire -1 java.lang.integer Not required Required? Property description Maximum allowed expire time in seconds that is specified in the SIP SUBSCRIBE request (recommended range: ) If not specified or a negative number, the maximum expires policy is disabled usagerecorddatasource jdbc/ xdmsur java.lang.string Not required Can be changed dynamically at runtime Data source used for communicating with the XDMSUR database that is used to store usage records (recommended value: jdbc/xdmsur) enablexcapputusagerecordlogging false java.lang.boolean Not required enablexcapgetusagerecordlogging false java.lang.boolean Not required enablexcapdeleteusagerecordlogging false java.lang.boolean Not required Cannot be changed dynamically at runtime The application must be restarted for this setting to take effect Enables or disables usage record logging for XCAP PUT requests (recommended value: false) If enabled, the usagerecorddatasource must be configured Can be changed dynamically at runtime Enables or disables usage record logging for XCAP GET requests (recommended value: false) If enabled, the usagerecorddatasource must be configured Can be changed dynamically at runtime Enables or disables usage record logging for XCAP DELETE requests (recommended value: false) If enabled, the usagerecorddatasource must be configured Can be changed dynamically at runtime 152 XML Document Management Server

159 Table 16. Resource Lists ACLS properties (continued) Property name Property value Property type enablexcappostusagerecordlogging false java.lang.boolean Not required enablesipsubscribeusagerecordlogging false java.lang.boolean Not required enableexternalelementvalidation false java.lang.boolean Not required auditlogbyuser username, java.lang.string Not username, required username... maxsearchresults 0 java.lang.integer Not required Required? Property description Enables or disables usage record logging for XCAP POST requests (recommended value: false) If enabled, the usagerecorddatasource must be configured Can be changed dynamically at runtime Enables or disables usage record logging for SIP SUBSCRIBE requests (recommended value: false) If enabled, the usagerecorddatasource must be configured Can be changed dynamically at runtime Whether newly inserted external elements should be validated to ensure that there are no recursive references (recommended value: false) Can be changed dynamically at runtime Comma-separated list of users If specified, requests and responses are logged only for these users Number of search results to return from the query (default value: 0) If equal to or less than 0, all search results are returned Can be changed dynamically at runtime RLS services ACLS Resource Environment Provider properties Table 17. RLS service properties Property name Property value enableschemavalidation true Property type Required? Property description java.lang.boolean Required Enables or disables XML schema validation (recommended value: true) Can be changed dynamically at runtime Chapter 9. Reference 153

160 Table 17. RLS service properties (continued) Property name Property value listminimummembers -1 java.lang.integer Not required Property type Required? Property description Minimum number of members in a list (recommended range: ) If not specified or a negative number, the minimum members policy is disabled listmaximummembers -1 java.lang.integer Not required Can be changed dynamically at runtime Maximum number of members in a list (recommended range: ) If not specified or a negative number, the maximum members policy is disabled Can be changed dynamically at runtime db!default!datasource jdbc/xdms java.lang.string Required Data source used for communicating with the XDMS database (recommended value: jdbc/xdms) Cannot be changed dynamically at runtime The application must be restarted for this setting to take effect db!default!table rlsservicesacls java.lang.string Required Database table to use for storing documents (recommended value: rlsservices) Cannot be changed dynamically at runtime enablestandardauthorization true The application must be restarted for this setting to take effect java.lang.boolean Required Enables or disables standard authorization (recommended value: true) Users with standard authorization have admin permission to their own home directory and read permission to global documents Can be changed dynamically at runtime 154 XML Document Management Server

161 Table 17. RLS service properties (continued) Property name Property value siprespondpending false Property type Required? Property description java.lang.boolean Required Whether to respond immediately to SIP SUBSCRIBE requests with a 202 status code meaning accepted but pending (recommended value: false) Can be changed dynamically at runtime sipdefaultexpire 3600 java.lang.integer Required Default expire time in seconds if no expire time is specified in the SIP SUBSCRIBE request (recommended value: 3600) sipminimumexpire -1 java.lang.integer Not required Can be changed dynamically at runtime Minimum required expire time in seconds that is specified in the SIP SUBSCRIBE request (recommended range: ) If not specified or a negative number, the minimum expires policy is disabled sipmaximumexpire -1 java.lang.integer Not required Can be changed dynamically at runtime Maximum allowed expire time in seconds that is specified in the SIP SUBSCRIBE request (recommended range: ) usagerecorddatasource jdbc/xdmsur java.lang.string Not required If not specified or a negative number, the maximum expires policy is disabled Can be changed dynamically at runtime Data source used for communicating with the XDMSUR database that is used to store usage records (recommended value: jdbc/xdmsur) Cannot be changed dynamically at runtime The application must be restarted for this setting to take effect Chapter 9. Reference 155

162 Table 17. RLS service properties (continued) Property name Property value enablexcapputusagerecordlogging false java.lang.boolean Not required Property type Required? Property description Enables or disables usage record logging for XCAP PUT requests (recommended value: false) If enabled, the usagerecorddatasource must be configured enablexcapgetusagerecordlogging false java.lang.boolean Not required Can be changed dynamically at runtime Enables or disables usage record logging for XCAP GET requests (recommended value: false) If enabled, the usagerecorddatasource must be configured enablexcapdeleteusagerecordlogging false java.lang.boolean Not required Can be changed dynamically at runtime Enables or disables usage record logging for XCAP DELETE requests (recommended value: false) If enabled, the usagerecorddatasource must be configured enablexcappostusagerecordlogging false java.lang.boolean Not required Can be changed dynamically at runtime Enables or disables usage record logging for XCAP POST requests (recommended value: false) If enabled, the usagerecorddatasource must be configured enablesipsubscribeusagerecordlogging false java.lang.boolean Not required Can be changed dynamically at runtime Enables or disables usage record logging for SIP SUBSCRIBE requests (recommended value: false) If enabled, the usagerecorddatasource must be configured Can be changed dynamically at runtime 156 XML Document Management Server

163 Table 17. RLS service properties (continued) Property name Property value enableexternalelementvalidation false java.lang.boolean Not required Property type Required? Property description Whether newly inserted external elements should be validated to ensure that there are no recursive references (recommended value: false) auditlogbyuser username, username, username... java.lang.string Not required maxsearchresults 0 java.lang.integer Not required Can be changed dynamically at runtime Comma-separated list of users If specified, requests and responses are logged only for these users Number of search results to return from the query (default value: 0) If equal to or less than 0, all search results are returned Can be changed dynamically at runtime Example property enableschemavalidation=true enableschemavalidation.type=java.lang.boolean enableschemavalidation.req=false enableschemavalidation.desc=enables or disables XML schema validation [Recommended value: true]. Aggregation Proxy Resource Environment Providers Several Resource Environment Providers exist for the Aggregation Proxy. Aggregation Proxy Environment Provider properties Table 18. Aggregation Proxy properties Property name Property value HTTPS_PROXY_XDMS false Property type Required? Property description java.lang.boolean Required Whether or not this Aggregation Proxy s backend XDMS instances are accessed by an https URL PROXY_ROOT java.lang.string Required The portion of the Aggregation proxy.com:9082 Proxy s URL ending with the context root THREEGPP_IMS false java.lang.boolean Required Whether or not the 3GPP-GAA is present. If false, Xdms-Asserted- Identity is used XCAP_CACHE_TIMEOUT 180 java.lang.integer Required Time in seconds that the XCAP-CAPS of each backend XDMS instance should remain in WebSphere s dynamic cache Chapter 9. Reference 157

164 Table 18. Aggregation Proxy properties (continued) Property name Property value Property type Required? Property description superadminuser superadmin java.lang.string Required ID used by the Aggregation Proxy during initialization and for sending an initial XCAP-CAPS request to each backend XDMS instance superadminpassword password java.lang.string Required Password used by the Aggregation Proxy during initialization XDMS_URI java.lang.string Required XCAP root of XDMS, per domain hostname1:9080/services# XDMS_URI!<domain> java.lang.string Required Defines the domain for which the list sharedlist2.com:9080/services/resource-lists of XDMS enablers is supported XDMS_URI_HTTPS java.lang.string Not The XUIs of the backend XDMS sharedlist1.com:9080/services# required clusters serviced by the Aggregation Proxy. List all XUIs here, separated by a # symbol XDMS_URI_HTTPS!<domain> java.lang.string Not Defines the secure domain for which sharedlist2.com:9080/services/resource-lists required the of XDMS enablers is supported alarminterval 15 java.lang.string Not Time in minutes between alarm required notifications for the same alarm (recommended value: 15) BAD_XDMS_POLLING_INTERVAL 20 java.lang.integer Required Time in seconds for polling XDMS instances that have never been online MAX_PROXY_THREAD_POOL_SIZE 60 java.lang.integer Required Maximum number of threads in the thread pool used to send proxy requests to XDMSes Related concepts Aggregation Proxy Aggregation Proxy is the contact point for the XDM Client implemented access XML documents stored in any XDMS. Aggregation Proxy Aggregation Proxy is the contact point for the XDMS client implemented in an IBM XDMS system to access XML documents stored in any IBM XDMS. Basic Aggregation Proxy routing on page 7 Basic routing uses the list of IBM XDMS enablers configured in the resource environment providers to route requests to specific AUIDs. Advanced Aggregation Proxy routing on page 9 Advanced routing uses domain partitioning and matching to determine the routing of XCAP requests. Related tasks Deploying the Aggregation Proxy on page 56 Perform a default installation of the Aggregation Proxy EAR (IBMXdmsAggregationProxy.ear) from the WebSphere Application Server console. Configuring basic routing on page 58 Configure just the basic routing when domain partitioning and routing are not required. 158 XML Document Management Server

165 Example Policy documents Configuring advanced routing on page 60 Configure advanced routing when domain partitioning and matching are required. Starting the Aggregation Proxy cluster on page 62 After you have deployed the Aggregation Proxy, start the cluster. Examples of XDMS Policy documents External list. <ruleset> <rule id="read"> <conditions> <external-list> <entry anc="..xcapuritolist1.."/> <entry anc="..xcapuritolist2.."/> </external-list> </conditions> <actions/> <transformations/> </rule> </ruleset> Anonymous request <ruleset> <rule id="read"> <conditions> <anonymous-request> </conditions> <actions/> <transformations/> </rule> </ruleset> Identity based authorization <ruleset> <rule id="read"> <conditions> <identity> <many domain="us.acme.com"> <except domain="rtp.us.acme.com"/> <except </many> <one </identity> </conditions> <actions/> <transformations/> </rule> </ruleset> Related concepts Chapter 4, Administering IBM XDMS, on page 73 From the command-line interface, you can perform administrative tasks for IBM XDMS such as adding, deleting, and modifying policy documents. Policy based authorization on page 77 Policy based authorization allows users to specify authorization rules by sending XCAP requests to create, update, or delete authorization documents. Chapter 9. Reference 159

166 Related tasks Example Resource List document Adding new policy documents on page 80 Add new policy documents using the xcap_put.sh request. Adding and editing documents on page 90 Use the xcap_put.sh request to add or edit documents from the command line interface. Retrieving documents on page 93 Use the xcap_get.sh request to retrieve stored documents. Deleting documents on page 94 Use the xcap_delete.sh request to delete XDMS documents. Searching documents on page 95 Use the xcap_post.sh request to search documents from the command line interface. Example Resource List document. TestResourceList.xml Resource List document <?xml version="1.0" encoding="utf-8"?> <resource-lists xmlns="urn:ietf:params:xml:ns:resource-lists" xmlns:oau="urn:oma:xml:xdm:resource-lis <list name="friends"> <list name="close-friends"> <display-name>close Friends</display-name> <external anchor=" <display-name>marketing</display-name> </external> <entry <display-name>joe Smith</display-name> </entry> <entry <display-name>nancy Gross</display-name> </entry> </list> <entry <display-name>bill Doe</display-name> </entry> <entry-ref </list> </resource-lists> Related concepts Using IBM XDMS to store and manage documents on page 87 IBM WebSphere XML Document Management Server Component enables storage, access, and manipulation of XML documents stored in a central repository. Using XCAP to store and manage documents on page 88 The XCAP specification defines how an HTTP Web address can identify the way XML documents are stored on an XCAP server. It also defines how the URI can be used to identify entire XML documents, individual elements, or XML attributes that can be retrieved, updated, or deleted Using the Node Selector on page 89 Node Selector is a subset of the XPath expression, used to identify a specific element or attribute of the XML document. Related tasks 160 XML Document Management Server

167 Javadoc for IBM XDMS Adding and editing documents on page 90 Use the xcap_put.sh request to add or edit documents from the command line interface. Retrieving documents on page 93 Use the xcap_get.sh request to retrieve stored documents. Deleting documents on page 94 Use the xcap_delete.sh request to delete XDMS documents. Adding and editing elements on page 91 Using a node selector statement in the XCAP URI you can select elements to be added or edited in an existing document. Adding and editing attributes on page 92 Using a node selector statement in the XCAP URI you can select attributes to be added or edited in an existing document. Javadoc is included for IBM XDMS. XcapUtils Link to the Javadoc for the XcapUtils. XdmsCore Link to the Javadoc for the XdmsCore. Chapter 9. Reference 161

168 162 XML Document Management Server

169 Notices This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user s responsibility to evaluate and verify the operation of any non-ibm product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY U.S.A. The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-ibm Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: IBM Corporation _Department number/building number_ Copyright IBM Corp

170 _Site mailing address City, State; Zip Code U.S.A. (or appropriate country) Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us. Information concerning non-ibm products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-ibm products. Questions on the capabilities of non-ibm products should be addressed to the suppliers of those products. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. If you are viewing this information softcopy, the photographs and color illustrations may not appear. Trademarks The following terms are trademarks of International Business Machines Corporation in the United States, other countries, or both: DB2 IBM IMS Notes purexml Tivoli WebSphere Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both. Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. 164 XML Document Management Server

171 Readers Comments We d Like to Hear from You IBM WebSphere XML Document Management Server IBM WebSphere XML Document Management Server Version 6.2 Publication No. SC We appreciate your comments about this publication. Please comment on specific errors or omissions, accuracy, organization, subject matter, or completeness of this book. The comments you send should pertain to only the information in this manual or product and the way in which the information is presented. For technical questions and information about products and prices, please contact your IBM branch office, your IBM business partner, or your authorized remarketer. When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in any way it believes appropriate without incurring any obligation to you. IBM or any other organizations will only use the personal information that you supply to contact you about the issues that you state on this form. Comments: Thank you for your support. Submit your comments using one of these channels: v Send your comments to the address on the reverse side of this form. v Send a fax to the following number: (US and Canada) If you would like a response from IBM, please fill in the following information: Name Address Company or Organization Phone No. address

172 Readers Comments We d Like to Hear from You SC SC Fold and Tape Please do not staple Fold and Tape BUSINESS REPLY MAIL FIRST-CLASS MAIL PERMIT NO. 40 ARMONK, NEW YORK POSTAGE WILL BE PAID BY ADDRESSEE IBM Corporation Information Development Department 6R4A P.O. Box Research Triangle Park, NC NO POSTAGE NECESSARY IF MAILED IN THE UNITED STATES Fold and Tape Please do not staple Fold and Tape Cut or Fold Along Line Cut or Fold Along Line

173

174 Part Number: 99F9999 Printed in USA SC (1P) P/N: 99F9999