SIST-V ETSI/EG 201 899 V1.1.1:2003

• Abstract:

  To specify interface classes between SCF/SA-GF and 3rd party applications using UML. The interface to be provide at least IN CS1 capabilities to those applications. Result will be used to influence SPAN-03070-1.

• Status: Published
• Publication Date: 31-Oct-2003
• ICS: 33.040.35 - Telephone networks
• Technical Committee: SPN - Services and Protocols for Networks
• Current Stage: 6060 - National Implementation/Publication (Adopted Project)
• Start Date: 01-Nov-2003
• Due Date: 01-Nov-2003
• Completion Date: 01-Nov-2003
• Ref Project: ETSI EG 201 899 V1.1.1 (2001-05) - Services and Protocols for Advanced Networks (SPAN); Service Provider Access; Modelling Service Provider Access Requirements using an API approach

SIST-V ETSI/EG 201 899 V1.1.1:2003 is the Slovenian identical adoption of ETSI EG 201 899 V1.1.1, an ETSI Guide in the Services and Protocols for Advanced Networks (SPAN) series. It specifies how service provider access requirements can be modelled with an Application Programming Interface (API) approach using Unified Modelling Language (UML). The guide is aimed at service providers and public telecommunications network operators (PTNOs) working with 3rd party applications on fixed public telecommunications networks (PTN), especially public switched telecommunications networks (PSTNs) and Integrated Services Digital Networks (ISDNs).

What does SIST-V ETSI/EG 201 899 V1.1.1:2003 specify?

SIST-V ETSI/EG 201 899 V1.1.1:2003 applies to the first phase of Service Provider Access Requirements (SPAR), mainly for fixed PTNs such as PSTNs and ISDNs. It shows how the phase-1 service provider access requirements can be fulfilled through an API, rather than defining a complete network implementation.

The document is organized into clauses 1 to 6, followed by informative Annex A. Clause 5 gives the API architecture overview, and clause 6 maps individual service provider access requirements to API methods and information flows. The guide also makes clear that it focuses on logical flows and API mapping examples, not on dimensioning, scalability, object management or full error-control design.

The scope also leaves some matters outside the model, such as the way to access PTN-hosted user profile information for functions like incoming call barring and call diversion. Those items are treated as management plane matters, so they are not specified through the API mappings in this guide.

What are the key requirements of SIST-V ETSI/EG 201 899 V1.1.1:2003?

SIST-V ETSI/EG 201 899 V1.1.1:2003 defines an API framework for service provider access, then maps the main service requirements onto API methods in clause 6. The practical purpose is to let a service provider control or observe network behaviour through standardised interface classes, while the PTNO keeps control of the underlying network.

How the API is structured

Clause 5 splits the API into an API Framework and API Services. The framework handles trust and security management, service discovery, integrity management and service subscription; the service part covers call control, messaging, user location, user status and user interaction services.

That matters because an application must first authenticate, discover which service capability features are available, select what it needs and agree the service contract before network functions become usable. In practice, this is the point where the service provider and PTNO establish who may use which capabilities.

Clause 6.1 also distinguishes asynchronous and synchronous methods. Methods ending in Req are request methods and may return Err or Res responses, while methods without a suffix are synchronous and return values implicitly. For implementers, this affects how notifications, responses and state changes are handled in the application.

How calling line identity is handled

Clause 6.2 covers Calling Line Identity (CLI) handling. The guide supports receiving CLI and its related indicators, presenting complete CLI information to the PTN, adding or substituting user-provided CLI, providing CLI for SP-initiated calls, and relaying malicious call identification data unchanged where needed.

In practice, this means the API must carry both the identity itself and the related status information, not just a dialling number. The guide also notes that national regulatory authorities may restrict what CLI information can be delivered or forwarded, so implementations must respect local rules and bilateral agreements.

Clause 6.2.5 is important for Malicious Call Identification (MCID). The service provider must relay received call-specific information without changing what the network needs for tracing, and the PTNO must protect essential MCID data from being overwritten. That protects lawful tracing while still letting the service provider handle the call.

How calls are set up, routed and cleared down

Clause 6.3 covers basic call set-up and clear-down capabilities. The guide maps service requirements for routing calls to or from the service provider, indicating originating or terminating calls, reporting unsuccessful call causes, providing destination and routing information, disconnecting a call in progress and handling call drop-back.

This matters because the service provider is not just receiving notifications - it can also give the PTN routing instructions, request release of a call and receive status information about call outcomes. Several of these functions depend on call event notifications being enabled first.

The same clause also covers user interaction before charging starts, connection to an interactive voice response (IVR) unit, reception of originally dialled digits, and alternate routing to another point of presence (PoP) of the service provider. In practice, that lets one service provider site take over if another site is unreachable, or lets an application interact with the caller before service charging begins.

How supplementary and data services are modelled

Clause 6.4 covers supplementary call and data processing capabilities. It includes interrogation of a network termination point (NTP) for data delivery, overriding incoming call barring, bypassing call diversion, and message waiting indication.

This is useful where the service provider needs to exchange data with a user terminal or control line-related services through the network. The guide shows both call-routing and messaging-based scenarios, and it notes that data protection legislation must be considered when accessing user data.

How charging and traffic are controlled

Clause 6.5 covers changing the charging rate of a call. The service provider can set a call charge plan during call set-up, before routing starts, and that plan can vary by call phase if bilateral agreements allow it.

Clause 6.6 then covers traffic-related capabilities such as event traceability, traffic control and avoidance of cyclical routing. In practice, the API supports load reporting, overload reporting, notification suspension and resumption, and call tracing data used by both service providers and PTNOs.

What terms does SIST-V ETSI/EG 201 899 V1.1.1:2003 define?

• Application Programming Interface (API) - A boundary across which application software uses programming language facilities to invoke services.
• Calling Line Identity (CLI) - The number that uniquely identifies the subscriber line used for a call.
• public telecommunications network (PTN) - A telecommunications network that provides services to the general public.
• public telecommunications network operator (PTNO) - The entity responsible for developing, providing, maintaining and operating services and the corresponding network.
• service provider access - The access facility that lets a service provider reach specific PTN functionality.
• service capability feature - Functionality offered through the standardised OSA interface.
• network API gateway - The API entity that provides access to the public telecommunications network.
• user-network interface (UNI) - The interface between terminal equipment and a network termination point where access protocols apply.

Who uses SIST-V ETSI/EG 201 899 V1.1.1:2003?

SIST-V ETSI/EG 201 899 V1.1.1:2003 is used by service providers, PTNOs and standards engineers who need to design or review service provider access interfaces. It is especially relevant when the parties need to agree call routing, CLI handling, charging behaviour, messaging, load control and tracing across a PTN.

It also helps application developers working on 3rd party service applications, because the guide links business requirements to API methods and information flows. Regulatory and compliance teams can use it to understand where local rules and bilateral agreements affect what can be forwarded, overridden or charged.

Which standards are used with SIST-V ETSI/EG 201 899 V1.1.1:2003?

• ETSI EG 201 722 - Defines service provider access requirements and the related interface concepts used throughout the mappings.
• ETSI EG 201 807 - Sets out network operator requirements for delivering service provider access.
• ISO/IEC JTC 1 Directives, Supplement 2 - Gives API standardization guidance used to frame the API approach.
• ETSI ETS 300 335 - Provides ISUP test context and supports CLI-related signalling references.
• ETSI ETS 300 090 - Describes Calling Line Identification Restriction (CLIR), used for presentation-restricted CLI handling.
• ETSI ETR 322 - Supplies vocabulary for PTN, PTNO, service and subscriber terms.
• ETSI TS 123 127 - Provides the OSA context for service capability features.
• ITU-T Supplement 29 to Series Q. Recommendations - Gives object-oriented service modelling background.
• ITU-T Recommendation Q.65 - Gives the unified functional methodology for characterising services and network capabilities.
• ETSI ETS 300 128 - Describes MCID, which is referenced in the malicious call identification mappings.
• ETSI ES 201 915 - Gives the detailed API specifications and example sequence diagrams that this guide points to.

What does the SIST-V ETSI/EG 201 899 V1.1.1:2003 document contain?

The document contains an API architecture overview, class descriptions and interface class diagrams in clause 5, followed by detailed requirement-to-API mappings in clause 6. It uses figures and parameter tables to show how call notification, CLI handling, routing, user interaction, IVR, messaging, charging, load control and cyclical routing are handled.

The mappings are presented as scenario diagrams with associated method calls and response paths, so they can be used for design and integration work rather than just reading. Annex A is an informative bibliography, and the history section records the document version and publication history.

SLOVENSKI STANDARD
01-november-2003
Storitve in protokoli za napredna omrežja (SPAN) - Dostop ponudnika storitve -
Modeliranje zahtev dostopa ponudnika storitve z uporabo pristopa API
Services and Protocols for Advanced Networks (SPAN) - Service Provider Access -
Modelling Service Provider Access Requirements using an API approach
Ta slovenski standard je istoveten z: EG 201 899 Version 1.1.1
ICS:
33.040.35 Telefonska omrežja Telephone networks
2003-01.Slovenski inštitut za standardizacijo. Razmnoževanje celote ali delov tega standarda ni dovoljeno.

ETSI Guide
Services and Protocols for Advanced Networks (SPAN);
Service Provider Access;
Modelling service provider access
requirements using an API approach

2 ETSI EG 201 899 V1.1.1 (2001-05)
Reference
DEG/SPAN-140504
Keywords
API, architecture, interface, UML
ETSI
650 Route des Lucioles
F-06921 Sophia Antipolis Cedex - FRANCE
Tel.: [phone] Fax: [phone]
Siret N° 348 623 562 00017 - NAF 742 C
Association à but non lucratif enregistrée à la
Sous-Préfecture de Grasse (06) N° 7803/88
Important notice
Individual copies of the present document can be downloaded from:
http://www.etsi.org
The present document may be made available in more than one electronic version or in print. In any case of existing or
perceived difference in contents between such versions, the reference version is the Portable Document Format (PDF).
In case of dispute, the reference shall be the printing on ETSI printers of the PDF version kept on a specific network drive
within ETSI Secretariat.
Users of the present document should be aware that the document may be subject to revision or change of status.
Information on the current status of this and other ETSI documents is available at http://www.etsi.org/tb/status/
If you find errors in the present document, send your comment to:
[e-mail]
Copyright Notification
No part may be reproduced except as authorized by written permission.
The copyright and the foregoing restriction extend to reproduction in all media.
© European Telecommunications Standards Institute 2001.
All rights reserved.
ETSI
3 ETSI EG 201 899 V1.1.1 (2001-05)
Contents
Intellectual property rights .4
Foreword.4
1 Scope.5
2 References.5
3 Definitions and abbreviations.6
3.1 Definitions . 6
3.2 Abbreviations. 7
4 Introduction.8
5 Architecture.8
5.1 API overview . 8
5.2 Description of classes . 10
5.3 Interface class diagrams. 11
6 An API approach to modelling the SPA requirements .11
6.1 Introduction. 11
6.2 Calling party information handling capabilities . 11
6.2.1 Reception of the calling line identity . 11
6.2.2 Presentation of the complete CLI information to the PTN . 12
6.2.3 Addition or substitution of a calling line identity. 13
6.2.4 Provision of CLI information to an SP-initiated call.14
6.2.5 Relaying of the malicious call identification data of a received call . 15
6.3 Basic call set-up and clear-down capabilities. 16
6.3.1 Return speech path connection from the terminating PTN to the calling party . 16
6.3.2 Routing of an originating or incoming call from the PTN to the SP . 17
6.3.3 Indication of an originating or incoming call from the PTN to the SP. 18
6.3.4 Routing of a terminating call from the PTN to the SP. 18
6.3.5 Indication of a terminating call from the PTN to the SP . 19
6.3.6 Reception of an indication of the cause of an unsuccessful call . 20
6.3.7 Provision of information for the destination and routing of a call. 21
6.3.8 Call drop-back . 22
6.3.9 User interaction without service charging of the end user. 23
6.3.10 Reception of the originally dialled digits. 25
6.3.11 Disconnection of a call in progress . 26
6.3.12 Connection of a call to an interactive voice response unit in the PTN . 27
6.3.13 Alternate routing of a call or the indication of a call to another 'point of presence' of the SP . 28
6.4 Supplementary call and data processing capabilities. 29
6.4.1 Interrogation of a network termination point for data delivery. 29
6.4.2 Overriding of the 'incoming call barring' supplementary service. 32
6.4.3 Bypassing of the 'call diversion' supplementary service. 32
6.4.4 Message waiting indication . 33
6.5 Charging-related capabilities . 35
6.5.1 Changes in the charging rate of a call . 35
6.6 Traffic-related capabilities. 36
6.6.1 Event traceability. 36
6.6.2 Traffic control capabilities. 40
6.6.3 Avoidance of the cyclical routing of a call. 43
Annex A (informative): Bibliography.45
History .46
ETSI
4 ETSI EG 201 899 V1.1.1 (2001-05)
Intellectual property rights
IPRs essential or potentially essential to the present document may have been declared to ETSI. The information
pertaining to these essential IPRs, if any, is publicly available for ETSI members and non-members, and can be found
in ETSI SR 000 314: "Intellectual Property Rights (IPRs); Essential, or potentially Essential, IPRs notified to ETSI in
respect of ETSI standards", which is available from the ETSI Secretariat. Latest updates are available on the ETSI Web
server (http://www.etsi.org/ipr).
Pursuant to the ETSI IPR Policy, no investigation, including IPR searches, has been carried out by ETSI. No guarantee
can be given as to the existence of other IPRs not referenced in ETSI SR 000 314 (or the updates on the ETSI Web
server) which are, or may be, or may become, essential to the present document.
Foreword
This ETSI Guide (EG) has been produced by ETSI Technical Committee Services and Protocols for Advanced
Networks (SPAN).
ETSI
5 ETSI EG 201 899 V1.1.1 (2001-05)
1 Scope
The present document applies to the first phase of the Service Provider Access Requirements (SPAR) work, aiming
primarily at fixed PTNs, e.g. public switched telecommunications networks (PSTNs) and Integrated Services Digital
Networks (ISDNs). This first phase is described by two documents, Service Provider Access Requirements; Enhanced
Telephony Services [1] and Network operators requirements for the delivery of service providers access [2]. The
present document shows how these requirements can be fulfilled using an Application Programming Interface (API).
2 References
The following documents contain provisions, which through reference in this text, constitute provisions of the present
document.
• References are either specific (identified by date of publication, edition number, version number, etc.) or
non-specific.
• For a specific reference, subsequent revisions do not apply.
• For a non-specific reference, the latest version applies.
[1] ETSI EG 201 722: "Intelligent Network (IN); Service provider access requirements; Enhanced
telephony services".
[2] ETSI EG 201 807: "Network Aspects (NA); Intelligent Network (IN); Network operators'
requirements for the delivery of service provider access".
[3] ISO/IEC JTC 1 Directives. Supplement 2: Guidelines for API Standardization.
[4] ETSI ETS 300 335: "Integrated Services Digital Network (ISDN); Signalling System No.7; ISDN
User Part (ISUP) version 1; Test specification".
[5] ETSI ETS 300 090 (1992): "Integrated Services Digital Network (ISDN); Calling Line
Identification Restriction (CLIR) supplementary service; Service description".
[6] ETSI ETR 322: "Intelligent network (IN); Vocabulary of terms and abbreviations for CS-1 and
CS-2".
[7] ETSI TS 123 127: "Universal Mobile Telecommunications System (UMTS); Virtual Home
Environment/Open Service Architecture (3GPP TS 23.127 version 3.2.0 Release 1999)".
[8] ITU-T Supplement 29 to Series Q. Recommendations: "Service Modelling Evolution to the Use of
Object Oriented Techniques".
[9] ITU-T Recommendation Q.65 (2000): "The unified functional methodology for the
characterization of services and network capabilities including alternative object-oriented
techniques".
[10] ETSI ETS 300 128 (1992): "Integrated Services Digital Network (ISDN); Malicious Call
Identification (MCID) supplementary service; Service description".
ETSI
6 ETSI EG 201 899 V1.1.1 (2001-05)
3 Definitions and abbreviations
3.1 Definitions
For the purpose of the present document, the following terms and definitions apply:
application: entity in a service provider's domain that provides a service (see definition of service below)
application programming interface: boundary across which application software uses facilities of programming
languages to invoke services (see ISO/IEC JTC 1 Directives)
calling line identity: number that uniquely identifies a subscriber line that is used for a call
end user: see "service user" definition
network API gateway: API entity that provides access to the public telecommunications network
network-network interface: interface at a network node which is used to interconnect the node with another network
node (see EG 201 722)
network-provided calling line identity: that is provided by the originating public telecommunications network to a
call set-up request, if the calling party has not provided any calling line identity or the user-provided calling line identity
has not passed a verification in the network (see ETS 300 335)
presentation-restricted calling line identity: calling line identity that is associated with a marking informing the
terminating local exchange not to display this calling line identity to the called party (see ETS 300 090)
public telecommunications network: telecommunications network which provides telecommunications services to the
general public (see ETR 322)
public telecommunications network operator: entity which is responsible for the development, provisioning and
maintenance of telecommunications services to the general public and for operating the corresponding networks
(see ETR 322)
service: that which is offered by an administration or recognized private operating agency (i.e. a public or private
service provider) to its customers in order to satisfy a telecommunication requirement (see ETR 322)
service capability feature: functionality offered by service capabilities that are accessible via the standardized OSA
interface (see TS 123 127)
service provider: entity which provides services to its service subscribers on a contractual basis and who is responsible
for the services offered. The same organization may act as a public telecommunications network operator and a service
provider (see ETR 322)
service provider access: access facility that enables a service provider to access specific functionality of a public
telecommunications network (see EG 201 722)
service provider access interface: interface between a public telecommunications network and a service provider's
equipment for enabling the service provider to access specific functionality of a public telecommunications network
(see EG 201 722)
service provider access requirement: requirement for access by a service provider to specific functionality of a public
telecommunications network (see EG 201 722)
service subscriber: entity that contracts for services offered by service providers (see ETR 322)
service user: entity external to the network that uses the services offered by the PTNO or SP (see ETR 322)
user-network interface: interface between the terminal equipment and a network termination point at which the access
protocols apply (see EG 201 722)
user-provided calling line identity: network number that has been provided by the calling party (see ETS 300 335)
ETSI
7 ETSI EG 201 899 V1.1.1 (2001-05)
user-provided, not screened calling line identity: network number that has been provided by the calling party and has
been passed forward by the originating public telecommunications network without performing any screening function
for verification purposes (see ETS 300 335)
user-provided, verified and passed calling line identity: network number that has been provided by the calling party
and has been successfully verified in the originating public telecommunications network (see ETS 300 335)
3.2 Abbreviations
For the purposes of the present document, the following abbreviations apply:
3GPP Third Generation Partnership Project
API Application Programming Interface
CAMEL Customized Applications for Mobile Enhanced Logic
CAP CAMEL Application Part
CLI Calling Line Identity
CS-1 Capability Set One
IP Internet Protocol
ISDN Integrated Services Digital Network
ITU-T International Telecommunications Union - Telecommunication standardization sector
IVR Interactive Voice Response
MCID Malicious Call Identification
NNI Network-Network Interface
NRA National Regulatory Authority
NTP Network Termination Point
O-O Object Oriented
OSA Open Service Architecture
PIN Personal Identification Number
PoP Point of Presence
PSTN Public Switched Telephone Network
PTN Public Telecommunications Network
PTNO Public Telecommunications Network Operator
SCF Service Control Function
SMTP Simple Mail Transmission Protocol
SP Service Provider
SPA Service Provider Access
SPAI Service Provider Access Interface
UI User Interaction
URL Universal Resource Locator
UML Unified Modelling Language
UNI User-Network Interface
ETSI
8 ETSI EG 201 899 V1.1.1 (2001-05)
4Introduction
An overview of an API is presented in clause 5, and mappings between the service provider access requirements and the
API methods are presented in clause 6. Sequence diagrams for example services are available in APIs for third party
service applications ES 201 915, and further information on service modelling is available in ITU-T documentation [8]
and [9].
API ES 201 915 implementation issues, which are not covered in the present document, include the following:
• dimensioning and scalability of operations;
• number and efficiency of operations;
• object management;
• error control, including error detection and recovery, needs to be considered for all operations over the API.
Those error control requirements specifically defined in the Service provider access requirements; Enhanced
telephony services [1] have been addressed in the API mapping examples in the present document, but other
error control mechanisms are defined in APIs for third party service applications ES 201 915;
• some of the requirements defined in the Service provider access requirements; Enhanced telephony services [1]
may require access to PTN hosted user profile information, e.g. incoming call barring and call diversion
information. The means of accessing such information is not defined in the present document. This is a
management plane requirement, as shown in [1];
• the call leg methods are not supported in the 3GPP OSA Release '99 [7].
5 Architecture
5.1 API overview
An Application Programming Interface (API) is a means of supporting the service provider access requirements
identified by ETSI. This API is defined using the Unified Modelling Language (UML), which is an Object Oriented
(O-O) technique [8] and [9].
Detailed descriptions of the API can be found in ETSI documentation ES 201 915, but an overview of the API
architecture is shown in figure 1.
Service Provider's Application
API
API
API
Framework
Service
Telecommunications Network
Figure 1: API Architecture
ETSI
9 ETSI EG 201 899 V1.1.1 (2001-05)
Service providers' applications (telecommunications services) and the PTN's service capability features use the API to
utilize each others resources in delivering services to end users. A contractual agreement and physical access interface
must exist between the service provider and network operator for the API to be used, the nature of these is dependent
upon commercial agreements between the parties involved and may be subject to national regulations.
This API, which is based on the ETSI API ES 201 915, contains an API Framework and one or more API Service,
where the API Framework provides control of the service-surround capabilities, and API Service provide control of the
real time network capabilities.
API Framework includes the following:
• Trust and security management, which is used to make initial contact with a framework provider, to authenticate
the application and framework, and to obtain access to other framework interfaces and service capability
features. This includes service capability feature selection and electronically signing service agreements;
• Service Discovery, which is used by the Application to get the identities of the service capability features that are
available from the underlying network. The identities are used during authentication to select the required
service capability features;
• Integrity Management, which is used for load management, fault management, heartbeat management, heartbeat
and Operation, Administration and Maintenance;
• Service Subscription, which is used to manage the contractual agreement between the parties.
API Service include:
• Generic Call Control Service, which is used to enable and disable call notifications, to notify call events, and to
control and manage simple calls consisting of one or two legs;
• INAP-1 Call Control Service (INAP CS-1), which enhances the Generic Call Control Service by allowing more
complex call behaviour to be used;
• CAP Call Control Service, which enhances the Generic Call Control Service to allow more control over charging
for mobile terminals;
• Enhanced Call Control Service, which enhances the Generic Call Control Service with load control, overload
reporting, and call leg control;
• Multi Media Call Control Service, which enhances the Enhanced Call Control Service to allow the control of
specific media channel characteristics;
• Conference Call Control Service, which enhances the Enhanced Call Control Service to allow the creation of
sub-conferences and the ability to move legs between sub-conferences, or merge sub-conferences;
• Multi Media Conference Call Service, which enhances the Conference Call Control and Multi Media Call
Control Services to allow interworking with network signalled conference protocols, manipulation of media, and
the handling of multi media conference policies;
• Generic Messaging Service, which is used to send, store and receive electronic and voice mail;
• User Location Service, which is used to establish the geographic location and status of fixed, mobile and
IP-based telephony users;
• User Location CAMEL Service, which supplements the User Location Service to provide network related
information;
• User Location Emergency Service, which supplements the User Location Service with specialized functionality
to handle emergency calls;
• User Status Service, which is used to request the current status, or the reporting of a change of status, of fixed,
mobile or IP-based telephony users;
ETSI
10 ETSI EG 201 899 V1.1.1 (2001-05)
• GenericUser InteractionService, whichisusedtointeractwithendusers;
• Call User Interaction Service, which is used in conjunction with another service interface (only the Generic Call
Control Service at present) to send information to, or gather information from, an end user.
Detailed example sequence diagrams can be found in APIs for third party service applications ES 201 915, but an
overview is given below.
When an Application starts, the following is a typical outline sequence of events:
1) application initiates client authentication;
2) mutual authentication of client and Framework Interface;
3) application discovers service capability features;
4) application selects required service capability features;
5) mutual signing of service agreement, e.g. by electronic signature.
At this point the agreed network operator service capability features become available to the Application. If the agreed
service capability features include inbound calls, the Application requests call notifications on the appropriate Service
Interface. The service capability features, and any call notifications, remain active until one of the parties chooses to
either terminate the service agreement, or disable the call notifications.
If call notifications have been enabled, the following is a typical outline sequence of events:
1) a call arrives in network and is identified as requiring a service provider;
2) a call object is created. (Other objects may also be created, e.g. Call leg object);
3) A call event notification is sent to the appropriate Application over the API;
4) the Application sends all appropriate information for call treatment, including routing and reporting
requirements;
5) network applies the call treatment and reports outcome, if requested;
6) the Application provides subsequent instructions, if required;
7) the network provides subsequent reports, if and when required.
The above sequence is repeated for each call received and an unlimited number of calls may co-exist.
If the Application initiates calls, the following is a typical outline of events:
1) the Application creates a call object. (Other objects may also be created);
2) the Application sends all appropriate information for call routing and reporting;
3) the network routes the call and provides requested reports;
4) the Application provides subsequent instructions, if required;
5) the network provides subsequent reports, if required.
The above sequence is repeated for each call initiated and an unlimited number of calls may co-exist.
5.2 Description of classes
Framework and service interface classes are defined in the ETSI document: APIs for third party service applications
ES 201 915.
ETSI
11 ETSI EG 201 899 V1.1.1 (2001-05)
5.3 Interface class diagrams
Interface class diagrams are defined in the ETSI document: APIs for third party service applications ES 201 915.
6 An API approach to modelling the SPA requirements
6.1 Introduction
Information flows and API mapping examples for each of the service provider phase 1 requirements, as defined in
Service Provider Access Requirements; Enhanced Telephony Services [1], are presented below. Only the mappings,
parameters and their values that directly relate to the individual requirements are shown in this clause. The complete
definitions of the API methods, parameters and parameter values can be found in the API Specifications ES 201 915.
The API mapping examples may be modified by the appropriate standardization groups and the regulatory
considerations have been included for information only. The network operators' requirements, as defined in Network
operators' requirements for the delivery of service provider access [2], have been included where appropriate. The
screening and charging aspects of the network operators document ([2] clauses 5.5.1 and 5.5.2, respectively) apply to all
the requirements and have not been shown, as these have no direct impact on the information flows between service
providers and network operators.
The circuit related and non-circuit related requirements have been combined to show the logical information flows,
which make no assumptions about the actual implementation. In all cases below, the application is assumed to have
been authenticated.
It should be noted that the API methods fall into two categories, asynchronous and synchronous. Asynchronous
methods, which are identified by the suffix 'Req' (Request), may receive explicit responses identified with the suffixes
'Err' (Error) or 'Res' (Result). Synchronous methods, which have no suffix, may receive implicit responses (return
values) when the methods terminate. These implicit responses are not shown in the API mapping examples.
PTNs will need the ability perform functions not defined in the network operators requirements [2], e.g. to monitor calls
for charging, operational and regulatory reasons, and to perform legal intercept, which are not included in the mapping
examples.
6.2 Calling party information handling capabilities
The implementation of the service provider functional requirements relating to the CLI should be in conformance with
the general European Commission and national regulations and with bilateral agreements where they exist.
6.2.1 Reception of the calling line identity
The service provider needs to receive the Calling Line Identity (CLI) from the PTN with a call or call indication, if the
CLI is available in the PTN in accordance with [1] clause 5.2.1 and [2] clauses 5.2.1 and 5.2.2. If the calling party is
using the services of the service provider and national regulations and/or legislation allows it, this requirement also
applies to a CLI marked as 'presentation-restricted'. All the indicators associated with the CLI need also to be delivered.
Information flows:
SP
PTN
New call (CLI, CLI indicators)
Figure 2: Reception of the calling line identity
ETSI
12 ETSI EG 201 899 V1.1.1 (2001-05)
API mapping example:
Pre-conditions: Call event notifications have been enabled using enableCallNotification () and CLIs are supported in the
underlying PTN.
SP
PTN
callEventNotify (Event Information)
Figure 3: Reception of the calling line identity
The Event Information includes the parameters shown in table 1.
Table 1: Event Information parameters
Destination Address Seetable2.
Originating Address Seetable2.
Original Destination Seetable2.
Address
Redirecting Address Seetable2.
Call Application Alerting mechanism, Network access type, Interworking indicators, Teleservice, Bearer
Information service, Party category, Presentation address (see table 2), Generic information, Additional
address.
Call Event Name Off hook, Address information collected, Address information is analysed, Called party is
busy, Called party is unreachable, No answer from called party, Failure in routing the call.
Regulatory considerations:
National regulatory authorities may impose restrictions on the delivery of some CLI information, therefore the PTNO
requires the ability to prevent the forwarding of restricted information.
6.2.2 Presentation of the complete CLI information to the PTN
The service provider needs the ability to present all the CLI information about the calling party to the PTN in
accordance with [1] clause 5.2.2. This includes the original CLI together with the related status information, as well as
all the relevant indicators of the category of the call.
Information flows:
PTN SP
Route call (CLI, CLI indicators)
Figure 4: Presentation of the complete CLI information to the PTN
ETSI
13 ETSI EG 201 899 V1.1.1 (2001-05)
API mapping example:
Pre-conditions: A call object exists and the service provider has either received a callEventNotify (Event Information),
or is to initiate a call. CLIs are supported in the underlying PTN. If the route () method is to be used, a call leg object
has been created using createCallLeg (), which includes address parameters containing the elements shown in table 2.
PTN SP
routeReq ()
or
route ()
Figure 5: Presentation of the complete CLI information to the PTN
The routeReq () method includes address parameters, which include the elements shown in table 2.
Table 2: Address parameter elements.
Address Plan IP, E.164, E.164 Mobile, URL, SMTP, Undefined.
Address String Address required by the service provider, e.g. CLI, dialled number, destination address.
Name Name associated with Address String.
Address Presentation 'Presentation allowed', 'presentation restricted', or 'presentation address not available' (see
note).
Address Screening 'User provided verified and passed', 'user provided not verified', 'user provided verified and
failed', or 'application/network provided'.
Subaddress String Subaddress.
NOTE: The address parameters may be null if the address is not available.
The address parameters need to contain routing information, including selected network operator, alternate network
operator, and chained transit network selection. Actual network codes may be agreed bilaterally or centralized by
national regulatory authorities (as harmonized by groups of NRAs or the European Commission).
Regulatory considerations:
National regulatory authorities may impose restrictions on the use of CLI information supplied by service providers. It
is assumed that the CLI provided by the PTN will not be changed, although the CLI provided by the service provider
may be used for presentation to the called party. Services such as Malicious Call Identification (MCID) [10] must not
be compromised.
6.2.3 Addition or substitution of a calling line identity
The service provider needs the ability to add or substitute the User Provided CLI to the CLI information of a call when
passing it forward in accordance with [1] clause 5.2.3.
Information flows:
PTN SP
Route call (Additional CLI, CLI indicators)
Figure 6: Addition or substitution of a calling line identity
ETSI
14 ETSI EG 201 899 V1.1.1 (2001-05)
API mapping example:
Pre-conditions: A call object exists and the service provider has either received a callEventNotify (Event Information),
or is to initiate a call. A second CLI can be transported through the underlying PTN and delivered to the service user. If
the route () method is to be used, a call leg object has been created using createCallLeg (), which includes address
parameters containing the elements shown in table 2.
PTN SP
routeReq ()
or
route ()
Figure 7: Addition or substitution of a calling line identity
The routeReq () method includes address parameters, which include the elements shown in table 2.
Regulatory considerations:
National regulatory authorities may impose restrictions on the use of CLI information supplied by service providers. In
general, it is assumed that the CLI provided by the PTN will not be changed, although the CLI provided by the service
provider may be used for presentation to the called party. Services such as Malicious Call Identification (MCID) [10]
must not be compromised.
6.2.4 Provision of CLI information to an SP-initiated call
The service provider needs the ability to provide CLI information to an SP-initiated call in accordance with [1]
clause 5.2.4.
Information flows:
PTN SP
Initiate call (CLI, CLI Indicators)
Figure 8: Provision of CLI information to an SP-initiated call
API mapping example:
Pre-conditions: A call object has been created and CLIs are supported in the underlying network. If the route () method
is to be used, a call leg object has been created using createCallLeg (), which includes address parameters containing the
elements shown in table 2.
SP
PTN
routeReq ()
or
route ()
Figure 9: Provision of CLI information to an SP-initiated call
The routeReq () method includes address parameters, which include the elements shown in table 2.
Regulatory considerations:
National regulatory authorities may impose restrictions on the use of CLI information supplied by service providers.
ETSI
15 ETSI EG 201 899 V1.1.1 (2001-05)
6.2.5 Relaying of the malicious call identification data of a received call
The service provider needs the ability to relay all the received call-specific information unchanged to the terminating
network, that may be used for malicious call tracing in accordance with [1] clause 5.2.5 and [2] clause 5.2.1.
Information flows:
PTN SP
Request malicious call identification data
Malicious call identification
Figure 10: Relaying of the malicious call identification data of a received call
NOTE: The request information flow is only required if the data has not been supplied during the call set-up
phase.
API mapping example:
The malicious call identification data can be supplied during the call set-up phase, as shown below, but there is no
support for requesting this information.
Pre-conditions: A call object exists and the service provider has either received a callEventNotify (Event Information),
or is to initiate a call. The PTNO has mechanisms in place to prevent essential MCID information being overwritten in
the PTN by the SP. If the route () method is to be used, a call leg object has been created using createCallLeg (), which
includes address parameters containing the elements shown in table 2.
SP
PTN
routeReq ()
or
route ()
Figure 11: Relaying of the malicious call identification data of a received call
The routeReq() and createCallLeg () methods include Origination Address, Redirecting Address and Call Application
Information, including a Presentation Address, parameters, which should contain sufficient addressing information for
malicious call identification when combined with information available in the network API gateway. The address
parameters include the elements shown in table 2. The Call Application Information is shown in table 1.
Regulatory considerations:
National regulatory authorities are likely to require the PTN to provide malicious call identification information for a
single call to support the malicious call identification service (MCID) [10]. In cases where a call has been routed
through a service provider's equipment as two separate calls, e.g. incoming and outgoing calls joined together by the
service provider, the malicious call identification information held by the PTN will not associate the two calls together.
ETSI
16 ETSI EG 201 899 V1.1.1 (2001-05)
6.3 Basic call set-up and clear-down capabilities
6.3.1 Return speech path connection from the terminating PTN to the
calling party
The service provider needs the ability to request the through-connection of a backward in-band message path to the
calling party immediately upon the arrival of a confirmation of the call set-up in accordance with [1] clause. 5.3.1.
There must be a mechanism for the support of charging between the PTNO and the service provider.
Information flows:
PTN SP
Call set-up confirmation
Connect backward speech path
Figure 12: Return speech path connection from the terminating PTN to the calling party
API mapping example:
Pre-conditions: A call set-up has been attempted using routeReq (responseRequested) or createCallLeg (),
eventReportReq (eventReportsRequested) and route (). The resources to provide the backward speech path must be
available in the underlying PTN.
PTN SP
routeRes ()
or
eventReportRes ()
createUICall
sendInfoReq ()
Figure 13: Return speech path connection from the terminating PTN to the calling party
The sendInfoReq () includes the parameters shown in table 3.
Table 3: sendInfoReq () parameters
Information Specifies the identity of the information to send to the user.
Variable Information Defines the variable part of the information to send to the user.
Repeat Indicator Defines how many times the information should be sent to the user.
The route call results or event report result include the parameters shown in table 4 and table 10 respectively,.
Table 4: Route call results parameters
Response Requested or These include: Progress, Routing Success, Answer, Refused Busy, No Answer,
Event Reports Requested Disconnect, Redirected, Routing Failure and Call Ended.
Regulatory considerations:
None identified.
ETSI
17 ETSI EG 201 899 V1.1.1 (2001-05)
6.3.2 Routing of an originating or incoming call from the PTN to the SP
On defined criteria, the service provider needs an originating or incoming call from a service provider service user to be
routed from the PTN to the SP, e.g. based on the dialled digits or CLI in accordance with [1] clause 5.3.2 and [2]
clause 5.2.2.
Information flows:
PTN SP
New call (Dialled digits, CLI, CLI indicators)
Route call (Service provider address)
Figure 14: Routing of an originating or incoming call from the PTN to the SP
API mapping example:
Pre-conditions: Call event notifications have been enabled using enableCallNotification ().
PTN SP
callEventNotify (Event Information)
<< Followed by either: >>
routeReq ()
<< or >>
createCallLeg
route ()
Figure 15: Routing of an originating or incoming call from the PTN to the SP
The Event Information includes the parameters shown in table 1.
The routeReq () and createCallLeg () methods include a Target Address parameter, which is set to route the call to the
service provider. The address parameters include the elements shown in table 2.
Regulatory considerations:
National regulatory authorities may impose restrictions on the delivery of some CLI and redirecting address
information, therefore the PTNO requires the ability to prevent the forwarding of restricted information.
ETSI
18 ETSI EG 201 899 V1.1.1 (2001-05)
6.3.3 Indication of an originating or incoming call from the PTN to the SP
On defined criteria, the service provider needs from the PTN the indication of an originating or incoming call from an
service provider service user e.g. based on the dialled digits or CLI in accordance with [1] clause 5.3.3 and [2]
clause 5.2.2.
Information flows:
PTN SP
New call (Dialled digits, CLI, CLI indicators)
Figure 16: Indication of an originating or incoming call from the PTN to the SP
API mapping example:
Pre-conditions: Call event notifications have been enabled using enableCallNotification ().
PTN SP
callEventNotify (Event Information)
Figure 17: Indication of an originating or incoming call from the PTN to the SP
The Event Information includes the parameters shown in table 1.
Regulatory considerations:
National regulatory authorities may impose restrictions on the delivery of some CLI and redirecting address
information, therefore the PTNO requires the ability to prevent the forwarding of restricted information.
6.3.4 Routing of a terminating call from the PTN to the SP
On defined criteria, the service provider needs to receive a terminating call of the service provider's service user, e.g.
based on the dialled digits or CLI. After that, the service provider can take a further action to direct the destination and
routing of the call in accordance with [1] clause 5.3.4 and [2] clause 5.2.2.
Information flows:
SP
PTN
New call (Terminating service user's identity, CLI, CLI indicators)
Route call (Service provider address)
Figure 18: Routing of a terminating call from the PTN to the SP
ETSI
19 ETSI EG 201 899 V1.1.1 (2001-05)
API mapping example:
Pre-conditions: Call event notifications have been enabled using enableCallNotification ().
PTN SP
callEventNotify (Event Information)
<< Followed by either: >>
routeReq ()
<< or >>
createCallLeg ()
route ()
Figure 19: Routing of a terminating call from the PTN to the SP
The Event Information includes the parameters shown in table 1.
The routeReq () and createCallLeg () methods include a Target Address parameter, which is set to route the call to the
service provider. The address parameter includes the elements shown in table 2.
Regulatory considerations:
National regulatory authorities may impose restrictions on the delivery of some CLI and redirecting address
information, therefore the PTNO requires the ability to prevent the forwarding of restricted information.
6.3.5 Indication of a terminating call from the PTN to the SP
On defined criteria, the service provider needs to rec
...