1. SOA-5: Introducing Native Invocation with the OpenEdge® Adapter for Sonic ESB®
Rob Straight, Principal Product Manager
David Cleary, Principal Engineer

2. Agenda Business Processes and Sonic ESB OpenEdge Adapter for Sonic ESB
Native Invocation Methodology

3. Business Processes
How do you create business processes that execute ABL components?
With Sonic ESB!
Flexibly assemble components
Heterogeneous
Distributed
Scalable
Sonic MQ®
Reliable Messaging
SONIC ESB®
J2EE™ APPL.
PACKAGED APPL.
.NET™ APPL.
OPENEDGE APPL.
WEB SERVICE
There are a variety of techniques that can be used with OpenEdge to assemble ABL components into a business process. Traditionally this has been accomplished by hard coding the calls between the components, but this limits the flexibility of the application. If changes are needed in the business flow, those changes need to be made in the source code. SOA is a methodology to treat code components as reusable services, and an Enterprise Service Bus (ESB) is a mechanism to flexibly assemble the components without the need for coding changes.
Sonic ESB is a messaging-based enterprise service bus that simplifies the integration and flexible re-use of business applications within a service-oriented architecture (SOA). Sonic ESB eliminates the rigidity and fragility of point-to-point integration with a robust, event-driven architecture that can evolve, scale and extend throughout the enterprise. Customers use Sonic ESB to reduce process cycle time, gather and disseminate information, and reliably respond to business conditions as they occur.
The typical use case is a development team is creating ABL components, and they are then controlling the sequencing of the execution of those components via Sonic ESB.
A secondary use case is a development team that is creating ABL components to sell to a third-party, who in turn will assemble those components for execution using Sonic ESB.

4. Model Business Process: Sonic Itinerary Process Editor
Use the Sonic Workbench Process Editor to create a process and/or to enhance an existing process by adding a step to call your ABL procedure.
This example assumes an existing process that will examine the current message content to determine if the Country is the USA or not, and route the message to the appropriate form. We want to insert a step in the process to call an ABL procedure to lookup the Country. As discussed earlier, you simply drag and drop the .esboe file for the ABL procedure onto the design canvas at the location where you want to execute the procedure within the business process.

5. OpenEdge Adapter for Sonic ESB
ABL components participate in business processes controlled by Sonic ESB
Prior to OpenEdge 10.1C:
ABL is disguised as a Web service
Developer needs detailed knowledge of Web service technologies
The setup in OpenEdge and Sonic™ is complex
Starting with OpenEdge 10.1C:
Native Invocation Methodology Added!
The OpenEdge Adapter for Sonic ESB provide the connection between OpenEdge ABL code and the Sonic environment.
Traditionally ABL code was treated as a Web service by the Adapter. This meant that the developer needed to have a detailed knowledge of technologies (e.g. WSDL) and of tools (e.g. OpenEdge ProxyGen, Sonic Management Console and Invocation Editor). The developer would then create and package ABL as a Web service:
For use stand-alone or with Sonic ESB
SOAP-based
WSDL is a standard, and tools exist to support it (e.g. generate test messages from WSDL)
ISV’s publish WSDL to their users
In practice, technically complex and run time performance impacted by SOAP
Beginning with the 10.1C release of OpenEdge, there is an alternative “Native Invocation” methodology supported by the OpenEdge Adapter for Sonic ESB.

6. Adapter Architecture: Web Service Invocation Methodology
Service1.wsm
Service1.wsdl
ProxyGen
Service1 Source Code
Sonic ESB Container
OpenEdge Adapter for Sonic ESB
Service1.wsm
OpenEdge Service1
SOAP to ABL
ABL to SOAP
Prior to OpenEdge 10.1C, in order to make use of an OpenEdge component as part of a business process itinerary managed by Sonic ESB, the OpenEdge component was made to look like it is a Web service. The ProxyGen tool is used to create:
A WSDL (Web Services Description Language) file for use by any client that wants to call the Web service.
A WSM (Web Service Mapping) file for use by Sonic ESB at run-time in order to locate and execute the OpenEdge component. It contains XML-encoded instructions that enable the OpenEdge Adapter for Sonic ESB to process SOAP messages according to the needs of the OpenEdge component.
At run-time when the Sonic ESB Itinerary has a process step that involves executing an OpenEdge component, the OpenEdge Adapter for Sonic ESB uses the WSM file for the target component (service) to request that an OpenEdge Application Server associated with the service execute that service. The OpenEdge Adapter for Sonic ESB is also responsible for translating the initial SOAP message from Sonic ESB into the appropriate ABL to execute the target service, and for translating the resulting ABL after the service executes into the appropriate SOAP message for use by Sonic ESB as it continues to execute the business process itinerary.
OpenEdge Application Server

7. ABL Native Invocation Methodology
Sonic ESB calls ABL procedures, functions and external procedures directly/natively
AppServer™ call information is collected at development time:
Source code annotation preferred
AppServer run-time properties & service initialization: info stored in invocation files
Input/output parameters of ABL procedure mapped to Sonic message content
Sonic ESB Process Editor

8. Adapter Architecture: Native Invocation Methodology
Sonic ESB Container
OpenEdge Adapter for Sonic ESB
OpenEdge Service1
SOAP to ABL
ABL to SOAP
Service1.wsm
OpenEdge Service2
Service2.esboe
Prior to OpenEdge 10.1C, in order to make use of an OpenEdge component as part of a business process itinerary managed by Sonic ESB, the OpenEdge component was made to look like it is a Web service. The ProxyGen tool is used to create:
A WSDL (Web Services Description Language) file for use by any client that wants to call the Web service.
A WSM (Web Service Mapping) file for use by Sonic ESB at run-time in order to locate and execute the OpenEdge component. It contains XML-encoded instructions that enable the OpenEdge Adapter for Sonic ESB to process SOAP messages according to the needs of the OpenEdge component.
At run-time when the Sonic ESB Itinerary has a process step that involves executing an OpenEdge component, the OpenEdge Adapter for Sonic ESB uses the WSM file for the target component (service) to request that an OpenEdge Application Server associated with the service execute that service. The OpenEdge Adapter for Sonic ESB is also responsible for translating the initial SOAP message from Sonic ESB into the appropriate ABL to execute the target service, and for translating the resulting ABL after the service executes into the appropriate SOAP message for use by Sonic ESB as it continues to execute the business process itinerary.
OpenEdge Application Server

9. Supported AppServer Session Models
Session-free (recommended)
No session information between client & AppServer is maintained
AppServer runs in a state-free operating mode
Session-managed
Client to AppServer persistent connection maintained
AppServer runs in State-reset, State-aware or Stateless operation modes
The ABL procedures, functions or external procedures will execute at run time under the control of the OpenEdge Application Server.
The recommended development best practice is to use the AppServer Session-free model, as this best supports the underlying concepts of a Service Oriented Architecture (SOA) as well as the basic tenants of Sonic ESB.
There may be situations, especially with existing (legacy) code, where a persistent connection between the Client and AppServer is appropriate. So the Session-managed model is also supported although generally not recommended.

10. Unified Development Environment
OpenEdge Architect and Sonic Workbench are both based on Eclipse
Easy to configure a combined development environment in a single Eclipse instance
OpenEdge 10.1C and either Sonic 7.5 or 7.6
No switching between OpenEdge and Sonic
Single unified view of project resources
Add OpenEdge Architect plug-ins to Sonic Workbench
Create OpenEdge and Sonic projects
Specify automatic generation of ESB invocation files (.esboe files)
Specify location of invocation files in Sonic project
Modify propath of esbbroker1
Start dev_OpenEdge container

11. Demonstration: Unified Development Environment

12. Native Invocation Development Process
New in OpenEdge 10.1C
STEP 1: Create .esboe file for each ABL procedure
Annotate Source Code
Don’t Annotate
ProxyGen builds .esboe from r-code
OE Architect
Annotation Wizard
.esboe built on-compile or on-demand
Manually
Command line utility* to build .esboe
STEP 1: Create .esboe file for ABL procedure
OE Architect
Annotation Wizard
.esboe built on-compile or on-demand
STEP 2: .esboe file in Sonic project (automatic or import)
STEP 3: Drop .esboe onto Sonic Workbench Process Editor
STEP 4: Map ABL parameters to message parts
In general the development best practice is to annotate the source code to indicate what procedures are to be publicly exposed.
For 10.1C, you can use a new ABL Annotation Wizard in OpenEdge Architect to quickly annotate the code. For those that are not using OpenEdge Architect, the annotation syntax is published so that the annotations can be manually entered if desired. To generate the .esboe file, simply save the source code with the new annotations and the file is automatically generated. If working outside of OE Architect, compile manually to generate the .esboe file.
We are not requiring annotations in 10.1C (and likely future releases). For those that want to continue using the ProxyGen process, we support the generation of .esboe files from ProxyGen without any source code annotations.
Once you have an .esboe file, you carry out the remaining steps in Sonic Workbench:
The .esboe files are added to the Sonic Workbench environment, either automatically or by importing them.
To add a call to an OpenEdge component from a Sonic business process, drag & drop the associated .esboe file onto the Sonic process
Map the ABL parameters using the Sonic Process Editor mapping tool.
* OpenEdge Architect must be installed

