Northbound Interface Adapter Reference Manual

Ericsson Dynamic Activation 1

1	Introduction
1.1	Purpose and Scope
1.2	Target Groups
1.3	Typographic Conventions
1.4	Prerequisites
2	Northbound Interface Adapter APIs
2.1	Northbound
2.2	Service List
2.2.1	AlarmService
2.2.2	AuthenticationService
2.2.3	MBeanService
2.2.4	ProcLogService
2.2.5	ProvisionService
2.2.6	NBINotifyService
2.3	Data Model
2.3.1	ProcLogEntry
2.3.2	Request
2.3.3	Response
2.3.4	SessionData
2.3.5	Acknowledge
2.3.6	AsyncRequestMetaData
2.3.7	AsyncResponse
2.4	Exception
2.4.1	NBIException
2.4.2	NBIExternalException
2.4.3	NBIInternalException
Reference List

1 Introduction

1.1 Purpose and Scope

This document is a reference for the development of northbound interface adapter in Ericsson™ Dynamic Activation (EDA).

1.2 Target Groups

The target group for this document is as follows:

Application designers

1.3 Typographic Conventions

Typographic conventions are described in the document Library Overview, Reference [1].

1.4 Prerequisites

This document is written with the assumption that the users have good knowledge of Dynamic Activation, Java™ language, OSGi, and Eclipse.

2 Northbound Interface Adapter APIs

There are more and more demands on customized northbound interfaces to meet the requirements from Customer Administration System (CAS) or order manager. To support customized northbound adapters, Dynamic Activation platform provides the following APIs so that customized northbound interfaces get to call Dynamic Activation platform services.

2.1 Northbound

Northbound interface is used for the customized northbound adapter to identify itself and get Dynamic Activation services.

Table 1 Method Summary
Modifier and Type	Method and Description
`void`	`configure(Map<String,String> properties)` This method is called by the Dynamic Activation platform when the configuration is updated for the northbound adaptor.
`String`	`getProtocol()` The identity of the northbound protocol, such as CAI, CAI3G, SOAP, etc.
`void`	`start(NBIContext nbiContext)` This method is called by the Dynamic Activation platform when the northbound adaptor is started.
`void`	`stop(NBIContext nbiContext)` This method is called by the Dynamic Activation platform when the northbound adaptor is stopped.

2.2 Service List

2.2.1 AlarmService

Northbound Interface Adapter (NBIA) Module Alarm is used for customized northbound adapter to send out events or alarms. For detailed information of Dynamic Activation system model, refer to Event and Alarm Handling, Reference [2].

The following table shows the AlarmService methods for NBIA.

Table 2 Method Summary
Modifier and Type	Method and Description
`org.osgi.service.event.Event`	`ceaseAlarm(int errorCode, String errorMessage)` Ceases an alarm
`org.osgi.service.event.Event`	`sendAlarm(int errorCode, String errorMessage)` Sends an alarm
`org.osgi.service.event.Event`	`sendEvent(int errorCode, String errorMessage)` Sends an event

2.2.2 AuthenticationService

AuthenticationService is used for the customized northbound adapter to authenticate the CAS login and logout requests towards Dynamic Activation user management.

Table 3 Method Summary
Modifier and Type	Method and Description
`boolean`	`authenticate(String userName, String password)` Authenticates whether the user name with the password is valid. If the user is valid, value `true` is returned.
`boolean`	`authenticate(String userName, String password, String mode)` Authenticates whether the user name with the password is valid with mode type. If the user is valid, value `true` is returned. There are two traffic modes: Normal traffic mode: "" (Default value) Test traffic mode: "Test"
`SessionContext`	`getSession(String sessionID, String protocol)` Get the context of session bound to the session ID
`String`	`login(String userName, String password, String protocol)` Authenticates whether the user name with the password is valid. If the user is valid, a new session ID is returned and is added to session floating controller.
`String`	`login(String userName, String password, String protocol, String mode)` Authenticates whether the user name with the password is valid with mode type. If the user is valid, a new session ID is returned and is added to session floating controller.
`void`	`logout(String sessionID, String protocol)` Log out according to the session ID.

