payload is an XML document instance using
XML extensions to the base notification schema)
7 S->N 200 OK (Notify)
In line 1, the SPIRITS subscriber subscribes to certain events using
an XML document based on the base schema defined in this document.
In line 6, the SPIRITS notifier notifies the SPIRITS subscriber of
the occurrence of the event using extensions to the base notification
schema. Note that this document defines a base schema for event
notification as well; the SPIRITS notifier could have availed itself
of these. Instead, it chooses to pass to the SPIRITS subscriber an
XML document composed of extensions to the base notification schema.
The SPIRITS subscriber, if it understands the extensions, can
interpret the XML document accordingly. However, in the event that
the SPIRITS subscriber is not programmed to understand the
extensions, it MUST search the XML document for the mandatory
elements. These elements MUST be present in all notification schemas
and are detailed in Section 9.
4. XML format definition
This section defines the XML-encoded SPIRITS payload format. Such a
payload is a well formed XML document and is produced by SPIRITS
notifiers and SPIRITS subscribers.
The namespace URI for elements defined in this document is a Uniform
Resource Name (URN) [14], using the namespace identifier ’ietf’
defined in [15] and extended by [16]:
urn:ietf:params:xml:ns:spirits-1.0
SPIRITS XML documents may have a default namespace, or they may be
associated with a namespace prefix following the convention
established in XML namespaces [17]. Regardless, the elements and
attributes of SPIRITS XML documents MUST conform to the SPIRITS XML
schema specified in Section 9.
The <spirits-event> element
The root of a SPIRITS XML document (characterized by a Content-
Type header of "application/spirits-event+xml">) is the <spirits-
event> element. This element MUST contain a namespace declaration
(’xmlns’) to indicate the namespace on which the XML document is
based. XML documents compliant to the SPIRITS protocol MUST
contain the URN "urn:ietf:params:xml:ns:spirits-1.0" in the
namespace declaration. Other namespaces may be specified as
needed.
<spirits-event> element MUST contain at least one <Event> element,
and MAY contain more than one.
The <Event> element
The <Event> element contains three attributes, two of which are
mandatory. The first mandatory attribute is a ’type’ attribute
whose value is either "INDPs" or "userprof".
These types correspond, respectively, to call-related events
described in Section 5 and non-call related events described in
Section 6.
The second mandatory attribute is a ’name’ attribute. Values for
this attribute MUST be limited to the SPIRITS mnemonics defined in
Section 5.2.1, Section 5.2.2, and Section 6.1.
The third attribute, which is optional, is a ’mode’ attribute.
The value of ’mode’ is either "N" or "R", corresponding
respectively to (N)otification or (R)equest (RFC3298:Section 4).
The default value of this attribute is "N".
If the ’type’ attribute of the <Event> element is "INDPs", then it
MUST contain at least one or more of the following elements
(unknown elements MAY be ignored): <CallingPartyNumber>,
<CalledPartyNumber>, <DialledDigits>, or <Cause>. These elements
are defined in Section 5.2; they MUST not contain any attributes
and MUST not be used further as parent elements. These elements
contain a string value as described in Section 5.2.1 and 5.2.2.
If the ’type’ attribute of the <Event> element is "userprof", then
it MUST contain a <CalledPartyNumber> element and it MAY contain a
<Cell-ID> element. None of these elements contain any attributes
and neither must be used further as a parent element. These
elements contain a string value as described in Section 6.1. All
other elements MAY be ignored if not understood.
A SPIRITS-compliant XML document using the XML namespace defined in
this document might look like the following example:
<?xml version="1.0" encoding="UTF-8"?>
<spirits-event xmlns="urn:ietf:params:xml:ns:spirits-1.0">
<Event type="INDPs" name="OD" mode="N">
<CallingPartyNumber>5551212</CallingPartyNumber>
</Event>
<Event type="INDPs" name="OAB" mode="N">
<CallingPartyNumber>5551212</CallingPartyNumber>
</Event>
</spirits-event>
5. Call-related events
For readers who may not be familiar with the service execution
aspects of PSTN/IN, we provide a brief tutorial next. Interested
readers are urged to consult [19] for a detailed treatment of this
subject.
Services in the PSTN/IN are executed based on a call model. A call
model is a finite state machine used in SSPs and other call
processing elements that accurately and concisely reflects the
current state of a call at any given point in time. Call models
consist of states called PICs (Points In Call) and transitions
between states. Inter-state transitions pass through elements called
Detection Points or DPs. DPs house one or more triggers. Every
trigger has a firing criteria associated with it. When a trigger is
armed (made active), and its associated firing criteria are
satisfied, it fires. The particulars of firing criteria may vary
based on the call model being supported.
When a trigger fires, a message is formatted with call state
information and transmitted by the SSP to the SCP. The SCP then
reads this call related data and generates a response which the SSP
then uses in further call processing.
Detection Points are of two types: TDPs (or Trigger Detection
Points), and EDPs (or Event Detection Points). TDPs are provisioned
with statically armed triggers (armed through Service Management
Tools). EDPs are dynamically armed triggers (armed by the SCP as
call processing proceeds). DPs may also be classified as "Request"
or "Notification" DPs. Thus, one can have TDP-R’s, TDP-N’s, EDP-R’s
and EDP-N’s.
The "-R" type of DPs require the SSP to suspend call processing when
communication with the SCP is initiated. Call processing resumes
when a response is received. The "-N" type of DPs enable the SSP to
continue with call processing when the trigger fires, after it sends
out the message to the SCP, notifying it that a certain event has
occurred.
Call models typically support different types of detection points.
Note that while INAP and the IN Capability Set (CS)-2 [7] call model
are used in this document as examples, and for ease of explanation,
other call models possess similar properties. For example, the
Wireless Intelligent Network (WIN) call model also supports the
dynamic arming of triggers. Thus, the essence of this discussion
applies not just to the wireline domain, but applies equally well to
the wireless domain as well.
When the SCP receives the INAP formatted message from the SSP, if the
SCP supports the SPIRITS architecture, it can encode the INAP message
contents into a SPIRITS protocol message which is then transmitted to
SPIRITS-capable elements in the IP network. Similarly, when it
receives responses back from said SPIRITS capable elements, it can
reformat the response content into the INAP format and forward these
messages back to SSPs. Thus the process of inter-conversion and/or
encoding between the INAP parameters and the SPIRITS protocol is of
primary interest.
An SCP is a physical manifestation of the Service Control Function.
An SSP is a physical manifestation of the Service Switching Function
(and the Call Control Function). To support uniformity of
nomenclature between the various SPIRITS drafts, we shall use the
terms SCP and SCF, and SSP and SSF interchangeably in this document.
5.1. IN-specific requirements
Section 4 of [4] outlines the IN-related requirements on the SPIRITS
protocol. The SUBSCRIBE request arriving at the SPIRITS notifier
MUST contain the events to be monitored (in the form of a DP list),
the mode (request or a notification, the difference being that for a
request, the SPIRITS subscriber can influence subsequent call
processing and for a notification, no further influence is needed),
and any DP-related parameters.
Section 4 of [4] also enumerates a list of Capability Set 3 (CS-3)
DPs for SPIRITS services. It is a requirement (RFC3298:Section 4)
that the SPIRITS protocol specify the relevant parameters of the DPs.
These DPs and their relevant parameters to be carried in a SUBSCRIBE
request are codified in an XML schema. All SPIRITS subscribers MUST
understand this schema for subscribing to the DPs in the PSTN. The
schema is defined in Section 9.
When a DP fires, a notification -- using a SIP NOTIFY request -- is
transmitted from the SPIRITS notifier to the SPIRITS subscriber. The
NOTIFY request contains an XML document which describes the DP that
fired and any relevant parameters. The DPs and their relevant
parameters to be carried in a NOTIFY request are codified in an XML
schema. All SPIRITS notifiers MUST understand this schema; this
schema MAY be extended. The schema is defined in Section 9.
In addition, Appendices A and B of [6] contain a select subset of
CS-2 DPs that may be of interest to the reader. However, this
document will only refer to CS-3 DPs outlined in [4].
5.2. Detection points and required parameters
The IN CS-3 DPs envisioned for SPIRITS services (RFC3298:Section 4)
are described next. IN DPs are characterized by many parameters,
however, not all such parameters are required -- or even needed -- by
SPIRITS. This section, thus, serves to list the mandatory parameters
for each DP that MUST be specified in subscriptions and
notifications. Implementations can specify additional parameters as
XML extensions associated with a private (or public and standardized)
namespace.
The exhaustive list of IN CS-3 DPs and their parameters can be found
in reference [13].
Each DP is given a SPIRITS-specific mnemonic for use in the
subscriptions and notifications.
5.2.1. Originating-side DPs
Origination Attempt Authorized
SPIRITS mnemonic: OAA
Mandatory parameter in SUBSCRIBE: CallingPartyNumber
Mandatory parameters in NOTIFY: CallingPartyNumber, CalledPartyNumber
CallingPartyNumber: A string used to identify the calling party for
the call. The actual length and encoding of this parameter depend on
the particulars of the dialing plan used.
CalledPartyNumber: A string containing the number (e.g., called
directory number) used to identify the called party. The actual
length and encoding of this parameter depend on the particulars of
the dialing plan used.
Collected Information
SPIRITS mnemonic: OCI
Mandatory parameter in SUBSCRIBE: CallingPartyNumber
Mandatory parameters in NOTIFY: CallingPartyNumber, DialledDigits
DialledDigits: This parameter contains non-translated address
information collected/received from the originating user/line/trunk
Analyzed Information
SPIRITS mnemonic: OAI
Mandatory parameter in SUBSCRIBE: CallingPartyNumber
Mandatory parameters in NOTIFY: CallingPartyNumber, DialledDigits
Origination Answer
SPIRITS mnemonic: OA
Mandatory parameter in SUBSCRIBE: CallingPartyNumber
Mandatory parameters in NOTIFY: CallingPartyNumber, CalledPartyNumber
Origination Term Seized
SPIRITS mnemonic: OTS
Mandatory parameter in SUBSCRIBE: CallingPartyNumber
Mandatory parameter in NOTIFY: CallingPartyNumber, CalledPartyNumber
Origination No Answer
SPIRITS mnemonic: ONA
Mandatory parameter in SUBSCRIBE: CallingPartyNumber
Mandatory parameter in NOTIFY: CallingPartyNumber, CalledPartyNumber
Origination Called Party Busy
SPIRITS mnemonic: OCPB
Mandatory parameter in SUBSCRIBE: CallingPartyNumber
Mandatory parameters in NOTIFY: CallingPartyNumber, CalledPartyNumber
Route Select Failure
SPIRITS mnemonic: ORSF
Mandatory parameter in SUBSCRIBE: CallingPartyNumber
Mandatory parameter in NOTIFY: CallingPartyNumber, CalledPartyNumber
Origination Mid Call
SPIRITS mnemonic: OMC
Mandatory parameter in SUBSCRIBE: CallingPartyNumber
Mandatory parameter in NOTIFY: CallingPartyNumber
Origination Abandon
SPIRITS mnemonic: OAB
Mandatory parameter in SUBSCRIBE: CallingPartyNumber
Mandatory parameter in NOTIFY: CallingPartyNumber
Origination Disconnect
SPIRITS mnemonic: OD
Mandatory parameter in SUBSCRIBE: CallingPartyNumber
Mandatory parameter in NOTIFY: CallingPartyNumber, CalledPartyNumber
5.2.2. Terminating-side DPs
Termination Answer
SPIRITS mnemonic: TA
Mandatory parameter in SUBSCRIBE: CalledPartyNumber
Mandatory parameters in NOTIFY: CallingPartyNumber, CalledPartyNumber
Termination No Answer
SPIRITS mnemonic: TNA Mandatory parameter in SUBSCRIBE:
CalledPartyNumber
Mandatory parameters in NOTIFY: CallingPartyNumber, CalledPartyNumber
Termination Mid-Call
SPIRITS mnemonic: TMC
Mandatory parameter in SUBSCRIBE: CalledPartyNumber
Mandatory parameter in NOTIFY: CalledPartyNumber
Termination Abandon
SPIRITS mnemonic: TAB
Mandatory parameter in SUBSCRIBE: CalledPartyNumber
Mandatory parameter in NOTIFY: CalledPartyNumber
Termination Disconnect
SPIRITS mnemonic: TD
Mandatory parameter in SUBSCRIBE: CalledPartyNumber
Mandatory parameters in NOTIFY: CalledPartyNumber, CallingPartyNumber
Termination Attempt Authorized
SPIRITS mnemonic: TAA
Mandatory parameter in SUBSCRIBE: CalledPartyNumber
Mandatory parameters in NOTIFY: CalledPartyNumber, CallingPartyNumber
Termination Facility Selected and Available
SPIRITS mnemonic: TFSA
Mandatory parameter in SUBSCRIBE: CalledPartyNumber
Mandatory parameter in NOTIFY: CalledPartyNumber
Termination Busy
SPIRITS mnemonic: TB
Mandatory parameter in SUBSCRIBE: CalledPartyNumber
Mandatory parameters in NOTIFY: CalledPartyNumber,
CallingPartyNumber, Cause
Cause: This parameter contains a string value of either "Busy" or
"Unreachable". The difference between these is translated as a
requirement (RFC3298:Section 5) to aid in the SPIRITS subscriber in
determining if the called party is indeed busy (engaged), or if the
called party is unavailable (as it would be if it were on the
cellular PSTN and the mobile subscriber was not registered with the
network).
5.3. Services through dynamic DPs
Triggers in the PSTN can be armed dynamically, often outside the
context of a call. The SIP event notification mechanism [3] is,
therefore, a convenient means to exploit in those cases where
triggers housed in EDPs fire (see section 3 of [4]). Note that [4]
uses the term "persistent" to refer to call-related DP arming and
associated interactions.
The SIP Events Package enables IP endpoints (or hosts) to subscribe
to and receive subsequent notification of events occurring in the
PSTN. With reference to Figure 2, this includes communication on the
interfaces marked "B" and "C".
5.3.1. Normative usage
A subscriber will issue a SUBSCRIBE request which identifies a set of
events (DPs) it is interested in getting the notification of. This
set MUST contain at least one DP, it MAY contain more than one. The
SUBSCRIBE request is routed to the notifier, where it is accepted,
pending a successful authentication.
When any of the DPs identified in the set of events fires, the
notifier will format a NOTIFY request and direct it towards the
subscriber. The NOTIFY request will contain information pertinent to
the event that was triggered. The un-encountered DPs MUST be
subsequently dis-armed by the SPIRITS notifier and/or the SCF.
The dialog established by the SUBSCRIBE terminates when the event of
interest occurs and this notification is passed to the subscriber
through a NOTIFY request. If the subscriber is interested in the
future occurrence of the same event, it MUST issue a new SUBSCRIBE
request, establishing a new dialog.
When the subscriber receives a NOTIFY request, it can subsequently
choose to act in a manner appropriate to the notification.
The remaining sections fill in the specific package responsibilities
raised in RFC3265 [3], Section 4.4.
5.3.2. Event package name
This document defines two event packages; the first of these is
defined in this section and is called "spirits-INDPs". This package
MUST be used for events corresponding to IN detection points in the
cellular or wireline PSTN. All entities that implement the SPIRITS
protocol and support IN detection points MUST set the "Event" request
header [3] to "spirits-INDPs." The "Allow-Events" general header [3]
MUST include the token "spirits-INDPs" if the entity implements the
SPIRITS protocol and supports IN detection points.
Event: spirits-INDPs
Allow-Events: spirits-INDPs
The second event package is defined and discussed in Section 6.
5.3.3. Event package parameters
The "spirits-INDPs" event package does not support any additional
parameters to the Event header.
5.3.4. SUBSCRIBE bodies
SUBSCRIBE requests that serve to terminate the subscription MAY
contain an empty body; however, SUBSCRIBE requests that establish a
dialog MUST contain a body which encodes three pieces of information:
(1) The set of events (DPs) that is being subscribed to. A
subscriber MAY subscribe to multiple DPs in one SUBSCRIBE request,
or MAY issue a different SUBSCRIBE request for each DP it is
interested in receiving a notification for. The protocol allows
for both forms of representation, however, it recommends the
former manner of subscribing to DPs if the service depends on any
of the DPs being triggered.
(2) Because of the requirement [4] that IN be informed whether the
detection point is set as the request or notification, all events
in the "spirits-INDPs" package (but not in the "spirits-user-prof"
package) are required to provide a "mode" parameter, whose values
are "R" (for Request) and "N" for notification.
(3) A list of the values of the parameters associated with the
event detection point (Note: the term "event" here refers to the
IN usage -- a dynamically armed DP is called an Event Detection
Point). Please see Section 5.2.1 and Section 5.2.2 for a list of
parameters associated with each DP.
The default body type for SUBSCRIBEs in SPIRITS is denoted by the
MIME type "application/spirits-event+xml". The "Accept" header, if
present, MUST include this MIME type.
5.3.5. Subscription duration
For package "spirits-INDPs", the purpose of the SUBSCRIBE request is
to arm the DP, since as far as IN is concerned, being armed is the
first essential pre-requisite. A DP maybe armed either statically
(for instance, through service provisioning), or dynamically (by the
SCF). A statically armed DP remains armed until it is disarmed
proactively. A dynamically armed DP remains armed for the duration
of a call (or more appropriately, no longer than the duration of a
particular SSF-SCF relationship).
Dynamically armed DPs are automatically disarmed when the event of
interest occurs in the notifier. It is up to the subscriber to re-
arm the DPs within the context of a call, if it so desires.
Statically armed DPs are considered outside the scope of the SPIRITS
protocol requirements [4] and thus will not be considered any
further.
5.3.6. NOTIFY bodies
Bodies in NOTIFY requests for the "spirits-INDPs" package are
optional. If present, they MUST be of the MIME type
"application/spirits-event+xml". The body in a NOTIFY request
encapsulates the following pieces of information which can be used by
the subscriber:
(1) The event that resulted in the NOTIFY being generated
(typically, but not always, this will be the same event present in
the corresponding SUBSCRIBE request).
(2) The "mode" parameter; it is simply reflected back from the
corresponding SUBSCRIBE request.
(3) A list of values of the parameters associated with the event
that the NOTIFY is being generated for. Depending on the actual
event, the list of the parameters will vary.
If the subscriber armed multiple DPs as part of a single SUBSCRIBE
request, all the un-encountered DPs that were part of the same
SUBSCRIBE dialog MUST be dis-armed by the SPIRITS notifier and/or the
SCF/SCP.
5.3.7. Notifier processing of SUBSCRIBE requests
When the notifier receives a SUBSCRIBE request, it MUST authenticate
the request and ensure that the subscriber is authorized to access
the resource being subscribed to, in this case, PSTN/IN events on a
certain PSTN line.
Once the SUBSCRIBE request has been authenticated and authorized, the
notifier interfaces with the SCF over interface D to arm the
detection points corresponding to the PSTN line contained in the
SUBSCRIBE body. The particulars about interface D is out of scope
for this document; here we will simply assume that the notifier can
affect the arming (and disarming) of triggers in the PSTN through
interface D.
5.3.8. Notifier generation of NOTIFY requests
If the notifier expects the arming of triggers to take more than 200
ms, it MUST send a 202 response to the SUBSCRIBE request immediately,
accepting the subscription. It should then send a NOTIFY request
with an empty body. This NOTIFY request MUST have a "Subscription-
State" header with a value of "pending".
This immediate NOTIFY with an empty body is needed since the
resource identified in the SUBSCRIBE request does not have as
yet a meaningful state.
Once the notifier has successfully interfaced with the SCF, it MUST
send a subsequent NOTIFY request with an empty body and a
"Subscription-State" header with a value of "active."
When the event of interest identified in the SUBSCRIBE request
occurs, the notifier sends out a new NOTIFY request which MUST
contain a body (see Section 5.3.6). The NOTIFY request MUST have a
"Subscription-State" header and its value MUST be set to "terminated"
with a reason parameter of "fired".
5.3.9. Subscriber processing of NOTIFY requests
The exact steps executed at the subscriber when it gets a NOTIFY
request will depend on the service being implemented. As a
generality, the UA associated with the subscriber should somehow
impart this information to the user by visual or auditory means, if
at all possible.
If the NOTIFY request contained a "Subscription-State" header with a
value of "terminated" and a reason parameter of "fired", the UA
associated with the subscriber MAY initiate a new subscription for
the event that was just reported through the NOTIFY request.
Whether or not to initiate a new subscription when an existing
one expires is up to the context of the service that is being
implemented. For instance, a user may configure her UA to
always re-subscribe to the same event when it fires, but this
is not necessarily the normative case.
5.3.10. Handling of forked requests
Forking of SUBSCRIBE requests is prohibited. Since the SUBSCRIBE
request is targeted towards the PSTN, highly irregular behaviors
occur if the request is allowed to fork. The normal SIP DNS lookup
and routing rules [11] should result in a target set with exactly one
element: the notifier.
5.3.11. Rate of notifications
For reasons of security more than network traffic, it is RECOMMENDED
that the notifier issue two or, at most three NOTIFY requests for a
subscription. If the subscription was accepted with a 202 response,
a NOTIFY will be sent immediately towards the subscriber. This
NOTIFY serves to inform the subscriber that the request has been
accepted and is being acted on.
Once the resource (detection points) identified in the SUBSCRIBE
request have been initialized, the notifier MUST send a second NOTIFY
request. This request contains the base state of the resource.
When an event of interest occurs which leads to the firing of the
trigger associated with the detection points identified in the
SUBSCRIBE request, a final NOTIFY is sent to the subscriber. This
NOTIFY request contains more information about the event of interest.
If the subscription was accepted with a 200 response, the notifier
simply sends two NOTIFY requests: one containing the base state of