13. Create .esboe File: Source Code Annotation
@openapi.openedge.export(type=“ESB”,ESBOEFilename=“%PROCNAME%”)
DEFINE INPUT PARAMETER ItemNumIn AS INTEGER NO-UNDO.
DEFINE OUTPUT PARAMETER DATASET FOR dsItemLocations.
FIND Sports2000.Item WHERE Sports2000.Item.Itemnum = ItemNumIn.
IF AVAILABLE(Item) THEN DO:
CREATE ttItem.
ASSIGN
ttItem.Itemnum = Sports2000.Item.Itemnum
ttItem.ItemName = Sports2000.Item.ItemName.
FOR EACH Sports2000.Bin WHERE Sports2000.Bin.Itemnum = ItemNumIn:
With the source code annotation method, each procedure that will be run from Sonic ESB is identified. At a minimum, one statement is added to the source code (as shown in the build). This can be accomplished one procedure at a time, or by selecting a set of procedures that you wish to apply the same annotation to.
There are a small set of annotation qualifiers that are available:
Type (Mandatory)- only type ESB is supported in this release.
esboeFileName (Optional)- name of the .esboe file (to override the default file naming).
executionMode (Optional) - default is Not Persistant, and can set to Persistant.
useReturnValue (Optional) - default is false, and can set to true to specify that a return string is generated.
writeDataSetBeforeImage (Optional) - default is false, and can set to true to write out before image data for ProDataSet parameters when they are serialized as XML.
Use wizard in OpenEdge Architect
Or, type in manually
Or, specify same information using ProxyGen

14. Create .esboe File: Several Methods Available
Annotate Source Code?
Yes (Declarative)
No (Non-Declarative)
Compile Source Code
r-Code
Run ProxyGen
.esboe
Add Annotations
Compile Source Code
.esboe
Annotation of the source code is the preferred method of declaring that a procedure will be used as part of a Sonic itinerary. Once the annotations have been added, either by using the Annotation Wizard or by entering manually, when the source is compiled, both the r-code (as usual) plus a new .esboe file is generated. These are used as inputs into Sonic Workbench when the procedure is to be used as part of a business process (itinerary).
Alternatively, developers can elect NOT to annotate their source code. In this case, they compile as usual to generate the r-code, and then they run ProxyGen to generate the .esboe file.
r-Code
Add ABL Call to Itinerary in Sonic Workbench

15. Demonstration: Source Code Annotation & Create .esboe File

16. Native Invocation Development Process
STEP 1: Create .esboe file for ABL procedure
Annotate Source Code
Don’t Annotate
ProxyGen builds .esboe from r-code
OE Architect
Annotation Wizard
.esboe built on-compile or on-demand
Manually
Command line utility* to build .esboe
STEP 3: Drop .esboe onto Sonic Workbench Process Editor
STEP 2: .esboe file in Sonic project (automatic or import)
STEP 3: Drop .esboe onto Sonic Workbench Process Editor
STEP 4: Map ABL parameters to message parts
At this point the .esboe file or files have been generated.
The .esboe files are automatically a part of the combined OpenEdge Architect and Sonic Workbench environments if that is how you have configured your installation. As an alternative, you can Import the .esboe files. Note that if you have a collection of .esboe files, you can combine them into a .XAR (zar) file similar to a zip file. Sonic WB knows how to import individual .esboe and also .XAR files.
Next you want to add an OpenEdge procedure call as part of a Sonic business process.
In Sonic Workbench, select the .esboe file for the ABL procedure that you would like to add to a business process step, and then drag and drop it onto the itinerary diagram in the Sonic WB Process Editor at the point in the process where you want to make the ABL call. You have the option to give the process step a more meaningful name and to do other high-level editing of the process step.
* OpenEdge Architect must be installed

17. Sonic Workbench Process Editor: Add ABL Process Step
Use the Sonic Workbench Process Editor to create a process and/or to enhance an existing process by adding a step to call your ABL procedure.
This example assumes an existing process that will examine the current message content to determine if the Country is the USA or not, and route the message to the appropriate form. We want to insert a step in the process to call an ABL procedure to lookup the Country. As discussed earlier, you simply drag and drop the .esboe file for the ABL procedure onto the design canvas at the location where you want to execute the procedure within the business process.

18. Demonstration: Sonic Workbench Process Editor

19. Native Invocation Development Process
STEP 1: Create .esboe file for ABL procedure
Annotate Source Code
Don’t Annotate
ProxyGen builds .esboe from r-code
OE Architect
Annotation Wizard
.esboe built on-compile or on-demand
Manually
Command line utility* to build .esboe
STEP 4: Map ABL parameters to message parts
Graphical mapping available
Use XPath to extract/insert simple types
Use message parts for TempTables/DataSets
STEP 2: .esboe files in Sonic project (automatic or import)
STEP 3: Drop .esboe onto Sonic Workbench Process Editor
STEP 4: Map ABL parameters to message parts
Finally, you need to map the OpenEdge procedure input and output parameters to the underlying Sonic business process message.
Use the Sonic Workbench Process Editor.
One method is to graphically connect the procedure parameters to the corresponding Sonic message parts.
Additional capability is available to have more control over simple data types using XPath, and for storing complex data types in message parts.
* OpenEdge Architect must be installed

20. Message Structure
Envelope
Header #0
Header #1
Body
Message
Payload

21. Mapping Message Parts: Request ABL
Use the existing Request/Response mapping capability in the Sonic Workbench Process Editor.
Here we’re mapping the initial/input message parts to the input parameters of the ABL procedure we are about to call.
Note that there is a lot of flexibility in getting the information out of the message header or body, including applying XPath expressions.
Flexible mapping capabilities

22. Mapping Message Parts: ABL Response
Next, graphically map the ABL output parameters that you are interested in propagating to the message parts of the resulting message. Again, there is additional flexibility provided to tailor exactly where in the resulting message the output data is placed.
You now have all of the information you need to test the process that calls the ABL procedure, and to then deploy it into a production environment.

23. Demonstration: Mapping Message Parts

24. Debugging and Deployment
Use scenarios in Sonic Workbench Process Editor to debug the business process
Deploy the business process, .esboe file and r-code
ABL is automatically executed when the business process runs
Sonic Workbench provides rich capabilities to test and debug an itinerary using scenarios. As a scenario is executed, the developer has full control over setting breakpoints and examining variables and status both locally and remotely.
Once the itinerary is working, it can be deployed into a production environment. The OpenEdge Adapter for Sonic ESB is part of the OE installation on the production machine. The developer / release engineer then deploys the Sonic itinerary, the .esboe file(s) and the r-code for the ABL procedures.
At run time, the itinerary is executed. When it reaches a step that involves the execution of ABL code, the OpenEdge Adapter for Sonic ESB carries out the defined mapping of message information to the input parameters of the ABL procedure, runs the ABL procedure on the AppServer, and then maps the output parameters as defined to the resulting message. This is all done automatically, guided by the .esboe file and the ABL parameter mapping done by the developer.

25. Demonstration: Debugging

26. Streamlined Process: p-code Drag & Drop
Drag & drop .p code onto Sonic itinerary
Annotations can still be captured and stored in the source code
A .esboe file is NOT generated or required
The procedure invocation information is stored “in-line” with the ESB process
Requires OE10.1C01 and Sonic 7.6, or higher

27. Demonstration: .p Code Drag & Drop

28. Native Invocation Methodology Benefits
Unified OpenEdge and Sonic development environment
Easy to expose ABL code as a service
Minimal technical knowledge needed
Basic use case is automated
Faster development
Optimized run-time performance (no SOAP)
.p Code drag & drop even faster!

29. Next Steps Get an evaluation copy of OpenEdge 10.1C and Sonic 7.6
Visit and click on the product tour and evaluation kits link

30. ?
Questions

31. Thank You