Configuration Guide for End User Notifications
Ericsson Service-Aware Policy Controller

Contents

1Introduction
1.1Document Purpose and Scope
1.2Revision Information
1.3Typographic Conventions
1.4Other Conventions

2
Configuration Prerequisites

3
Configure Notification Network Data
3.1Configure Notifications Delivery
3.2Configure Notification Servers
3.2.1Configure SMS Centers
3.2.2Configure Web Service End Points
3.3Configure Notification Destinations
3.3.1Notifications Sent to End Users
3.3.2Notifications Sent to External Systems

4
Provisioning Notification Policies
4.1Notifications Sent to End Users
4.2Notifications Sent to External Systems
4.3Notification Sent to End Users and to External Systems
4.4Dynamic Notification Message Content
4.5Encoding Schemes in Notification Messages

5
Configuration Examples for Use Cases
5.1Notifications Based on Fair Usage
5.1.1Notifications to be sent to Subscribers
5.1.2Notifications and Shared Dataplans
5.2Notifications Based on Subscriber Group Activation or Deactivation

6
Appendix A. End User Notifications Policy Types

Glossary

Abstract

This document is a guideline to configure the SAPC for End User Notifications.


1   Introduction

1.1   Document Purpose and Scope

Next figure, shows the main parts related to configuration and provisioning in the the SAPC.

Figure 1   Configuration and Provisioning Overview

The purpose of this document is to provide a guideline for configuring End User Notifications in the SAPC by providing some configuration examples.

This document does not intend to be an exhaustive guide for configuring all possibilities related to End User Notifications in the SAPC.

The complete parameter list and details of all configuration options of the SAPC are included in separate documents, refer to Managed Object Model (MOM) and Provisioning REST API.

General concepts on how to provision Subscribers, Subscriber Groups and how to configure policies are covered in Configuration Guide for Subscription and Policies.

Examples on this document cover the case of data configured in the SAPC internal repository. In case an external repository is used, refer to Database Access.

1.2   Revision Information

Rev. A This is the first release of this document.

1.3   Typographic Conventions

The following typographic and document conventions are used:

Table 1    Typographic Conventions

Convention

Description

Example

Representational State Transfer (REST)

SAPC REST provisioning.


Exact REST resources, methods, attibutes, or their corresponding values.

PUT /dataplans/Silver

{
  "dataplanName" : "Silver",
  "notification" : "sms"
}

Managed Object Class (MOC)


or Attributes value

Exact COM model object, classes names, attributes, or their corresponding values.

SmsCenter


enableDelivery=true

NETCONF

SAPC COM configuration

<edit-config>
  <target>
    <running />
  </target>
  <config>
   <ManagedElement
      xmlns="urn:com:ericsson:ecim:ComTop">
    <managedElementId>
      1
    </managedElementId>
    <PolicyControlFunction
      xmlns="urn:com:ericsson:ecim:sapcmom">
       <policyControlFunctionId>
          1
       </policyControlFunctionId>
       <NotificationConfig
       xmlns="urn:com:ericsson:
       ecim:notificationconfigmom">
        <notificationConfigId>
          1
        </notificationConfigId>
        <enableDelivery>
          true
        </enableDelivery>
       </NotificationConfig>
    </PolicyControlFunction>
   </ManagedElement>
  </config>
</edit-config>

1.4   Other Conventions

This document refers to some configuration and provisioning data.

To clarify which detailed data is managed by COM or by the REST API, this document uses the following conventions:

2   Configuration Prerequisites

Before configuring the SAPC in an operational network, assure that:

3   Configure Notification Network Data

In End User Notifications, it is possible to differentiate the following types of notifications:

To make the SAPC possible to send notifications, it is needed to:

  1. Enable notifications to be delivered, see Section 3.1
  2. Configure the notification servers where the SAPC sends the notifications. The notification server is responsible for sending the notifications to the end user or to the external system. See Section 3.2
  3. Configure the subscriber notification destination that includes mechanism or address. The specific configuration depends on the type of notification: end user or External System, see Section 3.3
  4. Specify the business condition that triggers the notification, by provision notification policies. Specify the content of the notification message, and associated mechanism and destination. Section 4
    Note:  
    Some specific details of the notification policies are configured in different ways depending on the notification type: end user or External Systems.

Next figure shows the main elements to configure to send notifications to End Users:

Figure 2   Notifications sent to End Users

Next figure shows the main elements to configure to send Notifications to External Systems:

Figure 3   Notifications sent to External Systems

Following sections contain the configuration details in a progressive way.

3.1   Configure Notifications Delivery

Notifications can be enabled or disabled using NotificationConfig COM object.

  1. To enable notifications to be sent, set enableDelivery attribute to true.

  2. To disable notifications, set enableDelivery attribute to false.

Next, the example to enable notifications:

Example 1   Configuration of delivery notifications

<edit-config>
   <target>
      <running />
   </target>
   <config>
      <ManagedElement xmlns="urn:com:ericsson:ecim:ComTop">
         <managedElementId>1</managedElementId>
         <PolicyControlFunction xmlns="urn:com:ericsson:ecim:sapcmom">
            <policyControlFunctionId>1</policyControlFunctionId>
       	    <NotificationConfig xmlns="urn:com:ericsson:ecim:notificationconfigmom">
               <notificationConfigId>1</notificationConfigId>
               <enableDelivery>true</enableDelivery>
            </NotificationConfig>
         </PolicyControlFunction>
      </ManagedElement>
   </config>
</edit-config>

3.2   Configure Notification Servers

Attention!

To adapt the SAPC depending on the behavior of the notification servers (for example number of connections, notification response time including network delay), contact Ericsson personnel.

