Don’t Fear the DevKit

I get the awesome opportunity to work with lots of MuleSoft developers. Today, many are venturing into the brave new world of connector development. I find a new connector developer’s first steps into this realm can be challenging. My hope, with this blog post, is to identify some of those common gotchas in connector development with Anypoint Connector . I won’t spend much time on implementation here. Let’s instead ensure the pieces are in place to make your implementing smooth.

A connector must be seen to be believed

Let’s set some context before we begin. Connectors…DevKit…what? First, keep in mind, your connector is an abstraction. It’s a reusable component that you, your team, and (possibly) the Mule community can use to interact with given system(s). Like any good abstraction, it should save your developer’s time while still remaining generic enough that additional logic can be implemented (e.g. in a Mule flow). In short, a connector is a beautiful means of hiding away all that crazy API complexity.

ec2-flow

DevKit is the tooling used to create connectors. With the help of auto-generated scaffolding, annotations, and tests we can be up and running with our new connector in no time. Many connectors MuleSoft developer use day-to-day are entirely open source. You should take some time exploring Anypoint Exchange to see a complete listing of connectors as well as MuleSoft’s GitHub to check the source code of community connectors implemented in DevKit. These can act as great patterns / reference in your own development. Lastly, it’s worth mentioning that DevKit can also be used to develop reusable modules and transformers.

You are your environment

A common stumbling point in connector development is setting up your environment. Let’s start by listing out what you need in order to develop connectors.

Anypoint DevKit plugin can be installed into Anypoint Studio via the update site. You can access Studio’s update sites by clicking Help > Install New Software in the menu bar. The Anypoint Addons site can be found within the Options dropdown. Within the Anypoint DevKit Plugin, check the Anypoint DevKit Extention. Run through the installation process (Studio will have to restart).

update-sites

Maven is a software project management tool that you’ll need to create Anypoint connectors. While I’ll spare you all the details about Maven in this post, if managing builds with a tool like Maven, Gradle, and/or SBT is new to you, consider visiting https://maven.apache.org/. Before going any further, be sure to install Maven on your machine. Maven can be installed by downloading the binary or via a package manager. Both routes are listed below.

Binaries – Download, unpack, and add the bin directory to your path. The binaries can be found at https://maven.apache.org/download.cgi. If you have a package manager, install directly via the respective command below.

After installation, it’s helpful to ensure that Maven is available to your PATH and environment variables such as JAVA_HOME are set. To check, run mvn -v from a command-line prompt. If the Maven bin directory is part of your PATH, results will be returned. If an error is returned, resolve what the error says is missing before continuing. Below is a shot of what a working Maven installation could return.
mvn-version

Lastly, let’s ensure Studio is aware of Maven’s existence. Open Anypoint Studio’s preferences. Within Anypoint Studio, select Maven Settings. If not already, set the Maven installation home directory. This is M2_HOME, not M2_HOME/bin. Ensure Automatic pom maintenance is checked. This way, Studio can update the pom as you develop.

maven-settings

Creating a connector project

Now that our environment is in check, we’re set to create a new Anypoint Connector Project. From the menu bar, navigate to File &gt; New &gt; Anypoint <a href="https://www.mulesoft.com/exchange#!/?types=connector" target="_blank" rel="" title="Cloud Connectors" >Connector</a> Project. Give the connector a name (note you do not need to add connector into the name). Open the Type dropdown. Here is our next source of confusion, which type of connector do I want?

  • Java SDK – Provides the most control over the connector and requires the most implementation. An obvious choice when a client library exists to communicate with the external resource. Also a good options when you’ll be using a library such as Jersey or creating your own library from scratch.
  • SOAP Connect (3.7+) – Automatically generate a reusable connector from a WSDL or multiple WSDLs. Learn more about SOAP connect here.
  • REST – Very convenient way to produce a REST-based connector. Settings are specified via annotations on an abstract connector class. If more control is desired, a Java SDK connector utilizing Jersey can be used.
  • SOAP – Generates processors based on WSDL. Uses wsdl2java and cxf client to interact with backend SOAP API. More control over interaction than with SOAP Connect connector.

In this example, I’ll be creating a Java SDK connector.

@Processor

Now we’ve generated a new connector project. What exactly will we be exposing to our developers? This is where the @Processor annotation comes in to play. Look inside of the main connector file {your-<a href="https://www.mulesoft.com/exchange#!/?types=connector" target="_blank" rel="" title="Cloud Connectors" >connector-</a>name}-<a href="https://www.mulesoft.com/exchange#!/?types=connector" target="_blank" rel="" title="Cloud Connectors" >connector</a>.java. You’ll see there’s already a method with @Processor on it. Creating a new method and annotating it with @Processor will expose it as another operation within your connector. Here are two connector operation examples for a AmazonEC2 connector. First is the perspective of the code, then how it’d be exposed to the integration developer.

connector-gui

Setting the icon

Lets face it…we all love seeing our awesome custom icon when dropping our connectors into Mule flows. Interestingly, this task also can be a point of contention for new connector developers. Good news for those using the newest DevKit in 3.7.0. We’ve included the icon as part of the setup wizard! Now you can set your icon before you get developing.

connector-icon-wizard

Now, what if you want to swap the icon during development? If you dig deep enough you may find a @Icon annotation. This annotation has been deprecated and should not be used. Instead, use the convention for large and small icons within the $PROJECT_HOME/icons directory. Your icon sizes should be 24x16 and 48x32. The naming convention of each file should match {<a href="https://www.mulesoft.com/exchange#!/?types=connector" target="_blank" rel="" title="Cloud Connectors" >connector-</a>name}-<a href="https://www.mulesoft.com/exchange#!/?types=connector" target="_blank" rel="" title="Cloud Connectors" >connector</a>-{dimensions}.png. Now, when developers install the connector, they’ll find the Studio palette and their flows to reflect your icon.

ec2-ui

Get installing

Last up, lets get this connector into studio. Using the DevKit plugin, we have a very convenient means of instantly installing a connector into Studio. Before attempting this, lets see if there are any errors in your connector project. If you also modified the original connector by adding a new @Processor or other changes, you may see problem(s) similar to this:

sources-error

Notice the error is part of the generated-sources directory. This means the connector’s automatically generated source code has become out of sync with the changes we’ve made. This is no problem! We have two options we can take to resolve it. First, right click on your connector project and select Anypoint Connector. Notice there is an options to Generate Sources from here. This should resolve any errors you’re experiencing within the generated package. Also notice there is a Install or Update option. To install, DevKit will need to regenerate sources. Lets click this option to begin the installation into Studio.

connector-install

Done! Using Maven, studio has generated an eclipse update site and installed the connector’s library to your local Maven repository. You can verify this by going to Help &gt; Install New Software and browsing through your available update sites. You’ll see a local address set to $PROJECT_HOME/target/update-site. Remember that project error from earlier? If it still remains, you simply need to refresh the connector project so Studio is aware of the changes to generated-sources. This entire build process has been controlled by Maven. This means you can add the connector project to your CI strategy and deploy the artifact(s) to a remote maven repository for all developers to enjoy!

Hope you enjoyed this little write-up on some random DevKit basics. Best of luck getting connected!


We'd love to hear your opinion on this post