Note: The "GetMortgagePayment" web service is no more available starting with April 2018.
Thinking about your Dream House ?
"Soon after moving into their seemingly idyllic new home, a family learns"...Sorry! Looks is not about that IMDb 2011 Dream House...Let's Move On.
Let's go back now to a more different dream house; a one that sometimes equals a Mortgage Payment.
I need now to add a "disclaimer": this will be a very long tutorial ! On the other hand, once you are done with it, you will feel more relaxed with the Oracle BPM Suite and in the future you will need less time to create a new Oracle BPM project/composite....Not to add that most of the rows here are as pictures.
In addition, some of the steps I used for the tutorial maybe will make no real sense but go with the idea behind it ... You can always add new details or improve a project or even have a different approach.
I will only add that this is a SOA & BPM project: so the focus is on both 😉
Let's start now with ...the end... of this project.
Below we have the input data [IN]:
And/or it can look like below:
I found the above nice png picture based on Google basic search and the link is here: https://d36csm6pmnryl5.cloudfront.net/assets/images/home-sold-5e18f5af20094bb46c699b267fb0ffa5.png. At the end use your own picture or -for tests- go with "mortgage filetype:png" Google search.
Below we have 2 options for the output data [OUT]:
Note: Once we are done with the SCA itself, later we can create a nice user interface for the project using different HTML/CSS/JavaScript options or we can also use Oracle APEX tool [like I used above].
Actually -spoiler alert- from a specific point of view we will use both of them.
Note: SOA and BPM is never about the UI ! Once you have the composite done you can later create your own UI based on whatever the technology. This is actually the beauty of SOA.
Speak of the...SOA and BPM beauty...this is how things will look like once all done:
I think we can now skip other nice stories and dive into the SCA composite pool. At the end the UI should be clear enough: based on some input from the client we will calculate the mortgage, check if a credit card is valid and the type, find details based on some ZIP US and based on some specific currency we will update the mortgage output to the new currency values; all the output will be later saved in a DB table and an email will be sent.
Note: Why the output is not back on the client side? Because we follow a scenario with some "human tasks" and this needs time...for the output to be created and I don't think a real customer/client can wait such amount of time. However, the customer/client will receive email notifications based on the "human tasks" output [details approved or rejected] and later can check the details from a specific account or any other scenario.
For this BPM 12c composite we need the below resources:
- SOA-BPM 12c domain with Oracle Database XE.
- US ZIP codes web service with MySQL & GeoNames.
- Luhn Checker web service: how to validate a credit card.
- Oracle Database 11g Express Edition (Oracle Database XE).
- Oracle APEX - you will have it by default with the Oracle XE or any other Oracle DB.
- Exchange Rates -> Interactive database - > Exchange Rate on Forex Market - daily values. We will keep this info locally in the Oracle Database XE as Exchange Rates table. You will create the specific table and insert the values. The provided details are more to have real values for the currency - at the end it can be whatever values.
- GetMortgagePayment web service. This is actually the main web service for this BPM project. All other services will "move around" it.
- SOA and Gmail
- SQL files and schema xsd files.
1. Oracle Database XE: Exchange Rates
We will provide no Oracle Database XE installation details here since this is just a "Next->Next" step for you to follow. If you already have an Oracle Database Standard Edition or Enterprise Edition instance then no real need for the extra Oracle XE one.
Once you have the Oracle Database instance up and running run the below sql - this sql will both "CREATE" and "INSERT" all the needed details:
Note: If you want to use a different schema - other than the "HR" one- then make sure to replace "hr" with your custom schema.
Values provided are demo only and such you can even update the values with your own details.
2. Oracle Database XE: Mortgage IN and OUT
Once you have the Oracle Database instance up and running run the below sql files - this will both "CREATE" and "INSERT" all the needed details:
Note: The "MORTGAGE_INPUT" table will be used only for the client input and will never keep the future updates more than 5 sec. We will link this table with the future Oracle APEX application as the BPM UI.
The "MORTGAGE_OUTPUT" table will be the final destination for the BPM composite: all specific details will be saved into this table. The sql will also create one dummy row with some dummy output. You need to visualize this table with some business impact: the mortgage provider will have all needed details here and later will use the already available details for some future customers....Again, this project is demo only so, of course, a different approach can be in some other real life scenario.
3. GetMortgagePayment web service
We will use an already complex and available GetMortgagePayment web service.
This service is powered by http://www.webservicex.net:
4. BPM SCA Composite
This chapter will be a very long one. It has 10 pages.
Even so, each step is very simple and the only reason why it goes very long is just because of some details I need to add about each step.
4.1 Create the blank BPM project
We will start and open JDeveloper to create the BPM project.... You can use the below patterns or you can even go with a different name for the App and the Proj:
- Application name: BPM_Mortgage_Payment_App
- Project Name: BPM_Mortgage_Payment_Proj
Note: Since I have no pic for the "Step 2 of 3" go with "BPM_Mortgage_Payment_Proj" for the project name.
Note: As always, use the "Empty Composite" option ! This approach will help you to better understand/visualize the SCA itself VS each component you will later create.
At the end you will have 2 main folders: SOA and BPM.
If not already open, click on the SCA main file: composite.xml. This file will always be under the SOA folder.
Now that we have our "blank canvas" we can go and "paint" all the needed SCA resources.
We will start with the "External References" - since all clear, we have them already; we just need to "paint" them on this project.
4.2 Luhn Credit Card Service
For the first "External Reference" we will use the "Luhn Checker web service: how to validate a credit card" service we just created.
Open the composite in EM Console and copy the WSDL location:
Use this link for the first "SOAP" reference:
All done !
4.2 MySQL ZIP US Service
For the next "External Reference" we will use the "US ZIP codes web service with MySQL & GeoNames" service we just created.
We will follow the same "SOAP" approach like for the above "Luhn" service....
All done !
4.3 Get Currency DB Service
For the next "External Reference" we will use the DBAdapter [Database technology] to select the information from the "CURRENCY" table - check the CURRENCY_export.sql file.
Note: Of course, we will also need to create the new data source on the SOA domain and update the DBAdapter application with the new JNDI.
In addition, use your own DB details [host, port, password].
The JNDI for the DBAdapter is:
- eis/DB/HR_XE_DB
All done.
For now we have 3 services for the "External References":
4.4 Get Mortgage Payment Service
For the next "External Reference" we will use again the "SOAP" option and this time we will link the new web service with the external/remote service provided by the http://www.webservicex.net team:
- GetMortgagePayment [http://www.webservicex.net/mortgage.asmx?WSDL]:
All done!
Now we can check again the SCA composite to see the list of "External References":
4.5 Save BPMN output details to DB Service
For the next "External Reference" we will use again the DBAdapter [Database technology] to merge the information into the "MORTGAGE_OUTPUT" table - check the Mortgage_Output_export.sql file.
The JNDI for the DBAdapter is the same one:
- eis/DB/HR_XE_DB
Note: Of course, based on some other scenario, we can use the "Insert Only" but for this demo we do not want to pay attention to the data itself so we can use the "Merge" option.
Note:We already selected the specific table - the query on the HR schema picture step was ignored.
Note: Select all and from here go with the "Next -> Next" pattern and then Finish.
Now we are 100% done with all the "External References":
Note: If you now go back and check the first rows of this tutorial you will notice one more "External Reference": the "BPM-NotificationService". However this reference will be automatically created... later... when we will define the BPMN flow and choose the specific email notification activity. So, at the end, the key word here is "automatically".
At this 4.5 step you probably already realized how simple [actually] is to define all such different references [using the Database and SOAP technologies].
Maybe you now think IF and [mostly] WHEN we will actually go and implement the BPMN itself....How about...now ? However, I do need to add that later we will switch from the new BPMN component to the BPEL one. Yes, there will be a BPEL component as well.
Since this is a BPM[N] tutorial -maybe- you will think like "why so many steps before the BPMN ? Why switching from BPMN to some other SCA component like BPEL ? " The answer is simple: BPMN is about some business flow between different people [of course this is a very simplistic definition] but at the end is not only about users interaction is also about some specific activities that defines the business itself: some data is saved [aka sql insert or update], some specific data needs to be found [aka sql select ] and some external web services needs to be invoked [aka Luhn, ZIP, Mortgage].
In addition, we will also find out that BPMN is also very much like the BPEL component: it needs variables and some specific data type.
4.6 The BPMN Component
4.6.1 The BPMN story
You can drag and drop the BPMN component into the....only possible SCA location: "Components" and check the details and then STOP.
Note: Most of the tutorials will focus on the "Manual Process" option. Such we will go with a different approach: "Async Service". Why ? Because at the end we want for this BPMN process to act as any other web service we used till now: we will have a WSDL that later can be invoked like we already saw it with other services and we will also go with 2 more options for the same BPMN process to be invoked: a REST interface and a Database one. This approach is not possible if the "Manual Process" option is used.
Before going with the "Next" step we need to download some files.... since in the SOA-BPM world is always about the messages that are exchanged between different services and those messages need to be defined based on some XSD files [aka XML schemas].
Why the extra files ? Why the XSD files? The answer is very simple: Java ! Actually it can be like any other programming languages where you have different data types:
- primitive data type
- complex data type aka Objects [a collection of properties]
Back to the BPMN we also have 2 main specific details we need to understand now - and once we are done we can go and play with them as much as we want:
- Business Objects = complex types = Objects = represented by XML Schemas. This is the "type" itself and not a specific variable ! This is the Java "class".
- Data Objects = the variable itself with a specific type like primitive data type or complex type defined by a Business Object. This is the Java "object".
4.6.2 The BPMN SCA
Required XSD files:
If not already done, you can now drag and drop the BPMN component into the only possible SCA location: "Components" and use the "Async Service" option:
Name: BPMN_Mortgage
Type: Async
Next.
We will define the Input as the "Client_BPMN_IN.xsd" Business Object type - such we will need to create it and also to import the required xsd file.
In addition, we will also define a new module [we can see it as a folder] as "Mortgage_Module" and here we will keep all future Business Objects.
Note: We need to use "Based on External Schema" just because this Business Object type has many elements and we do not want to create them manually. If no such schema already available then we can create the type...manually.
Note: Since there is no output then we can ignore the "Output" tab.
From here is "Next->Next":
All done:
Note: Since some of the "External References" were added after some time and others are not yet generated => see the "External References" as an overview for now. However, most of the web services are there.
For now the new BPMN component is exposed as SOAP service; later we will define other new options [REST and DB].
Go now and check the Business Catalog:
I think now all makes sense; is more clear and soon we will create new Business Objects [aka types]. Do keep in mind: we only have the type for now but there is no variable itself to work with [so no Data Objects].
How about we now create such Data Objects ? Right click the "Process Data Objects" and select "New":
The new Data Object name should be "client_IN" and the type is the "Client_IN_BusinessObject".
Note: To make all details clear we will use almost the same name both for the Business Objects and the Data Objects variables.
Download the required XSD files:
Below is the full list of Business Objects:
Below is the full list of Data Objects variables:
Now we can see it even more clear:
Now that we are done with all the needed data types and variables we only have one more step before going with the flow itself: "users". Yes, is "users" and not users since in BPMN the users can be both specific users [and this is how we will implement them] but can also be groups of users.
If user "X" enjoys the vacation => a different user "Y" -but from the same department- should be available to handle a specific input/ task.
For this demo project we will need 3 users: the customer or the client, a user to approve the credit card [even if this task sounds odd in areal life scenario] and a user to approve the mortgage.
Since users are part of an "Organization" then this is where we will define them for the BPMN project....
But first we will define 3 new users on the WebLogic side:
- Client
- CreditCardOfficer
- MortgageOfficer
Note: When defining the BPMN users we can follow 2 main different patterns: we define only the user name on the BPMN side but with no link with the WebLogic domain or any other external LDAP; if so, once the BPM project is deployed we will later see what BPMN users will be assigned on what WebLogic users/ groups .... OR the second scenario: we define the BPMN users and in the same time we link them with some already available users/groups [from WebLofic side or external LDAP].
Of course, in this demo we will go with the 2 scenario.
Back to the BPMN and the "Organization". Create the first user: "Client" and link it with the WebLogic user with the same name:
Implement the same for the 3 user: CreditCardOfficer
Now that we have all the 3 users we need for this demo project, we can create all the 3 corresponding Swimlanes and we can also see the entire flow....
This is how the flow will look like once all steps are implemented.
Of course, the flow itself can be different than whatever we have here. For example in our case a human task [so eventually a real user] will approve or reject the credit card - this scenario will most likely never happen in real life.
What is that we have in the above picture? Basic BPMN components:
- Activities: as "service" [on blue] and "human task" [on green].
- Gateways: both "Parallel" and "Exclusive".
- Events: "Start", "Strop,", "Save" and "Terminate".
You can start by just adding the big players on the BPMN "canvas": the activities.
Why such specific activities ? Simple, each will handle a different ... activity in the background.
The "Service" will call a service. The "User" will call a service user and the "Mail" will call a notification service. Do we also need to implement all such services ? NO ! This is why we postponed so much the BPMN itself. However, now the question is where do we find such services and the answer is always the same one: the SOA canvas - aka the composite.xml:
As we can see, the BPMN can call services form the "External References" list or even other "Components".
As a very simple approach: you can just drag-and-drop all such activities into the BPMN canvas. Later, we will also "draw" wires between them. Ignore also the warning - all such warning are simply because by default there is no specific connection between each activity and an external service.
Gateways. We will implement 2 main gateways: "Parallel" that does exactly what the name suggests: will run in parallel 2 or more services.
As in any flow and business itself: we will need some decisions: "Exclusive" gateways. This stand for the old known pattern: IF a THEN b ELSE c.
So, just add them on the canvas and once done we will also wire them with the other components.
You can now place the first activity between the gateway:
Since the "Parallel" equals more than 1 single service we need to create the new wire:
Now we can also place the 2 activity between the same Parallel gateway:
You can now rename each service activity - if not already done. This can be done by "right- click" and "Properties" -> Name:
I think already all clear and simple. At the end we spent more time and pictures here than it actually makes sense :D
All is simple enough - ONCE and only ONCE we know the flow. The flow itself is actually where we need to spend always more time: how to think the flow... how to think the business itself ?
In Oracle BPM Suite the most difficult part is the flow [aka the business we need to implement] and the messages [ the XML schemas and other variables and types we will need]. Once we have them then is very simple to implement them.
In addition to the new name you can also start and go with the first step of the "Implementation":
Once done with the first service you can switch to the SOA composite and see that ....
Now a new one:
And finally: no more warnings for the first 2 activities:
Actually, since we also have the Email activities the SOA composite should looks like this:
Now we will stop here with the BPMN since the 2 remaining services will be merged as 1 single service and.... such the answer is..... ? What SOA component helps us to integrate some services ? Of course the answer is : Bpel !
BPEL Mortgage
From the SOA composite drag-and-drop a Bpel component....
Import the 2 XSD files to define the IN and OUT of this Bpel and make sure NOT to select the "Expose as SOAP service". We will not expose this Bpel to the client world so no need to select this check-box. Save all and OK and all done with this step.
We will now link the Bpel with the 2 services we want to include in the Bpel:
This step will create the corresponding "partner Links" inside the Bpel.... For some unknown reason some of the partners will be both in the left and right side; ignore this and think that both of them are in the right side.
As you can see below I already added some new activities inside the Bpel: the "Flow" and for each cell will be 1 "Assign" and one "Invoke" activity:
The last step is to add a new "Assign" activity that will assign the output back to the client.... In this case the client is the "service" or the "service interface" or whatever the future real client we will define....
With each "Invoke" activity we will also create the In and OUT variable - per each "Invoke".
Long story short: we will check the Mortgage and in the same time [flow = parallel] we will check the DB for the specific currency and the value.
In this demo the currency is for demo and such the math behind it: we will use the "divide" as the operation to find the new value based on the specific currency.
The first Assign that assigns the client IN to the Mortgage IN variable:
The second Assign - that assigns the client IN tot the DB service:
Now the last and final Assign step.... that covers more details. First is the basic Mortgage OUT details to the client OUT:
What about the "TO" variables?
The math is simple: "FROM / currency" - and for this we will use the "Expression":
Now we need to "DIV":
Once done, save, close OK and we will link the new "DIV" expression to the corresponding Client _TO variable:
And one more...actually "3" more:
Don't forget also to include the "currency" and the "currency Name" details:
Once all Bpel steps are done ....
Note: Keep in mind you will later use the bpel client details:
Save and close the Bpel. All done!
Back to the BPMN
Link the new Bpel with the BPMN component by pointing the specific "Service" activity to the new Bpel component client:
Note: Make sure you select the Bpel client service [aka the service interface] and not the Mortgage WSDL external service !
The last activity we need to implement is actually the "stop event" and in this case we will link it with the "save to DB" service:
Note: Please double check the above picture and see that now is all about a "Message" implementation type - so this time this activity is no more a "service" one.
Till now all should be clear related with how we link a service activity [or event] with an already defined service [from the SOA composite.xml level].
Next step ? Now that we know what service each activity will trigger we also need to define the message flow pattern.... Since in SOA-BPM world is always about the messages and about the types.
So, long story short: this is why we also defined the Data Objects [based on specific new Business Objects]:
This step is also a very simple one; the step is like an "Assign" activity from Bpel and at the end since we use external services [external to BPMN that is] then we will also see that some steps are almost automatically done by JDeveloper.
BPMN Data Associations
We can start with the first service activity: Luhn one. We already know the rule: we need an "IN" and an "OUT":
- we have an IN from the BPMN client to the IN for the external service
- we have an OUT from the external service to an OUT for the BPMN variable [Data Objects that is]
The same rule/ pattern will go also for the "ZIP US" service and the "Find Mortgage" Bpel component.
We will skip for now the Human Tasks and the last step where we save the data [implemented by the event component]....
Human tasks
I think this section should be some rows above [when you also drag-and-drop the Human task activities]. However since till now we focused on other steps for this project chances are you still have no such Human tasks on your BPMN canvas.
How important are such Human Task activities ? I think very important since a business goes around the people [users] that implements it.
For this project we will have only 2 users to approve or reject some business components: the credit card and the mortgage output.
Note: I already covered this pattern with "user + approve/reject+ cred card"; it makes no sense in a real life scenario but we will use it however for the demo only.
Before everything else, we will need 2 more Data Objects: "card_approved" and "mortgage_approved"; both Data Objects will be simple type as "string".
So, drag-and-drop the first Human task activity and we will define a new Human Task componenet + the input and the Output [Outcome]:
The IN in this case is the information that future task will display for the user to handle it [aka: to approve it or to reject it]. Since we don't want for the user to change this info we will not select the "Editable" option.
Once all done, we can swicth to the SOA composite canvas and see that we also have a Human Task component:
We will follow the same steps for the new Human Task: the Mortgage one
I think is all clear: the IN that each task will dispay is actually the OUT from each related service.
Now we need what ? A nice UI for each task...so we can ask the Jdeveloper to create it:
There is a nice pattern to be used: add the whatever name you want but at the end use the "_UI" - this will also help you once the related application is deployed:
Give it some time and once is done you will see the specific jspx file and the UI defined:
What next? You can search for a nice png picture and include it on top of the card details. This step is however an optional one !
Note: I found this nice picture here: http://www.casumobonus.com/wp-content/uploads/2017/05/credit-cards.png
Once more for the Mortgage task:
And with the extra picture:
Note: I found this nice picture here:
https://cdn3.iconfinder.com/data/icons/business-terms/512/mortgage-256.png
Again, you can add whatever the picture but the recommendation is to use "png" pictures.
Once the project is deployed you will have the below UI details:
EXPOSE AS REST
Database SCA Exposed Service
The below UI was created using Oracle APEX:
