Explore a process integration scenario implemented using Oracle Enterprise Service Bus, step by step.
by Ronald van Luttikhuizen
Published March 2008
Foo Inc. is a telephone company. Due to new legislation, greater customer demands, mergers, and fiercer competition, its profits have gradually declined over the last few years. Foo hires the business consultancy firm “U-Build & We-Advise Inc.” to help turn the tide. The outcome of the audit shows that better business-IT alignment can resolve the problems by resulting in both more-flexible business and more-flexible IT. The report furthermore states that an architecture based on Service-Oriented Architecture (SOA) can achieve these goals.
The firm decides to implement an SOA, and that enterprise architecture will be used as a means to structure and streamline this effort. An enterprise architecture team is set up, which reports directly to Foo’s corporate level. To avoid becoming an ivory tower and producing unnecessary paperwork, the team decides to model enterprise architecture on a need-only basis, thereby producing tangible results early. A meet-in-the-middle approach is used: while modeling business processes in a top-down fashion, the required and already provided services are inventoried.
Early in the project, a proof-of-concept is started—not only to get used to the new SOA technology stack but also to gain the trust of Foo’s more-skeptical employees. Ineffective and problematic activities are dealt with first. In this case, the problem concerns invoice processing for Acme Inc., Foo’s preferred supplier for consumer electronics. These products are used for promotional activities. Handling these invoices is error-prone because they are all sent by fax and processed manually. As it turns out, Acme is more than willing to cooperate in this project because it will cut costs for both companies.
This concept of an ecosystem in which organizations are helping each other based on mutual benefits is one of the cornerstones of service enablement.
From a business perspective, invoice processing is a service, among others, used in the “Purchase-to-Pay” (procurement) business process. This process is depicted in the following Business Process Modeling Notation (BPMN) diagram.
Figure 1 The “Purchase-to-Pay” business process
As the figure shows, the process involves the following steps:
The activity “Pay Supplier” itself is a subprocess, depicted below.
Figure 2: The “Pay Supplier” subprocess
The process is initiated when an invoice is received. The invoice is then automatically validated. In the case of a valid invoice, the invoice is paid. Otherwise, a human workflow starts in which the invoice will be manually processed.
As the diagram shows, the “Pay Supplier” subprocess makes use of a service to receive invoices. In the case of Acme invoices, a service “Receive Acme Invoice” is needed.
If we drill down to this level of service design and implementation, we cross the border between process and technical architecture. Instead of BPMN, a more technical modeling notation, Unified Modeling Language (UML), is used.
The UML activity diagram below models the behavior of the “Receive Acme Invoice” service.
Figure 3 The “Receive Acme Invoice” service
When we look at the invoice service more specifically, we can define the following actions:
The activity diagram is split into an Acme-specific part (from start activity to transform activity) and a generic part that applies to all types of incoming invoices. This promotes both design-time and runtime reuse.
Although SOA, like all new paradigms, is no universal silver bullet, a correct usage of SOA in the right situations provides numerous benefits. This case shows some of the promises delivered by service enablement:
As stated in the beginning of this article, the invoice processing service will be implemented using Oracle ESB, which facilitates implementation of more low-level services within an SOA and EDA based on open standards (XPath, XSLT, SOAP, JMS, JCA, and so on). ESBs are particularly well suited for virtualization, routing, and data transformation, thereby separating these concerns from the design, implementation, and execution of business logic and processes, which in the Oracle stack is typically done with BPA and BPEL tooling. In this use case, we primarily need adapter, transformation, and routing capabilities rather than business and process logic.
The position of the previously named components in an overall, high-level Oracle SOA platform is depicted below.
Figure 4 The Oracle SOA platform
From a technical point of view, the invoice process is not entirely straightforward to implement; the remainder of this article will outline the particular steps needed to get it working. In short, this involves:
Event publishing is beyond the scope of this article.
Let’s get started with the implementation. Note that all sources can be found in the project files zip.
The preliminary setup is documented in the accompanying setup guide.
Some interesting things to note about the installation and configuration procedures are:
Now that the infrastructure setup is completed, we can actually start building the ESB flow that processes Acme invoices.
Figure 5 Creating a new application in Oracle JDeveloper
Figure 6 Creating a new ESB project in Oracle JDeveloper
The next step involves structuring the future services in our ESB project. For this purpose, systems and service groups are used. Systems are mandatory top-level organizational units, and service groups are optional suborganizational units. This means that a service is either part of another service group or that a service directly belongs to a system.
A system is a representation of a single application, proxy for an application, or a technical system. In this example, ESB systems are used to divide our enterprise into functional domains such as “Finance” or “Customers.”
A service group can be used to further organize services much like Java packages or file system directories. A service group bundles a set of related services.
Figure 7 The Create System/Service Group option in Oracle JDeveloper’s ESB Designer
Figure 8 Creating the ESB System “Finance” in Oracle JDeveloper
Figure 9 The ESB Service Group Browser in Oracle JDeveloper
Select the system Finance that was created in the previous step and click OK. Back in the Create ESB System or Service Group dialog box, enter Invoice as name, possibly provide a description, and click OK to create the new service group.
Figure 10 Creating the “Invoice” service group in Oracle JDeveloper as part of the “Finance” system
You have now defined the structure in which the ESB project will be deployed. As a result, the Finance.esbsys and Finance_Invoice.esbgrp files are added to the project.
It’s time to create the actual services and adapters. Because all data flowing through the ESB is in XML format, we’ll first need to create an XML Schema describing the Acme invoice data (in other words, the data entering our ESB flow).
Figure 11 Creating an inbound file adapter
Enter ReadAcmeInvoice as the service name and optionally add a description. Make sure that Finance.Invoice is selected as containing System/Group. If it is not already selected, use the flashlight icon to open the ESB Systems/Groups browser and select Finance → Invoice.
Figure 12 Step 3 of the inbound file Adapter Configuration Wizard
In this wizard, use the following settings:
Figure 13 Selecting the XSD element for inbound Acme invoices
A routing service for this inbound file adapter, called ReadAcmeInvoice_RS, is automatically added to the project when the file adapter wizard is completed. This adapter provides routing and transformation capabilities.
Figure 14 The ESB Designer after creating the inbound file adapter service
However, before continuing with the routing service, we’ll first complete the file adapter configuration by providing values for the logical names:
Figure 15 The Endpoint Property Chooser dialog box
Figure 16 The routing service after providing values for the inbound file adapter service properties
You have completed the adapter configuration for reading Acme invoice files. Save all files by clicking the Save All icon.
We continue by creating a database adapter that will insert invoice data into the master-detail tables.
Figure 17 Creating a database adapter
Figure 18 Step 2 of the database Adapter Configuration Wizard
Figure 19 Step 3 of the database Adapter Configuration Wizard
Figure 20 Importing master and detail invoice tables
In this wizard, use the following settings:
Some postconfiguration steps are required to use database sequences. Because database adapters are implemented using Oracle TopLink, we need to configure TopLink-specific settings. The adapter uses Oracle TopLink’s XML-Object (XO) and Object-Relational (OR) mapping capabilities to transform XML into SQL statements. When the following sequence settings are configured, the database adapter will automatically populate primary and foreign keys at runtime when inserting data in the invoice tables.
Figure 21 Modify the Oracle TopLink map to enable native sequencing
Figure 22 Configure sequence settings for the Invoices TopLink descriptor
Figure 23 Configure sequence settings for the InvoiceLines TopLink descriptor
If you compile the project by right-clicking it in the Applications Navigator and selecting Rebuild, you might get the warning TopLink found problems in InsertAcmeInvoice. You can resolve this warning by expanding the Invoices descriptor of the InsertAcmeInvoice map in the Structure window, selecting the invoiceLinesCollection mapping, and deselecting Use Method Accessing.
Figure 24 Deselecting the “Use Method Accessing” option
The warning should be resolved if you rebuild the ESB project.
Sometimes the TopLink sequence information might not be generated correctly. This can result in runtime errors indicating that no primary keys are created.
To verify whether this is the case, open the InsertAcmeInvoice_toplink_mappings.xml file located in the project’s root directory, in an external text editor. Search for the <toplink:sequencing> element. This element should appear twice—once for every invoice descriptor/table (INVOICES and INVOICE_LINES). If no such elements can be found, do the following:
<toplink:sequence-field table="INVOICE_LINES" name="ID" xsi:type="opm:column"/>
<toplink:sequence-field table="INVOICES" name="ID" xsi:type="opm:column"/>
As already mentioned, Oracle JDeveloper automatically created a routing service for the inbound file adapter. However, this routing service does not contain any routing or transformation logic yet. Let’s create this functionality to connect the inbound file adapter to the outbound database adapter.
Figure 25 The routing service with no routing rules for the ReadInvoice operation
Figure 26 Selecting the insert service of the InsertAcmeInvoice adapter as the target service
The Routing Service window shows that the insert is synchronously invoked after an invoice file is read by the file adapter.
Figure 27 The routing service including a routing rule for the ReadInvoice operation
You will need to create a transformation rule because the XML format of the inbound invoice files differs from the XML format expected by the database adapter.
Figure 28 The XSLT mapper tool in Oracle JDeveloper
The XSLT mapper enables you to visually define mappings from input elements to output elements by allowing drag-and-drop actions. The mapper also provides auto-complete functionality for input and output elements that (partially) have the same name.
Figure 29 Auto-mapping input and output XML files by using the XSLT mapper tool in Oracle JDeveloper
Leave the defaults of the mapper unchanged and click OK. As you can see, almost all elements are mapped. Only the following two modifications are needed:
The resulting mapping should look like this:
Figure 30 Final mapping
The project is finished and ready to be deployed to the ESB server and taken for a spin by testing it with a sample Acme invoice file.
Deploy the ESB project to Oracle Application Server by right-clicking the project in the Applications Navigator and selecting Register with ESB. Oracle JDeveloper will inform you that the Finance system, Invoice service group, and adapter and routing services are created on the server.
Figure 31 Registering the ESB project with Oracle ESB
Figure 32 Registration successful
Open to the ESB Control to view the registered ESB flow. Select Start → Programs → Oracle – <SOA Suite instance name> → Oracle ESB → ESB Console. This will open the ESB Control in a browser window.
Figure 33 Oracle Application Server ESB Control
In the Services overview, drill down to view the Finance system, the Invoice service group, and the services that you have just created and deployed. (The ESB Control is documented in the Oracle Enterprise Service Bus Developer’s Guide .)
You can initiate and test the ESB flow by copying the AcmeInvoice_20071230.xml test input file from the InvoiceDemo/InvoiceESB/resources/input directory in the zip file to the inbound directory specified as the acmeInvoiceIn endpoint property of the inbound file adapter.
As a result, the Acme invoice data from the XML file is inserted into the invoice database tables. Verify this by looking in the database. Note that the primary and foreign keys are automatically populated.
Also view the completed instance in the ESB console.
Figure 34 An instance of the ESB flow completed successfully
You have designed and implemented a real-life integration scenario and tested it using an example input file.
Based on a real-life scenario, this article demonstrates how enterprise architecture can be used to identify and model services required from a business perspective. These services can then be used in the composition and execution of processes. This approach guarantees that services provide concrete business value and can be reused.
With this article, you have implemented such a service using Oracle ESB by composing multiple, already available adapters and routing services into a flow used for processing invoices. This is done based on open standards such as Web services and various other Java and XML-related standards.
Future additions for reading invoices from other suppliers can easily be integrated by merely extending this ESB flow. Only inbound and transformation services need to be added while functionality for persisting data and publishing events is already in place.
In our case study, we have further integrated this invoice service into the overall SOA environment by implementing another service whose purpose is to process all new invoices—not only Acme invoices. This service subscribes to new invoice events published by the read invoice service; validates the invoice; and, based on the outcome, automatically pays the supplier or starts a human task. This flow is universal for all types of incoming invoices. The supplier-specific logic is part of the validate invoice service. The above scenario thus implements the remainder of the “Pay Supplier” subprocess, as shown in Figure 2.
Some other, more general, issues to keep in mind:
Ronald van Luttikhuizen ( firstname.lastname@example.org) is an architect at Approach Alliance ( www.approach-alliance.com), a Netherlands-based information and communications technology consultancy focusing on SOA and business intelligence.