MuleSoft Custom connector using XML based SDK

In this Tutorial we will talk about how to create a MuleSoft custom connector using XML based SDK. MuleSoft provides many connectors to connect to various third-party system. However, you may find yourself in a situation where there is no connector provided by MuleSoft to connect to a different system OR you see a repetitive piece of business/technical functionality (error handling, custom logging etc) in your organization which can be reused in different projects.

Connectors can make your life easy. MuleSoft SDK comes very handy to create connectors by yourself. The same connectors can be used by just dragging the connector from the Mule Palette section by the developers.

For this tutorial, we will be creating a calculator connector, which would accept the mathematical expression to be evaluated by the calculator and the connector would responds with the result. Calculator connector would internally be calling a calculator API http://api.mathjs.org/v4/

Follow the steps below to create a sample custom connector using xml-based SDK.  You can refer to MuleSoft documentation for more details https://docs.mulesoft.com/mule-sdk/1.1/

Creating the Project for the Custom connector

To create the project for the connector, run the command below in the command prompt where you want to create the project. Since MuleSoft does not provide a way to create connector project from Anypoint Studio, we need to use maven archetype.

mvn archetype:generate -DarchetypeGroupId=org.mule.extensions -DarchetypeArtifactId=mule-extensions-xml-archetype -DarchetypeVersion=1.2.0 -DgroupId=com.mulesy.mule.modules -DartifactId=mulesy-calculator-connector -Dpackage=mule-module -Dversion=1.0.0-SNAPSHOT -DextensionName="Mulesy Calculator Connector"

Apart from below parameters all other parameters passed are static. Use the latest value of the parameter DarchetypeVersion

• DgroupId – group id of your connector.
• DartifactId – artifact id of your connector.
• Dversion – version of the connector
• DextensionName – name of your connector

You will see a project generated as below with the xml file

Import the project in Studio to add the logic into your connector. You can use any MuleSoft existing modules and orchestration in this connector to build your logic of the connector. E.g Database, choice router, Dataweave, http connector etc.

Building the Custom connector

You will need to define below for your connector.

• Operation
  • Input
    • Input Parameters of the Operation
  • Body
    • Body of the of the Operation
  • Output
    • Output of the Operation

You can have multiple operations in the connector to support various functions. You can use any mule modules to build the body of the connector.

For our connector demo, we will be having one operation called “calculate” with one input called “expression” and one output called “result”

Here we have defined the input, a sample body, and the output.

<?xml version="1.0" encoding="UTF-8"?>
<module name="Mulesy Calculator Connector Smart Connector"
	prefix="module-mulesy-calculator-connector" doc:description="This module relies in runtime provided components"

	xmlns="http://www.mulesoft.org/schema/mule/module" 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-mulesy-calculator-connector"
	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-mulesy-calculator-connector http://www.mulesoft.org/schema/mule/module-mulesy-calculator-connector/current/mule-module-mulesy-calculator-connector.xsd">

	<operation name="calculate"
		doc:description="Takes a mathemaitical expression and returns the result of it">
		<parameters>
			<parameter name="expression" type="string" doc:description= "mathematical expression" />			
		</parameters>
		<body>
			<mule:set-payload value="Sample Output" />
		</body>
		<output type="string" doc:description="Payload's output" />
	</operation>

</module>

NOTE: The best way to create the body of the connector is to create another flow with all the mule modules to construct the body of the connector. Then copy the XML snippet from the flow to the xml file of the connector to create the body.

Here is the final xml snippet of the connector. Do not forget to copy the namespace of the mule modules also. We have used “http:request” component hence added the related namespaces in the connector config file.

<?xml version="1.0" encoding="UTF-8"?>
<module name="Mulesy Calculator Connector Smart Connector"
	prefix="module-mulesy-calculator-connector" doc:description="This module relies in runtime provided components"

	xmlns="http://www.mulesoft.org/schema/mule/module" 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-mulesy-calculator-connector"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:http="http://www.mulesoft.org/schema/mule/http"
	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-mulesy-calculator-connector http://www.mulesoft.org/schema/mule/module-mulesy-calculator-connector/current/mule-module-mulesy-calculator-connector.xsd
           http://www.mulesoft.org/schema/mule/ee/core http://www.mulesoft.org/schema/mule/ee/core/current/mule-ee.xsd
		   http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd">

	<http:request-config name="HTTP_Request_configuration" doc:name="HTTP Request configuration" doc:id="58a47650-8884-41ca-8e86-5e8fb9854933" basePath="/v4">
		<http:request-connection host="api.mathjs.org" >
			<http:authentication >
				<http:basic-authentication username="username" password="password" />
			</http:authentication>
		</http:request-connection>
	</http:request-config>

	<operation name="calculate"
		doc:description="Takes a mathematical expression and returns the result of it">
		<parameters>
			<parameter name="expression" type="string" example="2*(7-3)"
				doc:description="mathematical expression" />
		</parameters>
		<body>
			<http:request method="GET" doc:name="Request"
				doc:id="f2ffd9f2-30d3-4532-9254-3e6b2f4c8b95" config-ref="HTTP_Request_configuration"
				path="/">
				<http:query-params>
					<![CDATA[#[output application/java
---
{
	"expr" : vars.expression
}]]]>
				</http:query-params>

			</http:request>
		</body>
		<output type="string" doc:description="Payload's output" />
	</operation>

</module>

Installing the custom connector

Next step in to install the connector. To install the connector, run “mvn clean install” from the project root. It will install the connector in your .m2 repository

Testing the custom connector

You can now use the connector in your project. Add the connector dependency below in the project

<dependency>
	<groupId>com.mulesy.mule.modules</groupId>
	<artifactId>mulesy-calculator-connector</artifactId>
	<version>1.0.0-SNAPSHOT</version>
	<classifier>mule-plugin</classifier>
</dependency>

Once you add the dependency in the project you would see the connector as in the screenshot below

Provide the input to the connector and run the project.

You should be able to see the response from the connector as shown in logs.

Sample Project – mulesy-calculator-connector