How to Execute a Custom Module 

Step 1: Associate the Custom Module with the Bridge

1. Click the settings gear icon at the top-right corner of the header bar.
   
2. Navigate to Advanced >> Bridge, then choose Bridge.
3. In the Bridge list page, click on the name of the Bridge to which the Custom Module needs to be associated. 
4. The selected Bridge details will be displayed. Under the Modules tab, click the Associate Modules button, and from the displayed list of modules select the name of the Custom Module you wish to associate with the Bridge.
   
5. Click Save.
   

      

Step 2 : Execute the Custom Module 

To execute the custom module in the Bridge, the Message module is utilized. To accomplish this:

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

2. In the Message list page that loads, click the New Message button.

3. In the New Message window, enter the following details.
   

• Name: Enter a unique name for the message.

• Bridge: Select the Bridge you would like to execute from the dropdown list.

• Module: The created custom module will be displayed in the dropdown list. Select the custom module to execute it through this message.

•  Type: Select the message type:

• Synchronous - Executes tasks in the same request and provides a response

• Asynchronous - Executes tasks in the background.

• Request Data: The instructions to be executed by the Bridge need to be given here in JSON format. Based on the custom module chosen, the request data format will vary.

      Note: The request data format is not predetermined and will vary according to the implementation of the custom module.

• Response: If the type is Synchronous, the response to the request will be displayed under this tab.

4. Once all the details are filled, click Execute.

Upon successful message execution, you can view the response (for synchronous type messages), and a server call entry in the message list of your 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.

Authenticator Class:

• 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".

Controller Class   

Users can implement their action implementations. Annotations and their purposes are detailed below:

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");
    }
}

SampleSoapService.java

import javax.jws.WebMethod;
import javax.jws.WebService;
@WebService
public class SampleSoapService {
    @WebMethod(operationName = "SayHello")
    public String sayHello(String name) {
        return "Hello " + name + "..!";
    }
}