donderdag 8 maart 2018

Creating REST APIs with Oracle Service Bus

When you think of Oracle Service Bus, you probably think about integration with SOAP and XML messages. However, since the introduction of REST adapters, it's also possible to offer RESTful APIs with JSON messages to your service consumers. Since RESTful APIs tend to be more light-weight than SOAP services, they have certain advantages in performance, especially for mobile usage, while also simplifying the interaction with your service. In this blog, I will show you how to create such an API based on an XSD for internal XML processing and what things to pay specific attention to. In Github I have provided a sample application created in version

Step 1: create your project and XSD

First of all, you will need to create a Service Bus Application in JDeveloper and a project within that. From there, create a Schemas folder and within that folder a MyMusic.xsd XML Schema with the following content:

As you can see, it's quite a straight-forward, simple XSD supporting the most common operations for integrating with a music database: get, getById, create, update & delete. Now, before you get overexcited and start hacking away on a WSDL, please don't! The WSDL will be automatically created later on in the process and making one manually will only hurt you. Needless to say that I found this out the hard way!
The interesting part of the XSD is that it contains some attributes in the schema declaration that you may be unfamiliar with: the nxsd parts are necessary to convert XML to JSON and vice versa later on, so they are absolutely mandatory. Also found this one out the hard way...

While normally I would create a container element Albums with an unbounded element Album in it, this is not looking pretty in JSON, so I have chosen to make Albums unbounded. If you want to know more about how XML is converted to JSON and vice versa, check the following blog by Oracle's A-team:

Another thing that I found out the hard way: don't put any "anyType" elements in your XSD. Later on, your generated WADL will fail because of this.

Step 2: the REST adapter

Once you have completed Step 1, you can go to your composite.xml, right-click on the left swimlane and choose REST. Call the REST Binding "MyMusicAPI" and tick the checkbox in front of "Service will invoke components using WSDL interfaces". Click "Next" and you will get to the Resources screen. This is where you bind your REST methods with your (generated) WSDL operations, so this one is highly important. You need two resource paths: "/" and "/{id}". These paths are coming back in the endpoints that your consumers need to invoke, so keep them as simple as possible and don't put any verbs in there, as they will be supplied by your methods already. The "/" path is allowing methods on the root, while "/{id}" is demanding an id to be sent in the URL and offering methods on that. A simple example: GET on "/" will get you all albums, while GET on "/{id}" gets you a specific album, based on the id supplied.

Now, under Operation Bindings, you start binding the REST methods on your paths to WSDL operations. Click the + button to start! In the next screen, you can set up the specific details. I will call the first operation "getAlbums", which is using the "/" resource and the "GET" HTTP Verb. Under the "Request" tab, in the schema URL, select the "getAlbumsRequest" element from your XSD. Any URI parameters that have been generated should be deleted, since the "/" resource is not having any, so they can't be bound to XML payload. In the Response tab, select "getAlbumsResponse" and leave everything else at the default setting. While it's a good practice to implement error handling, we will leave it for the next blog. Now click "OK" and you have created your first Operation Binding.

Now create "getAlbumById", which binds a GET method on resource "/{id}". Select the appropriate elements from the XSD under Request and Response and make sure to remove the second "id" parameter under URI parameters in the Request part, one is enough. The mapping to the internal XML payload is automatically created!

The next operation is "createAlbum", which is a POST method on resource "/". Remove any URI parameters in the Request and select JSON for the Response before you can select the appropriate XSD element. You can create a sample payload in the Request if you like, so you can see how your XSD content translates to JSON.

Next is "updateAlbum", which is a PUT on "/{id}". The implementation is similar to the POST we just did, but we don't remove any URI parameters here unless they're double. "deleteAlbum" can be implemented the same way.

Now you can press "Finish" and Oracle Service Bus will generate a ProxyService, a WSDL and a WADL. Look into these files and see what they contain! In your composite, you now see an errored Proxy Service, since it's not tied to anything. That's okay for now, no cause for concern. When you right-click on your Proxy Service, you can choose "Edit" and "Edit REST". The first one is the edit function that we know for Proxy Services, including Endpoint URI etc... but "Edit REST" allows you to edit the bindings and the paths exposed by the API.

Step 3: implement the Pipeline

Right-click in the middle swimlane of your composite and select "Pipeline". Call this one "MyMusicPipeline" and on the next screen select "WSDL" as service type. Here you will choose the WSDL that OSB has generated. Untick "Expose as a Proxy Service", since we already have one and we want to make a RESTful API. Now you can drag a wire between the Proxy Service and the Pipeline in the composite or edit the Proxy Service and select the Pipeline as target. In the Pipeline, you need to create an operational branch with all the operations in the WSDL. Give each operation a Pipeline Pair.

