WebSphere brand IBM WebSphere Telecom Web Services Server, Version 7.1

Integrating with Parlay X Address List Manager over XCAP

The Parlay X Address List Manager over XCAP Web service provides Web service-based mechanisms to create, read, update, and delete group definitions stored within the XDMS. This service uses the XCAP protocol rather than just the group definitions. This service implementation interfaces with XDMS which provides an XML Configuration Access Protocol (XCAP).

The Parlay X Address List Manager over XCAP Web service defines the faults or alarms that are replaced. All faults or alarms are replaced by the component name and the operation name.

Error handling

The following is an example of error handling, which displays the HTTP response codes that are generated and returned by the XDMS system. Additional HTTP response codes can be returned by the HTTP Server or WebSphere Application Server.

The Address List Manager handles response codes as follows:
  • Response codes between 100 and 199: the response is ignored.
  • Response codes between 200 and 299: a Parlay X output message is returned.
  • Response codes 304, 400, 403, 404, and 415: SVC0002 is returned.
  • All other response codes: SVC0001 is returned.
When either SVC0001 or SVC0002 is returned, the response code is included in the message.

HTTP response codes

Table 1. SOAX faults caused by HTTP response codes
HTTP Response code SOAX number
304 6020
400 6021
403 6022
404 6023
405 6024
409 6025
412 6026
415 6027
500 6028
Other 300-999 responses 6029

Group URI mapping

The Address List Manager URI maps the group URIs that are used in the Parlay X Address List Manager over XCAP, and the IBM® XDMS XCAP URI.

The following is the Address List Manager group URI format:
GroupScheme:list_name@user_domain.provider_domain;user=user_uri
where:
GroupScheme
  • Specified for the MBean property.
  • Determines whether a URI is a group URI or an XCAP user identifier (XUI).
  • The value of a scheme MBean property should not be the same as the scheme used for user URIs.
list_name
Group list name
user_domain
The domain specified by or for the user (specified in the Parlay X API parameter).
provider_domain
The domain specified in the MBean property. Should not be passed as part of the parameters on the Parlay X Address List Manager over XCAP API.
user_uri
  • A URI that corresponds to any user, for example sip:user@ibm.com.
  • Constant global for global groups.
For example, in the URI group:mybuddies@friends.ibm.com;sip:user@ibm.com:
  • The group scheme is group.
  • The group list name is mybuddies.
  • The subdomain is friends.
  • The service provider domain is ibm.com.
  • The user is sip:user@ibm.com.
Here are some examples of XCAP URIs:
User Group
XCAP RootURI/AUID/users/user_uri/file_name/~~/Node_Selector
Global Group
XCAP RootURI/AUID/global/file_name/~~/Node_Selector
Mapped XCAP URI
http://xdms.example.com:9080/services/resource-lists/users/sip:user@example.com/friends
Each of these example URIs contains some or all of the following elements:
XCAP Root URI
The context root for the application, for example http://xdms.ibm.com:9080/services/.
AUID
An XCAP application-unique ID that defines the type of XML document. AUIDs are defined according to XCAP usage specifications, for example resource-lists or rls-services.

In Parlay X Address List Manager over XCAP, the AUID value is always resource-lists.

Document Selector
Identifies the specific document to be stored or accessed. XCAP documents are segregated into two tree branches:
  • Global: Contains documents which can only be created by administrators, but accessed by anybody.
  • User: Contains user-specific documents for a specific XCAP user identifier (XUI).

In both branches, a file_name is a user-selected name for the group for example, friends. It is specified on the Parlay X Address List Manager over XCAP MBean configuration.

Examples:
  • user/file_name
  • global/file_name
Node Selector
An optional XPATH expression that can be used to identify a specific XML element or attribute which is to be updated, retrieved, or deleted. The /~~/ is a separator between the document selector and the node selector.
Note: TWSS supports address URIs that use the following schemes only: tel:, sip:, sips:, short:.

Interfaces

GroupManagement
createGroup
Creates a group definition.

If the autoName parameter is set to true, the Address List Manager attempts to create unique groups if the original name already exists, and then sends the request.

IBM XDMS supports autoName. To take advantage of this support, open the Integrated Solutions Console and update the ibm-xdms Resource Environment Provider by setting enableDraftPutConditionalSupport to true.

deleteGroup
Deletes a group definition.
Group
addMember
Adds a member to the specified group.
addMembers
Adds multiple members to the specified group.
deleteMember
Removes a member from the specified group.
deleteMembers
Removes multiple members from the specified group.
queryMembers
Retrieves the names of the members of the specified group.
addGroupAttribute
Adds a new attribute or updates an existing attribute for the specified group.
deleteGroupAttribute
Deletes an attribute from the specified group.
queryGroupAttributes
Retrieves a list of attributes and their associated values for the specified group.
addGroupMemberAttribute
Adds a new attribute or updates an existing attribute for the specified group member.
deleteGroupMemberAttribute
Deletes an attribute for the specified group member.
queryGroupMemberAttributes
Retrieves a list of attributes and their associated values for the specified group member.



Terms of use
(C) Copyright IBM Corporation 2009. All Rights Reserved.