Friday, November 30, 2007

Check Your SOA

Finally found the time to finish this posting which I started to write like three months ago! It's about time, as it might not take too long before it's content will start to get more and more obsolete.

Some time ago I was asked to check whether the SOA Suite had been properly installed at a customer site. So what do you do when you are asked to check something? You go and look for a checklist! At least that is what I do, and not verify surprisingly, found nothing. As you might recall from an earlier article I have the memory of a gold fish, so to prevent that I need to reinvent that wheel some next time, I thought I write it down. If not for you, than for myself.

The following describes a checklist regarding the installation of the Oracle SOA Suite 10.1.3.0 or 10.1.3.1 and with the patch to version 10.1.3.3 on top of that.

By the way, the current 10.1.3.1 version you can download from OTN. You should also be able to find the patch on OTN, but don't ask me how. Using the regular way it pointed me to MetaLink. After some inquiries I got a direct link the Windows version as well as the Linux version. Don't get confused by the fact that you actually are downloading files to install the Oracle Application Server. Installing the SOA Suite is part of that and one of the installation options.

Unless you are running the SOA Suite just for reasons of doing some howto's or create some "look mammy, my first BPEL-process!", you rather not install the ORABPEL, ORAESB and ORAWSM schemas in the Oracle Lite instance that comes with the default installation because of it's limitations.

Schemas Log File

One of the first things you can check is the log file of the creation of the schemas. Installation of the schemas is a separate step and will have been done before installation of the Application Server / SOA Suite. The irca[yyyy-mm-dd]_hh-mm-ss[AM|PM].log file will reside in the directory from which the irca.bat or .sh has been run, e.g. [SOA_Oracle_Home]\install\soa_schemas\irca\ There should be no error reported in this file other than errors related to dropping non-existent database objects (in case of first-time installation).

Installation Log Files

The next things you might want to check are the log files of the installation of the Application Server / SOA Suite itself. In case of installation on a Windows machine there will be two bigger log files in the in the folder C:\Program Files\Oracle\Inventory\logs\ (on Windows, dunno where they are on Linux) with names like installActions[yyyy-mm-dd]_hh-mm-ss[AM|PM].log. One is of the installation of 10.1.3.1 and the other one of the installation of 10.1.3.3. As they are big you better scan them for strings like "ERROR" (in uppercase).

Finding out the Ports

To check the installation you need to know the OPMN and http port. By default the OPMN (request) port of the Application Server will be 6003. The Integration Server will run on the http port, by default 8888. Both ports might have been configured differently during and after installation.

The ports that have been used during installation are configured in the [SOA_Oracle_Home]\bpel\utilities\ant-orabpel.properties file. Make a note of the values of the opmn.requestport and http.port properties.

In case the port numbers have been changed after installation, the actual OPMN port can be found in the [SOA_Oracle_Home]/opmn/conf/opmn.xml file. Search for a line like .

Whenever the http port has been changed after installation, the actual value can be found in the [SOA_Oracle_Home]/Apache/conf/httpd.conf file using the Port and Listen properties.

Checking the Consoles

The next thing you can verify is if every component works properly. The following assumes that the Application Server / SOA Suite has been installed on a machine which an IP address that can be resolved to the host name "localhost", and using the (default) http port 8888.

The components that you should check are:
  • HTTP Server
  • Application Server Control
  • BPEL Console
  • ESB Console
  • Web Service Manager Control
  • Rule Author

Except for the HTTP Server, every other component will require you to log in. By default the user name will be oc4jadmin. The actual user name can be found in the [SOA_Oracle_Home]/j2ee/home/config/system-jazn-data.xml file. Look for a user with display-name OC4J Administrator. The password will be obfuscated so if you don't know, ask your customer.

HTTP Server
Check if the HTTP Server works using the URL http://localhost:8888. This should show the "Welcome to Oracle SOA Suite 10.1.3.3" page, from now on referred to as the Application Server Control. From there you can browse to the Application Server, BPEL, ESB and Web Services Manager Control.

Application Server Control

