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 and OMA-TS-XDM_Core-V2_0 for
the new xcap-diff event type.
Subscription types
The
IBM XDMS supports
two type of subscription events:
- UA-profile events
- UA-profile events allow for subscription to XDMS documents. Notification
patch operations may include a <changelog> element describing changes
made to the subscribed document.
- xcap-diff events
- xcap-diff events allow for subscriptions to documents as well
as elements and attributes within those elements. These documents,
elements, or attributes may already exist, or if not, subscriptions
can be made in pending state. xcap-diff events also allow for batch
subscriptions, where more than one resource is subscribed to in one
session. Notifications may include patch operations for document level
subscriptions, and complete element or attribute content for node
level subscriptions.
Subscription notifications
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 conditions will cause a SIP NOTIFY request
to be sent:
- 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
- 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:
- ACTIVE: indicates that the subscription has been accepted.
- 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
- In IBM XDMS when
using UA-profile events 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 resource element or attribute.
- Because the xcap-caps is a generated document, the SUBSCRIBE interface
does not accept subscriptions to it.
- 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 requester 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.