Teaching How to Use the Solace MuleSoft Connector

In a previous blog, I explained the importance of being able to consume and understand messages in real time, where it might be required to reach out to external systems and applications in order to fully accomplish a business outcome.

This type of interactions tend to follow a service choreography pattern (as opposed to purely a traditional orchestration), where there is no central micro-management logic that constrains the rules of interactions, but on the contrary, services will freely interact with each other as required by the nature of the messages that are being triggered.

Solace is well known for providing rich and scalable choreography capabilities, while maintaining guaranteed delivery of messages across multiple types of messaging-transport protocols. On the other hand, MuleSoft is specialised in unlocking access to systems and applications, as well as data transformation, across multi-cloud, on-premise and hybrid deployments.

Together, MuleSoft and Solace provide a strong foundation that allows companies to build a digital strategy for real-time Enterprise Event Driven Integrations.

In this blog, I am going to demonstrate how to use the Solace connector for MuleSoft, which simplifies the interactions between multiple event channels to publish and subscribe messages.

The use case that I am going to use is very simple and topical! It’s about generating medical tests results to then be pushed as SMS notification to the end users.

The choreography is as follows:

1. MuleSoft “Microservice A” is used to extract data from a Health System, containing patients’ test results. 

NB: Depending on the health system, there are multiple ways to achieve this outcome. For example, the health system might invoke REST APIs ad hoc or the MuleSoft microservice could be using some type of inbound connector to subscribe to events into the actual Health System for a more real time focus. For the purpose of this PoC, I am going to use simple REST APIs to be invoked externally with the patients tests records.

2. MuleSoft “Microservice A” publishes the test results into a topic via the Solace connector.
3. MuleSoft  “Microservice B” is subscribed for events with Solace Topic t/patients/tests/results via a Solace connector.
4. On the occurrence of events, “Microservice B” integrates into a backend system (e.g. Salesforce) to enrich the incoming patients test data with the patients mobile numbers for example.
5. “Microservice B” publishes the enriched messages into a guaranteed delivered queue via the Solace connector.
6. MuleSoft “Microservice C” is subscribed for events to Solace Queue q/patients/tests/results/notifications via the Solace connector.
7. On the occurrence of events, “Microservice C” pushes the test notifications to patients as SMS notifications.

This is a quick visualization of our proof of concept:

Pre-requisites

In order to complete this exercise, it is expected that you:

• Have access to MuleSoft Anypoint platform account – If not, you can subscribe for free here.
• If you are new to MuleSoft and want to have a full overview first, have a stop here.
• In this blog I am going to use Vagrant VM, it is recommended that you are familiar with it and have it installed on your computer. For more information, see here.

First, let’s run a Solace Event Broker environment

For the purpose of this blog, I am going to use a local Solace Event Broker running on Docker. For this, I prepared a Vagrant VM box already configured to bootstrap everything necessary to run a Solace Event Broker when initiating the vagrant box.

• Assuming that you already have Git and Docker installed, clone this repo that I prepared for this demo:

git clone https://github.com/mulethunder/solace-mule-connector-test

• Move inside this repository and do a:

vagrant up

• Once the Vagrant VM loads, Solace Event Broker will be bootstrapped and run inside the VM.
• SSH into the vagrant VM

vagrant ssh

• Run the Solace Docker container:

docker run -d -p 8080:8080 -p 55555:55555 -p:8008:8008 -p:1883:1883 -p:8000:8000 -p:5672:5672 -p:9000:9000 \
    -p:2222:2222 --shm-size=2g --env username_admin_globalaccesslevel=admin --env username_admin_password=admin \
    --name=solace solace/solace-pubsub-standard

• Make sure Solace Docker container is running:

docker ps

• To make sure all the ports are open in the host machine, open a browser window to http://localhost:8080 – You should see the Solace web console.

• Login with admin/admin
• By default Solace comes with 1 default Message VPN, click on it.

• On the left menu Click on Try Me!

• Connect to both Publisher and Subscriber. On the subscriber click
• Subscribe to the default try-me topic name.

Make sure no connection errors appear. That proves that the ports are properly opened and mapped in the host machine.

• Type a message on the Publisher text area and click Publish, you should be able to see it coming in the publisher.

Congratulations, the Solace Event Broker environment is ready to be used as part of our PoC.

Using the Solace Connector for MuleSoft

The Solace connector for MuleSoft is available in Anypoint Exchange (see here). 

Let’s start by creating a MuleSoft  application in Anypoint Studio and configure it with the Solace Connector. At the time of writing this blog, I used Anypoint Studio 7.10

