.. _nbi-integration-considerations-and-messaging-sequencing:

--------------------------------------------------
Integration Considerations and Message Sequencing
--------------------------------------------------

This section provides examples on integration with northbound systems.


NBI Sandbox for Lab Testing and Payload Validation
===================================================

Initial implementation of the NBI in the lab can be supported with an inbuilt stub (known as the *Sandbox*), 
to represent the northbound system. This is a separate process that can be configured to run on 
the same machine as the main NBI processes. 

The Sandbox:
 * Receipts each billing payload message received from the NBI Notifier Function, responding with a 200 Ok 
   (NBI marks the message as UserInProgress)

 * Then performs a Call Back function, marking the field Response.Status in the call back JSON as "Success"
   (NBI marks the message as UserProcessed)

.. figure:: /src/images/nbi-image-007.png

The Sandbox can be used to review and validate the payload sent under various use cases. 

Contact VOSS Support for configuration of the NBI Sandbox.



Integration into Billing
=========================

Whereas the Sandbox presents a simple integration use case, a typical integration into a northbound system 
is more complex because although APIs exist, they are not modern REST-based APIs. Typically, the 
billing system is often installed and has evolved over time, and as a result, is 
somewhat rigid in terms of how it can be engaged.

In this integration the choice is to deploy a thin shim to receipt the NBI payload and then make the 
necessary local API calls or engagement with the billing system. Once this operation is complete, the shim is
then responsible for initiating the call back with NBI.

In this scenario a single call back is made, with *response.status* set to "Success" or "Error". For the 
latter, a suitable error response can then be carried in the *response.ResponseText* field.

The shim itself requires some design from a provider's IT team, with regard to its design and deployment.

.. figure:: /src/images/nbi-image-008.png



Integration and Upstream Provisioning
======================================

NBI also provides flexibility to integrate into more complex environments, where further upstream 
provisioning activities take place on receipt of a payload. For example, a use case where a 
subscriber is configured with additional services, such as a Fixed / Mobile package (FMC) that 
requires provisioning in upstream systems (outside of the HCS domain, and in this case with the 
provider's mobile fulfilment system). 

.. figure:: /src/images/nbi-image-009.png

In these more complex deployment scenarios, there is a requirement for an intermediate layer 
that can receipt the NBI payload and then orchestrate the various northbound systems. 

The steps for the use case example above is as follows: 

1.	The NBI sends the payload northbound.

2.	The payload is receipted by the intermediate layer, which then activates order management.

3.	On activation, the mobile provisioning system is contacted to provision the mobile (FMC).

4.	NBI is updated, by call back, as to the progress of the operation (UserInProgressMob).

5.	Mobile provisioning completes and the intermediate layer pushes the change into billing.

6.	NBI is updated, by call back, of the final state of the operation (UserProcessedMob).

In this more complex example, the call back function is initiated more than once by the intermediate 
layer to update NBI on progress in the northbound systems.


.. note::
    Above user states are examples – specifics to be discussed with VOSS Solutions.


.. sidebar:: **Reference Case**:
   
   NBI has been successfully implemented in a complex OSS/BSS estate – 
   interfacing into an intermediate layer constructed on Software AG's WebMethods. 
   In this deployment customer and order management was performed by SalesForce.com and 
   charging and billing using Convergys's Geneva billing system.



Typical Sequence Diagram
==========================

The sequence diagram below illustrates the sequence of events and messages for the case 
where NBI is integrated with the billing system, through a shim layer.

.. figure:: /src/images/nbi-image-010.png