Now you can create a mock response in the Response pipelines. You can do this with a Replace activity, which gives you several XQuery and XSLT options to do so. My preference is to use XSLT resources. Why a mock response? Because we want to follow an API first pattern, which means that we deliver our API to consumers as soon as possible, so they can start working on their side and deliver feedback, while we work on the real implementation in the back end.

To create the XSLTs, I've created a Transformations folder and will make an XSL Map for each of the operations. Use the request and response elements from the XSD as sources and targets and fill in the mock response as you desire. Check the sample code in Github to see my implementation. When implementing the Replace activities, choose "body" as Location and "replace node contents" as Replace Option. For Value, you select "XSLT Resources" and select your XSL Map in the next screen, while setting Input Document Expression to $body/* and you're done.

Step 4: wrap it up and deploy

Go back to the Proxy Service and choose 'Edit'. Under "Transport", change the endpoint to /rest/albums to make it more straight-forward for the consumers. Now we're ready to deploy and test! You can deploy directly from JDeveloper, with Maven, through any continuous delivery tool, it doesn't matter to me. For this, I will just use JDeveloper and deploy to my localhost environment by right-clicking on my project, choosing deploy and following the wizard. Of course, you do need an OSB domain for this, so make sure you have. It falls out of the scope of this blog to teach you how to create one. Now you can check http://localhost:7001/servicebus to verify that "MyMusicProject" is there and start testing the Proxy Service!

Step 5: test your REST API

You are ready to test your proxy service. You can do this directly from the OSB console or from any client that can handle REST, like SoapUI/ReadyAPI, curl or Postman. For GET methods, even your browser will work! In this case, I choose the OSB console, which can be accessed at http://localhost:7001/servicebus. Just open the project, select the MyMusicAPI Proxy Service and hit the green button saying "Launch Test Console".

Test 1, "GET" method on resource "/" should give us a list of albums and it does.
Test 2, "POST" method on resource "/" should create an album and it does.
Test 3, "GET" method on resource "/{id}" expects an id to be entered and then returns the album.
Test 4, "DELETE" method on resource "/{id}" expects an id to be entered and removes an album.
Test 5, "PUT" method on resource "/{id}" expects an id to be entered and gives us a nasty error message!

Step 6: fix the bug!

What happened here? Since the id element in the XSD for internal usage, it's also exposed in the API. However, we've also mapped the id from the resource path to this element, so OSB doesn't know which one we want to use: the one from the JSON payload (even if the id is empty or removed). Following RESTful standards, we will want to use one in the resource path, but how do we do that? Let's go back to JDeveloper and "Edit REST" on our Proxy Service. Select the "updateAlbum" binding and edit. Edit the "id" parameter and change its mapping to "$", so it's stored as a property, instead of fighting with the id in the JSON payload.

Now go to your Pipeline and do the following:
Click on the arrow button in the left top corner of your Pipeline to see "Shared Variables" and "External Services". Right-click and create a Shared Variable called albumId. Now add an Assign activity above the Replace activity. Choose "XQuery Expression" for Value and access your with the following expression:
For Variable, select the "albumId" variable that you've just created.

Now create a new Mock XSL Map for Update... you can also edit the old one, but for demonstration purposes, I've created a second one (UpdateAlbumMock2) to show the differences. Create it the same way as the other one, just add an additional source (green + button) and call it "albumId". Leave all the default settings. Now you will do your mapping to id from this parameter, not from the id in the payload. Now update the XSLT Resource in the Replace activity and bind the parameter to the albumId variable. Save and redeploy. Test your PUT method again and you'll see that it works!


Through this blog, you should now understand the basics of creating a RESTful API on Oracle Service Bus with JSON input and output. In my next blog, I will show you how to deal with search parameters and error handling.

donderdag 7 december 2017

UKOUG Tech - PaaS & Development review


This year, I went to UKOUG Tech for the first time, as I got my paper about Oracle Process Cloud Service accepted. Looking at the agenda in advance, the content of the conference looked very interesting and I can already say that I wasn't disappointed. Not being particularly interested in the vast amount of database sessions, I decided to mainly focus on the Middleware and Development tracks, to see the latest developments on Oracle's PaaS offerings and the coolest new technology trends.

