We live in a world where the slow one is left behind. You company must adapt to the ever changing and complex world of technology integration. We live in a world where it is no longer acceptable to take months to integrate new services. So today’s post is about speed. I will show how you can build a Cloud Connector for Mule in five easy steps. The same cloud connector that you will be able to use on Mule standalone or Mule iON to integrate into your company. Ready?
To follow this guide step by step you need a few things. First and foremost is that you need Maven installed. Second you will need an account for whatever API you are trying to connect to. In this post I will show you how to implement Freshbooks API. You can register for a FREE account with them here.
Step 1: Creating the Project
Creating a skeleton cloud connector is as easy as running a Maven archetype. The following command line will look complicated just by the sheer number of arguments, but do not despair since most of them are default values. The important bits are the last three arguments which indicate the Java package under which the skeleton code will be generated, the name of the project itself and the name of the cloud service.
Optionally you could potentially also change the kind of service (via the cloudServiceType argument), the groupId of the project and/or the targeted Mule version (muleVersion). More information about this can be found on our wiki.
Step 2: Understanding the Skeleton
Before we can move one we need to understand what has been generated for us as a skeleton connector. The most crucial piece is the connector class itself located at src/main/resources/org/mule/modules/freshbooks/FreshbooksCloudConnector.java. This is where most of your coding will ocur and this is the class that the Cloud Connect SDK will later process to generate the Mule component.
NOTE: The code generation occurs during the generate-sources phase in Maven which is part of the compile lifecycle. In short, to trigger the generation do either mvn compile or mvn install.
Every method in this class marked with @Operation will receive a special treatment by our SDK. That special treatment involves the generation of several Java source files that will allow the invocation of this method from a Mule flow using a naming convention. As it has been generated, the method myOperation could be invoked from a Mule flow as:
Also for every argument that the method receives it will get an attribute on the XML invocation. So imagining that the myOperation method had an argument String text then it could be invoked as follows:
Step 3: Configuring the connector
A connector may require some configuration from its user in order to perform its job. In this case every call that we will make to Freshbooks requires an authentication, therefore we will need the user of this connector to provide us with credentials of some sort that we can then pass on to Freshbooks.
Freshbooks supports two authentication forms. OAuth rev 1.0A and a token-based mechanism. We will choose the latter for this exercise as it is easier to implement. Freshbooks API endpoint is dependent on a particular user, so we need to ask our user that piece of information as well.
The configuration information is coded in the cloud connector as bean properties annotated with @Property.
Let’s write that up shall we?
NOTE: It is very important that for every property that you mark as configurable with @Property, you make sure that there are setters and getters for it.
If you run mvn compile or mvn install then the code generation engine will kick in and notice automatically that you have properties in the connector that you are configurable and therefore generate a special XML element called config which can be used to configure it. This element can only be used outside of flows. The following is an example of such use:
Step 4: Your First Real Operation
The time has come to actually write some code. Writing an operation is extremely simple and most operation will reduce to a basic outline of three easily identifiable blocks:
- Create a Request (wherever that is XML, JSON or even a REST url)
- Send Request to Cloud Provider (in this case Freshbooks)
- Parse Response and Return It
This outline accounts for the 90% of the connectors we have written. We are not going in detail into any of these steps. You can find a number of resources online that will explain the basics of constructing requests, parsing responses or even communicating to a Cloud provider. But I’m going to be showing you how can you put it all together in an @Operation. See the following example:
We have a method named buildCreateCategoryRequest that will build the request for us taking as arguments the same arguments that the operation receives. Once my request has been built I need to send it to Freshbooks and parse its response. The actual communication is accomplished in the sendRequest method.
The method annotated @Operation may use any of the class properties as it see fit, in this case we don’t see it but the sendRequest method is using the previous authorizationToken and apiUrl to authenticate against Freshbooks and to know where to send the requests respectively.
The SDK will take every method that is annotated with @Operation and build a Message Processor around it. The message processor will handle expression evaluation, argument transformation, configuration management and more for free. After running mvn install or mvn compile over the example you would be able to do this:
The expression evaluation performed by the Message Processor that wrapped the operation allowed the user to actually use #[INBOUND:categoryName]. This is an extremely powerful combination, let me show you using the last example in a flow:
The flow presented in the example will start an HTTP listener at port 9090, when you access it with your web browser by using the following url http://localhost:9090/create-category it will invoke the following chain of message processors. The chain in the example is single message processor, our message processor. Check this out. The HTTP inbound endpoint will attach every portion of the query string as an inbound property. So if I use this url http://localhost:9090/create-category?name=Sports it will create a category named Sports in Freshbooks. Isn’t it cool?
Step 5: Wrapping it all up
A Cloud Connector at the end of the day is nothing more and nothing less than a specialized JAR file. This JAR file (which is automatically built for you by Maven when you do mvn install) contains all the required byte code needed to execute your connector plus the much needed Mule schema file. So, the question is how do you use it in your Mule app? First, you need to add it as a Maven dependency to your Mule project and then you need to reference the schema from your mule-config.xml.
If you go back to the beginning of the article you will notice that the connector class had a @Connector(namespacePrefix=”Freshbooks”), this annotation is used to create the namespace. The namespace format is always:
and the schema location is:
Therefore to use it, declare the namespace like this in your mule-config.xml:
Of course that this is just the tip of the iceberg of what you can accomplish with Mule and Cloud Connect, if you require more information you can find the full source code for the connector in our GitHub repository here.
I truly hope that you enjoyed this guide. If you have developed a cloud connector and want the recognition earned by doing so, let us know. We’ll make sure that are properly acknowledged at our MuleForge.
If you have further questions you can reach me at firstname.lastname@example.org. Alternatively you can post your questions in our forums. If you want to follow my every move you can do so here: @3miliano.
See ya next time!