2.2.3 MBeanService

MBeanService is used to provide JMX MBean service.

Table 4 Method Summary
Modifier and Type	Method and Description
`void`	`registerMBean(StandardMBean mbean, String name)` Registers the `mbean` and uses the northbound interface name for the object `name`.
`void`	`unregisterMBean(String name)` Unregisters the `mbean`.

2.2.4 ProcLogService

ProcLogService is used for the customized northbound adapter to record processing logs.

Table 5 Method Summary
Modifier and Type	Method and Description
`boolean`	`isLevelThreeEnabled()` Indicates whether to record debug processing logs.
`boolean`	`isProclogEnabled()` Indicates whether to record processing logs.
`void`	`recordLog(ProcLogEntry procLogEntry, String component)` Saves a log item in the processing log file.

2.2.5 ProvisionService

ProvisionService is used for the customized northbound adaptor to execute and schedule the request.

Table 6 Method Summary
Modifier and Type	Method and Description
`Response`	`execute(Request request)` Executes the `request` synchronously.
`Acknowledge`	`schedule(Request request)` Schedules the `request` to execute it asynchronously.

Performance consideration:

For the network protocol of customized northbound interface adapter such as SOAP, Jetty can handle multiple threads automatically, if internal HTTP server Jetty is used.
For the network protocol of customized northbound interface adapter such as Telnet, multiple threads receive different TCP requests. Each TCP connection has a separate server thread to handle requests.

2.2.6 NBINotifyService

NBINotifyService defines the interface for asynchronous notification. The northbound asynchronous interface adapter needs to implement this interface NBINotifyService, and the platform calls this interface to send out the response after executing the request.

Table 7 Method Summary
Modifier and Type	Method and Description
`Acknowledge`	`notify(AsyncResponse response)` Handles the asynchronous response.

2.3 Data Model

2.3.1 ProcLogEntry

This is a holder class that contains the information about logs.

Table 8 Method Summary
Modifier and Type	Method and Description
`void`	`cancel(int responseCode)` Indicates this entry as a cancelled one; records stop time and response code.
`void`	`cancel(String responseCode)` Indicates this entry as a cancelled one; records stop time and response code.
`static ProcLogEntry`	`createRootProcLogEntry(String protocol)` Creates a root `ProcLogEntry` without start time.
`static ProcLogEntry`	`createRootProcLogEntry(String protocol, boolean start)` Creates a root `ProcLogEntry` with start time.
`static ProcLogEntry`	`createNorthBoundProcLogEntry(String protocol)` Create a northbound `ProcLogEntry` without start time.
`static ProcLogEntry`	`createNorthBoundProcLogEntry(String protocol, boolean start)` Create a northbound `ProcLogEntry` with start time.
`static ProcLogEntry`	`createNorthBoundProcLogEntry(String protocol, String procLogId)` Creates a northbound `ProcLogEntry` instance with provided `procLogId` (child `ProcLogId` in most cases if this API is used)
`static ProcLogEntry`	`createNorthBoundProcLogEntry(String protocol, boolean start, String procLogId)` Creates a northbound `ProcLogEntry` instance with start time and provided `procLogId` (child `ProcLogId` in most cases if this API is used).
`void`	`fail()` Indicates this entry as a failed one; records stop time.
`void`	`fail(int responseCode)` Indicates this entry as a failed one; records stop time and response code.
`void`	`fail(String responseCode)` Indicates this entry as a failed one; records stop time and response code.
`ProcLogId`	`getLogId()` Gets the object `ProcLogId`. It includes `rootId` and `subId` of the `proclog`.
`String`	`getInstance()` Gets the instance of this `ProcLogEntry`.
`String`	`getLogType()` Gets the `logType` of this `ProcLogEntry`.
`String`	`getOperation()` Gets the operation of this `ProcLogEntry`.
`String`	`getProcLogId()` Gets the `procLogId` of this `ProcLogEntry`.
`String`	`getProtocol()` Gets the protocol of this `ProcLogEntry`.
`String`	`getRequest()` Gets the request of this `ProcLogEntry`.
`String`	`getResponse()` Gets the response of this `ProcLogEntry`.
`String`	`getResponseCode()` Gets the `responseCode` of this `ProcLogEntry`.
`long`	`getStartTime()` Gets the `startTime` of this `ProcLogEntry`.
`String`	`getStatus()` Gets the status of this `ProcLogEntry`.
`long`	`getStopTime()` Gets the `stopTime` of this `ProcLogEntry`.
`String`	`getTarget()` Gets the target of this `ProcLogEntry`.
`String`	`getTransactionId()` Gets the `transactionId` of this `ProcLogEntry`.
`String`	`getUser()` Gets the user of this `ProcLogEntry`.
`void`	`setInstance(String instance)` Sets the instance of this `ProcLogEntry`.
`void`	`setLogType(String logType)` Sets the `logType` of this `ProcLogEntry`.
`void`	`setOperation(String operation)` Sets the operation of this `ProcLogEntry`.
`void`	`setProtocol(String protocol)` Sets the protocol of this `ProcLogEntry`.
`void`	`setRequest(String request)` Sets the request of this `ProcLogEntry`.
`void`	`setResponse(String response)` Sets the response of this `ProcLogEntry`.
`void`	`setResponseCode(String responseCode)`. Sets the `responseCode` of this `ProcLogEntry`.
`void`	`setStartTime(long startTime)` Sets the `startTime` of this `ProcLogEntry`.
`void`	`setStatus(String status)` Sets the status of this `ProcLogEntry`.
`void`	`setStopTime(long stopTime)` Sets the `stopTime` of this `ProcLogEntry`.
`void`	`setTarget(String target)` Sets the target of this `ProcLogEntry`.
`void`	`setTransactionId(String transactionId)` Sets the `transactionId` of this `ProcLogEntry`.
`void`	`setUser(String user)` Sets the user of this `ProcLogEntry`.
`void`	`start()` Sets start time of the `procLogEntry` to current time.
`void`	`succeed()` Indicates this entry as a successful one; records stop time and assigns a default response code 0.
`String`	`toString()` Represents this log entry.

