Configure Custom Module 

The module page includes three main sections:

• Module Overview: View and configure module details and properties.

• Settings: Displays configuration widgets linked to the module. You can view or update these as needed.

• Task Meta: Available for JAR-type modules. Defines the payload JSON used to validate incoming payloads or generate form builders. Refer to the Task Meta section for more details.

The Task Meta section appears in the Custom Module page only when the module type is set to JAR.

Module Overview 

Click the Module Overview section of the selected module. The details of the chosen custom module are displayed here, allowing you to configure and manage its properties.  

Properties

This section displays the details of the created module, including its deployed version, which can be updated as needed. 

Source File(s)

• Upload the JAR file generated from the SDK (if applicable).

• The uploaded JAR becomes active automatically.

Limitations:

• A maximum of three ZIP files can be attached.

• Only one JAR file can be active at a time.

• When a new JAR is activated, previously active files become inactive, and the new one is automatically deployed.
  

Menu Configuration

Create widgets to collect module-specific properties using custom forms. These widgets appear as configurable menus in either the Bridge Agent or Qntrl Cloud interface.

To create a new menu widget:

1. Click New Settings Menu.

2. Provide the following details:
   

1. Name: Enter a name for the menu.
   

2. Location: Choose where the menu should appear:
   

1. Bridge Agent – Listed under the Configuration section in the Bridge Agent.
   

2. Bridge Cloud – Listed under Settings tab in the Custom Module.
   

3. Click Save to create the widget.

The Publish button turns green when unpublished changes exist.

To manage widgets, hover over the widget name, click the action menu (⋮), and choose Disable or Delete.

Associated Bridges  

Displays the bridges linked to this module.

• When a new JAR is activated, it is automatically deployed to the associated bridge.

• If deployment doesn’t occur automatically, click Deploy to deploy and update the bridge manually.

Configurations 

Task Meta   

1. Payload validation — Validates that incoming payloads conform to the defined JSON schema before execution. This prevents errors by ensuring all required fields are present and follow the correct data type (e.g., string, object, number).
2. Form Builder (UI Generation) — Automatically construct form builders by extracting field details from the Task Meta schema. This allows users to easily provide the required task parameters without manually writing JSON.

1. Open your Custom Module.

2. Navigate to the Task Meta section.

3. Click Create Task Meta.

4. Provide the following details:

1. Name: A unique name for the Task Meta.

2. Description: A short explanation of what the task does.

5. Choose one of the schema creation methods:

1. Payload (auto-generate): Use this option when you already have a sample payload.
   

1. Give your sample payload JSON and click Generate.
   

2. The right panel automatically generates a JSON schema based on the structure.
   

3. Review the schema and click Create to save it.
   

4. This method is ideal when the payload structure is known and consistency is required.
   

2. Custom (manual schema creation): Use this when you want full control over the JSON schema or already have a predefined schema.
   

1. Directly enter or paste your JSON schema.
   

2. Click Create to save.
   

      

Managing Task Meta 

Click any Task Meta to open its details.

The following actions can be done:

• Edit Description  : Use the edit icon to modify the description.

• Edit Schema  : In the editor section, update the JSON schema as needed.

• Delete Task Meta  : Click the delete icon at the top to remove the entire Task Meta definition.

• Version  : Each Task Meta maintains version history. Every update creates a new version. Use the Version dropdown to switch between versions.

• Download Current Version: Downloads the current version.

• Delete Current Version: Delete the version that is currently selected. Latest version cannot be deleted, since it is used for validation.

• Sample Payload  : Use the Sample Payload dropdown to view the sample payload derived from the schema. This helps users understand the correct format when sending inputs to the Bridge task.

• Once changes are done click Save as New Version.
  

Version Limitations:

1. A maximum of 50 versions can be stored.
   
2. To add the 51st version, you must delete an older version, except the latest version, which cannot be removed.
   

Sample Task meta

Below is an example schema defining the payload for an SSH task:

{
    "$schema": "https://json-schema.org/draft/2020-12/schema#",
    "type": "object",
    "properties": {
          "task_name": {
              "type": "string",
              "default" : "ssh_task"
          },
          "credential": {
              "type": "object",
              "properties": {
                    "name": {
                           "type": "string"
                    }
             }
          },
          "task_details": {
              "type": "object",
              "properties": {
                    "host": {
                        "type": "string"
                    },
                    "command": {
                        "type": "string"
                    }
              }
          }
        }
}

How to Execute a Custom Module 

1. Associate the Custom Module with the Bridge

The custom module is now associated with the bridge and will be listed under the Modules section of the Bridge configuration. Cick Save again to confirm this bridge configuration update.

2. Execute the Custom Module 

Custom module executions are performed through the Messages module in Bridge.

To execute your custom module task:
Refer to the Messages section to learn how to create and run a message in Bridge.

While creating a new message, choose your custom module and select the appropriate task from the task list, then execute it.

Upon a successful message execution:

• The response is displayed immediately for synchronous messages.
• A server call entry appears in the Message list within the Bridge Agent.
  
  

Types of Custom Module  

1.  Jar 

Your main class in custom module is expected to extend the JarModule interface and override the request method.

Sample Java class 

2.  Rest API Services 

Support for REST API services in custom modules allows end users to develop their own REST API modules in their preferred format. Upon deployment, these REST API endpoints will be published on the Bridge server.

Deployment on the Bridge Server:

1. Upon deployment on the Bridge server, REST API endpoints will be retrieved using the RestController and RequestDetails annotations.
   
2. URL Construction: URLs are constructed as rest/{module_name}/{controller_path}/{request_path}.
   
• Module Name: Retrieved from the main class's getModuleBasePath() function.
• Controller Path: Path fetched from the RestController annotation.
• Request Path: Path retrieved from the RestController annotation.
• URL Method: Retrieved from the RequestDetails annotation.
3. REST Module Configuration File:
• Method and path details are added to the rest_modules.xml file, which is loaded during server start.
  
• If a new version is updated in Qntrl, URLs in the configuration file are deleted and replaced with URLs fetched from the new version.
  
• Upon module deletion in Qntrl, the module's details are removed from the configuration file.
  

Implementation

REST API Service Classes  

Classes and their purposes for implementing the REST API Service are detailed below:

Configuration Class:

• Contains the module's base path and the authenticator's class instance.

• Implements
  com.zoho.qntrl.bridge.sdk.module.rest.RestServiceModule

• Override Methods

➤ getModuleBasePath()
Should return the module's base path used to construct the REST API Url.

➤ getServiceAuthenticatorClassInstance()
Should return the authenticator's class instance.

• Users must implement their authentication methodology.

• Implements com.zoho.qntrl.bridge.sdk.module.rest.RestServiceAuthenticator

• Override Methods
  

• authenticate (HttpServletRequest, HttpServletResponse)
  

• Request and response instances of the triggered API's are passed as arguments. If the request is authenticated and valid, the respective method implementation will be called; otherwise, it returns the error message as "User is not authorized".

i. RESTContoller: Marks the class as a REST API controller, which can also be mentioned as an entity. In the future, for OAuth 2, scope will be mapped in the controller.

• Type - Class Annotation

• Fields

• basePath - Maps the controller with the base path; it should not have the same base path. It provides provision to retrieve the global metadata of the controller using the URL. No validation is done. If the same base path is used, it will be added to the rest module configuration file, and whichever returns first will be executed.

ii. RequestDetails: Identifies the method to invoke for the URL. The URL's method and path will be retrieved using it.

• Type - Method Annotation

• Fields

• method - The request method name should be provided (mandatory).

• path - The path URL should be mentioned. It's not mandatory as the base path will be provided in the controller, and for basic CRUD operations, it's enough.

Generating ZIP File

To generate a ZIP file:

1. Generate the class files along with the parameter names stored with it. The parameter name will be used to fetch the value from the request's parameter or header.

2. Create a JAR file using those class files and then ZIP the JAR file.

Global Info   

Users can retrieve the global information of the module and controller using the following endpoints.

1. For Module:
1. Endpoint: rest/{module_name}/_global_info
2. Returns all the paths along with the method details in the module.
2. For Controller:
1. Endpoint: rest/{module_name}/{controller_path}/_global_info
2. Returns all the paths along with the method details present in the particular controller.
   

3. SOAP Services  

Support for SOAP services within Custom Modules allows end users to create their own SOAP service custom modules in their desired format. Upon deployment, these SOAP service endpoints will be made available on the Bridge server.

Deployment on the Bridge Server: 

• Upon deployment in the Bridge server, SOAP service endpoints are retrieved  from the main class getEndpoint() method.

• Endpoint URLs must begin with /soap.

• SOAP Module Configuration File:
  

• Configuration details of SOAP modules are stored in the  soap_modules.xml  file, which is loaded during server startup.
  

• If a new version is updated in Qntrl, existing URLs related to the module in the configuration file will be deleted and replaced with the endpoints retrieved from the new version.
  

• Upon module deletion in Qntrl, corresponding module details are removed from the configuration file.

Implementation:

To create a SOAP service module, you need to implement the SoapServiceModule interface in the main class. Below is an example of the main class and a SOAP endpoint.

SampleSoapServiceModule.java

import com.zoho.qntrl.bridge.sdk.module.soap.Endpoint;
import com.zoho.qntrl.bridge.sdk.module.soap.SoapServiceModule;

import java.util.Arrays;
import java.util.List;
import java.util.logging.Level;
import java.util.logging.Logger;

public class SampleSoapServiceModule implements SoapServiceModule {

    private static final Logger LOGGER = Logger.getLogger(SampleSoapServiceModule.class.getName());

    @Override
    public void serviceStarted(Endpoint endpoint) {
        LOGGER.log(
            Level.INFO,
            "service {0} - {1} is started",
            new Object[]{endpoint.getName(), endpoint.getUrlPattern()}
        );
    }

    @Override
    public List<Endpoint> getEndpoints() {
        return Arrays.asList(
            new Endpoint(
                "SampleSoapService",
                SampleSoapService.class.getName(),
                "/soap/sample"
            )
        );
    }

    @Override
    public void serviceStopped(Endpoint endpoint) {
        LOGGER.log(
            Level.INFO,
            "service {0} - {1} is stopped",
            new Object[]{endpoint.getName(), endpoint.getUrlPattern()}
        );
    }

    @Override
    public void moduleUnregistered() {
        LOGGER.log(Level.INFO, "sample soap service module got removed");
    }
}      

import javax.jws.WebMethod;
import javax.jws.WebService;

@WebService
public class SampleSoapService {

    @WebMethod(operationName = "SayHello")
    public String sayHello(String name) {
        return "Hello " + name + "..!";
    }
}

To view or update a custom module properties:

1. Navigate to(settings) >> Advanced >> Bridge, then select Custom Module.

2. On the module list page, click the name of the module you want to edit.

3. The module details page opens, where you can view or modify its properties.

4. After making the necessary changes, click Save to apply them.