Creating a custom connector using XML SDK

  • June 14, 2022

MuleSoft provides the option to create custom connectors in case we do not have a readymade connector in place. You can use either the advanced, feature-rich Java Mule SDK or the simpler XML SDK, which provides only outbound operations and doesn’t support recursive calls.

Here we’ll see how to create a custom connector using XML SDK.

The XML SDK is an alternative to the more advanced Java-based Mule SDK. Let’s understand the basics of XML SDK.

XML SDK basics
The framework simply adds a few syntactic idioms as XML elements <module>, <operation>, and <property> that enclose the main parts of module.

Module
The <module> element is the root of an XML SDK module. It contains all properties and operations that belong to the module.

Properties
The properties are similar to the parameters exposed by operations, but they act at a level that affects all instances of the XML SDK component in the project instead of a specific operation. You can think of this as a configuration of the connector.

Operations
An <operation> element defines a set of input parameters and a single output(Like a function)

  • Input parameters (<parameter>): Declares a type to be entered when calling the operation. Keep in mind that these parameters are the only data that the message processors in the <body> scope can access.
  • Body (<body>): Defines a chain of components to be executed, similar to a flow.
  • Output (<output>): Declares the output type of your XML SDK module. This is the type of the payload after it is processed by the <body>.
  • Errors: Declares the error types the XML SDK can raise (or map) within the <body>. 

Now that we understand the basics of XML SDK, let’s create one demo custom connector.

Demo XML SDK connector
 We’ll be creating a demo connector named as “Sample-connctor,” which will have one processor named “Get response”. It will hit one online testing API and get the JSON data, convert it into a string and provide back to the calling flow.

To create an XML SDK module kindly follow below steps:

1. Add the MuleSoft repository to your Maven (mvn) settings file:

<profiles>
     <profile>
         <id>Mule</id>
         <activation>
             <activeByDefault>true</activeByDefault>
         </activation>
         <repositories>
             <repository>
                 <id>mulesoft-releases</id>
                 <name>MuleSoftRepository</name>
                 <url>http://repository.mulesoft.org/releases/</url>
                 <layout>default</layout>
             </repository>
         </repositories>
     </profile>
 </profiles>

2. Use Maven (mvn) from to execute the following command:(You can use your own connect names)

mvn archetype:generate -DarchetypeGroupId=org.mule.extensions
-DarchetypeArtifactId=mule-extensions-xml-archetype
-DarchetypeVersion=1.2.0 -DgroupId=org.mule.extension
-DartifactId=Sanket-demo-connector-mule-extension
-DmuleConnectorName=Sanket-demo-connector

3. When prompted to indicate whether the values are correct, press enter to continue. Your build should be successful.

4. The Maven archetype creates a stub project with a minimal amount of code for the XML SDK module and a functional test to run it.

5. Add following tag in POM if not present:

  <pluginRepository>
     <id>mulesoft-releases</id>
    <name>mulesoft release repository</name>
     <layout>default</layout>
     <url>https://repository.mulesoft.org/releases/</url>
  <snapshots> 
    <enabled>false</enabled>
  </snapshots>
    </pluginRepository>
 </pluginRepositories>

6. Do the modifications in the created XML module-<app>.xml in \src\main\resources\org\mule\extensions\smart\connector

7. You also need to update corresponding test-suite file for Munits to run. For this demo, we’ve removed the Munit file.

8. If you have to consume any Mule Plugin from XML SDK, then you need to take two steps as below:

a. Add the dependency into the POM file for the XML SDK module

b. Add the schema location to the root element

9. In our case, we want to use httt module. After modifications the files look like:

POM

<?xml version=”1.0″ encoding=”UTF-8″?>
<project xmlns=”http://maven.apache.org/POM/4.0.0″
xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xsi:schemaLocation=”http://maven.apache.org/POM/4.0.0
http://maven.apache.org/xsd/maven-4.0.0.xsd”>
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.mule.extension</groupId>
    <artifactId>Sanket-demo-connector-mule-extension</artifactId>
    <packaging>mule-extension</packaging>
    <version>1.0.0-SNAPSHOT</version>

    <name>Smart Connector: using mule components</name>
    <description>A Mule extension done with pure Mule DSL that depends in the runtime operations (set-payload, set-variable, etc.)</description>


    <properties>
        <mule.version>4.1.1</mule.version>

        <mule.extensions.maven.plugin.version>1.1.6</mule.extensions.
maven.plugin.version>

        <munit.version>2.1.0</munit.version>
        <munit.extensions.maven.plugin.version>1.0.0-BETA</munit.extensions.maven.plugin.version> 
       <munit.input.directory>src/test/munit</munit.input.directory>
       <munit.output.directory>${basedir}/target/test-mule/munit</munit.output.directory>

        <maven.resources.version>3.0.2</maven.resources.version>
    </properties>


    <dependencies>
        <!–Needed to discover the ‘xml-based’ XmlExtensionLoader for smart connectors–>
        <dependency>
            <groupId>org.mule.runtime</groupId>
            <artifactId>mule-module-extensions-xml-support</artifactId>
            <version>${mule.version}</version>
            <scope>provided</scope>
        </dependency>
        <!–MUnit Dependencies–>
        <dependency>
            <groupId>com.mulesoft.munit</groupId>
            <artifactId>munit-runner</artifactId>
            <version>${munit.version}</version>
            <classifier>mule-plugin</classifier>
            <scope>test</scope>
        </dependency>