2.3.2 Request

Request is the general data model representing coming requests, and it defines several mandatory and optional attributes that are used by Dynamic Activation services. And also it provides a common format to carry the payload of the request.

Table 9 Attributes Used in Request
Attribute	Type	Description
`operation`	`String`	`operation` usually means CRUD operations, but it can be any operation name. For example: `Create, Delete, Get,` etc.
`moName`	`String`	`moName` is the logical name of a target MO. In CAI3G protocol, it is as same as MO type. For example: `HLRSUB, Subscription@http://schemas.ericsson.com/pg/auc/13.5/`
`moIds`	`Map`	`moIds` means the MO identification, which needs to be unique identified target in BL. For example: `{{imis, 494600000001}, {msisdn, 494600000001}}`
`moAttributes`	`XML Document`	Any XML format content that contains all required information for BL. `moAttributes` is used to transfer data from northbound interface to proxy, and it is transparent to the current Dynamic Activation service, because it contains BL related information.
`sessionData`	`SessionData`	A set of session related data, such as user name, processing log ID, session ID `SessionData` carries the session specific data, which is used by the Dynamic Activation framework.
`rawRequest`	`String`	Original requests sent from northbound interface `rawRequest` stores the original requests from upstream, and it is used in the request search functions.
`metadata`	`RequestMetadata`	`metadata` is used to describe the attribute of the request. These attributes independent from the request protocol, payload type and session. These attributes are defined by framework for all requests and are independent from the request protocol, payload type and session.
`testRequest`	`Boolean`	`testRequest` indicates whether the request is in test mode.

The procedure of transporting provisioning data by Request is as follows:

Northbound interface receives the northbound requests and transforms the provisioning data to internal data model. moAttributes is used to save the internal data.
If you use your own interface and provisioning logic, save the northbound request data to moAttributes, and moAttributes is routed to the provisioning logic by Dynamic Activation.

The following example shows the CAI3G internal data model for the Create Request.

Example 1 CAI3G Internal Data Model for the Create Request

