A SOA Suite Use Case - Healthcare Example

Introduction:

     Today I will show you a simple healthcare use case using Oracle SOA Suite in Jdeveloper 12c.In this use case, we'll use a business rule, a java embedding, if and throw activities, a xslt transformation and a database adapter in Bpel.Before continue be sure about the below prerequests are satistifed on your computer.

• Download SOA Suite 12c from the below link.   http://www.oracle.com/technetwork/middleware/soasuite/downloads/index.html. Note that its now much more easier than SOA Suite 11g  to build a development environment.In 11g you need to download and install oracle web logic server, oracle service bus, oracle XE database, RCU, SOA Suite and finally Jdeveloper respectively.On the contrary in 12c, you just need to install a zip file, and when you extract it you'll see two jar files naming fmw_12.1.3.0.0_soa_quickstart.jar and fmw_12.1.3.0.0_soa_quickstart2.jar.
• Install SOA suite 12c by running a command line as an administrator, and execute the following command. java -Duser.language=en -jar fmw_12.1.3.0.0_soa_quickstart.jar. Be sure to have at least java 7 update 55 and use -Duser.language=en runtime argument, if your computer's display language is not english.It will install all the features that a developer needs including jdeveloper with SOA extension, an integrated weblogic server and a Java DB.
• Set the JDEV_USER_DIR environment variable to define the directory for your jdeveloper projects.     

     For details of the installation process you can have a look at the Oracle SAO Suite user guide.

     http://docs.oracle.com/middleware/1213/core/SOAQS/index.html

When the installation finish, open jdeveloper and start the integrated weblogic server.It will be created a default domain when you first execute the weblogic server.You should open the enterprise manager at http://localhost:7101/em where you can see, test and manage your projects.

After that you're ready to develope SOA projects and you can easily deploy them on the weblogic server by just right clicking the project and choose Deploy. At the end of this write, we'll see how to test and debug our projects,but first let's first develope our use case, At the end of this write we'll get the below composite.

Figure 1

Building the Bpel Process:

     We'll start with a synchron bpel process like below.Just create a SOA application, open the composite.xml which is named as your projects, right click the components part, and create a Bpel Process as synchronous.Remember to choose Bpel 2.0.

 Figure 2

Now, we'll edit the automatically created xsd and wsdl files to build the interface as our need.

Figure 3

As can be seen from the Figure 3, in the xsd file we define the request as a patient identifier with simple type to restrict the value with 11 characters string, a string provision date, an integer hospital code, a string speciality code, treatment type with enumeration and chase type with enumeration. The response object has only a string type message, and also there is a fault message with a string detail message.

Figure 4

In the wsdl file we define the correspending request, response and fault messages.

Create Database Adapter and Connection:

      We now define the Java DB database connection and the database adapter.

Figure 5

In the Application Resources -> Connections -> Database, right click and create a new database connection like Figure 5. You need to choose the correspending Java DB jdbc driver.

Then, right click the created database connection branch, and create a new table named HASTA_KABUL like in Figure 6.

Figure 6

Now, open the composite.xml, and at the external referecences part, right click and create a database adapter.You will choose the previously created database connection and a builtin JNDI name at the wizard.

Figure 7

Choose insert only operation type.

Figure 8

Select the previosly created table HASTA_KABUL.

Figure 9

After creating a reference from the Bpel to the newly created database adapter, the composite should now look like the following.

Figure 10

Create The Business Rule:

     Drag and drop a business rule from the SOA components to the composite.xml's components, rename it, and choose the input and output as the input and output of the defined bpel process from the HastaKabulBpel.xsd file.

Figure 11

   

After referencing from the Bpel process to the business rule, the composite will look like this.

Figure 12

Double click the business rule, and start to edit the rules.You have two options defining the rules, either General Rules which is more programmer friendly as you can define the rules with if/then statements or Decision Tables which is more generic and to define it you don't need to be a programmer.Under Decision Tables tab, press the plus button and create a decision table.

We want a business rule that gives error if tedaviTuru is A and takipTipi is Y or tedaviTuru is G and takipTipi is Y, and continue otherwise.

In the decision table screen, you have conditions and actions parts. In the conditions part, add two conditions, choosing the tedaviTuru and takipTipi fields of the request object.Then define five rules by clicking the plus button again.You will choose values of the rules from the enumerated values when you click on each rule. Since there is conflict with Rule 3,4, and 5 we choose to override R4 and R5's rules by R3.

In the actions part, add a new action with "assert new" form, and choose HastaKabulCevap under the facts. In the properties part, choose the sonucMesaji as parametrized as shown in Figure 13.

Figure 13

Finally, we'll get a decision table like below.

Figure 14

Now, we'll add a second rule that gives error if the provision date is before 45 days ago.

Add a second decision table.Create one condition, open the expression editor and type JavaDate.from date string(HastaHabulGiris.provizyonTarihi.trim()) < JavaDate.add days to(Calendar.getInstance() ,-45). type Since it's a boolean type condition, add one rule as true.The actions part will be similar to the previously created rule. However this time we modify the previously created HastaKabulCevap object with the required messages.

Figure 15

We completed the business rules. The bpel editor should now look like below. You should drag and drop a business rule in the bpel editor after the receiveInput.

Figure 16

Double click the rule and choose the previously created business rule as the dictionary.For the assign input facts, assign the request payload to the business rule's input and for the assign output facts, assign the business rule's output of message to the response's message as shown in Figure 17 and Figure 18.

Figure 17

Figure 18

Create If and Throw Activities For Rules:

     According to the output of the business rule component we either throw a fault or continue to the process.To accomplish this, first drag and drop an if activity from the Components -> Structured Activities to the place after the business rules component in bpel editor.Double click it and in the condition section type $outputVariable.payload/client:sonucMesaji != ''.You can write an explanation for the if activity if you like.See in Figure 19.

Then drap and drop an assign activity inside the if activity, it will be executed if the condition of if activity is met.Create a variable FaultMessage by using the predefined Fault Message Type and set the sonucMesaji to the Fault message's detail section.See in Figure 20.

Then drag and drop a throw activity after the assign activity.Choose the fault from the project wsdl file and set the Fault Variable as the FaultMessage variable that we defined in the previous step.See in Figure 21.

Figure 19

Figure 20

Figure 21

Create The Java Embedding:

     We may use java embedding, if we have previously developed java code and do not want to deal with again to implement the same code in bpel.In this part, we will define a java class to validate the personel identifier number according to the desired algorithm and call this class from the java embedding component to complete the validation.

First create a simple pojo under the project. The created java file will be under the Application Sources folder.The class validate the personel identifier which has a static validate method that takes the personel identifier as the parameter.See Figure below.

Figure 22

Drag and drop a java embedding component from the Components -> Oracle Extensions to the place after the business rule that we defined before in the bpel editor. 

Figure 23

Double click on java embedding and type the code shown in Figure 21.

Figure 24

In Figure 21, we use getVariableDate and setVariableDate methods to get the input from the request and to set the output of java embedding respectively. Since we use XMLElement and TCKNoValidation classes, we have import the desired packages in the bpel source like in Figure 22.

Figure 25

Here we define a boolean variable in bpel process named "TCKNoValidationResult" and set to false if the validation failed.

If you want to use a class or jar file outside of the project, you just need to place the class file under the $PROJECT_DIR\SOA\SCA-INF\classes and place the jar file $PROJECT_DIR\SOA\SCA-INF\lib folder, set the jar files to the classpath from the Project Properties -> Libraries and Classpath and make the imports in bpel source file.

Create If and Throw Activities For Java Embedding's Result:

     Accoding to the output of the previous java embedding component we either throw a fault or continue to the process.To accomplish this, first drag and drop an if activity from the Components -> Structured Activities to the place after the java embedding in bpel editor.Double click it and in the condition section type $TCKNoValidationResult != true().You can write an explanation for the if activity if you like.See in Figure 23.

Then drap and drop an assign activity inside the if activity, that is it will be executed if the condition of if activity is met.Create a variable FaultMessage by using the predefined Fault Message Type and set an error message to the Fault message's detail section.See in Figure 24.

Then drag and drop a throw activity after the assign activity.Choose the fault from the project wsdl file and set the Fault Variable as the FaultMessage variable that we defined in the previous step.See in Figure 25.

Figure 26

Figure 27

Figure 28

Create XSLT Transformation For Database:

     The next step is just to define a xslt tranformation after the if activity, to set the input of database adapter. Normally xslt transformation is used for more complex transformations and calculations, here we may use an assing activity, however we use xslt for just explanation,Since all the validations up to know are passed, we can safely set input payload to the database adapter input..See in Figure 26.

Figure 29

Figure 30

    Finally, drag and drop an assign activity and set the result message as successful after the invoke of database reference.

Figure 31

Figure 32

At the end, the whole bpel process will look like in Figure 31 and 32..Unless a fault is thrown, the response message with status code 200 will be returned to the client. 

Debug and Test the Application:

     To test the application, open the composite, right click the service and set a breakpoint point. After starting the weblogic server, right click the application and choose Deploy, then right click again and choose Debug.The composite will be opened like in Figure 33. Right click the service again and choose Initiate WS Debugging.

Figure 33

An Http Analyzer page will be opened, you can either enter the values from the form interface or enter them as xml from the Http Content tab. Below Figures 34,35,36,37 and 38 shows the possible faults that can be thrown and the successful result.

Figure 34

Figure 35

Figure 36

Figure 37

Figure 38

