Developing a remote module

---

Introduction

Welcome to the TeleCloud module development guide! External modules are a powerful feature that allows you to integrate your TeleCloud instance with any third-party system, such as a carrier or Mobile Virtual Network Enabler (MVNE).

At its core, an external module is a script hosted on your own server at a specific URL. When a transaction occurs in TeleCloud (like a new order or a service change), TeleCloud can be configured to send a real-time HTTP POST request to your module's URL. Your module then performs the necessary actions on the external system (e.g., activating a SIM card with a carrier) and returns a response to TeleCloud to confirm the outcome.

This guide will walk you through the entire process, from understanding the data TeleCloud sends to building and responding from your own module.

The Workflow

The interaction between TeleCloud and your external module follows a simple, robust workflow:

1. API Call : A user or system makes an API call to TeleCloud (e.g., Order/Create).
   
   
2. Module Trigger : TeleCloud identifies the Product Group for the order and sees that an external module is assigned to the "Order" action.
   
   
3. Data POST : TeleCloud gathers all relevant customer, order, and product data and sends it in a single HTTP POST request to the URL you've configured for your module.
   
   
4. Module Processing : Your script at the URL receives the POST data. It should then:
   • Parse the data.
   • Perform its own logic, such as calling the carrier's API to provision the service.
   • Handle any success or error responses from the carrier.
     
     
5. XML Response : Your module sends a response back to TeleCloud in a specific XML format.
   
   
6. Action Completion : TeleCloud parses your XML response.
   • If successful, it completes the action (e.g., marks the order as ACTIVE).
   • If an error is returned, it stops the process and returns the error message to the original API caller.
   • If new data is returned (e.g., a new phone number), it updates the order details in the database.

Step 1: What TeleCloud Sends to Your Module

When TeleCloud calls your module, it sends a POST request with a body containing numerous parameters. Here are the most important parameters you will receive:

• SERVICE (string): The API endpoint that triggered the module call. This is crucial for your module to know what action to perform. Examples: Order/Create, Order/Replenish, Order/Status, Order/Swap.
• Customer (object): An object containing all information about the customer, similar to the response received from Customer/Search (e.g., first_name, last_name, address, email).
• Product (object): An object containing details about the core product, this way you know which service to provision.
• VARProduct (object): An object containing details for the specific rate plan (similar to response from Plan/Search)
• VAR (object): An object containing the account details of the VAR (Value-Added Reseller) (similar to response from CloudAccount/Search)
• VAR1 - VAR20 (string): These are the workhorses of the module system. They contain the dynamic data provided during the API call, such as an IMEI, a SIM number, or a port-in request. The meaning of each VAR is defined by you in the Product Group settings.
• CARRIER_PRODUCT_ID (string): A specific identifier for the carrier's product or plan (e.g., a SOC code). This is configured on the core Product in TeleCloud and passed to your module for easy identification.
• order_number (string): The unique TeleCloud order number. This is primarily sent for actions on existing orders, like Replenish or Status changes.
• NEW_STATE (string): For Order/Status calls, this indicates the target state (e.g., ACTIVE or SUSPENDED).

 

Step 2: What Your Module Must Return

Your module's response is just as important as the request. It must be a well-formed XML document. TeleCloud will parse this XML to determine the next steps.

Required XML Structure:

<MODULE>
<SUCCESS>N</SUCCESS>
<ERROR>Carrier Error: Invalid SIM card provided.</ERROR>
</MODULE>

• <MODULE>: The root element of the response.
• <SUCCESS> (Required): This must contain either Y for success or N for failure.
  • If N, you must also include an <ERROR> tag.
• <ERROR> (Required on Failure): If <SUCCESS> is N, this tag should contain a clear, human-readable error message. This exact message will be passed back to the original API caller.

<MODULE>
<SUCCESS>N</SUCCESS>
<ERROR>Carrier Error: Invalid SIM card provided.</ERROR>
</MODULE>

<VAR1> - <VAR20> (Optional): If your carrier returns data during provisioning (like a newly assigned phone number or a unique carrier account ID), you can return it in these tags. TeleCloud will automatically update the corresponding VAR fields on the order, saving the data permanently.

<MODULE>
<SUCCESS>Y</SUCCESS>
<!-- The carrier assigned a phone number, and we want to save it in VAR2 on the order -->
<VAR2>5551239876</VAR2>
</MODULE>

• <STATUS> (Optional): For Order/Create calls, you can return <STATUS>PENDING</STATUS>. This tells TeleCloud that provisioning is in progress but not yet complete. The order will be created with a PENDING status. You would then need a separate process to call the Order/Update API to set the status to ACTIVE or FAILED once the carrier has finished.

 

Step 3: Building Your Module + Examples

Once you develop your module be sure to add it to TeleCloud as a module using the Module/Create service. To utilize the module you'll need to link it to one or more of your Product Groups, assigning it to be utilized for orders, replenishments, and more - you can do that with the ProductGroup Create or Edit service or in the TeleCloud App.

We've put together some sample templates for your external module. It demonstrates how to handle the test request, parse incoming data, and return a valid XML response.

Link : PHP Example

Link : Python Example (requires Flask, install with "pip install Flask")

Best Practices & Security

• Security: Your module URL is publicly accessible. The APIAuth object, which includes the API key of the calling account, is sent with every request. It is highly recommended that your module validates this key against a known value to ensure the request is legitimately from your TeleCloud instance.
  
  
• Error Handling: Your module should be robust. Use try...catch blocks when calling your carrier's API. If any error occurs, ensure you always return <SUCCESS>N</SUCCESS> with a clear <ERROR> message.
  
  
• Logging: For easier debugging, log every incoming request from TeleCloud and every outgoing request (and its response) to your carrier. This will be invaluable when troubleshooting issues.
  
  

You are now equipped with the knowledge to build powerful, real-time integrations for your TeleCloud platform. Happy coding!