CONFIDENTIAL

@Home – Roaming Disablement on HLRs

Functional Requirements Specification

Release V1.00

Document Owner

Created 2015-02-04

Last Saved 2015-02-16

Last Saved By

File Name
 @Home – Roaming Disablement on HLRs – Functional Requirements Specification

Document History

Rev No. Date Author Last Change

0.1 2015-02-04 Gavin Loveland Created the document

1.00 2015-02-16 Gavin Loveland Updated document to incorporate comments and

prepare final version for submittal to vendor.

Page 2 of 17
 @Home – Roaming Disablement on HLRs – Functional Requirements Specification

Related Documents

Rev No. Date Author Description File

Page 3 of 17
 @Home – Roaming Disablement on HLRs – Functional Requirements Specification

Table of Contents

 
Document History ........................................................................................................................................... 2  

Related Documents ........................................................................................................................................ 3  

Table of Contents ........................................................................................................................................... 4  

List of Tables .................................................................................................................................................. 5  

Glossary.......................................................................................................................................................... 6  

1.   Background ............................................................................................................................................. 7  

1.1   Introduction ...................................................................................................................................... 7  

1.2   Goals and Objectives ....................................................................................................................... 7  

2.   Detailed Requirements ............................................................................................................................ 8  

2.1   Introduction ...................................................................................................................................... 8  

2.2   HLR Profile Query ............................................................................................................................ 8  

2.3   Call Forwarding and Barring of Roaming ....................................................................................... 12  

2.4   Reverting of Call Forwarding and Roaming State .......................................................................... 15  

2.5   Additional Functional Requirements .............................................................................................. 17  

2.5.1   Additional Error Logging ......................................................................................................... 17  

Page 4 of 17
 @Home – Roaming Disablement on HLRs – Functional Requirements Specification

List of Tables

Table 1 USA HGSDP Command (Subscriber TS10 Supplementary Data Query) ......................................... 8  
Table 2 - USA HGSDP Command (Subscriber TS10 Supplementary Data and Permanent User Data
Query) ............................................................................................................................................................. 9  
Table 3 - USA HGSDP Response with Subscriber TS10 Supplementary Data and Permanent User Data .. 9  
Table 4 - Possible OBR Values .................................................................................................................... 11  
Table 5 - USA HGSSI Command (Setting of Unconditional Call Forwarding) .............................................. 12  
Table 6 - USA HGSDC Command (Enabling Operator Determined Barring of Roaming) ........................... 12  
Table 7 - USA HGSDC Response (Enabling Operator Determined Barring of Roaming) ............................ 13  
Table 8 - USA HGSSE Command (Unsetting of Unconditional Call Forwarding) ........................................ 15  
Table 9 - USA HGSDC Command (Reverting of Operator Determined Barring of Roaming Status) ........... 15  
Table 10 - USA HGSDC Response (Reverting of Operator Determined Barring of Roaming) .................... 16  

Page 5 of 17
 @Home – Roaming Disablement on HLRs – Functional Requirements Specification

Glossary

Acronym Definition

CFU Call Forwarding (Unconditional)

HLR Home Location Register

HTTP HyperText Transfer Protocol

MSISDN Mobile Subscriber ISDN

OBR Operator-Determined Barring of Roaming

USA Universal System Access

UTF-8 Universal Character Set Transformation Format – 8 bit

Page 6 of 17
 @Home – Roaming Disablement on HLRs – Functional Requirements Specification

1. Background

1.1 Introduction

There currently exists an issue with a particular @Home call case. When a subscriber is out of country, and
roaming is enabled for that subscriber on the HLR, they are being billed for a ‘non-existent’ roaming leg of a
GSM call, when called via the @Home application. Therefore, not only is this subscriber charged @Home
credits in this case, but they are charged an additional Rand value for the call.

As an interim solution to this problem, development is required on the @Home platform to ensure that the
respective field on the HLR is changed for the subscriber when they choose to make use of the @Home
platform while out of country. This will prevent the subscriber from being charged an additional Rand value
over and above their @Home credit charge.

The purpose of this document is to detail the functional requirements in achieving the above interim fix.

1.2 Goals and Objectives