Even though many visitors to the conference are still working on on-premise projects, I haven't been able to find even one session about on-premise middleware. This is only logical, since SOA Suite, BPM Suite and Oracle Service Bus are lacking spectacular new features: it's all happening in the cloud. So, what exactly is happening in the cloud?

PaaS (Platform as a Service)

The main thing is that Oracle's iPaas (Integration Platform as a Service) portfolio is ever growing stronger. Every three months, these products are getting updated, rapidly maturing and expanding in, occasionally overlapping, functionality. Oracle Mobile Cloud Service impressed me as a solid back end for mobile, offering APIs, offline synchronization, authorization and tons of other features that are really useful for the challenges that come with mobile (or multi-channel) integration. Oracle API Platform is growing stronger as well and makes us re-think our way of agile development. API first is the way to go, so we get feedback from consumers early, while we are still working on the actual implementation in the back end. Another advantage here is that the back end is not impacting the API design much, so we can keep things clean and smart.

Moving further down the road, we see that Integration Cloud Service is turning more and more into a full-blown SOA platform and I was happy to present the Decision Models of Process Cloud Service myself. Once Dynamic Processes (Case Management) capabilities are released, I think we can say goodbye to BPM Suite, at least for new projects. Development in Process Cloud Service has become a smooth experience and the UI has improved dramatically since the product was launched in 2014.

Open Source & Development

But PaaS is not everything. We have seen an increasing interest in open source technology recently and even Oracle is embracing those products these days, standing at the very heart of their cloud offerings. So, I had the opportunity to learn more about Docker, which is a key element in Oracle's many Container oriented cloud offerings, Kubernetes, for which Oracle will provide a managed platform soon and Wercker, which can be used for continuous integration/continuous delivery of containerized microservices.

However, the star of the show was Apache Kafka. Brought to us with much grandeur by Robin Moffatt and Guido Schmutz, among others, Apache Kafka is looking extremely promising for not big data and streaming content, but basically for any event-driven style of architecture. Kafka can be used as an open source product, but you can also choose to use the Confluent Platform or Oracle's Event Hub Cloud Service. I believe that Kafka will be the cornerstone of modern integration architecture, powerfully delivering the promise that traditional SOA couldn't live up to. It's also perfect for being the event hub between your microservices, so they can communicate with each other without dependencies.

All in all, I can say that it was a fantastic conference, with not just great content, but also great social activities. It was a great opportunity to catch up with my friends, meet new people, exchange ideas and attend my first Oracle ACE dinner. I hope to be back next year!

woensdag 29 november 2017

Running SoapUI Test Cases with Maven

So, you have developed your software and you've done the right thing by creating your tests in SoapUI and they're all running smoothly. Now it's time to make the next step: make sure that your tests can be run automatically, preferably on different environments, for example every night or after a deployment. This is a major improvement in your continuous integration and delivery efforts, but how can this be achieved? In this blog, I will show how it can be done by using Maven, which can then again be used in for example Bamboo, Jenkins or any other continuous integration tooling.

With Maven, you basically just need a POM and a command to kick things off. In this example, we are using SoapUI 3.5.0, which is the latest open source version, Maven 3.5.2 and (since we need Java) JDK 1.8.0_131, but any other recent version will do as well.

Now, before we begin, if you use any JDK 1.8.x version, you need to copy a jar file named "jfxrt.jar" from ..\jdk1.8.0_131\jre\lib\ext into the ..\jdk1.8.0_131\jre\lib folder to make things work. If you resist, you will get a nasty error message and your test will not run with Maven. This obviously also applies to your continuous integration server.

Once you're setup, you will need to create a pom.xml file like the one below. You can place it in the same folder as your actual SoapUI test, but if you prefer to put it elsewhere, that's fine too. Just make sure to adjust the path to the SoapUI test then and be aware of differences between Windows and Linux environments (forward and backward slash). This is why I prefer to put the POM in the same folder as the SoapUI project.

Now there are several important elements here that you need to change for your own testing:
1. projectFile: the location plus name of your SoapUI project. Don't forget the .xml extension.
2. testSuite: the TestSuite that you want to be executed. If you leave it out, all TestSuites will be run.
3. testCase: the TestCase that you want to be executed. If you leave it out, all TestCases will be run within the specified TestSuite.
4. projectProperties: here you can manipulate the Custom Properties in your SoapUI project. Very useful for environment settings, for example.

Once you have the POM in place, you can navigate to its folder with command line, powershell or whatever tool you use and execute the following command:

mvn com.smartbear.soapui:soapui-maven-plugin:5.3.0:test -Denv=localhost

So, in the sample above, I have chosen to test my local environment by entering the value "localhost" into my Custom Property called "Env".

You might see some harmless error messages now, but they will not stop the test from running adequately. If you want to get rid of these, navigate to C:\Users\[Your User]\.soapuios\plugins and remove all files from there.

Once you run the test project like this, it will go through the specified TestSuite and TestCase, performing all the TestSteps in those and reporting on all the assertions. In the end, you'll get a BUILD SUCCESS or BUILD FAILURE message, depending on whether the result of the test matches the expectations set in your assertions.

Now you are ready to use the same command from your continuous integration tooling, decide when it should be run and which environment should be triggered.

dinsdag 31 oktober 2017

REST API for Oracle Adaptive Case Management

For all of you who have been struggling with how to interact with their cases, there is good news. Since 12c, Oracle has created a REST API for Adaptive Case Management (ACM):

Since the API is pretty much self-explanatory and fairly easy to use, I will not write a lot of detail about it (at least not right now, maybe later). However, I think that those of you who are struggling with the Java API or something custom made will definitely find something much easier to use here, for both integration and testing. Since most blogs about the subject have been written before this REST API became available, I thought it would be good to draw people's attention to this.

woensdag 10 mei 2017

Oracle Process Cloud Service - Decision Model Notation part 2

In my previous blog, I showed how to get started with Decision Model Notation (DMN) in Oracle Process Cloud Service and how to create a simple Decision Table. Picking up from there, we will now look into creating If-Then-Else rules, which should also be familiar to people who know Oracle's old Business Rules. We will also create a service and call it from a process.

Creating an If Then Else Decision

As Input, I have created a TotalAmount object, which is the total amount of a Sales Order. Based on this TotalAmount, we are going to calculate a Discount Price, for which I have created a DiscountPrice type to make the service interface a bit prettier than just 'output'. To create an If-Then-Else rule, just click the + button next to Decisions, enter a name and set the output type to string, number or any other type, in this case DiscountPrice.

Now, Oracle will have created a rule for you, in which you only need to fill in the "if", "then" and "else". Since you've already decided your output object, we will not use that one in the expression, which is different from the old Oracle Business Rules. So just enter the value that you want for this object and you'll be fine. You can also create nested expressions, as shown below:

One thing that I don't like, is that all the nesting needs to be done in the "else" part. I hope for Oracle to acknowledge this and create a new "if" section (for example with indent), where I can happily nest away in a more user-friendly manner. However, it works (use the Test feature to verify) and if you don't make things too complicated, it's mainly a minor display issue.

Calling an If Then Else Decision

Calling any Decision from a process is super easy. Just make sure to have a service created for your Decision and deploy it, so the process can find it. In Oracle Process Cloud's Process Composer, you can then select "Decision" as a system task, select the Decision Model that you want to use and the service within that Decision Model that you want to call:

From here, you can make your data associations and you're done. Obviously, a process is generally not as simple as this one, but using Decisions within processes is.

So that's the second part of this blog series. The third part will be an overview of other DMN functionality: Expression, Relation, List, Function and Context. I still think that we will mostly be using If/Then/Else and Decision Tables though, so for most use cases, the information in this blog and the previous one should provide you with a nice kickstart.

maandag 8 mei 2017

Oracle Process Cloud Service - Decision Model Notation part 1

Recently, Oracle Process Cloud Service (PCS) has made another major step forward through the addition of a whole new way of dealing with business rules. This brand new Decision Model Notation (DMN) feature is developed seperate from the actual processes and deployed as a microservice, so your decision models can be reused and everything is nicely loosely coupled. I like it.

What I also like about DMN is that it's much more (business) user friendly than the rule engine from Oracle SOA Suite, which was used until now. While it was performing well and somewhat agreeable for technical users, business users were often lost and leaving the business rule modelling to developers. With this new DMN feature, this is no longer necessary. Business users will be able to do much more, if not everything, themselves and actually enjoy the experience!

I've decided to write a series of blogs about the different types of decision models that can be created and how to use them. But first we need to turn it on.

Getting Started

When you're in the home screen, click on your login name in the top-right corner and choose 'Administration'. On the Admin page, go to 'UI Customization' and tick 'Enable DMN in Composer', then Save.

Now you're ready to go! You can go back to the home page now, click 'Develop Processes' and then under Create, you will have the option to create a New Decision Model. As you can see, these Decision Models are seperate from your normal PCS applications, but you can call them from your processes. Once you have created your Decision Model, your interface will show you Services on the left, Input Data on the right and Decision Models in the middle.

