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.
- 200 OK – A GET, DELETE, or PUT which performed an Update completed successfully.
- 201 Created – The document, element, or XML attribute was created successfully.
- 304 Not Modified – The Etag of requested document matches that specified in the If-None-Match header.
- 400 Bad Request- Name Space not included in the query component of the request.
- 403 Forbidden – Used to indicate that authorization has failed
- 404 Not Found – The request is for an AUID that the XDMS does not support, or a GET or DELETE is for an item that does not exist in the XDMS.
- 405 Method Not Allowed - Post is not supported.
- 409 Conflict - Should return XML.
- 412 Precondition Failed – See the use of If-Match, and If-None-Match headers.
- 415 Unsupported Media Type – If a PUT request contains an element and Content-Type is not "application/xcap-el+xml", or a PUT request contains an attribute and Content-Type is not "application/xcap-att+xml".
- 500 Internal Error – Used to indicate that an error occurred in the XDMS that has nothing to do with the request.
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 codesHTTP 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.