The primary goal is to provide an interim fix to the charging issue which currently resides on the network in
the context of the @Home application. In order to achieve this goal, the following objectives shall be met;

- When a subscriber chooses to set their unconditional call forwarding to the @Home platform
(making use of the mobile app), the @Home platform will be responsible for determining the current
value of the operator determined barring of roaming field for that subscriber on their respective HLR.
@Home will change this value in certain cases, keeping record of the current value, in addition to
setting their unconditional call forwarding to the @Home platform (as current logic already dictates).
- When a subscriber chooses to stop making use of the @Home platform (by disabling unconditional
call forwarding using the mobile app), the @Home platform will be responsible for determining the
previous value of the operator determined barring of roaming field for that subscriber, and altering
the field for that subscriber on their respective HLR when necessary (back to the previous value), in
addition to removing the unconditional call forwarding configuration (as current logic already
dictates).

Page 7 of 17
 @Home – Roaming Disablement on HLRs – Functional Requirements Specification

2. Detailed Requirements

2.1 Introduction

Currently, when a subscriber logs into the @Home mobile application, the app queries the @Home
platform, which in turn queries USA to determine the subscriber’s current unconditional call forwarding
status from the subscriber’s TS10 supplementary service data. If the subscriber’s unconditional call
forwarding is not set, the mobile app provides an option for setting unconditional call forwarding to the
@Home platform.

When a subscriber chooses to enable unconditional call forwarding to @Home, the mobile app issues a
request to the @Home platform, which in turn issues a request to USA to set unconditional call forwarding
to the @Home platform on the subscriber’s respective HLR. Unconditional call forwarding is also disabled
in a similar manner when the subscriber chooses to stop using the platform.

Going forward, this process is required to change. Upon app initiation, the @Home platform shall no longer
only query USA for the relevant subscriber’s TS10 supplementary service data, but will query USA for the
subscriber’s permanent user data as well. Additionally, when a subscriber chooses to enable unconditional
call forwarding to @Home, the @Home platform shall not only set the subscribers unconditional call
forwarding as before, but also record and then change their operator determined barring of roaming if
necessary . Upon the user’s request to stop using the platform, @Home should not only unset the
subscribers unconditional call forwarding, but restore the subscriber’s operator determined barring of
roaming field to its previously known state.

The following sections in this document detail the requirements in altering the current logic on the @Home
platform in accommodating the abovementioned changes.

2.2 HLR Profile Query

Currently, the @Home platform queries USA for the subscriber’s supplementary service data on subscriber
login. In order to do this, @Home sends an HTTP POST request to USA, containing the following XML as a
POST parameter labelled “command”;

Table 1 USA HGSDP Command (Subscriber TS10 Supplementary Data Query)

<usareq COMMAND='HGSDP:MSISDN=SUBSCRIBER_MSISDN,ALL;' NODE='HLR'

TRANSFORM='HGSDP:TS10’ USERNAME=_athome'
PASSWORD=_athome'/>

Where SUBSCRIBER_MSISDN is the MSISDN of the subscriber in question.

Page 8 of 17
 @Home – Roaming Disablement on HLRs – Functional Requirements Specification

Going forward, the above is required to change. The new request shall not only query USA for the
subscriber’s TS10 supplementary service data, but will query USA for the subscriber’s permanent user data
as well. In order to achieve this, the ‘TRANSFORM” parameter in the XML payload is required to be
changed from “HGSDP:TS10” to “HGSDP:TS10,PERMANENT SUBSCRIBER DATA”;

Table 2 - USA HGSDP Command (Subscriber TS10 Supplementary Data and Permanent User Data Query)

<usareq COMMAND='HGSDP:MSISDN=SUBSCRIBER_MSISDN,ALL;' NODE='HLR'

TRANSFORM='HGSDP:TS10,PERMANENT SUBSCRIBER DATA' USERNAME=_athome'
PASSWORD=_athome'/>

Where SUBSCRIBER_MSISDN is the MSISDN of the subscriber in question.

Upon querying USA with the above XML payload, USA will return the subscriber’s TS10 supplementary
service data as it did before, as well as the their permanent user data;

Table 3 - USA HGSDP Response with Subscriber TS10 Supplementary Data and Permanent User Data

