Writing your first BPEL process

Ensure that the Oracle SOA Suite has started (as described in the previously mentioned installation guide) and start JDeveloper. When you start JDeveloper for the first time, it will prompt you for a developer role, as shown in the following screenshot:

JDeveloper has a number of different developer roles that limit the technology choices available to the developer. Choose the Default Role to get access to all JDeveloper functionality. This is needed to access the SOA Suite functionality.

After selecting the role, we are offered a Tip of the Day to tell us about a feature of JDeveloper. After dismissing the Tip of the Day, we are presented with a blank JDeveloper workspace.

The top-left-hand window is the Application Navigator, which lists all the applications that we are working on (it is currently empty as we have not yet defined any). Within JDeveloper, an application is a grouping of one or more related projects. A Project is a collection of related components that make up a deployable resource (for example, an SCA Assembly, Java application, web service, and so on).

Within the context of the SOA Suite, each SCA Assembly is defined within its own project, with an application being a collection of related SCA Assemblies.

On the opposite side of the screen to the Application Navigator tab is the Resource Palette, which contains the My Catalogs tab to hold resources for use in composites and the IDE Connections tab. If we click on this it will list the types of connections we can define to JDeveloper. A connection allows us to define and manage links to external resources such as databases, application servers, and rules engines.

Once defined, we can expand a connection to inspect the content of an external resource, which can then be used to create or edit components that utilize the resource. For example, you can use a database connection to create and configure a database adapter to expose a database table as a web service.

Connections also allow us to deploy projects from JDeveloper to an external resource. If you haven't done so already, then you will need to define a connection to the application server (as described in the installation guide) because we will need this to deploy our SCA Assemblies from within JDeveloper.

The connection to the application server is used to connect to the management interfaces in the target container. We can use it to browse deployed applications, change the status of deployed composites, or as we will do here, deploy new composites to our container.

The main window within JDeveloper is used to edit the artifact that we are currently working on (for example, BPEL Process, XSLT Transformation, Java code, and so on). The top of this window contains a tab for each resource we have open, allowing you to quickly switch between them.

At the moment, the only artifact that we have opened is the Start Page, which provides links to various documents on JDeveloper.

The bottom-left-hand corner contains the Structure window. The content of this depends on the resource we are currently working on.

Creating an application

Within JDeveloper, an application is the main container for our work. It consists of a directory where all our application projects will be created.

So, before we can create our Echo SCA Assembly, we must create the application to which it will belong. Within the Applications Navigator tab in JDeveloper, click on the New Application… item.

This will launch the Create SOA Application dialog, as shown in the preceding screenshot.

Give the application an appropriate name like SoaSuiteBook11gChapter2.

We can specify the top-level directory in which we want to create our applications. By default, JDeveloper will set it to the following:

<JDEVELOPER_HOME>\ mywork\<Application Name>

Normally, we would specify a directory that's not under JDEVELOPER_HOME, as this makes it simpler to upgrade to future releases of JDeveloper.

In addition, you can specify an Application Template. For SOA projects, select SOA Application template, and click on the Next button.

Next, JDeveloper will prompt us for the details of a new SOA project.

Creating an SOA project

We provide a name for our project such as EchoComposite and select the technologies we desire to be available in the project. In this case, we leave the default SOA technology selected. The project will be created in a directory that, by default, has the same name as the project and is located under the application directory. These settings can be changed.

Clicking on Next will give us the opportunity to configure our new composite by selecting some initial components. Select Composite With BPEL to create a new Assembly with a BPEL process, as shown in the next screenshot:

SOA project composite templates

We have a number of different templates available to us. Apart from the Empty Composite template, they all populate the composite with an initial component. This may be a BPEL component, a Business Rule component, a Human Task, or a Mediator component. The Composite From Oracle BPA Blueprint is used to import a process from the Oracle BPA Suite and generate it as a BPEL component within the composite.

It is possible to create an Empty Composite and then add the components directly to the composite, so if you choose the wrong template and start working with it, you can always enhance it by adding more components. Even the Empty Composite is not really empty, as it includes all the initial files you need to start building your own composite.

Creating a BPEL process

Clicking Finish will launch the Create BPEL Process wizard, as shown in the following screenshot:

Replace the process with a sensible Name like EchoProcess and select a template of the type Synchronous BPEL Process and click OK. JDeveloper will create a skeleton BPEL Process and a corresponding WSDL that describes the web service implemented by our process. This process will be wrapped in an SCA Assembly.