<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<MOAttributes>
    <MOAttributes>
        <CreateEPSMultiSC imsi="494500100000" xmlns="http://schemas.ericsson.com/ma/HSS/">
            <imsi>494500100000</imsi>
            <epsProfileId>Profile900C</epsProfileId>
            <epsRoamingAllowed>true</epsRoamingAllowed>
        </CreateEPSMultiSC>
    </MOAttributes>
    <Extension/>
    <NAMESPACE>
    default-ns-c9e9111b-fa9e-454a-b691-4578c8e14c27=http://schemas.ericsson.com/ma/HSS/ext/
    </NAMESPACE>
</MOAttributes>

The following example shows the CAI internal data model for the Create Request.

Example 2 CAI Internal Data Model for the Create Request

Command:
CREATE:HLRSUB:MSISDN,12340101:IMSI,56780101:PROFILE,0:BS31,1:BS32,1:BS33,1:BS34,
1:BS3G,1:BS3F,1:TS11,1:CFB,1,1,191019120003,OFA-1,1-A0AFBE01C001A:CFNRC,1,1,
191019120004,1-A0AFBE01C001A:CFNRY,1,1,191019120000,OFA-0:CFU,1,1,191019120000:DCF,
1,1,191019120000,20:SPN,1,1,191019120000:BAIC,1,1:BAOC,1,1:BICRO,1,1:BOIC,1,
1:BOIEXH,1,1:CAW,1,1; 

<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<MOAttributes>
    <MOAttributes>
        <CreateHLRSUB xmlns="http://schemas.ericsson.com/ma/cai/1.0/">
            <MSISDN>12340101</MSISDN>
            <IMSI>56780101</IMSI>
            <PROFILE>0</PROFILE>
            <BS31>1</BS31>
            <BS32>1</BS32>
            <BS33>1</BS33>
            <BS34>1</BS34>
            <BS3G>1</BS3G>
            <BS3F>1</BS3F>
            <TS11>1</TS11>
            <CFB>
                <value id="1">1</value>
                <value id="2">1</value>
                <value id="3">191019120003</value>
                <value id="4">OFA-1</value>
                <value id="5">1-A0AFBE01C001A</value>
            </CFB>
            <CFNRC>
                <value id="1">1</value>
                <value id="2">1</value>
                <value id="3">191019120004</value>
                <value id="4">1-A0AFBE01C001A</value>
            </CFNRC>
            <CFNRY>
                <value id="1">1</value>
                <value id="2">1</value>
                <value id="3">191019120000</value>
                <value id="4">OFA-0</value>
            </CFNRY>
            <CFU>
                <value id="1">1</value>
                <value id="2">1</value>
                <value id="3">191019120000</value>
            </CFU>
            <DCF>
                <value id="1">1</value>
                <value id="2">1</value>
                <value id="3">191019120000</value>
                <value id="4">20</value>
            </DCF>
            <SPN>
                <value id="1">1</value>
                <value id="2">1</value>
                <value id="3">191019120000</value>
            </SPN>
            <BAIC>
                <value id="1">1</value>
                <value id="2">1</value>
            </BAIC>
            <BAOC>
                <value id="1">1</value>
                <value id="2">1</value>
            </BAOC>
            <BICRO>
                <value id="1">1</value>
                <value id="2">1</value>
            </BICRO>
            <BOIC>
                <value id="1">1</value>
                <value id="2">1</value>
            </BOIC>
            <BOIEXH>
                <value id="1">1</value>
                <value id="2">1</value>
            </BOIEXH>
            <CAW>
                <value id="1">1</value>
                <value id="2">1</value>
            </CAW>
        </CreateHLRSUB>
    </MOAttributes>
</MOAttributes>

Table 10 Method Summary
Modifier and Type	Method and Description
`RequestMetadata`	`getMetadata()` Gets the `requestMetadata` of the `Request`.
`Document`	`getMOAttributes()` Gets the `moAttributes` of the `Request`.
`Map<String,String>`	`getMoId()` Gets the `moIds` of the `Request`.
`String`	`getMoName()` Gets the `moName` of the `Request`.
`String`	`getOperation()` Gets the `operation` of the `Request`.
`String`	`getRawRequest()` Gets the `rawRequest` of the `Request`.
`SessionData`	`getSessionData()` Gets the `sessionData` of the `Request`.
`boolean`	`isTestRequest()` Check if the request is in test mode.
`void`	`setMetadata(RequestMetadata metadata)` Sets the `requestMetadata` of the `Request`.
`void`	`setMOAttributes(Document moAttributes)` Sets the `moAttributes` of the `Request`.
`void`	`setMoId(Map<String,String> moIds)` Sets the `moIds` of the `Request`.
`void`	`setMoName(String moName)` Sets the `moName` of the `Request`.
`void`	`setOperation(String operation)` Sets the operation of the `Request`.
`void`	`setRawRequest(String rawRequest)` Sets the `rawRequest` of the `Request`.
`void`	`setSessionData(SessionData sessionData)` Sets the `sessionData` of the `Request`.
`void`	`setTestRequest(boolean testRequest)` Sets the `testRequest` of the Request.

2.3.3 Response

Table 11 Method Summary
Modifier and Type	Method and Description
`Document`	`getMoAttributes()` Gets the `moAttributes` of the `Response`.
`void`	`setMoAttributes(Document moAttributes)` Sets the `moAttributes` of the `Response`.

2.3.4 SessionData

Table 12 Method Summary
Modifier and Type	Method and Description
`String`	`getProclogId()` Gets the `proclogId` of the `SessionData`.
`Properties`	`getProperties()` Gets the `SessionData` properties.
`Object`	`getProperty(String name)` Gets the property from the `SessionData` properties.
`String`	`getSessionId()` Gets the `sessionId` of the `SessionData`.
`String`	`getUsername()` Gets the username of the `SessionData`.
`void`	`setProclogId(String proclogId)` Sets the `proclogId` of the `SessionData`.
`void`	`setProperties(String name, Object value)` Sets the property of the `SessionData`.
`void`	`setSessionId(String sessionId)` Sets the `sessionId` of the `SessionData`.
`void`	`setUsername(String username)` Sets the username of the `SessionData`.

2.3.5 Acknowledge

Table 13 Method Summary
Modifier and Type	Method and Description
`BigInteger`	`getCode()` Gets the code of `Acknowledge`.
`String`	`getMessage()` Gets the message of `Acknowledge`.
`void`	`setCode(BigInteger ackCode)` Sets the code of `Acknowledge`.
`void`	`setMessage(String ackMessage)` Sets the message of `Acknowledge`.

2.3.6 AsyncRequestMetaData

Table 14 Method Summary
Modifier and Type	Method and Description
`String`	`getContext()` Gets the `context` of `AsyncRequestMetaData`.
`String`	`getFaultTo()` Gets the `faultTo` of `AsyncRequestMetaData`.
`Date`	`getFireTime()` Gets the `fireTime` of `AsyncRequestMetaData`.
`String`	`getGroupId()` Gets the `groupId` of `AsyncRequestMetaData`.
`String`	`getMessageId()` Gets the `messageId` of `AsyncRequestMetaData`.
`String`	`getNotifyProtocol()` Gets the `notifyProtocol` of `AsyncRequestMetaData`.
`String`	`getPriority()` Gets the priority of `AsyncRequestMetaData`.
`String`	`getReplyTo()` Gets the `replyTo` of `AsyncRequestMetaData`.
`AsyncRequestMetaData`	`setContext(String context)` Sets the `context` of `AsyncRequestMetaData`.
`AsyncRequestMetaData`	`setFaultTo(String faultTo)` Sets the `faultTo` of `AsyncRequestMetaData`.
`AsyncRequestMetaData`	`setFireTime(Date fireTime)` Sets the `fireTime` of `AsyncRequestMetaData`.
`AsyncRequestMetaData`	`setGroupId(String groupId)` Sets the `groupId` of `AsyncRequestMetaData`.
`AsyncRequestMetaData`	`setMessageId(String messageId)` Sets the `messageId` of `AsyncRequestMetaData`.
`AsyncRequestMetaData`	`setNotifyProtocol(String notifyProtocol)` Sets the `notifyProtocol` of `AsyncRequestMetaData`.
`AsyncRequestMetaData`	`setPriority(String priority)` Sets the priority of `AsyncRequestMetaData`.
`AsyncRequestMetaData`	`setReplyTo(String replyTo)` Sets the `replyTo` of `AsyncRequestMetaData`.