<?xml version="1.0" encoding="UTF-8"?>

<usarsp COMMAND="HGSDP:MSISDN=27832229138,ALL;" INSTANCE="nlusa04" NODE="HLR"
REQ_ID="1415126895449_309637470" RESPONSE_TIME="52" SVC_RESULT="F"
TRANSFORM="HGSDP:TS10,PERMANENT SUBSCRIBER DATA" USERNAME=" _athome">
<datablock NAME="HLR SUBSCRIBER DATA">
<datasection NAME="TS10 DATA">
<data NAME="BAIC" VALUE="NOT ACTIVE"/>
<data NAME="BAOC" VALUE="NOT ACTIVE"/>
<data NAME="BICRO" VALUE="NOT ACTIVE"/>
<data NAME="BOIC" VALUE="NOT ACTIVE"/>
<data NAME="BOIEXH" VALUE="NOT ACTIVE"/>
<data NAME="CAW" VALUE="ACTIVE-OP"/>
<data NAME="CFU" VALUE="NOT ACTIVE"/>
<data NAME="CFB" VALUE="NOT ACTIVE"/>
<data NAME="CFNRY" VALUE="NOT ACTIVE"/>
<data NAME="CFNRC" VALUE="NOT ACTIVE"/>
<data NAME="DCF" VALUE="ACTIVE-OP 278314832229138 20"/>
</datasection>
<datasection NAME="PERMANENT SUBSCRIBER DATA">
<data NAME="CAT" VALUE="10"/>
<data NAME="DBSG" VALUE="1"/>
<data NAME="TSMO" VALUE="0"/>
<data NAME="STYPE" VALUE="7"/>
<data NAME="OBR" VALUE="2"/>

Page 9 of 17
 @Home – Roaming Disablement on HLRs – Functional Requirements Specification

<data NAME="OSB4" VALUE="1"/>

<data NAME="TS11" VALUE="1"/>
<data NAME="TS21" VALUE="1"/>
<data NAME="TS22" VALUE="1"/>
<data NAME="TS61" VALUE="1"/>
<data NAME="TS62" VALUE="1"/>
<data NAME="BS2G" VALUE="1"/>
<data NAME="BS3G" VALUE="1"/>
<data NAME="BS2F" VALUE="1"/>
<data NAME="BS3F" VALUE="1"/>
<data NAME="RSA" VALUE="1"/>
<data NAME="REDMCH" VALUE="1"/>
<data NAME="OFA" VALUE="1"/>
<data NAME="PWD" VALUE="0000"/>
<data NAME="EMLPP" VALUE="1"/>
<data NAME="DEMLPP" VALUE="3"/>
<data NAME="MEMLPP" VALUE="3"/>
<data NAME="OICK" VALUE="720"/>
<data NAME="CFU" VALUE="1"/>
<data NAME="CFB" VALUE="1"/>
<data NAME="CFNRY" VALUE="1"/>
<data NAME="CFNRC" VALUE="1"/>
<data NAME="BAOC" VALUE="1"/>
<data NAME="BOIC" VALUE="1"/>
<data NAME="BOIEXH" VALUE="1"/>
<data NAME="BAIC" VALUE="1"/>
<data NAME="BICRO" VALUE="1"/>
<data NAME="CAW" VALUE="1"/>
<data NAME="SOCFB" VALUE="0"/>
<data NAME="SOCFRY" VALUE="0"/>
<data NAME="SOCFRC" VALUE="0"/>
<data NAME="SOCFU" VALUE="0"/>
<data NAME="SOCB" VALUE="1"/>
<data NAME="SOCLIP" VALUE="0"/>
<data NAME="SOCLIR"VALUE="2"/>
<data NAME="SODCF" VALUE="0"/>
<data NAME="SOSDCF" VALUE="7"/>
<data NAME="HOLD" VALUE="1"/>
<data NAME="MPTY" VALUE="1"/>
<data NAME="CLIP" VALUE="1"/>

Page 10 of 17
 @Home – Roaming Disablement on HLRs – Functional Requirements Specification

<data NAME="CLIR" VALUE="1"/>