• Create and scaffold a new MuleSoft project using this simple Patients RAML API spec that I put together. It has 3 simple API resource methods:

• GET /patients/tests
• POST /patients/tests
• POST /notifications/patients/tests

Feel free to get a local copy of the RAML file or build your own spec and import from Exchange. It’s up to you. In the next image, I am creating a new MuleSoft project using a local RAML spec file.

• Once the scaffold completes, you will have 5 flows. The standard public flow router, the console and 3 additional flows for each of your resource methods.

• Now, using the panel on the right, go and search from Exchange the Solace connector

• Select and add this connector by clicking Finish. 

Note: As a good rule of thumb, always try to use the latest version of connectors. That way you can ensure to be on top of any known issue and latest functionality. At the time of writing this blog, the latest version for the Solace connector was 1.0.0

• You should see the new Solace connector available in your project and ready to use.

• Open again the patients.xml flow view. Also notice that the connector is in the Mule Palette.

• If you click on the Solace Connector, you will be able to see all the operations that it allows you to do. 

Have a look at the official documentation for a complete explanation of each function. 

As a quick summary, to the best of my understanding, these functions are as follows:

• Ack: Allows the user to acknowledge successful processing of a message so it can be removed from the PubSub+ event broker.
• Consume: Consume persistent messages from either Topics or Queues
• Direct Topic Subscriber: Subscribe for messages from a Topic
• Guaranteed EndpointListener: This is a “sourced” based operation. It is triggered when a guaranteed message is received on a queue or topic endpoint.
• Publish: Operation to publish Direct messages to a Topic or Guaranteed messages to an Endpoint on the PubSub+ event broker.
• Request reply: As the name indicates, this is a synchronous request/reply type of communication that sends a guaranteed message to a queue or topic and waits for a response on the reply-to temporary queue automatically created by the sender. It throws an exception if no response was received in a configured timeout setting.

We will use most of these operations as part of our proof of concept in this blog.

Publishing Events to the Event Broker

The first flow that we are going to implement is “Microservice A” i.e. the POST /patients/tests 

Note: For the purpose of this poc, we are going to focus on the messaging choreography and skip the integration to the Health System. Instead we are going to send the patients tests payload in postman as a testing mechanism.

• Drag a Solace Publish processor inside this flow, after the logger.

• At the bottom of the screen, click on the green plus icon to configure the Connector.

• In the connection details, enter:
  • Broker Host: localhost
  • Message VPN: default
  • Client Username: default
  • Client Password: default

• Test the connection and make sure it is successful. Then click OK and OK to close the connector connection configuration.

For more advanced configurations, refer to the Solace documentation.

• Back to the Connector Publish configuration, set the Delivery Mode as DIRECT.
• Set the Destination name to t/patients/tests/results
• Set the Destination Type to TOPIC.
• Set Message Type to TEXT_MESSAGE

• Don’t forget to save the project.
• Your project should look like this:

• Run the project in Studio

• Once it loads, make sure no exceptions are thrown. 

• Open the embedded testing web console, postman or any other API test tool and send a request to the POST /patients/tests API endpoint.
• I am using the default embedded console. You can open it by clicking on the Open Console button at the bottom left in Studio, or simply go to http://localhost:8081/console 