In this section, it is explained how to configure the notification servers towards the SAPC send notifications.

3.2.1   Configure SMS Centers

In the SAPC, it is possible to configure only one SmsCenter COM object and several children SmsDestination COM object. Then, the SAPC sends each SMS message, towards a different SMS destination, selecting the SMS destination using a round robin algorithm.

Next, an example on how an SmsCenter with one SmsDestination is configured:

Example 2   Configuration of one SmsDestination

<edit-config>
   <target>
      <running/>
   </target>
   <config>
      <ManagedElement xmlns="urn:com:ericsson:ecim:ComTop">
         <managedElementId>1</managedElementId>
         <PolicyControlFunction xmlns="urn:com:ericsson:ecim:sapcmom">
            <policyControlFunctionId>1</policyControlFunctionId>
            <Network xmlns="urn:com:ericsson:ecim:networkmom">
               <networkId>1</networkId>
               <SmsCenter xmlns="urn:com:ericsson:ecim:smscentermom">
                  <smsCenterId>1</smsCenterId>
                  <SmsDestination xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" 
                                        nc:operation="merge">
                     <smsDestinationId>159.107.22.33</smsDestinationId>
                     <serverPort>2775</serverPort>
                     <serverUser>SAPC</serverUser>
                     <serverPwd>
                        <cleartext></cleartext>
                        <password>Password</password>
                     </serverPwd>
                     <serverTonDestination>3</serverTonDestination>
                     <serverTonOrigin>3</serverTonOrigin>
                     <serverNpiOrigin>14</serverNpiOrigin>
                     <serverNpiDestination>14</serverNpiDestination>
                  </SmsDestination>
               </SmsCenter>
            </Network>
         </PolicyControlFunction>
      </ManagedElement>
   </config>
</edit-config>

The previous example configures a single SmsDestination child of the SmsCenter "1", whose IP address is "159.107.22.33", listening to SMPP protocol on 2775 port. The connection to this server is done using user "SAPC" and password "Password".

3.2.2   Configure Web Service End Points

It is possible to configure several Web Service End-Point servers. Each of one of these servers represented by the corresponding WebServiceEndPoint COM object, has common properties shared among their children represented by WsDestination COM object. In case a WebServiceEndPoint has several WsDestination children configured under it, the notification is sent to one of them following a round robin algorithm.

Next, an example on how to configure several WebServiceEndPoint and WsDestination COM objects:

Example 3   Configuration of several WebServiceEndPoint and WsDestination objects

<edit-config>
  <target>
    <running/>
  </target>
  <config>
    <ManagedElement xmlns="urn:com:ericsson:ecim:ComTop">
      <managedElementId>1</managedElementId>
      <PolicyControlFunction xmlns="urn:com:ericsson:ecim:sapcmom">
        <policyControlFunctionId>1</policyControlFunctionId>
        <Network xmlns="urn:com:ericsson:ecim:networkmom">
          <networkId>1</networkId>
            <WebServiceEndPoints xmlns="urn:com:ericsson:ecim:webserviceendpointsmom">
            <webServiceEndPointsId>1</webServiceEndPointsId>
              <WebServiceEndPoint xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" 
                                  nc:operation="merge">
              <webServiceEndPointId>BBSC</webServiceEndPointId>
                <connectionTimeout>3000</connectionTimeout>
                <maxNumberRetries>1</maxNumberRetries>
                <soapAction>http://operator1.org/abc#MySoapNotif</soapAction>
                <WsDestination xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" 
                               nc:operation="merge">
                  <wsDestinationId>http://10.1.22.337:11222/webservice/service1
                  </wsDestinationId>
                  <httpProxy></httpProxy>
                </WsDestination>             
                <WsDestination xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" 
                               nc:operation="merge">
                  <wsDestinationId>http://10.1.22.338:11222/webservice/service2
                  </wsDestinationId>
                  <httpProxy>http://134.15.20.229:11000</httpProxy>
                </WsDestination>
              </WebServiceEndPoint>
              <WebServiceEndPoint xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" 
                                  nc:operation="merge">
              <webServiceEndPointId>WsUsageLimitSurpassed</webServiceEndPointId>
                <connectionTimeout>3000</connectionTimeout>
                <maxNumberRetries>1</maxNumberRetries>
                <soapAction>post</soapAction>
                <WsDestination xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" 
                               nc:operation="merge">
                  <wsDestinationId>http://10.1.22.339:11222/webservice/service3
                  </wsDestinationId>
                  <httpProxy>http://134.15.20.229:11000</httpProxy>
                </WsDestination>
              </WebServiceEndPoint>
              <WebServiceEndPoint xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" 
                                  nc:operation="merge">
              <webServiceEndPointId>WebServiceEndPoint1</webServiceEndPointId>
                <connectionTimeout>3000</connectionTimeout>
                <maxNumberRetries>1</maxNumberRetries>
                <soapAction>post</soapAction>
                <WsDestination xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" 
                                  nc:operation="merge">
                  <wsDestinationId>http://192.168.14.42:11222</wsDestinationId>
                  <httpProxy></httpProxy>
                </WsDestination>
              </WebServiceEndPoint>
              <WebServiceEndPoint xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" 
                                  nc:operation="merge">
              <webServiceEndPointId>WebServiceEndPoint2</webServiceEndPointId>
                <connectionTimeout>3000</connectionTimeout>
                <maxNumberRetries>1</maxNumberRetries>
                <soapAction>post</soapAction>
                <WsDestination xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" 
                               nc:operation="merge">
                  <wsDestinationId>http://192.168.14.42:11222</wsDestinationId>
                  <httpProxy></httpProxy>
                </WsDestination>
              </WebServiceEndPoint>
            </WebServiceEndPoints>
        </Network>
      </PolicyControlFunction>
    </ManagedElement>
  </config>