<data NAME="SCHAR-4" VALUE="0"/>
<data NAME="MOPRBT"VALUE="1"/>
</datasection>
</datablock>
</usarsp>

The failure response for the above request remains the same. The ‘SVC_RESULT’ field denotes whether
the request was successful or a failure (i.e. when ‘SVC_RESULT equals “F” the request shall be deemed a
success, and when ‘SVC_RESULT’ equals “T” the request shall be deemed a failure).

In the case where the subscriber’s TS10 supplementary service data / permanent user data request fails,
the @Home platform shall return an error to the mobile application, which shall in tern present a user-
friendly error message;

“Your request could not be processed. Please try again later.”

The @Home platform already performs an analysis on the response to determine the subscriber’s current
unconditional call forwarding status (by searching for the ‘data’ tag where the ‘NAME’ field is equal to
“CFU”, and thereafter analysing the ‘VALUE’ field of this tag).

Going forward, the @Home platform shall be required to determine the subscriber’s operator determined
barring of roaming status as well. This shall be achieved by searching for the ‘data’ tag where the ‘NAME’
field is equal to “OBR” (found within the ‘datasection’ tags where the ‘NAME’ field is equal to “PERMANENT
SUBSCRIBER DATA”). When this tag is found, the “VALUE” field shall be analysed to determine the
subscriber’s operator determined roaming status.

The following are possible values for this field;

“0” This means that operator determined barring of roaming is disabled.

“1” This means that operator determined barring of roaming outside home PLMN is enabled.
“2” This means that operator determined barring of roaming outside home PLMN country is enabled.
Table 4 - Possible OBR Values

At this point, the @Home platform will be aware of both the subscriber’s unconditional call forwarding
status, as well as their operator determined barring of roaming status. If the subscriber’s unconditional call
forwarding is not set to forward to the @Home platform, their operator determined barring of roaming value
shall be recorded at this point.

The reason the OBR value is required to be recorded on a per-subscriber basis, is due to the fact that this
value will be required to be changed if the subscriber chooses to begin receiving calls via the @Home
platform. Once the subscriber is finished making use of the @Home platform and decides to disable their

Page 11 of 17
 @Home – Roaming Disablement on HLRs – Functional Requirements Specification

unconditional call forwarding, the subscriber’s OBR value is required to be reverted back to what it was
prior to enable their unconditional call forwarding.

The OBR value shall not be recorded in the case where the subscriber’s unconditional call forwarding is
already set to the @Home platform, as in such a case the OBR value will have already been recorded
(prior to setting their unconditional call forwarding).

Thus, the process flow shall be as follows;

No Record  OBR  value

Respond  to  app  

Query  USA  f or  HLR   Check  T S10  CFU  and   TS10  CFU  set  to  
Login Yes with  call  forwarding  
profile OBR  values @Home?
status

2.3 Call Forwarding and Barring of Roaming

Currently, the @Home platform issues commands to subscribers’ HLRs via USA in order to set call
forwarding to the @Home platform. In order to do this, @Home sends an HTTP POST request to USA,
containing the following XML as a POST parameter labelled “command”;

Table 5 - USA HGSSI Command (Setting of Unconditional Call Forwarding)

<usareq
COMMAND='HGSSI:MSISDN=SUBSCRIBER_MSISDN,SS=CFU,BSG=TS10,FNUM=B_MSISDN;'
NODE='HLR' TRANSFORM='none' USERNAME=_athome' PASSWORD=_athome'/>

Where SUBSCRIBER_MSISDN is the MSISDN of the subscriber for which unconditional call forwarding
must be set, and B_MSISDN is the MSISDN to which calls must be forwarded unconditionally.

Going forward, in addition to the above, the @Home platform is required to issue a request to the
subscriber’s HLR via USA to enable operator determined barring of roaming. To achieve this, @Home shall
send a HTTP POST request to USA, containing the following XML as a POST parameter labelled
“command”;

Table 6 - USA HGSDC Command (Enabling Operator Determined Barring of Roaming)

<usareq COMMAND='HGSDC:MSISDN=SUBSCRIBER_MSISDN,SUD=OBR-2'
NODE='HLR' TRANSFORM='none' USERNAME_athome' PASSWORD=_athome'/>