Note

BPEL process templates cover the different ways in which a client may interact with the process. A Define Service Later template is just the process definition and will be used when we want to have complete control over the types of interfaces the process exposes, we can think of this as an empty BPEL process template. An Asynchronous BPEL Process template is used when we send a one-way message to a process, and then later on we send a one-way message from the process to the caller. This type of interaction is good for processes that run for a long time. A Synchronous BPEL Process is one in which we have a request/reply interaction style. The client sends in a request message and then blocks waiting for the process to provide a reply. This type of interaction is good for processes that need to return an immediate result. A One Way BPEL Process simply receives a one-way input message but no reply is expected. This is useful when we initiate some interaction that will initiate a number of other activities. We may also create a BPEL process that implements a specific interface defined in WSDL by using the Base on a WSDL template. Finally, we may have a BPEL process that is activated when a specific event is generated by the Event Delivery Network (see Chapter 8, Using Business Events) using the Subscribe to Events template.

If we look at the process that JDeveloper has created (as shown in the following screenshot), we can see that in the center is the process itself, which contains the activities to be carried out. At the moment, it just contains an initial activity for receiving a request and a corresponding activity for sending a response.

Either side of the process we have a swim lane containing Partner Links that represent either the caller of our process, as is the case with the echoprocess_client partner links, or services that our BPEL process calls out to. At the moment this is empty as we haven't defined any external references that we use within our BPEL process. Notice also that we don't currently have any content between receiving the call and replying; our process is empty and does nothing.

The Component Palette window (to the right of our process window in the preceding screenshot) lists all the BPEL Activities and Components that we can use within our process. To use any of these, we have to simply drag-and-drop them onto the appropriate place within our process.

If you click on the BPEL Services drop-down, you also have the option of selecting services which we use whenever we need to call out to an external system.

Getting back to our skeleton process, we can see that it consists of two activities; receiveInput and replyOutput. In addition it has two variables, inputVariable and outputVariable, which were created as part of our skeleton process.

The first activity is used to receive the initial request from the client invoking our BPEL process; when this request is received it will populate the variable inputVariable with the content of the request.

The last activity is used to send a response back to the client, and the content of this response will contain the content of outputVariable.

For the purpose of our simple EchoProcess we just need to copy the content of the input variable to the output variable.

Assigning values to variables

In BPEL, the <assign> activity is used to update the values of variables with new data. The <assign> activity typically consists of one or more copy operations. Each copy consists of a target variable, that is, the variable that you wish to assign a value to and a source, which can either be another variable or an XPath expression.

To insert an Assign activity, drag one from the Component Palette on to our BPEL process at the point just after the receiveInput activity, as shown in the following screenshot:

To configure the Assign activity, double-click on it to open up its configuration window. Click on the green cross to access a menu and select Copy Operation…, as shown in the next screenshot:

This will present us with the Create Copy Operation window, as shown in the following screenshot:

On the left-hand side, we specify the From variable, that is, where we want to copy from. For our process, we want to copy the content of our input variable to our output variable. So expand inputVariable and select /client:process/client:input, as shown in the preceding screenshot.

On the right-hand side, we specify the To variable, that is, where we want to copy to. So expand outputVariable and select /client:processResponse/client:result.

Once you've done this, click OK and then OK again to close the Assign window.

Deploying the process

This completes our process, so click on the Save All icon (the fourth icon along, in the top-left-hand corner of JDeveloper) to save our work.

Note

As a BPEL project is made up of multiple files, we typically use Save All to ensure that all modifications are updated at the same time.

Our process is now ready to be deployed. Before doing this, make sure the SOA Suite is running and that within JDeveloper we have defined an Application Server connection (as described in the installation guide).

To deploy the process, right-click on our EchoComposite project and then select Deploy | EchoComposite | to MyApplicationServerConnection.

This will bring up the SOA Deployment Configuration Dialog. This dialog allows us to specify the target servers onto which we wish to deploy the composite. We may also specify a Revision ID for the composite to differentiate it from other deployed versions of the composite. If a revision with the same ID already exists, then it may be replaced by specifying the Overwrite any existing composites with the same revision ID option.

Clicking OK will begin the build and deployment of the composite. JDeveloper will open up a window below our process containing five tabs: Messages, Feedback, BPEL, Deployment, and SOA, to which it outputs the status of the deployment process.

During the build, the SOA tab will indicate if the build was successful, and assuming it was, then an Authorization Request window will pop up requesting credentials for the application server.