<dependency>
<groupId>org.mule.connectors</groupId>
<artifactId>mule-http-connector</artifactId>
<version>1.6.0</version>
<classifier>mule-plugin</classifier>
</dependency>
    </dependencies>
    <build> 
       <pluginManagement> 
           <plugins> 
               <plugin>
                    <groupId>com.mulesoft.munit</groupId>
                    <artifactId>munit-extensions-maven-plugin</artifactId> 
                   <version>${munit.extensions.maven.plugin.version}</version> 
                   <executions> 
                       <execution> 
                           <id>munit-extension-test</id>  
                          <phase>integration-test</phase>
                            <goals>  
                              <goal>test</goal> 
                           </goals>  
                      </execution>  
                  </executions>
                    <configuration>
                        <dynamicPorts>
                            <dynamicPort>a.dynamic.port</dynamicPort> 
                       </dynamicPorts>
                        <environmentVariables>
                            <MY_ENV>envVar</MY_ENV>
                        </environmentVariables>
                    </configuration>
                </plugin> 
               <plugin>
                    <groupId>org.apache.maven.plugins</groupId> 
                   <artifactId>maven-resources-plugin</artifactId>
                    <version>${maven.resources.version}</version>
                    <executions> 
                       <execution>
                            <id>copy-munit-resources</id>
                            <phase>process-test-resources</phase>
                            <goals>
                                <goal>copy-resources</goal>
                            </goals>
                            <configuration>
                                <outputDirectory>${munit.output.directory}</outputDirectory> 
                               <resources>
                                    <resource>
                                        <directory>${munit.input.directory}
</directory>
                                        <filtering>true</filtering> 
                                   </resource>
                                </resources>    
                        </configuration>
                        </execution>
                    </executions>
                </plugin> 
           </plugins> 
       </pluginManagement>

        <plugins>
            <plugin> 
               <groupId>org.mule.runtime.plugins</groupId> 
               <artifactId>mule-extensions-maven-plugin</artifactId>
                <version>${mule.extensions.maven.plugin.version}
</version>  
             <extensions>true</extensions> 
           </plugin>
            <plugin>
                <groupId>com.mulesoft.munit</groupId>  
              <artifactId>munit-extensions-maven-plugin</artifactId>  
          </plugin>
        </plugins> 
   </build>
<pluginRepositories> 
  <pluginRepository>
     <id>mulesoft-releases</id>
    <name>mulesoft release repository</name>
     <layout>default</layout>
     <url>https://repository.mulesoft.org/releases/</url>
    <snapshots>
     <enabled>false</enabled>
  </snapshots>
    </pluginRepository>
 </pluginRepositories>

</project>

module-Hello.xml

<?xml version=”1.0″ encoding=”UTF-8″?>
<module name=”Sample-connctor”
        prefix=”module-hello”
        doc:description=”This module relies in runtime provided components”

        xmlns=”http://www.mulesoft.org/schema/mule/module”
xmlns:http=”http://www.mulesoft.org/schema/mule/http”
        xmlns:mule=”http://www.mulesoft.org/schema/mule/core”
        xmlns:doc=”http://www.mulesoft.org/schema/mule/
documentation”
        xmlns:tns=”http://www.mulesoft.org/schema/mule/module-hello”
        xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
        xsi:schemaLocation=”http://www.mulesoft.org/schema/
mule/module
http://www.mulesoft.org/schema/mule/module/current/mule-module.xsd http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/module-hello
http://www.mulesoft.org/schema/mule/module-hello/current/mule-module-hello.xsd
http://www.mulesoft.org/schema/mule/http
http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd”>

    <property name=”username” type=”string” doc:description=”Username credential.”/>
<property name=”password” type=”string” password=”true” doc:description=”Password credential”/>
<http:request-config name=”HTTP_Request_configuration” basePath=”/api/”>

<http:request-connection protocol=”HTTPS” host=”reqres.in” />
</http:request-config>
<operation name=”get-response” doc:description=”get-response”>
<parameters>  
<parameter name=”page” type=”number”/>
  <parameter name=”numberBlowercaseUPPERCASE” type=”number”/>
</parameters>
        <body>
<http:request method=”GET”  config-ref=”HTTP_Request_configuration” path=”/users”>
<http:query-params >
<![CDATA[#[output application/java—{ page : 2}]]]>
</http:query-params> </http:request> <mule:set-payload value=”#[%dw 2.0output application/java—write(payload, ‘application/json’)]”/>
        </body>
        <output type=”string” doc:description=”Payload’s output”/>
    </operation>

 </module>

10. Run mvn clean install in the /Sanket-demo-connector-mule-extension to create the plugin for the Hello XML SDK module.

11. Now the connector is created into your local repository, you can use it by adding below dependency tag in any application’s POM.xml where you want to use this connector.

<dependency> 
      <groupId>org.mule.extension</groupId>
       <artifactId>Sanket-demo-connector-mule-extension</artifactId>
       <version>1.0.0-SNAPSHOT</version>
       <classifier>mule-plugin</classifier>
</dependency>

12. Once dependency is added in your POM, you will be able to view connector in the Mule Pallet

You can also publish your connector to Anypoint Exchange. Please refer this official documentation for the steps.

NOTE: The aim of the article is to give familiarity with creating custom connector with XML SDK The demo connector does not provide any real purpose to any business/use case.

References
[1] https://docs.mulesoft.com/mule-sdk/1.1/
[2] https://docs.mulesoft.com/exchange/to-publish-assets-maven
[3] https://docs.mulesoft.com/mule-sdk/1.1/xml-sdk

— By Saket Kangle