UI plug-ins

Using plug-ins, you can integrate PortaBilling with external systems and manage external data via the PortaBilling web interface.

The UI Plug-ins tab on the Configuration server web interface allows you to add plug-ins in one place and automatically have them on all web servers. Upon adding new web servers, the plug-ins will be available there as well. They are preserved after a system update to a new release as well. Refer to the Integrating external systems with UI plug-ins documentation for more details.

You can install UI plug-ins in the admin web interface as well as in the distributor, representative, and reseller portals. The configuration process is the same, you only need to specify the appropriate realm (admin, reseller, distributor, or representative).

To configure a plug-in:

1. Prepare a ZIP archive with the following files:
   • The index.html file that describes the plug-in structure.
   • The main.css file that describes the visual appearance of the plug-in.
   • The main.js file that describes the logic and behavior of the plug-in.
     In the main.js file of the plug-in code, use the Extras.make_request API method for the plug-in to retrieve information (e.g., about customer contracts) from the external system, such as CRM, and display it in the PortaBilling web interface.

     

2. Prepare a JSON file with the following fields:
   • route – specify the ID of a panel on the web interface where the plug-in is installed and shown. For example, https://my.portabilling.com/ui/ is your system URL. The trailing / represents the main menu. Therefore:
     • "route": "/company_info" means the new plug-in is accessible from My Company > Company Info in the PortaBilling UI.
     • "route": "/customer/:id/general_info" means the new plug-in is accessible from Customer > General Info in the PortaBilling UI.
       You can add a new panel only if there are existing panels at the same level under a specific entity, such as a customer or reseller. For example, you can add a subpanel to the Customer > General info panel, as it already contains other subpanels, such as Address info, Web self-care, Life cycle panels, etc.
   • routerLink – specify the link that is used as the URL of the panel with the plug-in.
   • linkLabel – specify the name of the panel with the plug-in that is visible to the end users.Optionally, you can also specify:
   • panelSize – the size of the panel where the plug-in is displayed. If you want to have a panel that is of a standard width, use “1”. You can also set other values to adjust the size. For example, setting it to “2” will make the panel twice as wide as the standard size.
   • data – any data that is shown in the panel with the plug-in.

     

1. Log in to the Configuration server web interface, open the Update tab, and the system will display additional tabs.
2. Go to the UI Plug-in tab.
   1. Click Upload Plug-in on the toolbar.
   2. Specify the plug-in name in the Plug-in Name field, e.g., Contracts.
   3. Specify the JSON string of the already prepared file in the Configuration string field.
   4. Select the appropriate realm, e.g., Admin.
   5. Select the prepared file in the .ZIP format from the list, e.g., contracts.zip.
   6. Click Upload Plug-in.

      

3. Go to the Configurations tab and clone the currently active configuration.
4. From the Configuration Tree, click on the ClusterSuite > Web Cluster node.
   1. On the Groups panel, select the UIExternalApps group and select the previously uploaded plug-in for the corresponding realm.

      

   2. Open the TokenBasedApps option and fill in the details required by PortaBilling to communicate with an external system:
      • TokenBasedApps_Name – define the application name, e.g., Contracts.
      • TokenBasedApps_ContentType – define the content type for the Extras.make_request API method (applies globally to all external applications), e.g., application/json. Default value is multipart/form-data.
      • TokenBasedApps_ServerUrl – define the server address where PortaBilling sends POST requests, e.g., https://external_system.com/Contracts.
      • TokenBasedApps_Token – specify the authorization token for external applications. This is used only with Bearer auth type.
      • TokenBasedApps_AuthType – defines the authorization type for external apps in Extras.make_request (is set per application), e.g., Bearer.

      • TokenBasedApps_EnableDelegatedAuthHeaders – defines whether to include X-Delegated-Access-Token and X-Delegated-CSRF-Token headers in outgoing requests to external applications. Set Y to include the headers.

        

5. Click Save. Then click Verify.
6. Click Check/Apply to apply this configuration.