On completion of the build process, the Deployment tab should state Successfully deployed archive…., as shown in the following screenshot:

If you don't get this message, then check the log windows for details of the error and fix it accordingly.

Testing the BPEL process

Now that our process has been deployed, the next step is to run it. A simple way to do this is to initiate a test instance using the Enterprise Manager (EM) console, which is the web-based management console for SOA Suite.

To access the EM console, open up a browser and enter the following URL:

http://<hostname>:<port>/em

This will bring up the login screen for the EM console. Log in as weblogic. This will take us to the EM console dashboard, as shown in the following screenshot:

The Dashboard provides us with a summary report on the Fusion Middleware domain. On the left-hand side we have a list of management areas and on the right we have summaries of application deployments, including our EchoComposite under the SOA tab.

From here, click on the composite name, that is, EchoComposite. This will take us to the Dashboard screen for our composite. From here we can see the number of completed and currently executing composite instances.

At the top of the Dashboard there is a Test button that allows us to execute a composite test. Pressing this button brings up the Test Web Service page, as shown in the following screenshot:

When we created our process, JDeveloper automatically created a WSDL file which contained the single operation (that is, process). However, it's quite common to define processes that have multiple operations, as we will see later on in the book.

The Operation drop-down list allows us to specify which operation we want to invoke. In our case, it's automatically defaulted to process.

When you select the operation to invoke, the console will generate an HTML form with a field for each element in the message payload of the operation (as defined by the WSDL for the process). Here we can enter into each field the value that we want to submit.

For operations with large message payloads it can be simpler to just enter the XML source. If you select the XML View drop-down list the console will replace the form with a free text area with a skeleton XML fragment into which we can insert the required values.

To execute a test instance of our composite, enter some text in the input field and click Test Web Service. This will cause the console to generate a SOAP message and use it to invoke our Echo process.

Upon successful execution of the process, our test page will be updated to show the result which displays the response returned by our process. Here we can see that the result element contains our original input string, as shown in the following screenshot:

If we expand the SOA and soa-infra items on the left-hand side of the page, we will arrive back at the dashboard for the EchoComposite. Clicking on a completed instance will give us a summary of the composite. From here we can see the components that make up our composite. In this case, the composite consists of a single BPEL process.

Clicking on the BPEL process takes us to an audit record of the instance. We can expand the tree view to see details of individual operations like the message sent by replyOutput.

Clicking on the Flow tab will display a graphical representation of the activities within the BPEL process.

Clicking on any of the activities in the audit trail will pop up a window displaying details of the actions performed by that activity. In the following screenshot, we can see details of the message sent by the replyOutput activity:

This completes development of our first BPEL process. The next step is to call it via the Mediator. This will give us the option of transforming the input into the format we desire and of routing to different components based on the input content.

Adding a Mediator

By selecting the composite.xml tab in JDeveloper, we can see the outline of the Assembly that we have created for the BPEL process. We can add a Mediator to this by dragging it from the Component Palette.

Dragging the Mediator Component will cause a dialog to be displayed requesting a Name and Template for the Mediator.

If we select the Define Interface Later template, then we can click OK to add a Mediator to our Assembly. Defining the interface later will allow us to define the interface by wiring it to a service. Note that the types of interface templates are the same as the ones we saw for our BPEL process.

We want to have the Mediator use the same interface as the BPEL process. To rewire the composite to use a Mediator, we first delete the line joining the EchoProcess in the Exposed Services swimlane to the BPEL process by right-clicking on the line and selecting Delete.

We can now wire the EchoProcess service to the input of the Mediator by clicking on the chevron in the top-right corner of the exposed service and dragging it onto the connection point on the left-hand side of the Mediator.

Now wire the Mediator to the BPEL process by dragging the yellow arrow on the Mediator onto the blue chevron on the BPEL process.

We have now configured the Mediator to accept the same interface as the BPEL process and wired the Mediator to forward all messages onto the BPEL process. The default behavior of the Mediator, if it has no explicit rules, is to route the input request to the outbound request and then route the response, if any, from the target to the client.

We can now deploy and test the Assembly containing the Mediator in the same way that we deployed and tested the Assembly containing the BPEL process.

Using the Service Bus

In preparation for this, we will need the URL for the WSDL of our process. To obtain this, from the EM Dashboard, click on the EchoComposite Assembly, and then the connector icon to the right of the Settings button. This will display a link for the WSDL location and Endpoint, as shown in the following screenshot: