TDC Mobil`s SPWEB SAOP API

Transcription

TDC Mobil SPWEB SOAP API
Author: Thomas Oestergaard
TDC A/S
SPWEB API and Toolbox Guide
SPPORTAL walkthrough
Author: Thomas Østergaard
Document version 2.7
Date: 2012-03-20
Page 1 of 91
Table of Contents
1
About this document ............................................................................................................... 4
1.1
2
Reader Guide .................................................................................................................... 4
SPWEB System Overview ......................................................................................................... 7
2.1
System Components .......................................................................................................... 7
2.2
Concept and Intentions – the short version ........................................................................... 8
2.3
Subscriber ........................................................................................................................ 8
2.3.1
3
4
5
6
SOC ......................................................................................................................... 9
Description of the TDC SPWEB AXIS SOAP Toolbox.................................................................... 11
3.1
Architecture for the AXIS client ......................................................................................... 11
3.2
Technology included with the Toolbox ................................................................................ 11
3.3
The Structure of the Toolbox ............................................................................................. 12
3.4
How to generate the AXIS client interfaces from the WSDL file .............................................. 13
3.5
How to build the application in the Toolbox ......................................................................... 13
3.6
How to configure the Toolbox ............................................................................................ 13
3.7
Implemented methods in the Toolbox ................................................................................ 14
3.8
How to use a method/service from the Toolbox ................................................................... 14
General Request and Reply in SPWEB ...................................................................................... 17
4.1
General update Request ................................................................................................... 17
4.2
General Reply ................................................................................................................. 17
Return Codes and Error description for SP-WEB ........................................................................ 18
5.1
Return Codes .................................................................................................................. 18
5.2
General pre/post conditions .............................................................................................. 19
SPWEB services available for the SOAP API .............................................................................. 24
6.1
SPWEB services ............................................................................................................... 25
6.1.1
test ........................................................................................................................ 25
6.1.2
getPrimaryServiceTypes ............................................................................................ 26
6.1.3
getAdditionalServiceTypes ......................................................................................... 27
6.1.4
getSuspensionTypes ................................................................................................. 28
6.1.5
cancelSubscriber ...................................................................................................... 29
6.1.6
restoreCancelledSubscriber ....................................................................................... 30
6.1.7
changeMsisdn .......................................................................................................... 31
6.1.8
changeICC .............................................................................................................. 32
6.1.9
changePricePlan ....................................................................................................... 33
6.1.10
suspendSubscriber ................................................................................................... 34
6.1.11
removeSuspension ................................................................................................... 35
6.1.12
updateSubscriber ..................................................................................................... 36
6.1.13
searchTransactionHistoryByMsisdn ............................................................................. 37
Page 2 of 91
7
6.1.14
searchServiceTransactionQueueByMsisdn .................................................................... 38
6.1.15
searchServiceTransactionQueueByTime....................................................................... 39
6.1.16
searchSubscriberByMSISDN ...................................................................................... 40
6.1.17
searchSubscriberByICC ............................................................................................. 41
6.1.18
searchSubscriberByIMSI ........................................................................................... 42
6.1.19
searchTransactionBySubscriberAndTransactionId ......................................................... 43
6.1.20
searchSuspensions ................................................................................................... 44
6.1.21
rejectExport ............................................................................................................ 45
6.1.22
releaseImport .......................................................................................................... 46
6.1.23
searchExportRequests............................................................................................... 47
6.1.24
getRejectionCodes .................................................................................................... 48
6.1.25
getReportTypes........................................................................................................ 49
6.1.26
createReportRequest ................................................................................................ 50
6.1.27
searchReportRequestByUserId ................................................................................... 51
6.1.28
getNPFlowTypes ....................................................................................................... 52
6.1.29
listNPFlowStatus ...................................................................................................... 53
6.1.30
importSubscriber_NO................................................................................................ 54
6.1.31
createSubscriber_NO ................................................................................................ 55
6.1.32
confirmExport_NO .................................................................................................... 56
6.1.33
getActivationTypes ................................................................................................... 57
6.1.34
createSubscriber ...................................................................................................... 58
6.1.35
confirmExport .......................................................................................................... 59
6.1.36
searchResourceByMsisdn........................................................................................... 60
6.1.37
updateMsisdnResource .............................................................................................. 61
6.1.38
getMsisdnTransistionStates ....................................................................................... 62
6.1.39
searchExportRequests_NO......................................................................................... 63
6.1.40
updateSIMResourceStatus ......................................................................................... 64
6.1.41
getSimCardDetails .................................................................................................... 65
6.1.42
getICCTransistionStates ............................................................................................ 66
6.1.43
lookupHLRinformation ............................................................................................... 67
AXIS - overview .................................................................................................................... 68
7.1
AXIS architecture ............................................................................................................ 68
7.2
How AXIS convert from JAVA to SOAP XML and back? .......................................................... 69
8
Number Porting..................................................................................................................... 70
9
SPPORTAL ............................................................................................................................ 77
10
SPWEB Reports ............................................................................................................... 82
11
References...................................................................................................................... 91
Page 3 of 91
1 About this document
This document is an introduction guide to SPWEB.
It covers the basic aspects of TDC‟s SPWEB API solution as well as the Tools and technical documentation
made available by TDC to new services providers.
The document is largely technical in nature and the intended audience is developers about to create a
Service Provider solution using the SPWEB web service interface or developers on existing solutions who
are about to take new areas of SPWEB into service for the first time.
Change History
V.
Date
1.0 2006-03-26
1.1 2008-01-28
2.0 2010-12-05
2.1
2011-01-27
2.2
2.3
2.4
2.5
2.6
2.7
2011
2011
2011
Jan – Feb 2012
Feb 2012
March 2012
1.1
Updated to be a guide in how to move from client.jar to axis
Updated to be more of a general guide to SPWEB
Updated to cover new SPWEB services and major update of document incl.
Number Porting.
Added Explanations of SP Mobile Reports drawn through the SPPORTAL and
SPWEB API interfaces.
Review comment changes and general SP PORTAL information added.
General consolidation of new version
Updated chapters 1 to 3.
Minor corrections to various areas
Work Version – Merged into 2.7
Aging, Cancel & Restore and Exclusion group additions and elaboration
Reader Guide
During reading it is recommended that the reader do not consider it as a standalone but also refers to the
other documentation included in the toolbox compilation.
This documentation is as follows:
The generated Java Doc.
o JavaDoc is a tool for generating API documentation in HTML format from doc comments in
source code this tool has been used to create what is referred commonly to as “the Java
Doc” found in the \doc\ dir of the toolbox.
o Format : HTML
o Click here to open it directly.
WSDL file.
o WSDL is an XML format for describing network services as a set of endpoints operating on
messages containing either document-oriented or procedure-oriented information.
o Format: HTML
o Click here to view it
The Toolbox examples and source code (Java)
o The toolbox is a standalone implantation of a client side SPWEB installation with examples.
It is using AXIS and Java but knowledge of either is not mandatory or required to use it.
o Platform : Windows
o Format : ASCII
o Click here for the source and here for the examples
Page 4 of 91
1.2
Terminology
Term
Description
Aging
The state of a number or serial no after a cancelSubscriber. Aging
follow the rules in TDC‟s resource management and will eventually
terminate the resource or return it to the range owner after a
preset period of time.
COREID
Validation system used for the SPPORTAL
CSM
An internal area in TDC‟s billing solution. It is used in number
porting.
DMZ
De-Militarized Zone. The zone between two firewalls. A DMZ is a
security measure.
The Karen system for SPWEB and CoreID for SPPORTAL are located in DMZ.
Donor Operator
The donor is operator which is being imported from in number
porting
The donor sees this as an export of a number to another operator.
KAREN
The security and access servers used by TDC in the SPWEB solution.
Karen-demo is the test system.
Karen-prod is the production system.
OI
TDC online. An internal area used in number porting.
Outcollect
The part of TDC‟s billing system NABS, which sends files containing the service provider‟s CDRs to the service provider system.
The CDRs are in a format called TAP3.09, which is also the CDR
format used for Roaming between Mobile Operators in the world.
NABS
TDC‟s billing system.
Number Porting
Number porting is the process involved in: moving a subscriber
number from the current operator and to new operator (see Number Porting Chapter).
Number Porting in TDC is split into two areas.
Full number porting (from Outside TDCs network)
RESELL number porting (Inside TDCs network)
See the chapter about number porting later in this document for
details
Recipient Operator
The operator which is being (im)ported to in Number Porting
RESELL
RESELL is a number porting flow where the number being ported
is already in TDC‟s system (the donor and recipient is both service
providers or operators at TDC).
Service Provider
A client operator at TDC.
The terms Provider and Operator are used interchangeably in the
text, ex. Service Provider and Operator is the same thing.
Page 5 of 91
Service Providers use SPPORTAL and SPWEB for business to business services and receive CDRs with calls in TAP3.09 format.
SP PORTAL
TDC‟s Portal solution for Service Providers.
It is a WEB portal containing most of the services also found in
the API. But in a thin web client interface.
SPWEB / SPWEB API
The Service Provider API solution at TDC. The term general
SPWEB covers the general solution as well as all services found in
the API.
The specific term SPWEB API covers only the services found in the
API.
The API is the business to business solution offered.
SPWEB Reports
SPWEB offers a number of Reports to its service provider users.
The reports can be requested either through the in SPWEB API or
SP PORTAL and are delivered to either the SPPORTAL or an FTP
server of the SPs choice.
The reports are the same regardless of where they are requested
or delivered to.
Page 6 of 91
2 SPWEB System Overview
The following contains a high-level overview of the SPWEB system.
2.1
System Components
The SPWEB application is a front end for TDC‟s billing system (NABS) providing Service Provider. It supplies Service Providers (SP) with services that allows them to interact with NABS.
The application area is split into two tiers: A front end handling security and user access and a back end
handling the actual API.
These tiers are outlined below:
Front End
Is deployed on a web server capable of handling
Java Server Pages (JSP).
Is located in the DMZ (De-Militarized Zone – the
network domain between two network firewalls).
It acts as the gateway for outside clients (service
providers) to contact the back-end located within
TDC‟s own network.
It uses CoreID for authorization and authentication of the service provider users.
The JSP-server works with the CoreID application
to provide user-control: all users are validated
with
Certificate
UserID
ServiceProviderID
TrustStore
IP address.
The front end server is referred to as:
Karen-prod for production
Karen-demo for test.
Back End
Is a J2EE-application server where the SOAP API
specific software is deployed, currently a Weblogic.
The backend handles all API services.
The SPWEB SOAP API back-end is accessed
through the KAREN front-end authority systems.
The drawing below shows the relationship between the elements in the SPWEB solution and the Service
Provider systems.
Page 7 of 91
Internet
DMZ
F
i
r
e
w
a
l
l
External Service
provider
application
(target: API)
TDC network
KAREN
Webaccess by
certificate
External Service
provider Webbrowser
F
i
r
e
w
a
l
l
SPWEB
Java Enterprise
application
J2EE Server
(Weblogic)
SPPORTAL
COREID
JSP Server
(Tomcat)
Access server
(target: Portal)
It is worth noting that the SPPORTAL looks at the same data as the SPWEB API (thus the arrow from the
portal to SPWEB).
The implication of this is that service providers can use the SPPORTAL to sample control if their SPWEB
API client applications are working correctly as SPWEB and SPPORTAL should always show the same data
and provide the same results.
Note. SPPORTAL is a production only application there is no test version of the SPPORTAL.
2.2
Concept and Intentions – the short version
The SPWEB system provides a large number of services to handle a subscriber‟s lifecycle. In the following
sections this is described along with flows for adding, removing and updating products.
2.3
Subscriber
This diagram shows the states of the subscriber.
cancel
suspend
Suspended
restore from suspension
yes
suspend
more suspensions?
no
create subscriber
Active
import?
no
(normal)
yes
cancel
Cancelled
resume from cancel
export
"ageout" of
resource
automatic import
Reserved
release
Figure 1 Subscriber states
Page 8 of 91
Note: The figure depicts the state of the subscription, not the resource “subscriber number”.
CreateSubscriber is used to create a new subscriber whether a new one use the SPs msisdn and SIM card
resources or a number import from another provider (the activationType parameter used in the service
determines its scope).
Resources prior to activation has the state AA meaning assigned available. They are assigned to an SP
and is available for use by that SP.
Once activated the resources switch to AI meaning assigned in use. They are assigned to an SP and are
in use by a subscriber owned by the SP.
The resources can be suspended (ex. if limits are crossed or the phone stolen). Suspensions are either
soft (usually tied to a usage limit of some sort, the phone can still be used for emergency calls etc) or
hard (usually used if stolen or criminal behaviour, the phone cannot be used).
The services suspendSubscriber and removeSuspension are used for this.
Resources end and be reclaimed through cancelling the subscriber after which they are moved automatically to a cancelled status called aging.
After a period of time the resources age-out and either terminate entirely or are returned to the range
owner. The SP can use services to change the state of resources in the age process to manually reclaim
resources faster or restore the subscription.
The services cancelSubscriber, restoreSubscriber, updateMSISDNresource, updateSimResourceStatus are
used for this.
2.3.1 SOC
State diagrams and transitions for different service types (SOCs and features).
SOC - primary or build-in
cancel
subscriber
create
subscriber
active
SOC - additional
update
subscriber
update
(parameter)
cancel
subscriber
active
update
subscriber
(disable)
create
subscriber
Feature
update
subscriber
update
(parameter)
cancel
subscriber
active
create
subscriber
update
subscriber
(disable)
update
subscriber
(enable)
Inactive
Figure 2 State and transitions for SOCs and features
2.3.2 Exclusion Group
Some features belong to an exclusion group.
Page 9 of 91
A feature can belong to 0-1 exclusion group. When a feature from an exclusion group is chosen
for a subscription another feature belonging to the same exclusion group cannot be chosen for
the same subscription.
They exclude each other.
Example.
GPRSL50E Datagrænse i udlandet 360 kr. ekskl. Moms
GPRSLU Ingen datagrænse i udlandet
LIMIT
LIMIT
GPRSL50E and GPRSLU both belong to the same exclusion group called LIMIT. So if one is use
for a subscriber the other cannot also be added to the subscriber as they belong to the same
exclusion group and only one feature pr. exclusion group can be active at a time for a subscriber.
There is no limit to the number of features, with an exclusion group, that a subscriber can
have, as long as the features as not of the same exclusion group.
The exclusion group a feature belongs to can be view with getPrimaryServiceType and getAdditionalServicType.
The service provider can also request the information in a formatted document from TDC. This
request can be made to the SP implementation team.
Page 10 of 91
3 Description of the TDC SPWEB AXIS SOAP Toolbox
To smooth the path getting from scratch and to a fully working solution TDC provides a fully running
Toolbox, with all services implemented1 to its service providers.
This toolbox is distributed as a compressed file to existing service providers2 or in the form of a CD/DVD
handed out at introduction meetings to new services providers.
The Toolbox includes the AXIS framework, build/compile scripts, JAVA source codes and run script (for
MS Windows) for the implemented services and the important WSDL file as well as documentation.
It is a standalone implementation of a basic client side SPWEB system implementation.
It is fully functional and can be used to access and test any service with real world data using the exact
same certificates/technology that is used towards production3.
It is intended to run on a windows machine.
Please note: The toolkit, while fully functional at a basic level, is an education and test tool. It is not intended as a full client side implementation.
3.1
Architecture for the AXIS client
There is no special architecture for the AXIS client aka the application running at the Service Provider.
AXIS is only used for SOAP transport and to generate the client JAVA interface from the SPWEB WSDL
file. For more information on how AXIS work please refer to section 7 AXIS - overview.
3.2
Technology included with the Toolbox
The Toolbox includes following technologies:
ANT 1.6.5
Apache Ant is a Java-based build tool. In theory, it is kind of like make, without
make's wrinkles.
In the Toolbox ANT is used for generation of JAVA source code from the WSDL file
and for JAVA compilation of the whole project.
AXIS 1.2
Apache Axis is an implementation of the SOAP protocol.
AXIS is used for the SOAP transport mechanism and to generate JAVA classes from
the WSDL file.
JAVA 1.4.2
SUN JAVA provides a complete environment for applications development on desktops and servers.
JAVA is used as programming language in the Toolbox.
Digital Signature
Digital Signature is used in the Toolbox for secure transport of data. To SSL encryption the Toolbox uses a JKS server certificate and for data encryption et use s
PKCS#12 (X509) certificate.
Please note:
Most of the technologies used are older proven versions of which some have passed their end of operational life. It is not required of users that they understand Java or the other technologies to use the toolbox.
1
The services implemented are those found in SPWEB at the end of 2010/start 2011. New services are added to the
toolkit as they are released on a going forward basis.
2
Pr. Request
3
It can be used towards both test & production. It is, however, not intended to be used outside of the implementation
and test phase.
Page 11 of 91
This does not affect the toolkit capabilities or its performance, however, should a service provider choose
to use Java in their installation it is suggested that they use current versions of Java and not 1.4.2.
3.3
The Structure of the Toolbox
The Toolbox CD/DVD is divided into two segments,
An information segment (Docs and Resources) which holds information about the SP API and
service provider specific information
The Toolbox itself containing implemented services, examples and the technologies used by the
Toolbox.
Directory Name
Description of directory contents
Docs
Contains the documentation for the SPWEB API toolkit. The primary documentation is
this word document, the Javadoc describing the SP API implementation and the rules
and procedures document for Number Porting.
Also found here are examples of some of the services results using test information
based on the individual service provider.
And the PowerPoint presentation used as an introduction to new Service Providers.
Also found here is the documentation of the TAP3.09 CDR format 4.
Resources
Contains the MSISDN and ICC which have been assigned to the Service Provider.
SPWEB API toolbox
Contains the Toolbox proper (see next table).
Directory Name
Description of directory contents
ant165
Apache Ant is a Java-based build tool. Used to generate AXIS client interfaces from
WSDL and build the source code in the toolbox
ant-build
Place for the ant scripts.
bin
Place for all “run” tasks for building the project and run the implemented methods.
This is the primary directory that service providers will use as the other directories
with the exception of the WSDL are technology or support directories containing the
technologies used by the toolkit.
build
Temporary place for the class file from the JAVA compilation.
dist
The place for the generated project “distribution place”.
etc
Place for the server SSL certificate and the SP client certificate.
java142
Java Platform, provides a complete development environment for the Toolbox
lib
Place for the AXIS and 3. Party tools.
src
The source code location for the Toolbox examples.
WSDL
Place for the “Web Services Description Language” file – description of the SPWEB
interface (methods call and return arguments).
4
Only relevant for service providers which receive files with CDRs from TDC and who wishes to decode the TAP3.09
files them-selves or know the specific contents of the files.
Page 12 of 91
3.4
How to generate the AXIS client interfaces from the WSDL file
In order to rebuild the axis client interface simply follow the single step below:
1. Generate the JAVA source from WSLD file use the following script in the bin directory:
BUILD_generate_axis_SPWebAPI_STUB_from_WSDL.cmd
3.5
How to build the application in the Toolbox
Every now and then a new WSDL file is releases and it becomes necessary to rebuild the toolkit to bring it
up to date.
There are two simple steps involved in doing this,
1. Remove the .jar file located in the dist dir.
2. Compile the JAVA source files use the following script in the bin directory:
BUILD_SPWebAPI.cmd
Doing this will make the Toolkit compile a fresh .jar file based on the WSDL, which is then placed in the
dist dir.
3.6
How to configure the Toolbox
Before a service can be invoked from one of the run scripts in the bin directory the Toolbox must be configured with the necessary environment parameters.
The Toolbox configuration for this is located in the SetEnv.cmd file in the bin directory. The configuration
is displayed below. All text in shown as “red” must be filled out with proper values.
set SPWEB_SET_ENV="ON"
set
set
set
set
PATH=..\java142\bin
JAVA_HOME=..\java142
ANT_HOME=..\ant165
AXIS_HOME=..\lib
set
set
set
set
set
set
set
CLASSPATH=..\dist\AXIS_SPWEB_MVNONO_client_2.3.0pl2.jar
CLASSPATH=%CLASSPATH%;%AXIS_HOME%\axis.jar
CLASSPATH=%CLASSPATH%;%AXIS_HOME%\commons-discovery-0.2.jar
CLASSPATH=%CLASSPATH%;%AXIS_HOME%\commons-logging-1.0.4.jar
CLASSPATH=%CLASSPATH%;%AXIS_HOME%\jaxrpc.jar
CLASSPATH=%CLASSPATH%;%AXIS_HOME%\saaj.jar
CLASSPATH=%CLASSPATH%;%AXIS_HOME%\wsdl4j-1.5.1.jar
set JAVA_OPTIONS= -classpath %CLASSPATH%
set JAVA_OPTIONS=%JAVA_OPTIONS% -DSpwebUrl=https://karendemo.tdc.dk:443/UnsignedV100
set
set
set
set
JAVA_OPTIONS=%JAVA_OPTIONS%
-Djavax.net.ssl.keyStore=..\etc\karendemoclient.pkcs12
-Djavax.net.ssl.keyStoreType=PKCS12
-Djavax.net.ssl.keyStorePassword=karen
-Djavax.net.ssl.trustStore=..\etc\karendemo.jks
Page 13 of 91
set JAVA_OPTIONS=%JAVA_OPTIONS% -Djavax.net.ssl.trustStoreType=JKS
set JAVA_OPTIONS=%JAVA_OPTIONS% -Djavax.net.ssl.trustStorePassword=karendemo
set JAVA_OPTIONS=%JAVA_OPTIONS% -DServiceProviderId=99
set JAVA_OPTIONS=%JAVA_OPTIONS% -DUserId=799999
Keystore is the service provider‟s certificate and the password for it. The type must be pkcs12
(extension .pfx or .pksc12 on windows platforms.)
Truststore is the „server‟ certificate. This is of the type Java KeyStore and will always be supplied
with the Toolkit with the correct information at the time of creation.
Service Provider ID is the service providers id code, a 2 digit numerical value.‟
User id is the Service Provider id prefixed with 7 and post fixed with 999. The 7 and 999 are
static default values where the 7 means service provider and the 999 is the user number.
After the configuration in setenv.cmd is done, run the configuration with:
SetEnv.cmd
This will make the script set up all environment variables required by the toolbox and it is now possible to
use any of the run scripts found in the bin dir.
Usually text.cmd is run first as a test that everything has been setup correct and that there is a connection through to the server.
3.7
Implemented methods in the Toolbox
The Toolbox includes source code and run scripts for the following services:
Pr. 31.12.2010 The Toolkit supports all services listed in section 6 of this document.
New services after 31.12.2010 will be updated on a regular basis but there may be a time interval between their availability and the creating of an example in the Toolbox.
For these services refer to the WSDL interface file for a description of them.
3.8
How to use a method/service from the Toolbox
Preconditions:
Your certificate is valid and active in the TDC authentication system “KAREN”.
The project is generated and build successful.
The SetEnv.cmd file in directory bin is configured with the right SPID and USER – provided from
TDC.
You run the SetEnv.cmd script file.
You run the scripts on a computer with Microsoft Windows.
If you don‟t run the SetEnv.cmd script, and you for example try to invoke the SearchSubscriberByMSISDN service - you got this ERROR:
Page 14 of 91
******************************************************
*
*
* Environment ERROR: "No environment set"
*
*
*
* Please run the "SetEnv.cmd" environment file before *
*
*
* the SPWEB example: SearchSubscriberByMSISDN
*
*
******************************************************
If you want to invoke the SearchSubscriberByMSISDN service run the script SearchSubscriberByMSISDN.cmd in the bin directory.
Before you can run the script the MSISDN number for the subscriber must be set in the script file, se
example below.
SearchSubscriberByMSISDN.cmd
@SETLOCAL
SET SPWEB_EXAMPLE=SearchSubscriberByMSISDN
@CLS
IF "%SPWEB_SET_ENV%" == "" (
GOTO RunSetEnv
) ELSE (
GOTO RunSPWEBExample
)
:RunSPWEBExample
SET JAVA_OPTIONS=%JAVA_OPTIONS% -DMSISDN=94540529
"%JAVA_HOME%\bin\java" %JAVA_OPTIONS% dk.tdc.spweb.%SPWEB_EXAMPLE%
@GOTO EndRun
:RunSetEnv
@call ERROR.cmd %SPWEB_EXAMPLE%
@GOTO EndRun
:EndRun
@ENDLOCAL
A precondition to success is that the MSIDN number exists in the system and has been assigned to your
service provider.
The first MSISDN found in the resources/msisdn.txt file will usually have been used as a test MSISDN
when setting up your service provider profile in TDCs system.
You can therefore enter that number in the example and use it for your first search.
Page 15 of 91
If the services have been invoked successfully, you will receive and answer along these lines:
yahooooooo
SearchSubscriberByMSISDN answer ***>
ActivationDateTime
null
PortingIndicator
N
PrimaryActivationDateTime null
SubscriberICC
89450100030212361106
SubscriberIMSI
238013810344984
SubscriberId
200181273 94540529
SubscriberMSISDN
94540529
SubscriberNpStatus
V
SubscriberNpStatusDate
null
SubscriberStatus
A
ServiceTypeId [0]: GPOST712
FetureTypeId
[0]: GPVNR
FetureTypeId
[1]: GPCF67
FetureTypeId
[2]: GPSMST
FetureTypeId
[3]: GPOAN
FetureTypeId
[4]: GPCF61
FetureTypeId
[5]: GPCF62
FetureTypeId
[6]: GSPPRI
FetureTypeId
[7]: GPCF21
ContextString
DataStoreStatus
FieldIdentifier
MessageTime
ReasonCode
ReturnCode
SeverityCode
:
:
:
:
:
:
:
Execution successful
1
null
null
0
0
I
Page 16 of 91
4 General Request and Reply in SPWEB
4.1
General update Request
These fields will always be present in the input area.
Name
Definition
Reference
originServerTime
DateTime
Control field for last known state.
userId
String
Identification of the user. This field will implicit be
filled based upon information from GetAccess
serviceProviderId
String
Identification of the serviceProvider. This field will
implicit be filled based upon information from GetAccess or KAREN
4.2
General Reply
These fields will always be present in the output area.
Name
Definition
Reference
severityCode
String
A code indicating the severity of exception described by the return/reason code combination.
Permitted values are:
“I” = informational, “W” = warning, “E” = error.
returnCode
Num
A five-digit numeric field used to return a standardized code indicating the type of failure or success
encountered during the operation execution. Valid
values are defined in pre/post conditions.
reasonCode
Num
A five-digit numeric field used to provide more explanation about why the failure or success notified
by the return code has occurred. Reason codes
must be greater than or equal to zero. Reason code
values may be specified or unspecified.
fieldIdentifier
String
Replacement string used in contextString. Used by
client to replace with other values.
originServerId
The server identifier of the component that originated the return/reason code combination. Each
installed copy of a component (termed a component server) is expected to identify itself using a
unique value – its “server id”.
originServerTime
DateTime
Control time for last known state.
messageTime
DateTime
Time this message was build. It may correspond to
internal logging
dataStoreStatus
String
1=Unchanged,2=Rolled back,3=Changed,4=Data
Integrity compromised
contextString
Intended for additional data about a failure encountered in an operation execution, which can then be
incorporated into end-user messages.
Page 17 of 91
5 Return Codes and Error description for SP-WEB
5.1
Return Codes
RetrieveReturnenObsoleteData
22
DeleteResultedInLogicalDelete
20
OptionalFieldMissing
10
SuccessfullCompletion
0
OperationNotAvailable
-1
NoPreconditionMet
-2
IdentifierNotFound
-10
IdentifierMissing
-11
IdentifierValidationFailed
-12
MandatoryFieldMissing
-20
MandatoryFieldValidationFailed
-21
OptionalFieldValidationFailed
-30
DataFormatError
-50
NumericOperationFailure
-51
NumberOfParametersAreNotCorrect
-55
PersistentStorageFailure
-60
OperatingEnvironmentFailure
-61
UnexpectedException
-999
DataHasChanged
-1001
RequiredDataNotFound
-1010
InvalidState
-1100
Page 18 of 91
5.2
General pre/post conditions
Note that ReturnCode numeric value is found in previous chapter
Description
Return Code example
System related dependant component
failed with an unhandled error code failure
ReturnCode : UnexpectedException
ReasonCode : identifies the underlying operation that
failed
Context : System returned an unexpected error {component code}
System related dependant component
Is not available
ReturnCode : OperationEnvironmentFailure
ReasonCode : identifies the underlying operation that
failed
Context : System component not available
Logical date is before today‟s date
ReasonCode : 3
Context : Logical Date is before today‟s date
Internal error
ReasonCode : 100
Context : Internal error
Cache error
ReasonCode : 200
Context : Internal caching error for service provider
{0}
Internal caching error
ReasonCode : 300
Context : Malformed service/feature identifier on index
key {0}
Unexpected internal
ReturnCode : UnexpectedException
ReasonCode : 3
Context : System returned an unexpected error code :
{0}
Description
Return Code example
Service provider identification is missing
in input
ReturnCode : IdentifierMissing
ReasonCode : 1
Context : ServiceProviderId missing
UserId is missing in input
ReasonCode : 2
Context : UserId missing
SubscriberId is missing in input
ReasonCode : 3
Context : SubscriberId missing
MSISDN is missing in input
ReasonCode : 4
Context : MSISDN missing
ServiceType is missing in input
ReasonCode : 5
Context : ServiceType missing
IMSI is missing in input
ReasonCode : 6
Page 19 of 91
Context : IMSI missing
ICC is missing in input
ReasonCode : 7
Context : ICC missing
SuspensionType is missing in input
ReasonCode : 8
Context : SuspensionType missing
SubscriberId is not valid
ReturnCode : IdentifierValidationFailed
ReasonCode : 1
Context : {} is not a valid SubscriberId
MSISDN is not valid
ReasonCode : 2
Context : {} is not a valid MSISDN
ICC is not valid
ReasonCode : 3
Context : {} is not a valid ICC
ServiceType is not valid
ReasonCode : 4
Context : {} is not a valid service type
ServiceFeatureType is not valid
ReasonCode : 5
Context : {} is not a valid service feature type
ServiceFeatureParameter is not valid
ReasonCode : 6
Context : {} is not a valid service feature parameter
IMSI is not valid
ReasonCode : 7
Context : {} is not a valid IMSI
ServiceProviderId is not valid
ReasonCode : 8
Context : {} is not a valid ServiceProviderId
Same MSISDN is more than once in input
ReasonCode : 20
Context : Duplicate msisdn {} found in input
Same ICC is more than once in input
ReasonCode : 21
Context : Duplicate icc {} found in input
Same service type is more than once in
input
ReasonCode : 22
Context : Duplicate service type {} found in input
Same servicefeaturetype is more than
once in input
ReasonCode : 23
Context : Duplicate servicefeaturetype {} found in
input
Same servicefeatureparameter is more
than once in input
ReasonCode : 24
Context : Duplicate servicefeatureparameter {} found
in input
Primary service type must not be
changed
ReasonCode : 25
Context : Primary service type must not be changed
Page 20 of 91
Not possible to change service type
ReasonCode : 26
Context : Not possible to change service type from {0}
to {1}
Suspensiontype already active
ReasonCode : 30
Context : Suspensiontype {0} already active
MSISDN is not valid when used with this
feature/service
ReasonCode : 200
Context : {0} msisdn {1} is not valid with this feature
ICC is not valid when used with this feature/service
ReasonCode : 201
Context : {0} icc {1} is not valid with this feature
MSISDN and ICC is not valid together
ReasonCode : 300
Context : msisdn {0} and icc {1} is not valid together
Description
Return Code example
Nothing in request
ReturnCode : MandatoryFieldMissing
ReasonCode : 1
Context : Required fields missing
StartTime missing
ReasonCode : 2
Context : StartTime missing
Mandatory (required) service missing
ReasonCode : 3
Context : {0} mandatory service missing
Mandatory (required) feature missing
ReasonCode : 4
Context : {0} mandatory servicefeature missing
Mandatory (required) parameter missing
ReasonCode : 5
Context : {0} mandatory parameter missing
Mandatory (required) parameter value
missing
ReasonCode : 6
Context : {0} mandatory parameter value missing
Mandatory (required) voucher missing
ReasonCode : 7
Context : mandatory voucher missing
Service type in same exclusion group in
input
ReturnCode : MandatoryFieldValidationFailed
ReasonCode : 1
Context : {0} services within same exclusion group
are mutual exclude
Features in same exclusion group in input
ReasonCode : 2
Context : {0} features within same exclusion group
are mutual exclude
Voucher is changed
ReasonCode : 3
Context : mandatory voucher missing
Description
Return Code example
ServiceProviderId is not registered as a
ReturnCode : IdentifierNotFound
Page 21 of 91
legal user of this system
ReasonCode : 1
Context : ServiceProvider {0} is not found
SubscriberId is not found or does not
belong to provider
ReasonCode : 2
Context : SubscriberId {0} is not found
MSISDN is not found or does not belong
to provider
ReasonCode : 3
Context : msisdn {0} is not found
ServiceType not found
ReasonCode : 4
Context : servicetype {0} is not found
ICC not found or does not belong to provider
ReasonCode : 5
Context : icc {0} is not found
Subscriber is not found or does not belong to provider
ReasonCode : 6
Context : subscriber {0} not found
Suspentiontype not found
ReasonCode : 7
Context : suspensiontype {0} not found
IMSI not found or does not belong to
provider
ReasonCode : 8
Context : imsi {0} not found
Description
Return Code example
NumberGroup reference not found
ReturnCode : RequiredDataNotFound
ReasonCode : 1
Context : Referencedata is missing
NumberLocation not found
ReasonCode : 2
Context : Referencedata is missing
Primary servicetype(s) not found
ReasonCode : 3
Context : No related servicetype found
Suspensiontypes not found
ReasonCode : 4
Context : No related suspensiontype found
Expected application data not found
May caused by invalid data
ReasonCode : 100-199
Context : Invalid subscriber data {0}
Switch data not found
ReasonCode : 30
Context : No switch data found
Description
Return Code example
SubscriberId is in an invalid state for
requested operation
ReturnCode : InvalidState
ReasonCode : 1
Context : Subscriber {0} is not in a valid state
MSISDN is in an invalid state for requested operation
ReasonCode : 2
Context : msisdn {0} is not in a valid state
ICC is in an invalid state for requested
Page 22 of 91
operation
ReasonCode : 3
Context : icc {0} is not in a valid state
Description
Return Code example
DataHasChanged since last request
(originServerTime – reply)
ReturnCode : DataHasChanged
ReasonCode : 1
Context : subscriber {0} has changed since last request
Commitment failed. Caused by a failure
in a tuxedo service.
Normal this means nothing
ReturnCode : RetrieveReturnedObsoleteData
ReasonCode : 1
Context : Operation did not complete, search subscriber and validate data.
Page 23 of 91
6 SPWEB services available for the SOAP API
Below is the Toolkit‟s list of supported services in the SPWEB API (per 1.1.2011). At the time of writing all
services found in the API are supported in the toolkit with examples and code.
The services can be divided into three main areas
Status changing services, which creates, changes or reacts to events
Information services, which supplies information about the service providers setup and describes
input and field information required in order to use the status changing services.
Miscellaneous services, which setup the toolkit or test connections towards Karen/Karen-demo.
Status changing services
Information services
CancelSubscriber
GetActivationTypes
ChangeICC
GetAdditionalServiceTypes
ChangeMSISDN
GetNPFlowTypes
ChangePricePlan
GetPrimaryServiceTypes
ConfirmExport
CreateReportRequest
SetEnv (not an API service)
Test
GetRejectionCodes
GetreportTypes
CreateSubscriber
&
CreateSubscriber Dobbelt kort
RejectExport
GetSuspensionTypes
ReleaseImport
SearchExportRequests
RemoveSuspension
SearchReportRequestsByUserId
RestoreCancelledSubscriber
SuspendSubscriber
Miscellaneous
ListNPFlowStatus
SearchResourceByMsisdn
SearchServiceTransactionQueuebyMSISDN
UpdateMsisdnResource
SearchServiceTransactionQueuebyTime
UpdateSIMResourceStatus
SearchSubscriberByICC
UpdateSubscriberAddService
SearchSubscriberByIMSI
UpdateSusbcriberRemoveService
SearchSubscriberByMSISDN
SearchSuspensions
SearchTransactionBySubscriberAnd
TransactionId
SearchTransactionHistoryByMsisdn
Page 24 of 91
6.1
SPWEB services
This section contains the description of the services together with their pre and post conditions.
The format is the same used in the java doc and the request / reply objects can be referenced directly
from this document to the java doc.
Note. Services with the post-fix _NO should not be implemented by service providers. They are MVNO
services and only listed here for explanation reasons.
6.1.1 test
public java.lang.String test(java.lang.String msg)
throws java.rmi.RemoteException
Test method. Return the same string as given in input. Used to test availability of the API.
Parameters:
msg - String to be returned
Returns:
String given as input.
Throws:
java.rmi.RemoteException - Is thrown by the EJB container if some kind of communication
failure occurs.
Page 25 of 91
6.1.2 getPrimaryServiceTypes
public GetPrimaryServiceTypesReplyInfo getPrimaryServiceTypes
(GetPrimaryServiceTypesRequestInfo req)
Usage: This method is used to retrieve all possible primary services for a given service provider. The data returned is reference data.
A primary service is the main subscription type(s) available to an SP.
A subscriber from the SP must always have exactly one primary service associated with it,
which is selected from the list of available primary services show by this service.
Pre condition
Post condition
A service provider identified by code exists AND has related non expired primary services (price plan(s)).
SuccessfulCompletion
A service provider identified by code exists AND has no related non
expired primary services (price plan(s)).
Parameters:
req - GetPrimaryServiceTypesRequestInfo
Returns:
GetPrimaryServiceTypesReplyInfo
Throws:
failure occurs.
Page 26 of 91
6.1.3 getAdditionalServiceTypes
public GetAdditionalServiceTypesReplyInfo getAdditionalServiceTypes
(GetAdditionalServiceTypesRequestInfo req)
Usage: This method is used to retrieve additional services (socs) for a given service provider
and chosen primary service (price plan soc). The data returned is reference data.
An additional service is a non-mandatory additional service which adds or blocks functionality to the subscriber.
A subscriber from the SP can have from zero to many additional services associated. Those
available to the SP to choose from are shown by this service.
Note. Some services belong to an exclusion group. You can only select one service belonging to the same exclusion group.
Pre condition
Post condition
A service provider identified by code exists AND has the related non
expired supplementary services (socs) AND has related non expired
additions socs.
expired primary services (price plan(s)).
Parameters:
req - GetAdditionalServiceTypesRequestInfo
Returns:
GetAdditionalServiceTypesReplyInfo
Throws:
failure occurs.
Page 27 of 91
6.1.4 getSuspensionTypes
public GetSuspensionTypesReplyInfo getSuspensionTypes
(GetSuspensionTypesRequestInfo req)
Usage: This method is used to retrieve suspension types for a given service provider. The
suspension code is used as a parameter for both suspension and removal of the suspension
(restore).
Adding a suspension is done through the service suspendSubscriber
Removing a suspension is done through the service removeSuspension
This service delivers the legal values to be used as input to the suspend/remove services.
Pre condition
Post condition
expired suspensiontypes.
expired suspensiontypes.
Parameters:
req - GetSuspensionTypesRequestInfo
Returns:
GetSuspensionTypesReplyInfo
Throws:
failure occurs.
Page 28 of 91
6.1.5 cancelSubscriber
public CancelSubscriberReplyInfo cancelSubscriber
(CancelSubscriberRequestInfo req)
Usage: Used for cancelling subscription. This implies expiration of the subscribers services
and removal of the subscriber from the transmission network. Resources change states according to the general rules for Resource Management.
The subscriber changes state from AI (assigned in use) to AG (aging).
Unless one of the services restoreCancelledSusbcriber, UpdateMsisdnResource or UpdateMsisdnResource are used to change the state of the aging resources, they will follow the
rules for resource management (termination or return to range owner after an aging period).
Pre condition
Post condition
A subscriber identified by subscriberId exists AND does not
have status Cancelled, Exported or Reserved AND belongs to
SP identified by ServiceProviderId. Moreover the requestedCancelDate is not in the future.
A subscriber identified by subscriberId does not exist or does
not belongs to the service provider identified by serviceProviderId.
IdentifierNotFound
A subscriber identified by subscriberId exists AND have status
InvalidState
free, cancelled, exported or other where you can‟t cancel.
Resource is not valid in this context. Voice number used as
voicemail or sim card used as virtual sim card
Parameters:
req - CancelSubscriberRequestInfo
Returns:
CancelSubscriberReplyInfo
Throws:
failure occurs.
Page 29 of 91
6.1.6 restoreCancelledSubscriber
public RestoreCancelledSubscriberReplyInfo restoreCancelledSubscriber
(RestoreCancelledSubscriberRequestInfo req)
Usage: Used to move the subscription from a cancel state to an active state, i.e. it is creating
a subscriber based on data from a cancelled subscription. This implies re-pairing of resources and activation of the subscribers selected services in the transmission network. Resources change states according to the general rules for Resource Management.
This service will restore the subscriber to the exact same state it had before being cancelled
including all features and services. The resources will move from AG (aging) to AI (assigned in use)
Pre condition
Post condition
A subscriber identified by subscriberId exists AND has status Cancelled AND belongs to SP identified by serviceProviderId. Moreover the SuccessfulCompletion
resources is in their retention period.
A subscriber identified by subscriberId does not exist or does not belongs to the service provider identified by serviceProviderId.
IdentifierNotFound
A subscriber identified by subscriberId exists AND has status Cancelled AND belongs to SP identified by serviceProviderId AND the resources is no longer available.
InvalidState
A subscriber identified by subscriberId exists AND does not have
status cancelled.
InvalidState
Parameters:
req - RestoreCancelledSubscriberRequestInfo
Returns:
RestoreCancelledSubscriberReplyInfo
Throws:
failure occurs.
Page 30 of 91
6.1.7 changeMsisdn
public ChangeMSISDNReplyInfo changeMsisdn
(ChangeMSISDNRequestInfo req)
Usage: This method is used to change the primary MSISDN number on a subscription to
another available number.
Pre condition
Post condition
A subscriber identified by subscriberId exists AND beThe primary number of the subscriber
longs to a service provider identified by serviceProviderId
is changed to msisdn SuccessfulAND does have status active AND resource identified by
Completion
msisdn exists AND is available.
A subscriber identified by subscriberId does not exist or
does not belongs to the service provider identified by
serviceProviderId.
IdentifierNotFound
Resource identified by msisdn does not exist or does not
belong to the service provider identified by serviceProviderId.
IdentifierNotFound
A subscriber identified by subscriberId exists AND has
status cancelled or suspended.
InvalidState
Parameters:
req - ChangeMSISDNRequestInfo
Returns:
ChangeMSISDNReplyInfo
Throws:
failure occurs.
Page 31 of 91
6.1.8 changeICC
public ChangeICCReplyInfo changeICC
(ChangeICCRequestInfo req)
Usage: The method change the pairing of the primary MSISDN and ICC-number from current ICC to a new primary ICC number.
Pre condition
Post condition
A subscriber identified by subscriberId exists AND beThe primary icc number of the sublongs to a service provider identified by serviceProviderId
scriber is changed to icc SuccessfulAND does have status active AND resource identified by
Completion
icc exists AND is available.
A subscriber identified by subscriberId does not exist or
does not belongs to the service provider identified by
serviceProviderId.
IdentifierNotFound
Resource identified by icc does not exist or does not
belong to the service provider identified by serviceProviderId.
IdentifierNotFound
A subscriber identified by subscriberId exists AND has
status cancelled or suspended.
InvalidState
Parameters:
req - ChangeICCRequestInfo
Returns:
ChangeICCReplyInfo
Throws:
failure occurs.
Page 32 of 91
6.1.9 changePricePlan
public ChangePricePlanReplyInfo changePricePlan
(ChangePricePlanRequestInfo req)
Usage : Used when changing primary service type of the subscription. This means activating new primary service and deactivating old primary service and all related services not related to the new service.
The changes effects the configuration of the subscriber in the transmission network. Resources change states according to the general rules for Resource Management.
Important note! This service is the only service which is valid to use when changing the
primary service type (one of those shown by the service: getPrimaryServiceType). Do not
use updateSubscriber to change the primary service type.
Pre condition
Post condition
A service provider identified by serviceProviderId exists AND
all resources specified by feature parameters belong to the
specified service provider AND are available AND all required
SOCs and features are specified AND are not mutual exclusive. Subscriber identified by subscriberId exists AND is in
active or suspended state.
Resource does not exist or don‟t belong to actual SP.
IdentifierNotFound
Resource is in use, exported or in retention period or others
where you cannot use it.
InvalidState
Resource is not valid in this context.Sample Voice number
used as voicemail or sim card used as virtual sim card
Parameters:
req - ChangePricePlanRequestInfo
Returns:
ChangePricePlanReplyInfo
Throws:
failure occurs.
Page 33 of 91
6.1.10
suspendSubscriber
public SuspendSubscriberReplyInfo suspendSubscriber
(SuspendSubscriberRequestInfo req)
Usage: Used for suspending the subscriber. The suspension inhibits the subscribers use of
the transmission network.
The valid values for suspension types used by this service as input can be found using the
service getSuspensionTypes.
Pre condition
A subscriber identified by subscriberId exists AND does have status
Active AND belongs to SP identified by serviceProviderId.
Post condition
A subscriber identified by subscriberId exists Suspended AND belongs
to SP identified by serviceProviderId AND does not have an active
suspension identified suspensionCode.
IdentifierNotFound
A subscriber identified by subscriberId exists AND have status <>
Active or Suspended.
InvalidState
Parameters:
req - SuspendSubscriberRequestInfo
Returns:
SuspendSubscriberReplyInfo
Throws:
failure occurs.
Page 34 of 91
6.1.11
removeSuspension
public RemoveSuspensionReplyInfo removeSuspension
(RemoveSuspensionRequestInfo req)
Usage: Used for removal of a specific suspension code from the subscriber.
The valid values for suspension types used by this service as input can be found using the
service getSuspensionTypes.
Pre condition
A subscriber identified by subscriberId exists AND
does have status Suspended AND belong to the SP
and has an active suspension identified by suspensionTypeId active
Post condition
The subscriber has the suspension code
identified by suspensionTypeId expired
A subscriber identified by subscriberId exists Suspended AND belongs to SP identified by serviceProviderId AND does not have an active suspension
identified suspensionCode.
IdentifierNotFound
A subscriber identified by subscriberId exists AND
have status <> Suspended.
InvalidState
Parameters:
req - RemoveSuspensionRequestInfo
Returns:
RemoveSuspensionReplyInfo
Throws:
failure occurs.
Page 35 of 91
6.1.12
updateSubscriber
public UpdateSubscriberReplyInfo updateSubscriber
(UpdateSubscriberRequestInfo req)
Usage: Used when changing or adding subscription features or parameters. This means activating and deactivating of parts of the primary service and change of parameters on additional services. The changes effects the configuration of the subscriber in the transmission
network. Resources change states according to the general rules for Resource Management.
Note. This service is not applicable if you want to change the actual primary service itself (an example of a primary service type is GPOSTxx, where xx is your subscriber number) as this involves a
fundamental change in the subscription (for example from a postpaid priceplan to a prepaid or to a
data priceplan).
Changes to the primary service type can only be done through changePricePlan. UpdateSubscriber
is used for all other changes to features and parameters to existing subscribers that the SP owns.
Pre condition
Post condition
SOCs and features are specified AND are not mutual exclusive.
IdentifierNotFound
Resource is in use, exported or in retentionperiod or others
where you cannot use it in creation.
InvalidState
Resource is not valid in this context. Voice number used as
voicemail or sim card used as virtual sim card
Parameters:
req - UpdateSubscriberReplyInfo
Returns:
UpdateSubscriberReplyInfo
Throws:
failure occurs.
Page 36 of 91
6.1.13
searchTransactionHistoryByMsisdn
public SearchTransactionHistoryByMsisdnReplyInfo searchTransactionHistoryByMsisdn(SearchTransactionHistoryByMsisdnRequestInfo req)
Method searchTransactionHistoryByMsisdn. Provides a full transaction history using the MSISDN
as input.
Parameters:
req - SearchTransactionHistoryByMsisdnRequestInfo
Returns:
SearchTransactionHistoryByMsisdnReplyInfo
Throws:
failure occurs.
Page 37 of 91
6.1.14
searchServiceTransactionQueueByMsisdn
public SearchServiceTransactionQueueByMsisdnReplyInfo searchServiceTransactionQueueByMsisdn
(SearchServiceTransactionQueueByMsisdnRequestInfo req)
Usage: The method retrieves provisioning transactions in any state for a given msisdn. This
includes information about the transmission network completion time.
Pre condition
Post condition
A subscriber identified by msisdn exists AND has related transactions
A subscriber identified by msisdn exists AND has no related transactions
MSISDN does not exists or does not belongs to SP
IdentifierNotFound
Parameters:
req - SearchServiceTransactionQueueByMsisdnRequestInfo
Returns:
SearchServiceTransactionQueueByMsisdnReplyInfo
Throws:
failure occurs.
Page 38 of 91
6.1.15
searchServiceTransactionQueueByTime
public SearchServiceTransactionQueueByTimeReplyInfo searchServiceTransactionQueueByTime(SearchServiceTransactionQueueByTimeRequestInfo req)
Usage: The method retrieves provisioning transactions in any state after a give datetime.
This includes information about the transmission network completion time.
Pre condition
Post condition
A subscriber identified by msisdn exists AND has related transactions
A subscriber identified by msisdn exists AND has no related transactions
IdentifierNotFound
Parameters:
req - SearchServiceTransactionQueueByTimeRequestInfo
Returns:
SearchServiceTransactionQueueByTimeReplyInfo
Throws:
failure occurs.
Page 39 of 91
6.1.16
searchSubscriberByMSISDN
public SearchSubscriberByMSISDNReplyInfo searchSubscriberByMSISDN
(SearchSubscriberByMSISDNRequestInfo req)
Usage: The method retrieves the current subscriber state. This includes information about
subscriber type and additional services.
Pre condition
Post condition
MSISDN exists and belongs to SP identified by sp-id and is assigned to
a subscriber.
MSISDN exists and belongs to SP identified by sp-id and was assigned
to a subscriber and is in the defined retention period.
IdentifierNotFound
Parameters:
req - SearchSubscriberByMSISDNRequestInfo
Returns:
SearchSubscriberByMSISDNReplyInfo
Throws:
failure occurs.
Page 40 of 91
6.1.17
searchSubscriberByICC
public SearchSubscriberByICCReplyInfo searchSubscriberByICC
(SearchSubscriberByICCRequestInfo req)
Pre condition
ICC exists and belongs to SP identified by sp-id and is assigned to a
subscriber.
Post condition
ICC exists and belongs to SP identified by sp-id and was assigned to a
subscriber and is in the defined retention period.
ICC does not exists or does not belongs to SP
IdentifierNotFound
Parameters:
req - SearchSubscriberByICCRequestInfo
Returns:
SearchSubscriberByICCReplyInfo
Throws:
failure occurs.
Page 41 of 91
6.1.18
searchSubscriberByIMSI
public SearchSubscriberByIMSIReplyInfo searchSubscriberByIMSI
(SearchSubscriberByIMSIRequestInfo req)
Pre condition
Post condition
IMSI exists and belongs to SP identified by sp-id and is assigned to a
subscriber.
IMSI exists and belongs to SP identified by sp-id and was assigned to
a subscriber and is in the defined retention period.
IMSI does not exists or does not belongs to SP
IdentifierNotFound
Parameters:
req - SearchSubscriberByIMSIRequestInfo
Returns:
SearchSubscriberByIMSIReplyInfo
Throws:
failure occurs.
Page 42 of 91
6.1.19
searchTransactionBySubscriberAndTransactionId
public SearchTransactionBySubscriberAndTransactionIdReplyInfo searchTransactionBySubscriberAndTransactionId
(SearchTransactionBySubscriberAndTransactionIdRequestInfo req)
Usage: The method retrieves provisioning features in any state for a transactiongiven
msisdn. This includes information about which SOC the switch feature is related to.
Pre condition
Post condition
a subscriber.
IdentifierNotFound
Parameters:
req - SearchTransactionBySubscriberAndTransactionIdRequestInfo
Returns:
SearchTransactionBySubscriberAndTransactionIdReplyInfo
Throws:
failure occurs.
Page 43 of 91
6.1.20
searchSuspensions
public SearchSuspensionsReplyInfo searchSuspensions
(SearchSuspensionsRequestInfo req)
Usage: The method retrieves a list of all suspensions (max 600) there are or have been on a
subscriber. Suspensions from the list that have been send to switch-control, can also be seen
in ‘SearchTransactionHistoryByMsisdn’. This includes information about suspend-date and
resume-date.
Pre condition
Post condition
a subscriber.
IdentifierNotFound
Parameters:
req - SearchSuspensionsRequestInfo
Returns:
SearchSuspensionsReplyInfo
Throws:
failure occurs.
Page 44 of 91
6.1.21
rejectExport
public RejectExportReplyInfo rejectExport
(RejectExportRequestInfo req)
Usage: The method is rejecting an export request. A reason must be given for rejecting an
export. Valid reasons are retrieved via the service getRejectionCodes(GetRejectionCodesRequestInfo)
This service is used in number porting.
Pre condition
Post condition
a subscriber.
IdentifierNotFound
Transaction is missing in Operators Interface
Transaction is in an invalid state in Operators Interface
Invalid State
Parameters:
req - RejectExportRequestInfo
Returns:
RejectExportReplyInfo
Throws:
failure occurs.
Page 45 of 91
6.1.22
releaseImport
public ReleaseImportReplyInfo releaseImport
(ReleaseImportRequestInfo req)
Usage: The method is releasing an import. (Porting is cancelled).
Pre condition
Post condition
to a subscriber as reserved.
IdentifierNotFound
Parameters:
req - ReleaseImportRequestInfo
Returns:
ReleaseImportReplyInfo
Throws:
failure occurs.
Page 46 of 91
6.1.23
searchExportRequests
public SearchExportRequestsReplyInfo searchExportRequests
(SearchExportRequestsRequestInfo req)
Usage: The method retrieves a list of number portability transactions, which are not yet confirmed or rejected. This list only shows export transactions. Used when operating in the
Danish market.
Pre condition
Post condition
A service provider identified by serviceProviderId exists.. SuccessfulCompletion
pageNo is less than zero.
pageSize is less than zero or greater than the server
specified maximum or (greater than 150 and 600 modulo OptionalFieldValidationFailed
pageSize <> 0)
Parameters:
req - SearchExportRequestsRequestInfo
Returns:
SearchExportRequestsReplyInfo
Throws:
failure occurs.
Page 47 of 91
6.1.24
getRejectionCodes
public GetRejectionCodesReplyInfo getRejectionCodes
(GetRejectionCodesRequestInfo req)
Usage: This method is used to retrieve rejection codes for a given service provider. The rejection code is used as a parameter for rejecting an export request.
The information provided by this service is used as input for rejectExport.
Pre condition
Post condition
expired rejection codes.
expired rejection codes.
Parameters:
req - GetRejectionCodesRequestInfo
Returns:
GetRejectionCodesReplyInfo
Throws:
failure occurs.
Page 48 of 91
6.1.25
getReportTypes
public GetReportTypesReplyInfo getReportTypes
(GetReportTypesRequestInfo req)
Usage: This method is used to retrieve report types for a given service provider.
This information is used as input to the service createReportRequest.
The reports contain information about various resources and number porting events. They
are described further in the report section of this document.
Pre condition
Post condition
A service provider identified by code exists. SuccessfulCompletion
Parameters:
req - GetReportTypesRequestInfo
Returns:
GetReportTypesReplyInfo
Throws:
failure occurs.
Page 49 of 91
6.1.26
createReportRequest
public CreateReportRequestReplyInfo createReportRequest
(CreateReportRequestRequestInfo req)
Usage: This method is used create a report request for a given service provider.
getReportTypes provides information about valid values the SP can use in this service.
Pre condition
Post condition
A report identified by reportName exists AND is allowed to be requested by the specific userId.
ReportName does not exist or is not allowed for the actual UserId.
IdentifierNotFound
Parameters:
req - CreateReportRequestRequestInfo
Returns:
CreateReportRequestReplyInfo
Throws:
failure occurs.
Page 50 of 91
6.1.27
searchReportRequestByUserId
public SearchReportRequestByUserIdReplyInfo searchReportRequestByUserId(SearchReportRequestByUserIdRequestInfo req)
Usage: This method is used retrieve a list of report requests for a given user.
Parameters:
req - SearchReportRequestByUserIdRequestInfo
Returns:
SearchReportRequestByUserIdReplyInfo
Throws:
failure occurs.
Page 51 of 91
6.1.28
getNPFlowTypes
public GetNPFlowTypesReplyInfo getNPFlowTypes
(GetNPFlowTypesRequestInfo req)
Usage: This method is used fetch a list of NP-flow types and corresponding description. The
NP-flowtype id is used in the service listNPFlowStatus.
This service is used in number porting
Pre condition
Post condition
A service provider identified by code exists. SuccessfulCompletion
Parameters:
req - GetNPFlowTypesRequestInfo
Returns:
GetNPFlowTypesReplyInfo
Throws:
failure occurs.
Page 52 of 91
6.1.29
listNPFlowStatus
public ListNPFlowStatusReplyInfo listNPFlowStatus
(ListNPFlowStatusRequestInfo req)
Usage: This method is used retrieve a list of number porting flows. Default pagesize set to
100.
GetNPFlowTypes provides the valid values the SP can use when calling this service
This service is used in number porting
Pre condition
Post condition
A service provider identified by code exists and the given
npFlowType id exists
A service provider identified by code exists AND no related npFlowTypes defined.
pageSize is less than zero or greater than 500 or (500
modulo pageSize <> 0).
No fromDate given, no toDate given or no npFlowType id
given.
toDate or fromDate string does not have the correct format: yyyy.MM.dd.HH.mm.ss.
DateFormatError
Parameters:
req - ListNPFlowStatusRequestInfo Gives the parameters for the request
Returns:
ListNPFlowStatusReplyInfo Output with the list of NPFlows and informations if there is more data
to be retrieved.
Throws:
failure occurs.
Page 53 of 91
6.1.30
importSubscriber_NO
public ImportSubscriberReplyInfo importSubscriber_NO
(ImportSubscriberRequestInfo_NO req)
Usage: Used when creating subscription by import of a foreign number.
Only used for norwegian subscribers.
Pre condition
Post condition
A service provider identified by serviceProviderId exists
AND (all resources specified by feature parameters belong to the specified service provider OR are eligible for
import) AND are available AND all required SOCs and
features are specified AND are not mutual exclusive.
IdentifierNotFound
Mandatory services type missing from request.
Resource is in use, exported or in retention period or
others where you cannot use it.
InvalidState
Resource is not valid in this context. Sample Voice number used as voicemail or sim card used as virtual sim
card
MSISDN is a fix-net number.
Resource is already owned by SP.
MSISDN is already present in the system, but not as
exported or cancelled.
Requested activation date is not after current date.
Parameters:
req - ImportSubscriberRequestInfo_NO
Returns:
ImportSubscriberReplyInfo
Throws:
failure occurs.
Page 54 of 91
6.1.31
createSubscriber_NO
public CreateSubscriberReplyInfo createSubscriber_NO
(CreateSubscriberRequestInfo_NO req)
Pre condition
Post condition
SOCs and features are specified AND are not mutual exclusive.
IdentifierNotFound
Resource is in use, exported or in retention period or others
where you cannot use it.
InvalidState
Resource is not valid in this context.Sample Voice number
used as voicemail or sim card used as virtual sim card
Parameters:
req - CreateSubscriberRequestInfo_NO
Returns:
CreateSubscriberReplyInfo
Throws:
failure occurs.
Page 55 of 91
6.1.32
confirmExport_NO
public ConfirmExportReplyInfo confirmExport_NO
(ConfirmExportRequestInfo_NO req)
Usage: The method is confirming an export request in the Norwegian market.
Pre condition
Post condition
a subscriber.
IdentifierNotFound
Invalid State
Parameters:
req - ConfirmExportRequestInfo_NO
Returns:
ConfirmExportReplyInfo
Throws:
failure occurs.
Page 56 of 91
6.1.33
getActivationTypes
public GetActivationTypesReplyInfo getActivationTypes
(GetActivationTypesRequestInfo req)
Usage: This method is used to retrieve activation codes for a given service provider. The activation code is used as a parameter for activating a subscriber.
This information is used as input to the createSubscriber service. The options are creating a
new subscriber using SP owned resources or numberImport a subscriber.
Pre condition
Post condition
expired activationtypes.
expired activationtypes.
Parameters:
req - GetActivationTypesRequestInfo
Returns:
GetActivationTypesReplyInfo
Throws:
failure occurs.
Page 57 of 91
6.1.34
createSubscriber
public CreateSubscriberReplyInfo createSubscriber
(CreateSubscriberRequestInfo req)throws java.rmi.RemoteException
Usage: Used when creating subscription. Only used for danish subscribers. The subscription
is made effective immediately on normal activation or the subscription is created as reserved
when performing number import of MSISDN-numbers not owned by the current service
provider. This implies pairing of resources and activation of the subscribers selected services in the transmission network either immediately or on the scheduled activation date.
Resources change states according to the general rules for Resource Management.
Pre condition
Post condition
A service provider identified by serviceProviderId exists
AND all resources specified by feature parameters belong
to the specified service provider AND are available AND
all required SOCs and features are specified AND are not
mutual exclusive.
IdentifierNotFound
Activation type does not exists.
Resource is in use, exported or in retention period or
others where you cannot use it.
InvalidState
Resource is not valid in this context.Sample Voice number used as voicemail or sim card used as virtual sim
card
On create: npDonorICC given.
On import: MSISDN is a fix-net number.
On import: Resource is already owned by SP.
On import: MSISDN is already present in the system, but
not as exported or cancelled.
On Import: Requested activation date is not after current
date.
Parameters:
req - CreateSubscriberRequestInfo
Returns:
CreateSubscriberReplyInfo
Throws:
failure occurs.
Page 58 of 91
6.1.35
confirmExport
public ConfirmExportReplyInfo confirmExport
(ConfirmExportRequestInfo req)throws java.rmi.RemoteException
Usage: The method is confirming an number porting export request in the Danish market.
Pre condition
Post condition
a subscriber.
IdentifierNotFound
Invalid State
Parameters:
req - ConfirmExportRequestInfo
Returns:
ConfirmExportReplyInfo
Throws:
failure occurs.
Page 59 of 91
6.1.36
searchResourceByMsisdn
public SearchResourceByMsisdnReplyInfo searchResourceByMsisdn
SearchResourceByMsisdnRequestInfo req)
Usage : The method retrieves the current msisdn resource state.
Pre condition
Post condition
MSISDN exists and belongs to SP identified by sp-id. SuccessfulCompletion
IdentifierNotFound
Parameters:
req - SearchResourceByMsisdnRequestInfo
Returns:
SearchResourceByMsisdnReplyInfo
Throws:
failure occurs.
Page 60 of 91
6.1.37
updateMsisdnResource
public UpdateMsisdnResourceReplyInfo updateMsisdnResource
(UpdateMsisdnResourceRequestInfo req)
Usage : The method updates the current msisdn with a gievn resource state.
ex. from status AG to AA (aging to assigned available)
Pre condition
Post condition
MSISDN exists and belongs to SP identified by sp-id. SuccessfulCompletion
IdentifierNotFound
Parameters:
req - UpdateMsisdnResourceRequestInfo
Returns:
UpdateMsisdnResourceReplyInfo
Throws:
failure occurs.
Page 61 of 91
6.1.38
getMsisdnTransistionStates
public GetMsisdnTransistionStatesReplyInfo getMsisdnTransistionStates
(GetMsisdnTransistionStatesRequestInfo req)
Usage : The method get allowed msisdn transistion states for a given state.
Pre condition
Post condition
Resource-state is valid. SuccessfulCompletion
Parameters:
req - GetMsisdnTransistionStatesRequestInfo
Returns:
GetMsisdnTransistionStatesReplyInfo
Throws:
failure occurs.
Page 62 of 91
6.1.39
searchExportRequests_NO
public SearchExportRequestsReplyInfo_NO searchExportRequests_NO
(SearchExportRequestsRequestInfo req)
Usage: operating in the norwegian market
Pre condition
Post condition
A service provider identified by serviceProviderId exists.. SuccessfulCompletion
pageSize is less than zero or greater than the server
specified maximum or (greater than 150 and 600 modulo OptionalFieldValidationFailed
pageSize <> 0)
Parameters:
req - SearchExportRequestsRequestInfo
Returns:
SearchExportRequestsReplyInfo
Throws:
failure occurs.
Page 63 of 91
6.1.40
updateSIMResourceStatus
public UpdateSIMResourceStatusReplyInfo updateSIMResourceStatus
(UpdateSIMResourceStatusRequestInfo req)
Usage : The method updates the current SIM Number of resource Status information with a
given SIM Number and Requested status.
ex. from status AG to AA (aging to assigned available)
Pre condition
Post condition
SIM Number exists and belongs to SP identified by sp-id. SuccessfulCompletion
SIM Number does not exists or does not belongs to SP
IdentifierNotFound
Parameters:
req - UpdateSIMResourceStatusRequestInfo The inputs caontaing the information of the sim card
to be updated in the database.
Returns:
The status whether the update was successful or not.
Throws:
java.rmi.RemoteException - Thrown by the EJB container if some kind of communication
failure occurs.
Page 64 of 91
6.1.41
getSimCardDetails
public GetSimCardDetailsReplyInfo getSimCardDetails
(GetSimCardDetailsRequestInfo req)
Usage : The method fatching the current SIM Number information with a given SIM Number.
Pre condition
Post condition
SIM Number exists and belongs to SP identified by sp-id. SuccessfulCompletion
SIM Number does not exists or does not belongs to SP
IdentifierNotFound
Parameters:
req - The inputs containing the sim card number whose deatils are to be retirved.
Returns:
the details of the sim card
Throws:
java.rmi.RemoteException - Thrown by the EJB container if some kind of communication
failure occurs.
Page 65 of 91
6.1.42
getICCTransistionStates
public GetICCTransistionStatesReplyInfo getICCTransistionStates
(GetICCTransistionStatesRequestInfo req)
Usage : The method get allowed sim transistion states for a given state.
Pre condition
Post condition
Resource-state is valid. SuccessfulCompletion
Parameters:
req - GetICCTransistionStatesRequestInfo
Returns:
GetICCTransistionStatesReplyInfo
Throws:
failure occurs.
Page 66 of 91
6.1.43
lookupHLRinformation
public LookupHLRinformationReplyInfo lookupHLRinformation
(LookupHLRinformationRequestInfo req)
Usage: The method retrieves the current HLR informations stored in the mobile network.
Inside the reply class, the data from the HLR is stored in a structured XML 1.0 string.
The service is NOT intented for bulk reads in the HLR. If overloaded, requests will be
dropped. The service allows approximately 100 to 200 requests per. minute before it starts
dropping requests.
Pre condition
Post condition
a subscriber.
MSISDN exists is of VOICE MAIL class
IdentifierNotFound
IdentifierNotFound
Service is flooded with requests
RequestDropped
Parameters:
req - LookupHLRinformationRequestInfo
Returns:
LookupHLRinformationReplyInfo
Throws:
failure occurs.
Page 67 of 91
7 AXIS - overview
Apache Axis is an implementation of the SOAP ("Simple Object Access Protocol") submission to
W3C.
From the draft W3C specification:
SOAP is a lightweight protocol for exchanging structured information in a decentralized, distributed environment. It is an XML based protocol that consists of three parts: an envelope that defines a framework
for describing what is in a message and how to process it, a set of encoding rules for expressing instances of application-defined datatypes, and a convention for representing remote procedure calls and
responses.
This project is a follow-on to the Apache SOAP project.
Please see the Reference Library for a list of technical resources that should prove useful.
7.1
AXIS architecture
Page 68 of 91
7.2
How AXIS convert from JAVA to SOAP XML and back?
Page 69 of 91
8 Number Porting
SPWEB5 supports number porting and contains a number of services which allows TDC‟s service providers
to carry out number porting.
TDC‟s service providers will act either as donor operators6 or as recipient operators7 depending on
whether they export or import.
Number porting is handled through rules and procedures set down by the mobile operator association
(TeleIndustrien). These rules and procedure documents may be found in \docs\Rules and Procedures\
section of the toolkit.
The specific implementations at the service providers must follow these guidelines, however, this is not to
say that number porting implementations are alike as there is a fair degree of room for variation.
The following covers the basics of TDC‟s number porting flows including TDC specific features.
TDC and Number Porting
Number Porting in TDC‟s implementation is separated into two flows,
NP (Full Number Porting)
RESELL (Number Porting inside TDC‟s network)
Both result in the same thing, that a number is ported from a donor operator to a recipient operator. But
there are differences in how they work and what their area of operation is.
NP is the general full blown number porting operation where two operators switch a number from one
operator network to another operator‟s network. It involves actors external to TDC and numbers outside
of TDC‟s network.
RESELL on the other hand is the internal number porting track. RESELL covers the situation where the
number being ported is already inside TDC‟s network, either at TDC itself or at one of TDC‟s service providers.
NP versus RESELL
It should be noted that it is generally not needed that a TDC service provider distinguishes between the
two flows as the system as TDC will do this for the service provider.
There is for example no extra service that the service provider needs to invoke in either case, as the actions on the service provider side are exactly the same for each flow.
The impact for the service provider is,
The reports will differentiate between NP and RESELL when reporting errors or warnings.
5
SPWEB is the term used for the entire SPWEB solution including the API. In the number porting section it is the services found in SPWEB‟s API which is being referred to.
6
From TI – Rules and Procedures: Donor Operator = The operator from which one or more numbers are in the process
of being ported out (exported from).
7
From TI – Rules & Procedures: Recipient Operator = The operator to which one or more numbers are in the process
of being ported in (imported to).
Page 70 of 91
This can be used to choose the appropriate action as RESELL is subject to a greater degree of internal control than NP and thus can be impacted through SP-SUPPORT requests to TDC.
Easier to understand technical and report feedback.
Number Porting: Import and Export
Number porting consists of two areas which are interrelated,
Import
Export
Import is the situation where the recipient operator wishes to import a customer that is already active at
the donor operator.
Export is the opposite direction where a recipient operator wishes to import one of the donor operator‟s
customers.
It follows from this, that an import will by a counterpart seen as an export request and visa verse. They
are simply the direction in which the customer is travelling based on the view point.
SPWEB: Number Porting services
The SPWEB solution offers full support to number porting, in the following the relevant functions and their
use is described.
There are 3 types of service functions,
Information and Status
Export Related
Import Related
Information and Status services are used to provide information to the Service Provider about the current
state of on-going number porting (together with the reports, see chapter 10) and also supplies values to
be used in other Number Porting services ex. RejectionCodes for a RejectExport:
GetNPFlowTypes (Provide information about NP flow status fields)
GetRejectionCodes (Supplies RejectionCodes when rejecting exports)
ListNPFlowStatus (Provides a list of NPFlows for the Service Provider)
SearchExportRequests (Searches and provides a list of ExportRequests against the Service Provider)
Export related services allow the service provider to Reject or Confirm exports:
ConfirmExport (Yes, the customer is available for Number Porting and it can be carried out at the
date supplied in the service)
RejectExport (No, The customer is NOT available for Number Porting and a RejectCode is supplied, which is retrieved from GetRejectionCodes)
Page 71 of 91
Import related services allow the service provider to initiate a number porting:
CreateSubscriber (CreateSubcriber doubles as both (a) creating totally new Subscribers and (b)
starting Number Import through its ActivationTypeId field)
o The ActivationId field‟s value is supplied by the service: GetActivationTypes
ReleaseImport (Allows a Service Provider to cancel a number import, Note: That this can be done
at any time during the Number Porting flow)
Number Porting Flow
The following is a walkthrough through a number import and a number export.
Basic Number Import
At its most basic a Number Import runs through 3 stages
1. Import Request
2. Confirm or Reject Received
3. Execute
(Import Request) In this basic example the recipient operator uses a CreateSubscriber to create an import request. This creates an NP IMPORT request in the number porting system with a given date the
recipient operator would like the number porting to take place (requested execution date).
(Confirm/Reject) The information is entered into OCH (if applicable) and the donor operator is subject to
a NP EXPORT request, which can either be confirmed or rejected (in which case a new Import Request
must be sent or the NP dropped, the choice will be based on circumstances ex. the RejectionCode etc).
Regardless of answer, the recipient operator here persists, and the import request is, eventually, confirmed (the donor operator does a ConfirmExport at their end) and the requested execution date is also
confirmed.
Time passes and at no stage is a failure encountered and the recipient operator does not send any cancel
(ReleaseImport) during the period on the number involved.
(Execute) At the confirmed execution date the system carries out the number porting and the customer is
now available to the recipient operator.
Basic Number Export
An export is simpler than the import, in fact, the export is just step 2 (confirm/reject) in the number import as an export is the other end of an Import when viewed from the donor service provider.
1. Export Request found
2. ConfirmExport or RejectExport
The donor operator discovers (Reports and API Search services can provide this information) an incoming
import request, which is an export request seen from the donor operator.
Page 72 of 91
The donor operator check if the subscriber can be exported and based on this sends either (a) confirm
with an execution date or (b) reject with a reject reason code.
If a Confirm is sent the subscriber will be ported on the confirmed execution date8.
If a Reject is sent, the number porting process is cancelled and the recipient operator can choose to either restart the flow with a new import request or drop the number import.
From the donor‟s point of view the confirm/reject is the final step and no further actions are required.
NABS reserved subscriber
When a NP-flow is started TDC‟s billing system NABS requires the creating of a subscriber. The Number
import request, done through the service CreateSubscriber, therefore requires the recipient operator to
provide an ICC.
The reserved subscriber is activated upon the execution date.
However, care must be taken because the reserved subscriber is removed, if the flow fails or is rejected.
This can lead to a little extra use of ICC cards.
8
Various failure situations can prevent this from happening. The basic example assumes that no errors are encountered in any step of export or import.
Page 73 of 91
Number Porting Flow
The following establishes the basic flow when working with number porting.
CreateSubscriber
Requested
-SubscriberMSISDN
Or
-SubscriberICC
-ActivationTypeId
Completed
Import Request Failed
-NpDonorICC
-ServiceTypeId
Next State / Time
-RequestedDate
No answer/reaction
Missing event
Cancel Event
Service Provider Cancel
Or
Next State / Time
Confirmed
Rejected
No answer/reaction
Missing event
Cancel Event
Service Provider Cancel
Or
Executed
Execution Failed
Bold box: A bold box signifies a state that will show up in reports or searches.
Dotted box: Dotted signifies an intended or missing event that prevents the process from moving forward
and which will eventually (typically by passing a critical date) lead to its abortion.
Next State/Time: A number porting flow is one occurring over time, often large amounts of it, there are
therefore often large pauses between states where a) nothing happens b) something bad happens or
most common c) everything goes as expected and the next step is carried out. The vertical line shows
the main path that must occur for success and the horizontals shows the alternatives that can prevent
success.
State
Page 74 of 91
A state is a status situation. The flow has reached a given state and is now resting in this state awaiting
an event (ex. Rejection, Confirmation, Cancel etc) or time trigger (ex. Time advances to the date of Execution) that will change its state.
When a TDC service provider is requesting reports/ doing searches in the system it is the state that will
be reported back.
Requested: The Number Import has been requested and the system will now process it. It will either move to Number Import Request Completed or Number Import Failed Status. While requested but not confirmed the number will show up on warnings (in reports) to illustrate that the
request has been received but the flow has not progressed.
Completed: This is a system state. It merely signifies that the Import flow has been started with
valid parameters and that the system successfully has registered it.
Confirmed: The order has been confirmed. The confirmation is done by the donor operator and
contains the execution date at which the number import can be carried out. This day may or may
not be the date originally requested by the recipient operator, both options are valid.
Rejected: The order has been rejected. This can be done by either a) The system or b) The donor
operator. The prior will do it when there is information missing, invalid or where the state of the
subscriber does not allow number porting, the latter will do for various business reasons. Once
rejected, the flow is stopped and progresses to Rejected as its final state.
Executed: The order has been executed and the subscriber has been moved to the service provider. This event should occur on the execution date established in the confirmed state.
Failed: Any command or state can result in failed. This is when the system/flow for some reason
could not carry out the command or commands linked to its state that it was supposed to. If a
state fails, the flow is stopped and does not progress to a new state. The recipient operator must
try again (start a new import) or contact SP-support to have failure investigated and process restarted.
o Most failures occur at Import Request, Rejection or Execution.
Event
Events are,
a) Actions either by actors (the recipient operator, the donor operator or the system) that leads to
changes in the state or
b) Missing actions from the actors that prevent the change of states in time (ex. Requested Confirmation
date from the request has been reached but no confirmation has been received leading to a error situation where the number import can no longer be carried out in its original state as a new Requested date
must be supplied).
No answer/reaction: The next required event in the flow does not occur within the expected time
horizon leading to a permanent unchanged state. If the event does not occur at all or after a required date has passed the flow stops and the Number Import has to be restarted by the recipient operator or SP-support must be contacted to help out.
Cancel: At any stage the recipient operator can cancel a number import. A cancel will move the
process to a cancelled state and then stop the process once all system related cancel events have
been carried out.
Rejected: The system or donor operator has rejected the import request. The flow moves to a rejected state and does not continue. A reject must always contain an explanatory RejectionCode/reason which allows the recipient operator to correct the problem (if possible) and start a
new number import with corrected information
Reject reasons
Rejections in number porting are strongly screwed towards a few reasons.
Page 75 of 91
By far the most common reason is providing a wrong ICC (60%).
The second most common cause is no written termination confirmation received (20%).
The remaining 20% are distributed between a large number of minor reasons.
It follows from this that extra care in the business processes at the donor operator, recipient operator
and customers will drastically reduce the number of rejects.
Failure reasons
These are very rare and generally system related. There is no dominant or systematic cause. They are
the normal by-product of any large computer system.
Page 76 of 91
9 SPPORTAL
Until now what has been described is largely the SPWEB API, which is to say the business to business
integration interface, however, TDC also offers its SPWEB services through an internet portal called
SPPORTAL.
Browser support
SPPORTAL is a web portal and can be accessed with the common internet browsers. The following are all
verified to work with the current (1Q 2011) SPPORTAL version.
Internet Explorer, versions 6,7 and 8
Mozilla Firefox, version 3 and forward
Goggle Chrome, version 8 and forward
Of some minor interest is that Firefox will show the VAS parts of the page a bit compacted compared to
the other browsers and that the Explorer is still the default for which it is being created.
Functionality and scope
It contains all common services also found in the SPWEB API using a regular graphical web GUI interface.
The services present are all functional and it has access to the same data that SPWEB API has.
Being a webpage with a thin presentation layer has the effect that the information presented is more
human in its format (readable) and less technical than that found in the API.
Being a simple webpage, however, it quickly becomes cumbersome at medium and large scale operation
(which is the domain of the API). It is thus best of minor tasks involving no more than a few customers
or support/check related queries.
Availability
All service providers at TDC have an account at the SPPORTAL and are capable of logging into it and use
its facilities.
Access is restricted through login, password linked to a given service provider id, meaning that a service
provider is only able to see his or her own data in the portal.
URL
The SPPORTAL is found at: https://spportal.tdc.dk/spportal/jsp/index.jsp
Language
SPPORTAL is in Danish.
SPPORTAL examples
Please refer to the screens below for a short introduction to the graphical layout of SPPORTAL. Also refer
to the PowerPoint Presentation located in the \docs\ directory, which contains general information about
SPPORTAL and API as well as some example screens.
Page 77 of 91
First Example: Login Screen
The login is a simple user and password screen accessed through the https link given earlier in this
document.
Your login and user name is tied to your service provider id, which ensures that once logged in you will
only be able to see and change data for your own customers.
Once logged in you will be moved to the next example, which is the main screen of the Portal.
Page 78 of 91
Second Example: Main Screen
Once logged in you will arrive at the main screen. Links to services are found at the left frame and provides access to the most common features in SPWEB.
Important to note is that the SPPORTAL is always pointing to production whereas SPWEB has both a test
and production implementation. Working in the portal should always be done with care as changes are
live.
Also easy to note is that the language is Danish.
Shown in the lower left corner is the service provider information. Here it‟s the dummy provider called
Fantom SP04 (this information will change to your SP information on your logins).
One of the most common actions is that of creating a customer, this is done through CreateSubscriber in
SPWEB API and here the corresponding action is „oprettelse‟, which is the second option in the left frame.
Page 79 of 91
Third Example: Oprettelse (CreateSubscriber)
Oprettelse works in the same manner as CreateSubscriber in the API. It will ask for the same information
and offer the same options, but will do so in a reader friendly interface.
An interesting exercise for a person new to TDC‟s SPWEB solution is to compare the „oprettelse‟ screen
with the code and examples for CreateSubscriber found in the \bin\ and \src\ dirs in the toolbox.
Doing so will give a general understanding of how data is formatted and presented and generally ease
the process.
As this document is not intended as a step-by-step walkthrough of the SPPORTAL but as a description of
the SPWEB API, the last example is of a feature often used from the SPPORTAL (it is also available in
SPWEB API, everything is): The reporting functionality.
Page 80 of 91
Last Example: The Mobile Reports
The SPWEB solution offers six different reports to its services providers. These can be requested through
the portal (see the screenshot below) or the SPWEB API.
The next chapter in this document examines these reports in more detail. Please move to the next page
for a walkthrough of the reports, their contents and fields.
Page 81 of 91
10 SPWEB Reports
The SPWEB system offers a number of reports to its users. The reports available are:
1. Afviste Imports (Rejected Imports)
2. NP fejlliste (Number Porting error list)
3. Igangværende Import Ordre (Pending Imports)
4. Igangværende Export Ordre (Pending Exports)
5. Assigned & Available CTN
6. Assigned & Aging CTN
The reports can be requested both through the SPPORTAL and the SPWEB API. They are numbered according to their order shown here.
Report Id
The report id is built in the following manner: SP[SP-ID][REPORT-ID]
Example: SP99001
Description: SP with the number 99 and the report is 001 (Afviste Imports).
Generated Report name
When ordering reports a generated counted / unique identifier is prefixed to the report identification and
concatenated report name is post-fixed to the id.
Example: 488963_SP04001_ATTACH_IMREJECT.txt
Description: Report number 488963 for SP04 consisting of report 001 which is Import Rejected/Afviste
Imports.
Ordering the reports
The reports can be ordered through the SPPORTAL or the SPWEB API. It is the same functionality being
called and the difference is thus one of cosmetics (graphical vs. command line interface).
SPWEB API
GetReportTypes
CreateReportRequest
SearchReportRequestByUserId
GetReportTypes will display a list of available reports that can be ordered by the Service Provider. As well
as provide the input parameters from createReportRequest.
CreateReportRequest will create a reportRequest in the mobile report system. The report will once finished be forwarded to a destination agreed upon with the service provider (usually the SPPORTAL‟s
download area or directly to a server at the Service Provider).
Page 82 of 91
SearchReportRequest allows the user to search for reports corresponding to the user id (service provider
id).
SPPORTAL
Go to the SPPORTAL
Choose rapport
Select the report you wish to order and click bestil
The report will once complete be delivered to the destination agreed upon which can be under the
download option also seen at the SPPORTAL.
Page 83 of 91
SPID001: Afviste Imports
This report shows rejected Number Porting Imports for which there has not been a new import request
within the last 60 minutes.
A number import is a Number Porting (NP) event where the Recipient operator is requesting the transfer
of a number from another operator (the donor operator).
Number Imports that has been rejected will show up on this report with an error explanation.
A rejection is an explicit action carried out by the system or the donor operator.
System rejection is usually due to missing information or wrong information ex. missing or wrong
ICC.
Provider rejection is usually due to contract periods in which the customer is bound.
Report Field
Description
Msisdn
The MSISDN number.
Type
Rejected (provider or system)
Orig
The Originator of the message. This will be a system component.
CSM, OI or RESELL
TransDate
The transaction date. This is the date the transaction here an import was rejected.
ReqDate
The requested date of the number import. Which is
the date the import was requested to take place.
RejectCode
Reject Code. A numeric code representing the rejection reason.
RejectText
Reject Text in string format. A short explanation of
why the rejection took place ex. “No ICC was
found”
Page 84 of 91
SPID002: NP fejlliste
This report is a collection of errors and warnings for number porting related to the service provider. It
separates its status reporting into two areas, NP (external providers) and RESELL9 (internal providers)
NP area (non-Resell)
Status
Description
Import failed
The import has failed in one of its steps (Request,
Confirm, Execute) and the number porting has
stopped.
A new number import must be started or SPsupport contacted depending on the reason for
failure.
Import Confirmation Date Exceeded
The import has been confirmed but the current
date is now past the confirmation date without
execute or cancel having taken place.
This is an indication that an event should have
taken place but did not.
SP-support should be contacted.
Import No OCH Response
There has not been an OCH response to the import
request and the request is left in Import Request
state instead of moving to Import Request Confirmed state.
Contact SP-support if the situation persists and the
status is unchanged.
Export Failed
The export has failed in one of its steps (Request,
stopped.
No action is required. It is up to the counterpart
doing the import to restart the flow.
Export Execution Date Exceeded
The export has been confirmed but the execution
date has passed without execute taking place.
RESELL area
Status
Description
Export (Resell) Failed
The export has failed in one of its steps (Request,
stopped.
No action is required. It is up to the counterpart
doing the import to restart the flow.
Export (Resell) Not Confirmed
A service provider has started an import towards
9
NP is number porting involving an external provider where RESELL is number porting from TDC or one
of TDC‟s Service Providers. This is two different flows in TDC.
Page 85 of 91
one of your customers and the import has not yet
been confirmed by you.
Export (Resell) Execution Date Exceeded
A confirmed export has not been executed on the
date it was scheduled for.
Import (Resell) Failed
The import has failed in one of its steps (Request,
Confirm or Execute) and the number porting has
stopped.
A new number import must be started or support
contacted depending on the reason for failure.
Import (Resell) Not Confirmed
The import has not been confirmed yet by the
other provider.
Note. This is not necessarily an error. All number
imports will start out as not confirmed.
Import (Resell) Confirmation Date Exceeded
The import has been confirmed but the current
date is now past the confirmation date with an
execute or cancel having taken place.
Report Field
Description
Error
Error Type. The status will be one of those listed
above.
MSISDN
The number involved.
Type
The type where the error or warning occurred. The
value will be a numeric.
001 = Request
004 = Confirm
006 = Reject
007 = Cancel
008 = Executed Import
010 = Executed Export
012 = Number Return
017 = Executed Resell
Orig
The system group the message originated from.
TransDate
The transaction date. This date is not the original
transaction date when the number porting request
was received but the date of the latest event
ReqDate
The requested execution date
ConfirmDate
The actual confirmed date.
ExecDate
The actual execution date.
Page 86 of 91
SPID003: Igangværende Import Ordre (NPOutstanding import)
This report shows pending import orders for the service provider. It shows both NP and Resell imports.
An import is a request to another provider or service provider to receive a customer through number
porting.
Report Field
Description
IMPORT/EXPORT
The NPOutstanding report handles both import and
export direction (report 003 and 004) this field
signifies the type
This is the format used for imports.
From
From provider
To
To provider
MSISDN
The number
Type
The current state of the process ex. Requested,
Confirmed, Executed etc.
Status
What the status is for the current state.
Trans-Date
Transaction Date
Exec-Conf
Confirmed Execution Date
Failed-Type
-
Failed-Status
-
Failed-Date
-
Reject-Code
The numeric Reject code
1.Trans-Date
Transaction Date for the first entry in the number
porting flow
Reserved ICC
The reserved ICC to be used in the TDC NABS system.
The Reserved ICC is the ICC supplied when making
the Number Import request.
It is an ICC that TDC‟s Billing System NABS uses to
create a Reserved Subscriber in the system.
Donor ICC
The donor‟s ICC.
Page 87 of 91
SPID004: Igangværende Export Ordre (NPOutstanding export)
This report shows pending export orders for the service provider. It shows both NP and Resell exports.
An export is a request from another provider or service provider towards you requesting that you transfer
one of your existing customers to them through number porting.
Report Field
Description
IMPORT/EXPORT
The NPOutstanding report handles both import and
export direction (report 003 and 004) this field
signifies the type
This is the format used for exports.
From
From provider
To
To provider
MSISDN
The number
Type
The current state of the process ex. Requested,
Confirmed, Executed etc.
Status
What the status is for the current state.
Trans-Date
Transaction Date
Exec-Conf
Confirmed Execution Date
Failed-Type
-
Failed-Status
-
Failed-Date
-
Reject-Code
The numeric Reject code
1.Trans-Date
Transaction Date for the first entry in the number
porting flow
Request-Date
Requested date for the export
Donor ICC
The donor‟s ICC.
Current ICC
The current ICC connected to the MSISDN
Recipient Service Operator
The code of the operator being exported to
Page 88 of 91
SPID005: Assigned and Available CTN
This report show the CTN (MSISDN numbers) that have been assigned to a service provider and which
are available for assignment to a customer.
In essence it shows all number available to be assigned to a customer for the given service provider. The
status is called assigned available (AA) not to be confused with assigned numbers in use called assigned
in use (AI).
Example:
Report Field
Description
CTN
The MSISDN
CTN_STATUS
The status of the MSISDN. This will always be AA
for assigned available.
NGP
Number Group in which the CTN occurs.
NL
Number Location. Usually the SPID-0000 ex. 990000 for SP99.
Page 89 of 91
SPID006: Assigned & Aging CTN
This report show the CTN which have been assigned but no longer are available and are now between
uses, which is called aging.
Aging is thus the grace period where a number is no longer assigned to a customer and when it can be
assigned again to a new customer.
Report Field
Description
CTN
The MSISDN
CTN_STATUS
The status of the MSISDN. This will always be AG
for assigned aging.
NGP
Number Group in which the CTN occurs.
NL
Number Location. Usually the SPID-0000 ex. 990000 for SP99.
Page 90 of 91
11 References
WEB-page for AXIS:
http://ws.apache.org/axis/
WEB-page for BEA Weblogic:
http://www.bea.com/framework.jsp?CNT=index.htm&FP=/content/products/weblogic
WEB-page for SUN JAVA:
http://java.sun.com/
WEB-page for XML:
http://www.xml.org/
WEB-page for SOAP:
http://www.w3.org/TR/soap/
Page 91 of 91

TDC Mobil`s SPWEB SAOP API

Transcription

Similar documents

Whitepages Pro Caller Identification API

Quarterly NL May 2010-b

ADSL Configuration

Batch Production of Driving Distances and Times Using SAS® and

Together Middlesbrough March 2015 Newsletter

to your all access subscription

1. Basic Concepts

World Records 2011, Limca Book of Records 2012, World Record

M2M Ecosystem Development

Bed, Bath and Beyond - Yale University Library