• Before sending the request, use the Solace Try Me! tool again in the local Solace web console (http://localhost:8080/) to subscribe to this topic and see any activity going on, as we did when we provisioned the Solace Event Broker environment earlier in this blog.

• Keep this page running in a separate window. We will come back soon to validate that we successfully published our message to the topic.
• Great, now back to MuleSoft testing console. I am sending the default payload of the equivalent that we would receive from a Health System, in the format expected by the Patients API spec that we used to scaffold our project.

[{  “PatientId”: “ABC123”,  “Name”: “John”,  “Surname”: “Muley”,  “Mobile”: “61440977662”,  “Email”: “john.muley@email.com”,  “TestId”: “XYZ123”,  “TestResult”: “Negative”}]

• Once you send your requests, you should be able to see a new direct message coming through in the Solace Web Console Try Me tool.

Congratulations, we are now posting our messages to the Topic successfully. Now, we need to continue the choreography by adding “Microservice B” that will subscribe to consume these messages.

Subscribing to Events in Topic

Microservice B has 3 jobs:

1. First it has to subscribe and listen to events coming on the specified topic (i.e. t/patients/tests/results)
2. Normally, it then would have to integrate with other backend systems, like Salesforce, in order to enrich the incoming data with anything required to then send the notification via SMS. 

Note: Normally the test results do not contain the patients mobile information, so we would need to correlate based on the patient id and extract this information from a backend system. For simplicity reasons in this PoC, I included the mobile number in the incoming payload, so that we can skip this step and continue focusing on the messaging choreography.

3. FInally, it has to push the result messages to a guaranteed delivery queue (i.e. q/patients/tests/results/notifications) for yet another service to accomplish the SMS notification.

Let’s get to it.

• In the Mule Palette, locate the Solace Direct Topic Subscriber operation and drop it outside any existing flow, so that it creates its own.

• Since we have already created a global configuration for our Message Broker, we can simply reuse it. That is, there is no need to re-create a new connection, it will automatically map to the previous one.

• Under Subscriptions, enter the Topic: t/patients/tests/results
• Set Content Type to: application/json 

• Save all.
• Drag and drop a logger as the first Processor in the new flow.

• Log the incoming payload (enable fx to treat it as a variable, not string)

• Save all again and run the project again.
• Send another API call, as we did before. The event will appear again in the Solace Try Me! Tool, but now we have another subscriber. The event will also appear in the log console in Studio.

Nice, huh?

• The next logical step would be to integrate back to applications to enrich the incoming data from the event and ensure that it has all it needs to be properly sent as an SMS notification. For example the mobile number to send the notification to. 

MuleSoft simplifies this task, by using hundreds of out of the box connectors available in Anypoint Exchange – However this step falls outside the scope of this PoC that focuses on explaining the Event Choreography pattern.

Since we already include the mobile number as part of the event’s payload, we can move on to the next step that is publishing this event into a guaranteed delivered queue, that will then be processed by “Microservice C” to send the actual SMS notification.

Publishing Events to a Queue

Once Microservice B receives an incoming event message, it will push it into a queue that will guarantee the delivery of the SMS notifications.

• Drag a publish step in front of the logger processor, inside patientsFlow.

• Click on this Publish step and make sure the Connector Configuration is set to the default connection that we created previously.

• Set Destination Name to: q/patients/tests/results/notifications
• Set Destination Type to: QUEUE

• Set the Message Content Type to: application/json

• Save All.

Before testing the project, let’s create the queue in Solace Event Broker.

• Go back to the Solace web console and click Queues on the left menu.

• Click the + Queue green button at the top right of the console.
• Set Queue name to: q/patients/tests/results/notifications
• Click Create. Then, set the Owner to default 
• Save the changes.
• A new queue will be created.

Great, now, we can run and test our Mule project.

• Run and Test the Mule project in Studio again. 
• You should see the message coming to the Topic as it did before. However, now it will also be published into the queue. 

In order to validate this, go to the Solace Web Console and click on the new Queue. Notice that a new message was created.

• If you click on the Messages Queued tab, you can see more details about this new message.

• However, notice that it is still marked as undelivered. That’s because we have not yet created the third and last microservice that will consume the message and send the SMS notifications.

Subscribing to our Queue

Similarly as we subscribed “Microservice B” to the Topic, “Microservice C” will subscribe to our Queue and then use the incoming message to send an SMS notification.

• Drag and drop a Solace Connector Guaranteed Endpoint Listener into the blank canvas to build a new flow.

• Make sure the default connect configuration is selected.
• Set the Endpoint Queue Name to: q/patients/tests/results/notifications
• Set Content Type to: application/json

• Drag and drop a Logger after the listener, as the first processor in the flow.

• Log the payload’s content.

• Save All.
• Run and test the project again. 
• Notice in the Solace Web Console that this time, it is marking 1 message was successfully delivered:

• More importantly, in the Mule Studio log console, we can see the original message coming from the topic, but also, the message coming from the queue.

• In order to send the SMS notification, I used Twilio, but using Twilio connector is outside the scope of this blog, but see here for more on how to use the Twilio Connector.

• The final outcome, the SMS comes on my mobile.

And that’s it, congratulations! 

We managed to go through many messaging-channel interactions in which the nature of events determined the logic that needs to follow. 

There is no master central orchestrator in our logic, but simply, by adding new subscribers, we can easily extend our business logic, without compromising nor disrupting anything that has been developed so far. That’s the flexibility of choreography and orchestration working together towards the greatest business outcome. 

That’s why MuleSoft and Solace work better together.

I hope you found this article useful. If you have any question or comment, feel free to reach me at https://www.linkedin.com/in/citurria/