</edit-config>

The Example 3 configures four WebServiceEndPoint objects (BBSC, WsUsageLimitSurpassed, WebServiceEndPoint1 and WebServiceEndPoint2) under the WebServiceEndPoints object "1". The WebServiceEndPoint object "BBSC" has two WsDestination. First one with URL http://10.1.22.337:11222 and no httpProxy configured and second one with URL http://10.1.22.338:11222 and httpProxy http://134.15.20.229:11000. The WebServiceEndPoint object "WsUsageLimitSurpassed" has only one WsDestination configured with URL http://10.1.22.339:11222 and httpProxy http://134.15.20.229:11000. The latter WebServiceEndPoint objects, "WebServiceEndPoint1" and "WebServiceEndPoint2", share the same WsDestination (http://192.168.14.42:11222) with no httpProxy attached.

3.3   Configure Notification Destinations

Next step is to configure the destination of the notifications.

3.3.1   Notifications Sent to End Users

The address for notifications sent to end users can be provisioned at subscriber or at subscriber group level.

Next, an example of provisioning of a notification address at subscriber level:

Example 4   Configuration of SMS Notification Data at subscriber level

PUT /subscribers/34600010101
{
    "dataplans" : 
    [
        {
            "dataplanName" : "Silver"
        }
    ],
    "smsDestinations" : [ "+341111111" ],
    "subscriberId" : "34600010101"
}

Next, an example of provisioning at subscriber group level:

Example 5   Configuration of SMS Notification Data at subscriber group level

PUT /dataplans/Gold
{
	"dataplanName" : "Gold",
	"notification" : "sms"
}

PUT /subscribers/34600010201
{
	"dataplans" : 
	[
		{
			"dataplanName" : "Gold"
		}
	],
	"subscriberId" : "34600010201"
}

3.3.2   Notifications Sent to External Systems

In the SAPC when the destination of a notification is not a subscriber but an external system it is needed to configure:

The notification mechanisms available for external systems are SMS and SOAP.

4   Provisioning Notification Policies

The final step for configuring notifications is to configure notification policies as it is shown in the following steps:

For configuration examples containing notification policies, see Section 5.

Warning!

Regarding the business condition that causes the notification to be sent: The same notification message can be sent several times if policy tags whose value can be different for several concurrent active IP-CAN sessions of a Subscriber are used.

For example, this can happen with the following:
AccessData.subscriber.ueIpAddress,
AccessData.subscriber.session.accumulatedUsage.reportingGroup[x].isLimitSurpassed and
AccessData.bearer.accessPoint.
Therefore, to avoid this notification repetition, Ericsson does not recommend using this kind of policy tags.

4.1   Notifications Sent to End Users

For end users notifications, fill the attribute attrValue of outputAttributes, using the following syntax:

"<notification message>"

Next, an example on how to configure the notification data message for end users notifications:

Example 6   Configuration of Notification Data Message for End Users 

