Common API entry point for Dual Version PortaSwitch

Dual Version PortaSwitch is a solution that enables service providers to perform smooth and controlled customer migration. It also provides extensible API for integration with third-party applications, CRM systems, building self-care portals, etc. Users must be able to log in to the same portal, under the same address regardless of their current location within Dual Version PortaSwitch in order to preserve their customary habits.

Thus, John Doe will log in to www.mybilling.com to check his balance and invoices, both when his record is on the source system and after it is moved to the target. Administrators and resellers, in turn, must be able to operate in both systems, via the API, without reconfiguring their applications.

Please note that administrators/resellers can log into their customer/account self-care interface. If that customer/account is already moved to the target system, PortaBilling denies automatic login. This is to protect against fraud since this login request comes from outside the network. To access the customer/account self-care interface, administrators/resellers must click Login again.

To this end, WebDispatcher for Dual Version PortaSwitch serves as a single API entry point for both the source and the target systems. It accepts API requests from applications (e.g., CRM) and dispatches them across systems for processing.

WebDispatcher is one of the components of the DSBC and operates on the same servers where the DSBC is deployed. Like other DSBC components, WebDispatcher is clustered, runs on several servers and is accessible via a single public IP address.

That is how WebDispatcher works. The application sends an API request to get customer information. WebDispatcher finds which system a customer is located in and sends a request there. After WebDispatcher receives the results, it returns that customer information to the application.

Note that when the application sends a PortaSIP API request (PortaSIP API allows to configure such features as auto-attendant, conferencing, voicemail), WebDispatcher sends this request to the source and the target system simultaneously. The system where the corresponding customer record is located sends a response and WebDispatcher returns the result to the application.

Thus, an application can receive data from the source, the target, or even both systems. The decision about which data to retrieve is based on the following:

• Who uses the application – the administrator/reseller or a retail customer/account, and

• The user’s location – if it is within the source or the target system.

Let’s consider how retail customers and administrators/resellers operate in Dual Version PortaSwitch via the API, separately.

Customers and accounts can only operate with a system where their records are located. Thus, when a customer logs on to the external self-care portal, the application sends the API request to WebDispatcher. It checks the customer’s location within Dual Version PortaSwitch and if the customer was moved to the target system, WebDispatcher sends the API request to that system.

Then, when the customer performs an action (e.g., selects xDRs for the previous billing period), WebDispatcher proxies the API request to the respective system (e.g., the target system). The target system then retrieves the xDRs and WebDispatcher delivers them to the application.

If a customer in the source system uses the external self-care portal, WebDispatcher receives the API requests and sends them to the source system for processing.

Administrators, resellers and their staff (representatives, customer care staff, etc.) manage their own configurations plus those of customers who exist in both systems within Dual Version PortaSwitch. Therefore, depending upon customer location, their applications must be able to send the proper context, i.e. which system will process their requests.

WebDispatcher automatically detects the context based on the i_customer/i_account values passed in the input parameters within API requests. For this purpose, customer and account records in Dual Version PortaSwitch have unique IDs. When you move customer data from one system to another, IDs are preserved. Later on, customers created on the source system receive odd ID values while customers created on the target system receive even ID values. This prevents data collision during customer migration from one system to another.

Some API applications use both the IDs of customers/accounts and the IDs of entities such as products, volume discount plans, etc. as static values in API requests. For example, to obtain information about a customer’s volume discount plan usage, the application sends i_customer and i_vd_plan values in the input parameters.

To preserve the workflow for these applications in Dual Version PortaSwitch, IDs for all configuration entities are preserved when moved between systems. Thus, your ABC product has the same ID (e.g., i_product=123) on both systems. As a result, fewer customizations are required to make the API application compatible with Dual Version PortaSwitch.

Differently from customers and accounts, these entities remain available in the source system, even when moved to the target one. Therefore, the administrator must remember to modify them in both systems in order to prevent differences in configuration.

Once an administrator has configured the interconnection between systems, the workflow is typically the following:

• If the application sends the API request to retrieve the customer list, WebDispatcher runs the request in both systems and then merges the results into a single list. Thus, the administrator or reseller sees those customers who are still within the source system, those who were moved to the target system, and those who were created in the target system.

• To manage a customer in Dual Version PortaSwitch, the application sends the ID of this customer’s record in an API request. WebDispatcher sends the request to the system, where this customer is provisioned. After the results are received, the data is delivered to the application.

• Entities such as products, bundle promotions, volume discount plans, etc. can exist independently, i.e., not be tied to a particular customer directly. Therefore, to retrieve the list of subscriptions from the target system, the application sets the session context by providing the unique ID for the target system’s billing environment within the API request. Then WebDispatcher runs further requests in the target system.

• To operate with subscriptions from the source system, the application switches the session context by providing the ID of the billing environment in the source system. In this case, all subsequent requests are processed by the source system.

• To modify a customer class with the same ID in both systems in Dual Version PortaSwitch the application must first set the session context to the source system and update the customer class there. Then the application switches the session context to the target system and updates the customer class there. We recommend this approach to avoid creating differences in entity configuration.

CPE profile provisioning is supported for Dual Version PortaSwitch. So when an IP phone connects to the Internet and requests a configuration file from WebDispatcher, WebDispatcher processes the request and retrieves the file from the target system and then delivers it to the IP phone.

The obsolete TFTP protocol is no longer supported, therefore the HTTP protocol is supported for CPE profile provisioning in Dual Version PortaSwitch.

WebDispatcher for Dual Version PortaSwitch provides a single place for customer management and system operation. This makes the migration process more fluid. The full application preserves user habits and thus improves the overall PortaSwitch customer experience.

When operating with Dual Version PortaSwitch via the API, consider the following implementation specifics:

1. Applications can operate with PortaSwitch only via the REST and SOAP API. The WebSocket API is not supported.

2. To establish a session with the target system, credentials for the API access must be the same for both systems.

3. After login, the application will be provided with the session ID that must be used in all subsequent API requests.

4. All communication between the application and PortaSwitch is done via WebDispatcher.

5. The common API entry point operates in conjunction with the dispatching SBC and Diameter proxy.

6. Only the get_customer_list method provides results from both systems. If you have defined limits for the list (the number of rows to retrieve), expect results that are twice as long because the same limit value will be used when querying both the source and the target system.

Bear in mind the following known limitations:

1. For security measures, add the WebDispatcher IP address to the allowed IP addresses for each entity (user, customer, reseller) on the PortaBilling web interface.

2. The systems are mapped with each other by their environment IDs. Therefore, be careful when switching the environment since this may result in broken mapping and session disconnect with the target system.

3. If the target system fails to establish the API session with the source system, it operates as if there is no source system.