Professor-X and Jean Grey for the rescue of your integration setbacks!
It’s a shiny morning and you are at work now. Suddenly your boss summons you. He says,
“Lisa, We need to provide SMS alerts about our product development status to our clients. I need it as fast as possible. Find me a way and get it done by tomorrow. Otherwise, you will be in trouble.”
Now your mind is on fire!! Did you hear what he said clearly?
Exactly, he said “SMS alert service”. You must be wondering how this should be done now. And your shiny day suddenly turns into a gloomy one.
Don’t worry! This is to all the Lisas and Toms out there, who are suffering from these type of integration related headaches. We are here to help you!
Now you must be wondering who this “We” means. They are Enterprise Service Bus(ESB)s.
ESBs are dead!
Really?
No, Not yet.
Still, they are around to make our lives easy by integrating our systems and services together.
Let me introduce you two important heroes of saving your day. (Drum Rolls playing… Dum dum dum…)
Ladies and Gentlemen, let me introduce you to the Professor-X, UltraESB-X and please welcome our Jean Grey, UltraStudio.
UltraESB-X is an ESB which would take care of all your integration actions efficiently while UltraStudio will provide you a platform to develop integration solutions for UltraESB-X easily.
Now assume that you want to be rescued from Mystique, the villain of the story. Let me introduce you to Mystique.. She is the one who makes your work difficult. Low performance, high cost, and high learning curves make you feel so hectic at the end of your day. This is the most hateful villain of yours.
To rescue you from mystique, our two heroes Professor-x and Jean Grey come to action… Tadaaah!
Oki, Let’s get in the game. Now you need to create an SMS alert service to inform your customers about your product status. So using UltraStudio, you will have to write a connector for a suitable application which provides you SMS services, if there is no connector implementation already provided by them. Then, you will have to create a flow and run it with UltraESB-X. That’s easy as that!
Hey hey! Go easy!
What is a Connector? What are we talking about?
What is a Connector?
Aaah Oki, This is the thing. I know it’s a bit hard to digest an alien word all of a sudden. Lisa, it’s a word used by developers in Integration.
So tell me, I will digest it. What is a Connector?
A connector is how our Professor-X talks with the applications, systems, and services you want to integrate with. You can read more about on this from here.
Really? But what about writing this connector? It won’t be easy, right?
The answer to your question lies right here in this article, dear Lisas, and Toms. That is what this tutorial is about. I’m guiding you, on how to write a connector easily!
OKi, now there is another character in this story. Ladies and Gentlemen, please welcome Logan AKA Wolverine of the story, Project-X. This is the underlying framework for UltraStudio. Just like Jean Grey knew that Logan is somewhere there for her, Project-X is backing up the UltraStudio.
With UltraStudio and Project-X you can do anything easily!
Let me show you how you can get things done easily..
Whatever the type of the application which you want to write a connector for, you have two options. You could either use a Java library which has implemented the REST API of the application or the REST API itself if there is no Java library implemented.
Let me first lead the way in the easy way to get your connector implemented since you got only one day. That is the easiest way to get it done.
First of all, we need to choose an application we need to write a connector for. Let me choose Twilio, one of the most popular applications these days, which allows programmers to send and receive text messages and make and receive voice calls.
This application has a Java Library which makes our lives easy!
You need to get our Jean Grey installed on your machine! You can read about how this is done easily from here.
So let’s start doing some coding!
Writing a Connector With Project-X Using a Java Library
You need to create a new project using UltraStudio, and all the coding will be done in the source directory under com.acme.esb package.
The project structure would look like Figure 1.
When you are implementing a connector, since you are giving out something, the Twilio connector should be an Egress Connector. And in the Egress Connector implementation, you will need to include the basic initialization part of the application including authentication.
Then you will have to write a Connector operation, to implement the SMS alert operation using Twilio.
The Project-X framework already provides the base for the implementation of your connector.
You just need to extend a CallOutEgressConnectorElement or a CallOutTypedEgressConnectorElement<T> from your Egress Connector Java class.
Moreover, it is essential to add the @EgressConnector to express that you are implementing an egress connector. Use @LogInfo annotation to use logging during the implementation.
The initial look of the Egress Connector implementation would look as Figure 2.
You will then have to add the Maven dependency of the Java library related to the Twilio API, to the POM of your project.
<!-- Twilio Java Library Dependency-->
<dependency>
<groupId>com.twilio.sdk</groupId>
<artifactId>twilio</artifactId>
<version>7.15.6</version>
</dependency>After including the dependency, you will have to refresh the dependencies via IntelliJ IDEA UI by right-clicking on your project folder of the Project view, and selecting Maven > Reimport or View > Tools Windows > Maven Projects : click on the Reimport All Maven Projects icon or via command line by mvn clean install.
Now when we are using the web services provided by Twilio, simply to send your messages, you need to find out what parameters are required to initialize the Twilio client.
The main parameters you will need are,
- Username: Your username (Account SID) to access your Twilio Account
- Password: Your password (Auth Token) to access your Twilio Account
I recommend you create a new Twilio account right away because you will need this when you are shooting messages through your connector.
Now, we need to take the above parameters from a user. Therefore, let’s add these two parameters as parameters taken from the UI of the UltraStudio.
As in the following code snippet, you can add the above two parameters by adding the @Parameter annotation.
@Parameter(displayName = "User Name",
inputType = InputType.TEXT_BOX,
placeHolder = "Twilio Account User Name",
description = "Twilio Account User Name",
propertyName = "userName")
private String userName;
@Parameter(displayName = "Password",
inputType = InputType.TEXT_BOX,
placeHolder = "Twilio Account Password",
description = "Twilio Account Password",
propertyName = "password")
private String password;Don’t forget to implement getters and setters for the parameters you have implemented!
As aforementioned, now we have to focus on the implementation of the egress connector. So what should we really implement here?
Oki, you took the necessary parameters that are required to initialize the Twilio client. Now you have to initialize the Twilio client here! Then only you can achieve your end goal of sending messages.
You just need to add the following line to initialize your egress connector,
Twilio.init(userName, password);You have to add this to the initBiEgressConnector(ApplicationContext context) method overridden by the CallOutEgressConnectorElement.
Now your egress connector implementation is done and dusted!
One more simple thing to keep in mind. If you want your logs to appear on the console, you will have to add the following line to the log4j2.xml file at src/test/resources of your project structure.
<Logger name="com.acme.esb" level="INFO"/>Writing Connector Operations Using Project-X
You now have to focus on implementing your Connector Operation related to sending messages.
Let’s begin it by creating a new package operations under com.acme.esb.
You will have to create a Java class that extends AbstractConnectorOperation abstract class, which would be used as the base for the connector operation implementation.
You will need to use the @ConnectorOperation annotation to specify that this class is a connector operation. Moreover, as aforementioned, to use logging, you will need to add @LogInfo annotation as well.
Now it is the time to do some coding to achieve our ultimate goal.
To send a message with Twilio, you need the following 3 parameters,
- Your phone number: your Twilio number which you can find on your Twilio Console (Phone Numbers)
- Phone number to send the message: any phone number on the list of Verified Caller IDs.
- Message Body: what you want to send as a message.
Let’s add these parameters to the Ultrastudio UI as we did before, using the @Parameter annotation as in the following code snippet.
@Parameter(displayName = "From Phone Number",
inputType = InputType.TEXT_BOX,
placeHolder = "Insert your phone number",
description = "Your phone number",
propertyName = "fromNumber",
order = 1)
private String fromNumber;
@Parameter(displayName = "To Phone number",
inputType = InputType.TEXT_BOX,
placeHolder = "Insert recipient's phone number ",
description = "Phone number to send the message",
propertyName = "toNumber",
order = 2)
private String toNumber;
@Parameter(displayName = "Message Body",
inputType = InputType.TEXT_BOX,
placeHolder = "Insert the message body",
description = "Message Body",
propertyName = "userName",
order = 3)
private String messageBody;Now you need to implement the message-sending part.
We are going to take some help from the Project-x framework for this, to make our lives easy. You just need to override the method prepareMessage(XMessageContext messageContext). Whatever the coding should be included in this method.
@Override
public XMessageContext prepareMessage(XMessageContext messageContext) {
Message message = Message
.creator(new PhoneNumber(fromNumber), new PhoneNumber(toNumber),
messageBody ).create();
logger.info(1,"Message Status : {} ", message.getStatus());
messageContext.getMessage().addMessageProperty("Response", message.getStatus());
return messageContext;
}Here we have attached the response status of the message we sent, to a context property on our message, named “Response”.
Yuhuu! You just finished writing a connector for Twilio client. It is so easy just like that when you use AdroitLogic’s UltraStudio.
Oki now, Next is the best part. Let’s test what we created! Whether we could actually send a message using what we wrote!
If you need to add custom icons for your connector and connector operations, you can specify the
iconFileNameproperty in the@EgressConnectoror@ConnectorOperationby adding the icon URL. Please note that you need to place your icon images at a remote place to be picked up by the UltraStudio
Testing Twilio Connector
First of all, you need to build your project. If you are more familiar with the command line, run mvn clean install and build your project. Or else, you can do this through the IntelliJ IDEA UI, Build > Build Project (or Ctrl+F9).
The build allows UltraStudio to see the connectors and connector operations you wrote.
Let’s create a flow to test the connector we wrote as Figure 6 shows.
You can create a new integration flow by right-clicking on conf folder > New > Integration Flow.
In this flow, apart from Twilio Egress Connector and Send Messages Connector Operation, we have used an HTTP NIO Ingress Connector . You can find this connector in HTTP NIO Connector dependency from the connector list.
Connect the Processor out port of the HTTP NIO Ingress Connector with the Twilio Egress Connector and configure it as Figure 7.
Connect the Connector Operation out port of the Twilio Egress Connector with the Send Messages Connector Operation and Response Processor out port with the HTTP NIO Ingress Connector’s Response Port.
To test this flow, you have to use the test account credentials of Twilio. Insert your test credentials and configure your Twilio Egress Connector as shown in Figure 8.
To test SMS alerts you will have to use the testing phone number 15005550006 as the To Phone number. Configure your Send Message Operation as shown in Figure 9.
Now main configurations are ready for testing the flow. Yet we need to configure Run/Debug Configurations of the project. Go to Run > Edit Configurations > Add new configuration > Choose UltraESB-X Server > Click Apply. Tadhaaaa! You are done with configuring the flow.
Create an HTTP Client using UltraStudio Toolbox (found on the bottom tool window pane) to send a request to our Twilio flow, as the following Figure 12 (using the URL http://localhost:8280/service/echo-proxy).
When you run this flow with UltraESB-X, our super savior Professor-X, by clicking Run > Run ‘configuration name’ wait until you see a log line saying, started successfully . Then, click the green run button on the toolbox of the HTTP client you created before.
If you see a response saying queued which means Twilio has allocated a phone number, indicating your request to send a message was successful and the message is queued to be sent out, you won your battle!
You can find the coding related to the tutorial from here!
Yeyyyyy! Congrats! You finally did it!
See how our Professor-X and Jean Grey saved your day!
Kudos to all the Lisas and Toms who make it a shinny day again using UltraStudio and UltraESB-X.