PUT /rules/rFirstBidirVolumeLimitSurpassed
{
    "condition" : "AccessData.subscriber.accumulatedUsage.reportingGroup[\"401\"].
                   isLimitSurpassed[\"bidirVolume\"][0]",
    "outputAttributes" : 
    [
        {
            "attrName" : "notification",
            "attrValue" : "\"First bidir Volume Limit Surpassed for reportingGroup 401\"",
            "result" : "permit"
        }
    ],
    "ruleName" : "rFirstBidirVolumeLimitSurpassed"
}

4.2   Notifications Sent to External Systems

Next figure shows the detailed elements to configure for sending notifications to external systems:

Figure 4   Elements to configure notifications to send to External Systems

In notifications sent to External Systems, the attrValue attribute contained in the outputAttributes object contains the notification receiver identities and the notification text, using the following syntax:

NotificationReceivers[ <notification msg> ]

NotificationReceivers is an instance name of an EDSource COM object. This NotificationReceivers includes both the list of the notification destinations and the notification message.

Thus, to configure in the SAPC a NotificationReceivers, create an EDSource COM object and fill:

Next the syntax of the main elements of the definition attribute of a NotificationReceivers EDSource:

def NotificationReceivers( msg ){
       dataSource = { url = ""; query = “"; }
       fieldDef = {
          sms = “MobileNumber1,MobileNumber2,...,MobileNumberN”;
          ws = “WebServiceEndPoint1,...,WebServiceEndPointN”;
          notifMsg = arg( "msg" ); }

Warning!

Do not include in the same notification receiver a SOAP destination with SMS destination because the message format is not compatible.

Following with NotificationReceivers, it contains the notification text and depending on the type of mechanism the format is different:

Configure SMS Notification Message

For SMS mechanism, fill it with the notification message text following this syntax:

NotificationReceivers[" < Notification message text > "]

Next, an example of both outputAttributes object and NotificationReceivers EDSource object to configure NotificationReceivers for SMS mechanism:

Example 7   Configuration of outputAttributes object with NotificationReceivers for SMS Notifications for SMS Notifications

PUT /rules/rFirstBidirVolumeLimitSurpassed
{
    "condition" : "AccessData.subscriber.accumulatedUsage.reportingGroup[\"401\"].
                   isLimitSurpassed[\"bidirVolume\"][0]",
    "outputAttributes" : 
    [
        {
            "attrName" : "notification",
            "attrValue" : "\"First bidir Volume Limit Surpassed for reportingGroup 401\"",
            "result" : "permit"
        },
        {
            "attrName" : "notification",
            "attrValue" : "SmsNotifReceivers[\"First bidir Volume Limit Surpassed for reportingGroup 401\"]",
            "result" : "permit"
        }
    ],
    "ruleName" : "rFirstBidirVolumeLimitSurpassed"
}

Example 8   Configuration of NotificationReceivers EDSource object for SMS notifications

<edit-config>
  <target>
    <running/>
  </target>
  <config>
    <ManagedElement xmlns="urn:com:ericsson:ecim:ComTop">
      <managedElementId>1</managedElementId>
      <PolicyControlFunction xmlns="urn:com:ericsson:ecim:sapcmom">
        <policyControlFunctionId>1</policyControlFunctionId>
        <EntityData xmlns="urn:com:ericsson:ecim:entitydatamom">
          <entityDataId>1</entityDataId>
          <EDSources xmlns="urn:com:ericsson:ecim:edsourcesmom">
            <eDSourcesId>1</eDSourcesId>                   
            <EDSource xmlns="urn:com:ericsson:ecim:edsourcemom" 
                             xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" 
                             nc:operation="merge">
              <eDSourceId>SmsNotifReceivers</eDSourceId>
              <definition>
                def SmsNotifReceivers ( msg )
                {
                  dataSource = {
                    url = "";
                    query = "";
                  }
                  fieldDef = {
                    sms = "+34609102030,+34609908070";
                    notifMsg = arg( "msg" );
                  }
                }
              </definition>
            </EDSource>
          </EDSources>
        </EntityData>
      </PolicyControlFunction>
    </ManagedElement>
   </config>
</edit-config>

The previous examples represent the SmsNotifReceivers eDSource that contains two destinations: the first one corresponds to the mobile number +34609102030 and the second one corresponds to the mobile number +34609908070. The notification text "First bidir Volume Limit Surpassed for reportingGroup Total" is passed to SmsNotifReceivers.

Configure SOAP Notification Message

For SOAP mechanism, fill it with the notification message text following this syntax:

NotificationReceivers[<New eDSourceId>[<arg1,...,argN>].xmlText]

In SOAP mechanism, instead of specifying the notification message itself, it can be formatted in an XML message. The XML message content depends on what the external Web Service End Point service needs.

To configure in the SAPC the XML message content, create another EDSource COM object with a xmlText fieldDef that contains the XML notification text. This new EDSource COM object is the argument of the notification receiver EDSource mentioned before and it can receive several input arguments. The input arguments serve to pass variable values inside the content of the XML message. This can be done using policy tags (see Section 4.4) as input arguments.

Next an example on how to configure a NotificationReceivers EDSource for SOAP Notifications:

Example 9   Configuration of the outputAttributes object for SOAP notifications

PUT /rules/rSecondBidirVolumeLimitSurpassed
{
    "condition" : "AccessData.subscriber.accumulatedUsage.reportingGroup[\"401\"].
                   isLimitSurpassed[\"bidirVolume\"][1]",
    "outputAttributes" : 
    [
        {
            "attrName" : "notification",
            "attrValue" : "SOAPNotificationReceivers[SOAPNotification[AccessData.
                           subscriber.msisdn, AccessData.subscriber.imsi].xmlText]",
            "result" : "permit"
        }
    ],
    "ruleName" : "rSecondBidirVolumeLimitSurpassed"
}

Example 10   Configuration of NotificationReceivers EDSource object for SOAP notifications

<edit-config>
  <target>
    <running/>
  </target>
  <config>
    <ManagedElement xmlns="urn:com:ericsson:ecim:ComTop">
      <managedElementId>1</managedElementId>
      <PolicyControlFunction xmlns="urn:com:ericsson:ecim:sapcmom">
        <policyControlFunctionId>1</policyControlFunctionId>
        <EntityData xmlns="urn:com:ericsson:ecim:entitydatamom">
          <entityDataId>1</entityDataId>
          <EDSources xmlns="urn:com:ericsson:ecim:edsourcesmom">
            <eDSourcesId>1</eDSourcesId>                   
            <EDSource xmlns="urn:com:ericsson:ecim:edsourcemom" 
                      xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" 
                         nc:operation="merge">
              <eDSourceId>SOAPNotificationReceivers</eDSourceId>
              <definition>
                def SOAPNotificationReceivers ( msg )
                {
                  dataSource = {
                    url = "";
                    query = "";
                  }
                  fieldDef = {
                    notifMsg = arg( "msg" );
                    ws = "WebServiceEndPoint1,WebServiceEndPoint2";
                  }
                }
              </definition>
            </EDSource>
          </EDSources>
        </EntityData>
      </PolicyControlFunction>
    </ManagedElement>
  </config>
</edit-config>

The preceding examples represent the SOAPNotificationReceivers eDSource object that contains two destinations: WebServiceEndPoint1 and WebServiceEndPoint2.

See next table to understand how input arguments are used:

Table 2    Example of Policy tags to use as Input Parameters in SOAP Notifications

XML Argument

Argument in SOAPNotification

SOAP Input Argument

MSISDN

arg1

AccessData.subscriber.msisdn

IMSI

arg2

AccessData.subscriber.imsi

Next an example on how to create the EDSource object for the SOAP message, with the arguments of the example above:

Example 11   Configuration by means of an EDSource for the SOAP notification text

<edit-config>
  <target>
   <running/>
  </target>
   <config>
    <ManagedElement xmlns="urn:com:ericsson:ecim:ComTop">
      <managedElementId>1</managedElementId>
        <PolicyControlFunction xmlns="urn:com:ericsson:ecim:sapcmom">
          <policyControlFunctionId>1</policyControlFunctionId>
            <EntityData xmlns="urn:com:ericsson:ecim:entitydatamom">
               <entityDataId>1</entityDataId>
                 <EDSources xmlns="urn:com:ericsson:ecim:edsourcesmom">
                   <eDSourcesId>1</eDSourcesId>
                     <EDSource xmlns="urn:com:ericsson:ecim:edsourcemom"
                               xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
                               nc:operation="merge">
                      <eDSourceId>SOAPNotification</eDSourceId>
                        <definition>
                           def SOAPNotification( arg1, arg2 )
                            {
                              dataSource = {
                              url = "";
                              query = "";
                              }
                              fieldDef = {
                              xmlText = <![CDATA["<soapenv:Envelope xmlns:soapenv='http://schemas.xmlsoap.org/soap/envelope/'
                                                            xmlns:xsd='http://wwww.w3.org/2001/XMLSchema'
                                                            xmlns:xsi='http://www.w3.org/2001/XMLSchema-Instance'
                                                            xmlns:tns='http://ericsson.com/sapc/soapnotifications'>
                                               <soapenv:Body>
                                                 <tns:SAPCNotification xmlns:soapNotifTypes='http://ericsson.com/sapc/soapnotifications/types'>
                                                    <Message>
                                                       <EventType>notification</EventType>
                                                       <MSISDN>" + arg(arg1) + "</MSISDN>
                                                       <IMSI>" + arg(arg2) + "</IMSI>
                                                     </Message>
                                                  </tns:SAPCNotification>
                                                </soapenv:Body>
                                          </soapenv:Envelope>";
                                 ]]>
                              }
                           }
                        </definition>
                     </EDSource>
                 </EDSources>
            </EntityData>
        </PolicyControlFunction>
    </ManagedElement>
   </config>
</edit-config>

The SOAPNotification eDSource of the example contains an XML format text with next predefined sections:

Warning!

Only SOAP 1.1 protocol is supported, so the SOAP message format and namespaces values has to be configured accordingly.

4.3   Notification Sent to End Users and to External Systems

When the same business condition is wanted to be triggered towards different nature destinations, the SAPC can combine it to send to end users and external systems, by adding several elements into the outputAttributes object.

Next an example on how to combine both notifications types:

Example 12   Combination of Notification Data Message for End Users and External Systems

PUT /rules/rFirstBidirVolumeLimitSurpassed_1
{
    "condition" : "AccessData.subscriber.accumulatedUsage.reportingGroup[\"total\"].
                   isLimitSurpassed[\"bidirVolume\"][0]",
    "outputAttributes" : 
    [
        {
            "attrName" : "notification",
            "attrValue" : "\"Usage limit has been surpassed, please visit ou
                             r portal to extend your subscribed limit\"",
            "result" : "permit"
        },
        {
            "attrName" : "notification",
            "attrValue" : "SmsNotifReceivers[\"First bidir Volume Limit Surpassed\"]",
            "result" : "permit"
        },
        {
            "attrName" : "notification",
            "attrValue" : "SOAPNotificationReceivers[SOAPNotification[AccessData.
                           subscriber.msisdn].xmlText]",
            "result" : "permit"
        }
    ],
    "ruleName" : "rFirstBidirVolumeLimitSurpassed_1"
}

In the example above, the first notification is a SMS notification sent to the subscriber configured (see Example 4 or Example 5), the second one is sent to the list of destinations specified within “SmsNotifReceivers” that sends the notification using SMS mechanism, and the last one is sent to the list of destinations specified within “SOAPNotificationReceivers” that sends the notification using SOAP mechanism.

4.4   Dynamic Notification Message Content

It is possible to include dynamic information within the notification message, by using any of the provided policy tags in Configuration Guide for Access and Charging Control (Gx) , Configuration Guide for Fair Usage and policy functions in Configuration Guide for Subscription and Policies.

For example, consider that several Subscription-Ids are received in the Gx traffic request, that the MSISDN is used to locate the subscriber profile (and in receipt of destination for the SMS), but consider that the IMSI is wanted to be included in the notification message. An outputAttributes like the following can be used:

"outputAttributes" :
[           
  {
    "attrName" : "notification",
    "attrValue" : "strcat(\"Subscriber is roaming, 
                          IMSI=\",AccessData.subscriber.imsi)",
    "result" : "permit"
  }
]

Another example: Imagine it is wanted to include in the notification message the current Fair Usage accumulator and expiration date at the end of each session (business condition AccessData.bearer.requestType==3). A dynamic string composition for the notification message is needed, to produce a message such as the following:

You have consumed: <XX> KBytes. Your subscription is valid till: <dd-mm-yyyyThh:mm:ss>

The configuration to be done in the rule resource is the following:

Example 13   Configuration to include dynamic information within the notification message

PUT /rules/r_notifDynamicTextVolume
{
    "condition" : "AccessData.bearer.requestType == 3",
    "outputAttributes" : 
    [
        {
            "attrName" : "notification",
            "attrValue" : "strcat(\"You have consumed: \",
                           strcat( AccessData.subscriber.accumulatedUsage.reportingGroup[\"total\"].
                                   current[\"bidirVolume\"],
                           strcat(\" KBytes.\",
                           strcat(\" Your subscription is valid till: \",
                                     AccessData.subscriber.accumulatedUsage.reportingGroup[\"total\"].
                                     expiryDate[\"volume\"] ))))",
            "result" : "permit"
        }
    ],
    "ruleName" : "r_notifDynamicTextVolume"
}

4.5   Encoding Schemes in Notification Messages

The SAPC supports the following encoding schemes:

When the notification message contains non-ASCII characters (for example for notification messages to be sent in chinese, arabic or cyrillic alphabet), use Base64 format for the value of the attrValue attribute within the outputAttributes object.

5   Configuration Examples for Use Cases

5.1   Notifications Based on Fair Usage

5.1.1   Notifications to be sent to Subscribers

Let us suppose a Subscriber Fair Usage with limits for total traffic (IP-CAN session):

Example 14   Configuration of a Subscriber Fair Usage Profile

PUT /subscribers/34600000200
{
    "subscriberId" : "34600000200",
    "smsDestinations" : [ "+341111111" ],
    "usageLimits" : 
    [
        {
            "absoluteLimits" : 
            {
                "bidirVolume" : [ 1572864, 2097152 ],
                "resetPeriod" : 
                {
                    "volume" : "monthly day 12 19:30"
                }
            },
            "description" : "Total traffic"
        }
    ]
}

And, next an example of configuration of a notification policy based on limits surpassed:

Example 15   Configuration of Notification Policy based on Fair Usage

PUT /rules/notifRuleVolumeLimit
{
    "condition" : "AccessData.subscriber.accumulatedUsage.reportingGroup[\"total\"].
                   isLimitSurpassed[\"bidirVolume\"][1]",
    "outputAttributes" : 
    [
        {
            "attrName" : "notification",
            "attrValue" : "\"Usage limit has been surpassed, please visit our portal to ex
                             tend your subscribed limit\"",
            "result" : "permit"
        }
    ],
    "ruleName" : "notifRuleVolumeLimit"
}

PUT /policies/notifPolicyVolumeLimit
{
    "policyName" : "notifPolicyVolumeLimit",
    "ruleCombiningAlgorithm" : "all-permit",
    "rules" : [ "notifRuleVolumeLimit" ]
}

PUT /locators/resources/any/contexts/notification
{
    "policies" : [ "notifPolicyVolumeLimit" ]
}

With the configuration above, a notification is sent for all subscribers when their respective provisioned usage limit, for total traffic (IP-CAN session), is reached. The notification text is the one specified in the attrValue attribute.

For the particular case of Subscriber 34600000200 (see Example 14) the limit considered for sending the notification is 2 Gbytes; the notification is sent using SMS mechanism (see Example 4 smsDestinations attribute) and the SAPC uses the data configured in to send the notification through the SMS center.

5.1.2   Notifications and Shared Dataplans

The following examples show how to set the notification policies when the subscribers receiving the notifications are members of a shared dataplan.

Notifications to each member of the Shared Dataplan

Consider a shared dataplan. Individual limits per member are defined and each subscriber wants to be notified when the corresponding individual limit is surpassed. To model this, it is necessary to define a notification policy per individual limit.

Next an example of this use case that extends the configuration of a Fair Usage use case. See the Fair Usage related configuration in Configuration Guide for Fair Usage:

Example 16   Configuration of Notifications For Members of a Shared Subscriber Plan

PUT /rules/rSubscBLimitSurpassed
{
    "condition" : "(AccessData.subscriber.id==\"34600702041\") && (AccessData.subscriber.
                    accumulatedUsage.reportingGroup[\"1111\"].counter[\"Subsc2\"].
                    isLimitSurpassed[\"bidirVolume\"])",
    "outputAttributes" : 
    [
        {
            "attrName" : "notification",
            "attrValue" : "\"Sublimit established for subscriber 2 has been surpassed\"",
            "result" : "permit"
        }
    ],
    "ruleName" : "rSubscBLimitSurpassed"
}

PUT /rules/rSubscCLimitSurpassed
{
    "condition" : "(AccessData.subscriber.id==\"34600702042\") && (AccessData.subscriber.
                    accumulatedUsage.reportingGroup[\"1111\"].counter[\"Subsc3\"].
                    isLimitSurpassed[\"bidirVolume\"])",
    "outputAttributes" : 
    [
        {
            "attrName" : "notification",
            "attrValue" : "\"Sublimit established for subscriber 3 has been surpassed\"",
            "result" : "permit"
        }
    ],
    "ruleName" : "rSubscCLimitSurpassed"
}

PUT /policies/pIndividualLimitsSurpassed
{
    "policyName" : "pIndividualLimitsSurpassed",
    "ruleCombiningAlgorithm" : "all-permit",
    "rules" : [ "rSubscBLimitSurpassed", "rSubscCLimitSurpassed" ]
}

PUT /dataplans/StreamingSharedPlan/locators/resources/any/contexts/notification
{
    "policies" : [ "pIndividualLimitsSurpassed" ]
}

PUT /dataplans/StreamingSharedPlan
{
    "dataplanName" : "StreamingSharedPlan",
    "notification" : "sms",
    "usageLimits" : 
    [
        {
            "absoluteLimits" : 
            {
                "bidirVolume" : 1228800,
                "conditionalLimits" : 
                [
                    {
                        "bidirVolume" : 307200,
                        "name" : "Subsc2"
                    },
                    {
                        "bidirVolume" : 409600,
                        "name" : "Subsc3"
                    }
                ],
                "resetPeriod" : 
                {
                    "volume" : "monthly"
                }
            },
            "name" : "1111"
        }
    ]
}

In this example, notification is set to "sms" within dataplan, so the notification is sent to the MSISDN of the subscriber for which the notification policies are evaluated. The dataplanName is set to the value of the dataplanName associated to the shared dataplan.

Define one notification per individual limit. To assure that the notification is only sent to the subscriber whose limit is surpassed, it is necessary to include in the condition the particular subscriber Id (AccessData.subscriber.id==\"<...>\") each individual limit applies to ( AccessData.subscriber.accumulatedUsage.reportingGroup[\"1111\"].counter[\"<...>\"].isLimitSurpassed[\"bidirVolume\"]).

Notification to the Head Member of the Shared Dataplan

Consider a shared dataplan. Category limits for shared dataplan members are defined and only the subscriber within "head" category (the head subscriber could typically be the one paying the shared dataplan) is notified when any of the shared dataplan limits is surpassed. To model this, it is necessary to define a notification condition per limit (one for the general shared dataplan limit and one for each category limit).

Here is an example that extends the configuration of a Fair Usage use case. See the Fair Usage related configuration in Configuration Guide for Fair Usage

Example 17   Configuration of Notifications to Head of Shared Subscriber Plan

PUT /rules/rHeadLimitSurpassed
{
    "condition" : "(Subscriber.category==\"head\") && (AccessData.subscriber.accumulatedUsage.
                    reportingGroup[\"Internet\"].counter[\"head\"].
                    isLimitSurpassed[\"bidirVolume\"])",
    "outputAttributes" : 
    [
        {
            "attrName" : "notification",
            "attrValue" : "\"Limit Surpassed for your category\"",
            "result" : "permit"
        }
    ],
    "ruleName" : "rHeadLimitSurpassed"
}

PUT /rules/rRegularLimitSurpassed
{
    "condition" : "(Subscriber.category==\"regular\") && (AccessData.subscriber.accumulatedUsage.
                    reportingGroup[\"Internet\"].counter[\"regular\"].
                    isLimitSurpassed[\"bidirVolume\"])",
    "outputAttributes" : 
    [
        {
            "attrName" : "notification",
            "attrValue" : "\"Limit Surpassed for your category\"",
            "result" : "permit"
        }
    ],
    "ruleName" : "rRegularLimitSurpassed"
}

PUT /rules/rTotalLimitSurpassed
{
    "condition" : "AccessData.subscriber.accumulatedUsage.reportingGroup[\"Internet\"].
                   isLimitSurpassed[\"bidirVolume\"]",
    "outputAttributes" : 
    [
        {
            "attrName" : "notification",
            "attrValue" : "\"Shared Internet limit surpassed\"",
            "result" : "permit"
        }
    ],
    "ruleName" : "rTotalLimitSurpassed"
}

PUT /policies/pInternetNotifications
{
    "policyName" : "pInternetNotifications",
    "ruleCombiningAlgorithm" : "all-permit",
    "rules" : 
    [
        "rRegularLimitSurpassed",
        "rHeadLimitSurpassed",
        "rTotalLimitSurpassed"
    ]
}

PUT /dataplans/InternetSharedPlan/locators/resources/any/contexts/notification
{
    "policies" : [ "pInternetNotifications" ]
}

PUT /subscribers/34600702320
{
    "operatorSpecificInfos" : 
    [
        {
            "attributeName" : "category",
            "attributeValue" : "head"
        }
    ],
    "sharedDataplan" : "DoeFamily",
    "smsDestinations" : [ "34600702320" ],
    "subscriberId" : "34600702320"
}

PUT /subscribers/34600702321
{
    "operatorSpecificInfos" : 
    [
        {
            "attributeName" : "category",
            "attributeValue" : "regular"
        }
    ],
    "sharedDataplan" : "DoeFamily",
    "smsDestinations" : [ "34600702320" ],
    "subscriberId" : "34600702321"
}

PUT /subscribers/34600702322
{
    "operatorSpecificInfos" : 
    [
        {
            "attributeName" : "category",
            "attributeValue" : "regular"
        }
    ],
    "sharedDataplan" : "DoeFamily",
    "smsDestinations" : [ "34600702320" ],
    "subscriberId" : "34600702322"
}

In this example, the smsDestinations attribute is defined for each subscriber of the shared dataplan, and it contains the addresses of the "head" member (SMS to "34600702320 "). The dataplanName is set to the same value as the dataplanName associated to the shared dataplan.

One notification per limit is defined:

Note:  
Head subscriber "34600702320" can receive the same notification, one for each different subscriber reaching the category limit or the shared limit.

To avoid that the Head subscriber receives the same notification several times, extend the condition for each limit with the following expression: 

&& ( (<...>.current[\"type\"][n] * 1024) - 
     AccessData.subscriber.receivedUsage.reportingGroup
       [\"total\"/\"reportingGroupName\"].usageType[\"type\"] ) 
    < ( <corresponding limit expressed in bytes> ))

In the previous example:

  • For the shared limit (1.2 Gbytes): 

    condition:
 (AccessData.subscriber.accumulatedUsage.reportingGroup
  [\"Internet\"].isLimitSurpassed[\"bidirVolume\"])&& 
 (((AccessData.subscriber.accumulatedUsage.reportingGroup
  ["\Internet\"].current["\bidirVolume\"] * 1024) - 
   AccessData.subscriber.receivedUsage.reportingGroup
    ["\Internet\"].usageType["\bidirVolume\"])
   < ( 1228800 * 1024 ))

     

  • For the regular limit (600 Mbytes): 

    condition:
(Subscriber.category=="\regular\") && 
 (AccessData.subscriber.accumulatedUsage.reportingGroup
  [\"Internet\"].counter[\"regular\"].
  isLimitSurpassed[\"bidirVolume\"])&& 
 (((AccessData.subscriber.accumulatedUsage.reportingGroup
  [\"Internet\"].counter[\"regular\"].
  current[\"bidirVolume\"] * 1024) - 
  AccessData.subscriber.receivedUsage.reportingGroup
   \"Internet\"].usageType[\"bidirVolume\"])
  < ( 614400 * 1024> ))

     


In case the subscriber surpassing the limit needs to be also notified, consider to add another item to the smsDestinations attribute, reflecting the corresponding subscriber MSISDN. Here is a figure that represents how it should be configured:

Figure 5   Notifications to Head Member and the corresponding Subscriber

5.2   Notifications Based on Subscriber Group Activation or Deactivation

It may be interesting to send a notification to a subscriber when any of the Service Offerings hired (applicable Subscriber Group) is active or inactive. This section covers how to achieve such Notifications.

Note:  
Apart from Notification Policies, this Use Case has sense together with Handling of Multiple Service Offerings or Dynamic Group Selection (for details on how to configure that, refer to Configuration Guide for Subscription and Policies).

To send notifications about activation or deactivation of groups for a Subscriber, use Notification Policies (as explained in Section 4) but with the following particularities:

Next, an example is provided:

Example 18   Configuration of Notification based on Subscriber Group activation/deactivation

PUT /rules/rActivatedCityGroup
{
    "condition" : "(Subscription.group[\"City\"].isActive)",
    "outputAttributes" : 
    [
        {
            "attrName" : "notification",
            "attrValue" : "\"INFO about your Subscription Plan\"",
            "result" : "permit"
        }
    ],
    "ruleName" : "rActivatedCityGroup"
}

PUT /rules/rDeactivatedCityGroup
{
    "condition" : "contains(Subscriber.groups, \"City\") && 
                   not(Subscription.group[\"City\"].isActive)",
    "outputAttributes" : 
    [
        {
            "attrName" : "notification",
            "attrValue" : "\"INFO about your Subscription Plan\"",
            "result" : "permit"
        }
    ],
    "ruleName" : "rDeactivatedCityGroup"
}

PUT /policies/pGroupActivation
{
    "policyName" : "pGroupActivation",
    "ruleCombiningAlgorithm" : "all-permit",
    "rules" : [ "rActivatedCityGroup", "rDeactivatedCityGroup" ]
}

PUT /locators/resources/any/contexts/notification
{
    "policies" : [ "notifPolicyVolumeLimit", "pGroupActivation" ]
}

PUT /subscribers/34600500400
{
    "dataplans" : 
    [
        {
            "dataplanName" : "Rustic"
        },
        {
            "dataplanName" : "City"
        }
    ],
    "smsDestinations" : [ "+34600500400" ],
    "subscriberId" : "34600500400"
}

In the Example 18, notifications by SMS are applied to Subscriber 34600500400. The notification message contains different text depending on whether the City group is active or inactive (assuming that Dynamic Group Selection policies are based on cell location for the Subscriber, refer to Configuration Guide for Subscription and Policies).

Note:  
contains function is used within the condition formula of the deactivation rule, to assure that such deactivation notification is only sent for the groups actually subscribed to the Subscriber.

Note:  
For a configuration where the SAPC is handling tens or hundreds of different Subscriber Groups (different dataplanName entries, that can be applicable for different functions such as Service Access Control, Bearer QoS Control or so on), take care in configuring as rules just the ones to the groups for which actually it is relevant to send activation/deactivation notifications.

Otherwise, for example if a rule (as the Notification message is different for each Subscriber Group id) is done for each of the hundreds of provisioned Subscriber Groups in the system, there may be a significant impact in the SAPC performance owing to the evaluation of useless conditions.


Here, there is another example where Multiple Service Offering is applied for the Subscriber, but there is no Dynamic Group Selection:

Example 19   Configuration of Temporary Group activation Notification

PUT /rules/notifActiveTurbo
{
    "condition" : "(Subscription.group[\"Turbo\"].isActive)",
    "outputAttributes" : 
    [
        {
            "attrName" : "notification",
            "attrValue" : "\"Your Subscription has been updated\"",
            "result" : "permit"
        }
    ],
    "ruleName" : "notifActiveTurbo"
}

PUT /policies/notifActiveTurbo
{
    "policyName" : "notifActiveTurbo",
    "ruleCombiningAlgorithm" : "all-permit",
    "rules" : [ "notifActiveTurbo" ]
}

PUT /locators/resources/any/contexts/notification
{
    "policies" : [ "notifPolicyVolumeLimit", "pGroupActivation", "notifActiveTurbo" ]
}

PUT /subscribers/34600500500
{
    "dataplans" : 
    [
        {
            "dataplanName" : "Basic",
            "priority" : 2
        },
        {
            "dataplanName" : "Turbo",
            "priority" : 1,
            "startDate" : "15-12-2020T20",
            "stopDate" : "15-12-2020T22"
        }
    ],
    "smsDestinations" : [ "34600500500" ],
    "subscriberId" : "34600500500"
}

In the example above, an SMS is sent to "34600500500" when Turbo group becomes active for Subscriber "34600500500".

6   Appendix A. End User Notifications Policy Types

Next figure shows the policy type related to End User Notifications that can be configured in the SAPC.

Figure 6   End User Notifications policies in the SAPC


Glossary

APN
Access Point Name
 
HTTP
Hypertext Transfer Protocol
 
IP
Internet Protocol
 
NPI
Numeric Plan Indicator
 
PCEF
Policy Charging Enforcement Function
 
REST
Representational State Transfer
 
SAPC
Ericsson Service-Aware Policy Controller
 
SMPP
Short Message Peer-to-Peer Protocol
 
SMS
Short Message Service
 
SMSC
Short Message Service Center
 
SOAP
Simple Object Access Protocol
 
ToN
Type of Number
 
URI
Uniform Resource Identifier
 
UTF
Unicode Transformation Format
 
XML
Extensive Markup Language
Legal | © Ericsson España, S