SAP Cloud Integration Adapter development using Maven Project perspective

[former_member468101]

Introduction

SAP Cloud Integration platform provides capability to add custom adapters to the Integration tooling via SAP ADK Framework. You can refer my earlier blog on how to create your own adapter using the SAP ADK Frame work. A new feature to this frame work is being introduced with the Aug 2017 release of Cloud Platform integration which is way more convenient for the developers. The project comes with Maven support out of the box and a sample Adapter implementation. i.e. you can simply create an Adapter project and experience the Adapter development by simply building, deploying and later consuming it in an Integration flow. Just like that. Not even writing a single line of code. Isn't it a cool feature?

In this blog, I am going to show you how you can use this new Adapter Project Creation wizard and implement your own adapter. This contains following sections

1. Create a Sample Adapter


2. Deploy the Sample Adapter


3. Consume the Sample Adapter in an Integration flow.


4. Modify the sample Adapter to consume external dependent service.

 

1. Create a Sample Adapter with new wizard

Before you begin, do the followings

Pre-requisite

1. Update your eclipse with latest SAP Cloud Integration tooling


2. [info]You will be referring to the maven plugin "com.sap.cloud.adk:com.sap.cloud.adk.build.archive".


3. You need to be aware of Java development


4. You need to be aware of OSGi and OSGi subsystem specification. The Adapter you develop is an OSGi esa file with type as Composite. That means it has be self contained. If you use any dependencies, they have to be bundled withing this ESA.

 

1. After above mandatory steps, open the eclipse (if you have not already after the update) and select File->New->Other, in the filter, provide “Adapter Project” and select “Adapter Project”. You must see the below dialog box

If you have experience in creating Adapters using SAP Cloud ADK frame work, you will see that this dialog box is almost similar. There is a check box Enable Maven, which states that this project is of type Maven by default. You can deselect this and old way of Adapter creation (Where things are manual) will be offered.

When to use the Old Project wizard? – before we begin lets understand if we need to use the old project wizard. Lets just say if you have a requirement of re-using an existing runtime component and you know its jar and dependent jars and you don’t want to add any customization, then you probably can use the Old project wizard.

Moving on, let’s enter the details keeping the Enable Maven check box selected. I have provided following details



Note that I have changed the Component and package names. Click Finish

If you have followed my suggestions on the details, you might see a fully functioning Adapter project in Maven nature.



As you can see, the new project structure is to help both UI (of your adapter) and runtime component development (along with dependencies management) in one place. Let’s look at the details of the sample implementation stub we have.

1. GreetComponentEndpoint.java This is Enpoint class which has a String variable ‘greetingsMessage’. It is annoted with @UriParam. It contains one more important thing which will help developer a lot – that is logger. A recommended logger API is already added for you to use. You must use this logger for all your logging needs.


2. metadata.xml – this is the metadata xml generated automatically for you (As sample). Observe that it has two fields or is firstUriPart which is by default. Another one is matching to your @UriParam i.e. ‘greetingsMessage’


3. GreetingComponentConsumer – this is a polling consumer. What is polling consumer? Refer here. It just adds a Hello string with current time stamp.


4. GreetingComponentProducer – this is the Receiver implementation which converts the ‘greetingsMessage’ to upper case and also appends the exchange input to the final message.


5. GreetingComponentComponentTest – The test has a very useful test case which is to assert whether the ‘greetingsMessage’ is converted to uppercase or not. Go ahead and run the test after Maven build. If you see some error, try building the project first and then run the test.

2. Deploy the sample adapter

Enough of theory. Now lets build and deploy. Since it is a maven project, all you need to do is run the maven clean install. Once you have successfully built, check your target. It will have an ESA generated along with sample component (refer image below). You can simply deploy this ESA to the tenant (by right clicking and selecting the Deploy Adapter Project)

3. Consume the sample adapter in an Integration flow

1. Create an Integration flow. Select your new Adapter which is Greetings as the Sender. In the Sender adapter configuration, leave the firstUri field empty and give a message to the message field say “Hello World one time” Since it is a polling consumer, you have to provide interval details. Give a longer interval to avoid many messages.


2. Add a Request reply step and add your new Adapter as Receiver. In the Receiver adapter configuration, leave the firstUri field empty and give a message to the message field say “Hello World two times”


3. Finally configure the email or SFTP adapter to receive the final message.

Deploy the Integration flow.

If you have configured an email adapter, you may receive periodic emails with message something like below

Hello World one time Now it is <some time stamp> : HELLO WORLD TWO TIMES

As you can see our receiver will be upper casing the given message.

4. Modify the sample adapter

Now lets get serious. This where I will show how you can start developing your adapter in more details.

Let’s think of an use case, where we want to extend this sample adapter to add some kind of formatting to the Greeting Message. Let’s say we want our Receiver to say “******** HELLO WORLD TWO TIMES *****”. i.e. add * as the formatter.

Ideally the formatting can be abstracted to a Service. There can be different formatter services (providing different characters as appenders say *, $, # etc)

For simplicity let’s assume we have StartFormatterService which appends “*” to a given message.

Let us also define that we will add this formatter only if user (Adapter user) wishes for it.

1. Change GreetingsComponentEndpoint class - First thing for this enhancement is to add a #UriParam to our GreetComponentEndpoint. Since we just want a flag from user i.e Boolean                 Note that you have to provide getters and setters for each @UriParam


2. Implement a formatter Service – Create a simple OSGi service which appends some *s to a given stringI will not details out on how an OSGi service will be built.


3. Note: It is not best practice to create class and expose it as OSGi service. For simplicity and speed I have done that. Ideally there should be an interface and an implementation.


4. Add the Formatter service dependency to your adapter project. You can directly add it to pom file or use pom file viewer (like I did here).


5. Use the formatter service in Producer implementation


6. Note: I have directly used the GreetMessageFormatter instance. You can use it via OSGi look up.


7. Build the adapter project. (make sure you do this before step f)


8. Regenerate the metadata.xml – Since we want user to take a decision about the formatting, we need to add the Boolean reference variable in the metadata. You can delete the current metadata and right click on the project and Select Generate Metadata -> Component Metadata. You can see that the new metadata has a check box added in addition to the greetingsMessage field automatically.


9. Now perform the Step 2) i.e deploy the adapter and Re consume it in an Integration Integration flow i.e. Step 3)