Dual Version PortaSwitch operates with two separate systems – source and target – simultaneously. For external applications that interact with PortaSwitch via the API, this means the API server must know where to execute each request.
WebDispatcher serves as a single API entry point, routing requests between two systems. It also enables seamless web interface operations for admins, customers, and end users, and supports the functioning of applications such as self-care interfaces with Dual Version PortaSwitch.
External applications, such as CRM systems, sign-up portals, and billing integrations built on top of the PortaSwitch API, may require adaptation to work correctly during the migration. Whether changes are necessary depends on how the application interacts with the API.
Session context
When distributing API requests, WebDispatcher relies on context. In a Dual Version setup, context is a session-level property that identifies the system – source or target – that should handle a given API request.
Context is tied to an API session. Once established, it is retained and automatically applied to all subsequent operations within that session and updated when needed. For example, if the current context points to the target system but the next request involves a customer on the source system, WebDispatcher automatically switches the context to source for that and all following requests.
WebDispatcher determines context depending on the parameters included in the API request. There are three access types:
- Transparent – WebDispatcher detects the context automatically based on customer or account credentials.
- Semi-transparent – context detection works automatically for some of the API methods.
- Explicit – the application must set the context manually before executing the request.
If WebDispatcher cannot determine the context from the request, the request is forwarded to the target system by default.
Transparent access to both systems
With transparent access, no additional actions are required for an external application to access either the source or the target system.
Applications that use the API with customer or account credentials (e.g., self-care portals) do not require any changes. A customer or account can be active on only one system at a time. Upon authentication, WebDispatcher detects where the corresponding customer record resides and routes all subsequent requests to that system.
The following request updates an account password. WebDispatcher automatically routes it to the relevant system based on the session context established at login:
POST /Account/update_account
{
"auth_info": {
"access_token": "your_access_token"
},
"params": {
"account_info": {
"i_account": 55,
"h323_password": "spU8bGBK32GrNw"
}
}
}
Response:
{
"i_account": 55
}
Semi-transparent access to both systems
Unlike customers and accounts, an admin or reseller can be active on both systems at the same time. This means WebDispatcher cannot always determine the correct system automatically.
With such access, context detection is partial: whether WebDispatcher can detect context automatically depends on whether the API method includes i_customer or i_account as an input parameter.
Context auto-detection
If an application uses the API with admin or reseller credentials and calls methods that operate on a specific customer or account, the request includes i_customer or i_account. WebDispatcher automatically detects the entity location from this parameter and executes the request on the relevant system.
The following request gives a $10 credit to each customer of the "Premium Cloud PBX" customer class. WebDispatcher automatically detects the relevant system for each customer based on the i_customer parameter:
Step 1. Retrieve the customer list.
POST /Customer/get_customer_list
{
"auth_info": {
"access_token": "your_access_token"
},
"params": {
"i_customer_class": 123
}
}
Step 2. For each customer in the response, apply a manual credit.
POST /Customer/make_transaction
{
"auth_info": {
"access_token": "your_access_token"
},
"params": {
"i_customer": "<i_customer from Step 1 response>",
"amount": 10,
"action": "Manual credit"
}
}
When using Customer.get_customer_list and Account.get_account_list in a Dual Version setup, be aware that these methods query both systems separately and concatenate the results. Use the skip_exported attribute to exclude already-migrated customers and accounts from the response and avoid duplicates.
Setting the context based on the relevant entity
Some API methods do not include i_customer or i_account as input parameters, so WebDispatcher cannot detect the target system automatically. In these cases, the application should be adjusted to set the context by calling Session.set_session_context with the dual_version_system value set to either "source" or "target" each time the application needs to query a different system.
The following example shows how to override an auto-detected session context mid-session. The application first updates a customer on the target system – WebDispatcher auto-detects the context as "target" from the i_customer parameter. The application then needs to add a rate to the "Premium Cloud PBX" tariff on the source system. Because the session context is still set to "target" from the previous call, the application must explicitly override it before making the add rate request.
Step 1. The application calls Customer.update_customer with i_customer in the request. WebDispatcher automatically detects the context as "target" based on the i_customer parameter and sets it for the session.
Step 2. Override the session context to the source system.
POST /Session/set_session_context
{
"auth_info": {
"access_token": "your_access_token"
},
"params": {
"dual_version_system": "source"
}
}
Response:
{
"success": 1
}
Step 3. Add the rate to the "Premium Cloud PBX" tariff. The request is routed to the source system.
POST /Rate/add_rate
{
"auth_info": {
"access_token": "your_access_token"
},
"params": {
"rate_info": {}
}
}
Explicitly setting the context
When creating new entities, WebDispatcher cannot detect the system automatically and the context must be set explicitly using Session.set_session_context with "source" or "target".
The following code creates a new customer on the source system. Because no customer ID exists yet, the context must be set explicitly before the request:
Step 1. Authenticate and obtain an access token.
POST /Session/login
{
"params": {
"login": "admin_login",
"password": "admin_password"
}
}
Response:
{
"access_token": "your_access_token",
"session_id": "your_session_id"
}
Step 2. Set the context to “source”.
POST /Session/set_session_context
{
"auth_info": {
"access_token": "your_access_token"
},
"params": {
"dual_version_system": "source"
}
}
Response:
{
"success": 1
}
Step 3. Create the customer.
POST /Customer/add_customer
{
"auth_info": {
"access_token": "your_access_token"
},
"params": {
"customer_info": {}
}
}
Response:
{
"i_customer": 1234
}
Step 4. Create the account for the new customer.
POST /Account/add_account
{
"auth_info": {
"access_token": "your_access_token"
},
"params": {
"account_info": {
"i_customer": 1234
}
}
}
Response:
{
"i_account": 55
}
Recommendations
When adapting external applications to work with Dual Version PortaSwitch, ensure the following:
- There are no IP/Netmask restrictions between the source and target system IP addresses. Internal authorization between systems requires unrestricted access when using Session/login.
- Logins and passwords are identical on both systems.
- Applications should not share the same session_id across multiple threads that access different systems (source and target) simultaneously, as this may cause unexpected context switching.
- Applications that rely on direct database queries should be refactored to use the API or as a temporary measure query both databases simultaneously.
Post-migration
When the Dual Version migration is complete, the source system can be decommissioned. External applications built according to the guidelines described in this document do not require any changes at that point. Once the source system is decommissioned, all API requests are performed on the target system. During subsequent Dual Version migrations, the applications continue to work as expected.