If you look at the Databases -> DbConnection -> SOAINFRA -> Tables , and right click your table and choose open object viewer, you can see your data inserted like in Figure 39.

 Figure 39

     You may also test, and trace the execution of your application from the enterprice manager. Open localhost:7101/em, login with the credentials you gave at the time of installation. Go to the SOA -> soa-infra -> default -> YOUR_APPLICATION. Click on test and see the following page that you can test your application.

 Figure 40

Now, lets see the trace of execution. Just go to the Flow Instances page like in Figure 41.

Figure 41

Click on the Flow ID and see the details of execution like in Figure 42.

Figure 42

If you click on "View Payload" at any stage you will see the input and output xml or the fault's xml representation of that stage. See in Figure 43.

Figure 43

Conclusion:

     Today I try to explain how to use some of the main components of Oracle SOA Suite environment. The examples are just for explanation and need to be improved for the real time projects. For example the request values need to ve validated and parsed, there can be a xsd validation in front of the application along with an authentication mechanism and logging and error handling features accomplished by a service bus application.You can see a simple restful example validating input data here.You can also see a Ldap example that can be used for the authentication and authorization at here.Also instead of throwing faults you may catch the faults and return just a result code with a message and use the result code to distinguish the error and succesfull conditions. Using this approach can help you collect all the errors return at the end. It can also improve the performance of the application since throwing is an heavy operation. An example of catching can be seen here.

You can download the source code from here.

Using Throw/CatchAll In SOA

Introduction:

     In this paper, I'll try to explain how throw and catchAll activities can be used in bpel process in Oracle SOA Suite environment.In the write of "healthcare example", we had thrown faults to clients. However we may catch all the faults that the application may throw and instead of throwing on error conditions we can return a result code and a result message to the client.In this way we can get both great performance improvement getting rid of the heavy throw statements and we could have the possibility of collecting all the error conditions and return it to the client at once.In either way we should include the result codes and messages at the documentation of the application since the client will distiguish the messages by this code and messages whether its an error condition or not.Also the client doesn't need to deal with catching the process anymore by this way.

In the example, we'll use assing, transformation, if, throw and catchAll activities.At the end of the write we should get the following composite and bpel process.

Figure 1

Figure 2

Create Bpel Process and Define Xsd and Wsdl Files:

    Create a synchron bpel process and open and edit the xsd and wsdl files according to the Figure 3 and Figure 4.We'll have two input fields as string and int, two output fields as resultCode and resultMessage, and a fault with two variables errorCode and errorMessage.

Figure 3

Figure 4

Define the Scope in Which We'll Use CatchAll:

     To use catchAll activity for the whole bpel process, drag and drop a scope from the Structured Activities to the place after the receiveInput.Now lets build the pseudo logic to see how throw and catchAll activities work.

First drag and drop an assing activity in the scope after the component receiveInput and just to be an example concat the input1 and input2 in the assign and set to the resultMessage.See in Figure 5 and 6.

Figure 5

Figure 6

Then, drag and drop an if activity after the assign statement and type the expression like in Figure 7. We simply want the lenght of concat of input1 and input2 to be greater than 5 and input2 to be greater than zero.

Figure 7

Before continue define a variable from the defined bpel fault message type to use in the throw activity.See in Figure 8.

Figure 8

Drag and drop an assign activity and a throw activity for the if condition is true.Assing for errorCode and errorMessage and throw with the predefined bpel fault using the previously defined fault message like in Figure 9 and 10.

Figure 9

Figure 10

For the else condition define another if activity for the condition input2 is zero and throw a builtin system fault invalidVariables.See in Figure 11 and 12.

Figure 11

Figure 12

Drag and drop another assign activity for the input2 is not zero condition and set the resultCode and resultMessage indicating the result is successful like in Figure 13.

Figure 13

Define CatchAll Activity:

     Now, we're ready to define catchAll activity. Go to the bpel editor, and choose catchAll from the scope we defined for the whole process like in Figure 14.

Figure 14

Drag and drop a xslt transformation under the catchAll activity and set the resultCode and resultMessage.If the errorCode and errorMessage are not empty we use them, otherwise we set "unexpected error" message with code 11.See in Figures 15, 16 and 17 for both design and xsl source.

Figure 15

Figure 16

Figure 17

Run the Application:

     We're ready to run the application.Just right click the application and choose Deploy and then choose Debug after placing breakpoint pair to the service reference in the composite. For details of how to test and debug the application you can have look at the "Debug and Test the Application" part of this write. Below we see the various results indicating success and error conditions in Figures 18,19 and 20.

Figure 18

Figure 19

Figure 20

Conclusion:

     Today, I talk about throw and catchAll activities and how to develop a fault handling strategy in Oracle SOA Suite environment.You can either choose to throw faults to the client or catch them and return result code and messages.The later has the advantage in performance and flexibility as you can collect all the errors and show the client.In any way, you should share the message codes and messages with the clients especially in the second case, since the client cannot distinguish the error and success conditions without having a fault.

You can download the source code from here.