Page 12 of 17
 @Home – Roaming Disablement on HLRs – Functional Requirements Specification

WHERE SUBSCRIBER_MSISDN is the MSISDN of the subscriber for which roaming outside of their PLMN
country should be barred.

The following can be expected in response to the above USA request;

Table 7 - USA HGSDC Response (Enabling Operator Determined Barring of Roaming)

<?xml version="1.0" encoding="UTF-8"?>

<usarsp COMMAND="HGSDC:MSISDN=27831234567,SUD=OBR-2;" NSTANCE="nlusa03"
NODE="HLR" REQ_ID="1416040739966_150495237" RESPONSE_TIME="53"
SUCCESSFUL

SVC_RESULT="F" TRANSFORM="none" USERNAME=" _athome">

<data>
<![CDATA[HGSDC:MSISDN=27831234567,SUD=OBR-2;EXECUTED]]>
</data>
</usarsp>
<?xml version="1.0" encoding="UTF-8"?>
<usarsp COMMAND=" HGSDC:MSISDN=27831234567,SUD=OBR-2;" INSTANCE="nlusa03"
NODE="HLR" REQ_ID="1416040739966_150571588" ESPONSE_TIME="24"
SVC_RESULT="T" TRANSFORM="none" USERNAME=" _athome">
<error>
UNSUCCESSFUL

<terminationCode>
<application>VAS-C</application>
<service>hlr</service>
<type>SERVICE_ERROR</type>
<message>Primary HLR lookup failed for MSISDN [27831234]</message>
</terminationCode>
</error>
</usarsp>

In the above responses, the ‘SVC_RESULT’ field denotes whether the request was successful or a failure
(i.e. when ‘SVC_RESULT equals “F” the request shall be deemed a success, and when ‘SVC_RESULT’
equals “T” the request shall be deemed a failure).

In the case where the CFU change request fails, the @Home platform shall not change the subscriber’s
OBR status, and shall return an error to the mobile application, which shall in turn present a user-friendly
error message;

“Your request could not be processed. Please try again later.”

Page 13 of 17
 @Home – Roaming Disablement on HLRs – Functional Requirements Specification

In the case where the CFU change request is successful, but the OBR change request fails, the @Home
platform shall attempt to roll back the CFU change, and return an error to the mobile application. The
mobile application shall in turn present a user-friendly error message;

“Your request could not be processed. Please try again later.”

In the case where both the CFU and OBR change requests are successful, the @Home platform shall
return success message to the mobile application, which shall in turn present the in-app dialler as
performed.

The typical process sequence when the subscriber enables their unconditional call forwarding via the
mobile app going forward, shall be as follows;

User Mobile  App @Home USA User's  HLR

Enable  call  forwarding

Enable  call  forwarding

usareq
(command,  node,  t ransform,  username,  password)
Determine
subscriber  HLR

HGSSI  command

Success

Prepare
response

Success  response

Determine
subscriber  HLR

HGSDC  command

Success

Prepare
response
Success  response

Success  response

Present  dialler

Figure 2-1 - New Process Flow for Enablement of Call Forwarding to @Home Platform

Page 14 of 17
 @Home – Roaming Disablement on HLRs – Functional Requirements Specification

2.4 Reverting of Call Forwarding and Roaming State

Currently, when a subscriber disables call forwarding in the @Home mobile application, the @Home
platform issues a command to the subscriber’s HLR via USA to disable their unconditional call forwarding.
In order to do this, @Home sends an HTTP POST request to USA, containing the following XML as a
POST parameter labelled “command”;

Table 8 - USA HGSSE Command (Unsetting of Unconditional Call Forwarding)

<usareq COMMAND='HGSSE:MSISDN=SUBSCRIBER_MSISDN,SS=CFU,BSG=TS10;' NODE='HLR'

TRANSFORM='none' USERNAME=_athome' PASSWORD=_athome'/>

Where SUBSCRIBER_MSISDN is the MSISDN for the subscriber for which call forwarding must be
disabled.

Going forward, in addition to the above, the @Home platform is required to issue a request to the
subscriber’s HLR via USA to revert their operator determined barring of roaming to its former state (as
stored prior to setting call forwarding and enabling operator determined barring of roaming). To achieve
this, @Home shall send an HTTP POST request to USA, containing the following XML as a POST
parameter labelled “command”;