Input Data

The objects and the left and right can be expanded. Here's a brief explanation of what they contain, starting with the right: Input Data. When you expand it, you can see two options: Input Data and Type Definition. In Type Definitions, you can setup complex types for your input data, like lists or elements that contain attributes. Types can also refer to other types and so on and so on. It's pretty much a declarative way to make an XSD.

In Input Data, you can then refer to these Types, but also create strings, numbers and other basic stuff. In this case, I choose to make a SalesOrder, referring to the SalesOrderType I've created. This Input Data is obviously very important, because it will be the facts in your Decision Model and defining the interface of your Service.

Decision Table

So, now we know how to turn on DMN and how to create Input Data. Now let's create a simple Decision Table to make it work. Just click on the Blue + next to Decisions and choose Decision Table on the right. Since my Decision Table will decide the approval level needed for the Sales Order, the output will be a simple string value.

Once the Decision Table has been created, you obviously need to fill it. You start with Enter Expression on the left and just type the first letters of your Input Data object. DMN will suggest automatically what you want and you can just select it. In this case, I wanted to have SalesOrder.TotalAmount as input, but oops... I forgot to add it to the Type! No problem, you can always modify your Types later and the changes can be used immediately. Now we can enter our rules, which is also very nice and declarative. It could look something like this:

Absolutely no coding is necessary! To test it, you can use the test button in the top-right corner (the blue play button) and the test interface is very easy to use. Once you're satisfied, save your work.

Creating a Service

Believe it or not, creating a Service is even easier. Expand the menu on the left, create a Service, give it a name and drag the Input Data and Decision on the Input and Output fields. It will generate a REST Service and will give you the URL, as well as request and response payload when you click on Payload. Obviously, you'll have to fill in the data yourself, but all the types are described, so it will be very easy to use. Now you're ready to deploy, but the runtime aspects and calling the Decision Model from a process we will save for a later blog.


Oracle has created a significant improvement in Decision Modelling with their DMN-based feature. It's easy to use, business friendly and allows for fast development. Further blogs will get into more complex rules, different types of rules, calling decision services from processes and the runtime environment.

woensdag 29 maart 2017

Why you want to become an Oracle SOA developer

With a mixture of surprise and amusement, I've read mr. Sten Vesterli's statement below:

"You don’t want to become an Oracle SOA developer, for two reasons: SOA and Oracle."

Quite a powerful statement, so let's dive deeper into the two reasons mentioned above and explain why I strongly disagree with mr. Vesterli.

First of all, he makes a rightful claim that SOA has over-promised and under-delivered for a decade. I share this feeling, but I do not believe in the bleak picture of the future of SOA that he is painting.

When you look at the Gartner hype cycle, it's clear that SOA is currently in the through of disillusionment, which is a rather tough place to be in. However, after this phase come the slope of enlightenment and plateau of productivity, so is this really a good moment to stop being interested in SOA? I don't think so. We have made our mistakes, learned our lessons and now it's time for "SOA done right".

Of course, we can now jump into microservices, which are at the peak of inflated expectations and doomed to fail in their own way with all the downsides and requirements that they have, or we can adjust our perspective on SOA and modernize our architectures. Take elements from microservices, don't run from one extreme to the opposite extreme and find your way into Domain Driven SOA Design, in which I strongly believe. We can and will do this right if we can for once stop thinking so black-and-white.

So, having covered SOA, let's talk about Oracle. It is indeed true that Oracle is making a strong movement to the cloud, which I embrace and support. Now, according to mr. Vesterli, apparently an Oracle SOA developer will only work on-premise and will not be working with Oracle Integration Cloud (ICS). I think this is not true and I can use myself as an example, having done projects with both Oracle SOA Suite and ICS and happily using my skills both on-premise and in the cloud with Oracle's rapidly expanding PaaS portfolio.

Apart from that, SOA Suite on-premise and Oracle SOA Cloud Service are exactly the same from a developer's point of view. They are the same products, requiring the same type of code, being developed in the same JDeveloper. And while ICS is very good for integrating SaaS applications with each other, it's not going to be the cornerstone of anyone's enterprise architecture anytime soon. Therefore, SOA will remain relevant for a long time and when you know SOA, you can easily learn about ICS as well. The other way around will be significantly harder!

So, I'd like to conclude by turning mr. Vesterli's statement around: now is a great and exciting time to become an Oracle SOA developer.