Mulesoft Service Implementation in Apex

Have you or your client’s Salesforce org recently made the switch to use Mulesoft for API Integrations? Are you having difficulty getting started implementing one of these RESTful services? If so, read on!

Below is a short summary of how to use a Mulesoft Service in Apex code. It is not intended to be comprehensive, but will hopefully help you learn how and where to get started. This is also not a summary of how Mulesoft itself works, or how a Mulesoft Service is developed. We’ll solely focus on the use of these services starting from within a Salesforce organization. If you want to know more about integrating Mulesoft, contact us! This is also not an introduction to REST APIs - I recommend familiarizing yourself with REST APIs prior, though I would say extensive knowledge is not necessary.

Setup

A list of your org’s Mulesoft services can be found through Setup < Mulesoft < Services. To import a service, you will need access to Mulesoft Anypoint Platform. Use the ‘Log In’ button on the Mulesoft Services page in setup to enter your credentials. Once logged in, you can click ‘Import’ on the setup page, then follow the import wizard.

After importing the service, you will find it listed under the ‘Imported Mulesoft Services’ section. Clicking on a service name will bring you to additional details about the available actions, i.e. the API endpoints.

Each action will have a drop down arrow on the right hand side, which you can click and select ‘More Details’. Additional information on input and output parameters will be displayed.

I find it easiest to understand the information in setup in tandem with understanding an example implementation, so let’s jump into some code!

Code

Below is an implementation of a fictitious Mulesoft Service, MyMulesoftService. There is one action on this service, myMulesoftMethod, which takes in two input parameters: ‘argument1’ of type String, and ‘body’ of type Object. There are three possible output parameters: Code200 of type String, defaultResponse of type String, and responseCode of type Integer. This information would be listed on the page described in step 2 and 3.

I will walk through each line step-by-step, but not in the exact order it is written. I will be referencing this code frequently, so I recommend you open it in another window to have on hand while reading.

First, let’s look at Line 17: this is where the call to the service occurs. There are two things to note about this line:

1. myService is an instance of ExternalService.MyMulesoftService, which matches the service name listed on the Mulesoft Services page in Setup, just prepended with ExternalService (which is the namespace of the class)
2. myMulesoftMethod() is a method called on the myService object, which matches the Action Name listed in the Mulesoft Services page in Setup

So, the basic structure to make these callouts is:

ExternalService.MY_SERVICE_NAME myService = new ExternalService.MY_SERVICE_NAME();
myService.myActionName();

Next, we will understand the request object - that is, the object passed into the action.

The initialization of this object occurs on Line 4/Line 9. Details on what the exact request object cannot always be found on the Mulesoft Services setup page, namely for parameters of type object. This is where dynamic apex classes come into play.

When a service is imported, apex classes will be generated defining action methods and request and response structures. These can be found in Setup > Apex Classes, then the bottom of the page will list dynamic apex classes. I recommended utilizing ‘Create New View’ under the dynamic apex classes section to easily find your relevant service’s classes. You will want to set the filter criteria to Class Name CONTAINS MyMulesoftService.

The apex class you will first want to take a look at is the one that is just the name of your service, e.g. MyMulesoftService. Since I want to implement the myMulesoftMethod action, I search for the method in the dynamic apex class, MyMulesoftService, which will show me the input and output objects of the method.

The passed in parameter is myMulesoftService_Request, which is defined in the same class.

You may recognize this information from the Mulesoft Services setup page - the class properties defined on the request object match the input parameters listed in setup.

The properties of myMulesoftMethod_Request may be header, path, or query parameters, depending on the mulesoft implementation. On our side however, these all just go onto the request object. An example of this is the ‘argument1’ property on Line 10.

A property you will likely find on a request object is a request body. This input parameter is of type object - the object definition can be found in another dynamic apex class, MyMulesoftService_RequestInfo.

You can find this class by going back to Setup > Apex Classes - dynamic apex classes. Below is the class definition for this object, which is very simple: it contains two properties, one that points to a list of another custom class and one primitive property.

This object is initialized on Line 11. Again, the object name is just the above apex class name prepended with ExternalService. For the sake of this example, only the ‘argument2’ property is required, so on Line 12 this property is set to the passed in ‘argument2’ argument.

Your request object is now built and ready to be passed into the action!

Now we will review the response handling. Recall Line 17 makes the actual callout, and that the action defined in MyMulesoftService also has a return object, myMulesoftMethod_Response. This response object is initialized on Line 6 and the value is set on Line 17.

Below is the definition of this response. In this case, there is no response ‘body’ for this method - it just returns the response status and response code.

You may notice that the property name in the above response class is ‘Code200’ - this object is only returned if the callout is successful. Otherwise, an exception is thrown on the line that invokes the callout, and is caught on Line 18. This exception class is defined in MyMulesoftService as well.

Again, it is a relatively simple class with just two properties, the integer response code and a string (which ideally gives additional details on the error).

How to handle the exception will vary by client, but the important part to note is on Line 19, the exception object’s properties are referenceable to build out a detailed error message.

And that’s it! 

Personally, I was surprised at how straightforward the implementation was once I knew where to look and understood naming conventions/patterns. I hope after reading this you will feel the same!
 
“Can I connect this with that?” Yes. You (probably) can. Connect with Digital Mass to help you make the connection between your disparate systems a reality.