2.3.7 AsyncResponse

This class carries the response of the asynchronous command. It carries the original com.ericsson.mpe.services.common.Request and a normal com.ericsson.mpe.services.common.Response if the request runs successfully, or a com.ericsson.mpe.common.error.NBIException if the command fail.

Table 15 Constructor Summary
Constructor	Description
`AsyncResponse(Request request)`	Constructs a non-instated asynchronous response.
`AsyncResponse(Request request, NBIException exception)`	Constructs a failed asynchronous response.
`AsyncResponse(Request request, Response response)`	Constructs a successful asynchronous response.

Table 16 Method Summary
Modifier and Type	Method and Description
`void`	`fails(NBIException exception)` Set the failed exception of `AsyncResponse`.
`NBIException`	`getException()` Gets the exception of `AsyncResponse`.
`Request`	`getRequest()` Gets the request of `AsyncResponse`.
`Response`	`getResponse()` Gets the response of `AsyncResponse`.
`boolean`	`isFailed()` Check if the `AsyncResponse` failed.
`void`	`succeeds(Response response)` Set the successful response of `AsyncResponse`.
`ProcLogEntry`	`getProcLogEntry(String protocol)` Generates the ProcLogEntry of the `AsyncResponse`.

2.4 Exception

2.4.1 NBIException

This exception is used by northbound interface.

Table 17 Constructor Summary
Constructor	Description
`NBIException(long code, String description)`	Constructs the `NBIException`.
`NBIException(long code, String description, String addInfo)`	Constructs the `NBIException`.
`NBIException(long code, String description, String addInfo, Throwable throwable)`	Constructs the `NBIException`.
`NBIException(long code, String description, Throwable throwable)`	Constructs the `NBIException`.

Table 18 Method Summary
Modifier and Type	Method and Description
`String`	`getAddInfo()` Gets the `addInfo` of `NBIException`.
`String`	`getDescription()` Gets the description of `NBIException`.
`long`	`getErrorCode()` Gets the `errorCode` of `NBIException`.

2.4.2 NBIExternalException

This exception stands for external errors, such as the errors from ElementManager or NetworkElement, or Business Logic errors.

Table 19 Constructor Summary
Constructor	Description
`NBIExternalException(long code, String description)`	Constructs the `NBIExternalException`.
`NBIExternalException(long code, String description, String addInfo)`	Constructs the `NBIExternalException`.
`NBIExternalException(long code, String description, String addInfo, Throwable throwable)`	Constructs the `NBIExternalException`.
`NBIExternalException(long code, String description, Throwable throwable)`	Constructs the `NBIExternalException`.

2.4.3 NBIInternalException

This exception stands for internal component errors or framework problems.

Table 20 Constructor Summary
Constructor	Description
`NBIInternalException(long code, String description)`	Constructs the `NBIInternalException`.
`NBIInternalException(long code, String description, NBIInternalException.ErrorType type)`	Constructs the `NBIInternalException`.
`NBIInternalException(long code, String description, String addInfo, NBIInternalException.ErrorType type)`	Constructs the `NBIInternalException`.
`NBIInternalException(long code, String description, String addInfo, Throwable throwable, NBIInternalException.ErrorType type)`	Constructs the `NBIInternalException`.
`NBIInternalException(long code, String description, Throwable e)`	Constructs the `NBIInternalException`.
`NBIInternalException(long code, String description, Throwable throwable, NBIInternalException.ErrorType type)`	Constructs the `NBIInternalException`.

Table 21 Method Summary
Modifier and Type	Method and Description
`NBIInternalException.ErrorType`	`getType()` Gets the `ErrorType`.
`void`	`setType(NBIInternalException.ErrorType type)` Sets the `ErrorType`.

Reference List

Library Documents
[1] Library Overview, 18/1553-CSH 109 628 Uen
[2] Event and Alarm Handling, 3/1553-CSH 109 628 Uen