Clicking the link to the Application Server Control (or typing in http://localhost:8888/em in your browser) should bring you to the login page of Application Server Control. When logged-in the Cluster Topology page should show, displaying the Application Server itself with at least two OC4J instances in it, one normally called home and the other one normally called oc4j_soa.

When the Application Server Control is not up, it might be that you have ran into the issue as described in section "7.9 Accessing Oracle Enterprise Manager after Applying Patch". It states that this happens in rare cases, of which my customer apparently was one.

When the control is up, click on the home instance and then on the Applications tab. From there expand the Middleware Services and then Other Services. That should show a WSIL-app application deployed on it. Click that and go to the Administration tab and on the row that reads View Proprietary Deployment Descriptor tab click on the Go to Task icon. Somewhere at the right it should read deployment-version="10.1.3.3.0".

When patching a 10.1.3.0 installation, one of the (manual) post-application tasks is to redeploy this web application. In the list with post-application tasks it is described that you have to deploy it manually only when patching 10.1.3.0. My customer patched a 10.1.3.1 installation, but for some reason the WSIL-app wasn't. In this way I discovered my customer had not yet done any of the post-application tasks.

I therefore suggest to check the deployment-version of each web application, just to make sure. It's not that much work any way. The other web applications you can check are deployed on the oc4j_soa instance and can be found by going to the Applications tab and expand the Middleware Services. That should list all the SOA Suite components, being:
  • Rules
  • ESB
  • WSM
  • BPEL
Mind that all these SOA Suite components are just web applications that have been deployed on the oc4j_soa instance. You can expand them all, check if they are up and have the correct version number in the same way as I did for the WSIL-app.

BPEL Control
Clicking the link BPEL Control from the Application Server home page should bring you to the login page of the BPEL Control. Normally you log in using the same credentials as for the Application Server Control, but these might have have been changed after installation.

When logged-in you should see the home page of the BPEL Control. Probably there is not much to see yet, so we move on to the next step. Later on we will deploy a simple BPEL process on the oc4j_soa instance and then you will use this control to test it.

Log out of the BPEL Control. This will bring you back to the login page. Follow the link on the login page to the BPEL Admin console and login. If you have never seen this before, it might be interesting to review and see what is being configured in there. Close the window once you're done.

ESB Control
Clicking the link ESB Control from the Application Server home page should bring you to a login page of the ESB Control home page. As with the BPEL Control, normally you use the same credentials as for the Application Server Control.

When logged-in you should see the home page of the ESB Control. There probably is not much to see here either, so we move on to the next step. Later on we will deploy a simple ESB service on the oc4j_soa instance and then you will use this control to test it.

Web Service Manager Control
Clicking the link Web Services Manager Control from the Application Server home page should bring you to a login page of the Web Service Manager Control. I discovered that it failed to show on my computer and can't replay what I saw at my customer's site so I leave that to your own imagination what to do here.

Rule Author
There is no link on the Application Server home page for the Rule Author (at least not in my case) so you have to check that by typing in http://localhost:8888/ruleauthor in your browser. This should bring you to the login page of the Rule Author.

Once logged in you should see the "Welcome to Oracle Rule Author!" page. As the Rule Author help is deployed using a separate web application, follow the link to "Help" in the corner right at the top and check that the help for Rule Author is coming up.

Creating JDeveloper Connections

After installation of the SOA Suite and having verified it runs you should be able to connect to the Application Server and the Integration Server from JDeveloper in order to be able to deploy BPEL and ESB processes on it.

If the connections have not been made already, start JDeveloper (10.1.3.x) and create an Application Server connection using the OPMN port you found out earlier (default 6003). After that creating an Integration Server connection using the http port you found out earlier (default 8888).

Testing BPEL Deployment

The next thing you can do is checking if you can deploy BPEL and ESB processes. I brought a prepared simple Hello World BPEL process with me, as shown below.


The assign takes some string (a name) as input and replies "Hello [name]. The time is now [date + time]", as shown in the next picture:


You should be able to deploy that on the Integration Server by right-clicking on the project and choosing Deploy and follow the link to the Integration Server. You probably deploy on the BPEL domain called "default," but your customer might have created other domains as well (which you can find out by going to the BPEL Admin console discussed earlier).

Once the Hello World project has been deployed, using the BPEL Control you can navigate to that process which will bring you to the Initiate tab. On that you can enter a value in input and press the Post XML Message button. That should show you a result similar to the following:


Hello jan. The time is now 2007-11-30T11:54:37+01:00


Testing ESB Deployment

Now the Hello World BPEL process has been deployed, you might want to test the deployment of an ESB service. What I did was creating a new ESB project that I called HelloWorldESB and using the ESB diagrammer executed the following steps (unless specified otherwise left everything default):
  • Create a directory on the application server, for example d:\input and put in there a plain text file called name.txt with in it one string (the name of your customer or whoever is watching every step you take, for example).
  • Make a copy of the name.txt file. You'll find out why.
  • From the Component Pallet -> Adapter Services drag a File Adapter to the diagram and call it readName.
  • Click on the icon next to the WSDL File field and using the Adapter Configuration Wizard create an adapter that reads a file and polls the directory you just created for the file named name.txt with a frequency of 5 seconds. Define a schema for it using the Define Schema for Native Format button and create a new native format of file type Delimited and browse to the name.txt file to sample it. Finally enter a name for the record, e.g. "name" and finish the wizard.
  • Double click the routing service (named readName_rs), expand the Routing Rules and using the green plus button navigate to the Hello World BPEL process you deployed before until you reach and select the process operation.
  • Create a new transformation mapper file by pressing the button next to Transformation Map and connect the C1 field from readName.wsdl to the input field of the HelloWorld.wsdl.

After saving an closing the routing service, the ESB diagram will look like this:


You can now deploy it on the Integration Server by right-clicking the project, choose Register with ESB and choose the Integration Server connection. After a successful registration is should show a window saying:

Registration of Services Successful

BPELSystem.default.HelloWorld.readName_RS created
BPELSystem.default.HelloWorld.readName created

If you navigate to the directory containing the name.txt file, you probably will find that it's gone. No panic, this indicates that the ESB service already is working, and will have read and processed the file!

You should able to verify this by going to the ESB Control and click on the printed-paper-page-looking button at the top-right side (what were they smoking when creating that?). At my customer's site it showed the ESB instance alright. However when replaying this at home I found out there is a problem with my ESB installation, as it failed to show instances with a ORA-00904 error. Too bad, I don't have the time to fix it. Anyway, let's be positive and assume that your case is similar to my customer's so that clicking the instance will show you it's flow.

You should also be able to go to the BPEL Control and verify that the ESB service actually called HelloWorld service. Click on the most recent instance of that process and go to the Flow tab. That should show you the flow of the executed BPEL process. When you click on the replyOutput icon, it should pop up a page displaying a message similar to the one you saw earlier when testing the service, this time with the content of the name.txt file.

This is where I concluded at my customer's site that they had installed the SOA Suite alright. Haven't heard otherwise yet, so I assume my conclusion wasn't premature!