Table 9 - USA HGSDC Command (Reverting of Operator Determined Barring of Roaming Status)

<usareq COMMAND='HGSDC:MSISDN=SUBSCRIBER_MSISDN,SUD=OBR-PREVIOUS_OBR_STATE'
NODE='HLR' TRANSFORM='none' USERNAME=_athome' PASSWORD=_athome'/>

Where SUBSCRIBER_MSISDN is the MSISDN of the subscriber for which operator determined barring of
roaming is being changed, and PREVIOUS_OBR_STATE is the previous state of the subscriber’s operator
determined barring of roaming field, as stored for that subscriber on the @Home platform.

The following can be expected in response to the above USA request;

Page 15 of 17
 @Home – Roaming Disablement on HLRs – Functional Requirements Specification

Table 10 - USA HGSDC Response (Reverting of Operator Determined Barring of Roaming)

<?xml version="1.0" encoding="UTF-8"?>

<usarsp COMMAND="HGSDC:MSISDN=27831234567,SUD=OBR-2;" NSTANCE="nlusa03"
NODE="HLR" REQ_ID="1416040739966_150495237" RESPONSE_TIME="53"
SUCCESSFUL

SVC_RESULT="F" TRANSFORM="none" USERNAME=" _athome">

<data>
<![CDATA[HGSDC:MSISDN=27831234567,SUD=OBR-2;EXECUTED]]>
</data>
</usarsp>
<?xml version="1.0" encoding="UTF-8"?>
<usarsp COMMAND=" HGSDC:MSISDN=27831234567,SUD=OBR-2;" INSTANCE="nlusa03"
NODE="HLR" REQ_ID="1416040739966_150571588" ESPONSE_TIME="24"
SVC_RESULT="T" TRANSFORM="none" USERNAME=" _athome">
<error>
UNSUCCESSFUL

<terminationCode>
<application>VAS-C</application>
<service>hlr</service>
<type>SERVICE_ERROR</type>
<message>Primary HLR lookup failed for MSISDN [27831234]</message>
</terminationCode>
</error>
</usarsp>

In the above responses, the ‘SVC_RESULT’ field denotes whether the request was successful or a failure
(i.e. when ‘SVC_RESULT equals “F” the request shall be deemed a success, and when ‘SVC_RESULT’
equals “T” the request shall be deemed a failure).

In the case where the CFU change request fails, the @Home platform shall not change the subscriber’s
OBR status, and shall return an error to the mobile application, which shall in turn present a user-friendly
error message;

“Your request could not be processed. Please try again later.”

In the case where the CFU change request is successful, but the OBR change request fails, the @Home
platform shall attempt to roll back the CFU change (i.e. set call forwarding back to the @Home platform),
and return an error to the mobile application. The mobile application shall in turn present a user-friendly
error message;

“Your request could not be processed. Please try again later.”

Page 16 of 17
 @Home – Roaming Disablement on HLRs – Functional Requirements Specification

The typical process sequence when the subscriber disables their unconditional call forwarding via the
mobile app going forward, shall be as follows;

User Mobile  App @Home USA User's  HLR

Disable  call  forwarding

Disable  call  forwarding

usareq
(command,  node,  transform,  username,  password)
Determine
subscriber  HLR

HGSSE  command

Success

Prepare
response

Success  response

Determine
subscriber  HLR

HGSDC  command

Success

Prepare
response
Success  response

Success  response

Hide  dialler  /  show  l ogin  screen

Figure 2-2 - New Process Flow Sequence for Disablement of Call Forwarding

2.5 Additional Functional Requirements

2.5.1 Additional Error Logging

• @Home shall log all cases of HLR command failures. I.e. errors shall be logged in the following
failure cases;
o Subscriber TS10 supplementary data / permanent user data query (i.e. HGSDP command)
o Unconditional call forwarding (CFU) set request (i.e. HGSSI command)
o Unconditional call forwarding (CFU) unset request (i.e. HGSSE command)
o Operator determined barring of roaming (OBR) change request (i.e. HGSDC command)

Page 17 of 17