incubator-agila-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <>
Subject [Agila Wiki] Update of "AgilaBpelUserGuide" by MatthieuRiou
Date Sun, 22 May 2005 10:53:18 GMT
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Agila Wiki" for change notification.

The following page has been changed by MatthieuRiou:

New page:
= Agila BPEL User Guide =

== Introduction ==

It's very easy to see how Agila BPEL works without any development. We included everything
necessary in the default distribution to let you send messages yourself and to see how Agila
BPEL is reacting. By reading this guide, you will be more familiar with Agila BPEL web interfaces
and will have a much better idea of what can be done with a process engine (and more particularly
Agila BPEL).

Before starting, we would like to emphasize that we're not providing here a complete explanation
of WS-BPEL. That's outside of our scope, to learn more about WS-BPEL, see our WS-BPEL Guide.
However we're going to explain here in detail the description of an example process, that
should at least give you an idea of what a WS-BPEL document looks like.

== A process lifecycle - Theory ==

Let's describe how, generally speaking, a process is created, lives inside the engine and
finishes its execution, that should clarify some points.

 * First, you should have a description of your process in a formal XML description language.
Agila BPEL uses WS-BPEL but could, later on, support other des cription schemas if necessary.
How do you obtain this description ? If you're very courageous you can type it with your two
hands but if you don't like cumbersome tasks we recommend using a graphical interface like
XMLSpy, BPWS4J (by IBM) or anything that suits you. Agila BPEL development plan includes such
a tool but it shouldn't be implemented before a little while.
 * The process description file must then be deployed in the engine using the Agila BPEL Deployer.
The Deployer will create, from the description, necessary structures in the engine so that
your process can actually be executed.
 * Upon reception of an appropriate message (as defined in the process description), a new
process instance will be created. The process instance is the execution representation of
your process, a process being executed several times.
 * When more messages arrive aimed at the process instance that have been created, the instance
activities gets executed step by step until the instance is completed (or faulted). Depending
your process definition the engine can reply to messages, send new messages, invoke services,
wait for a specific date or deadline, ask the WorkList Manager for a Work Item creation...
 * When the process instance execution is finished, it is simply archived. and that's it !

So, as you can see, Agila BPEL is just receiving messages and reacting to those messages by
sending other messages. It also holds the information contained in all exchanged messages
that form the state of a process instance. Agila BPEL is therefore able to react according
to each execution's state.

== Learning by example ==

=== Business Case ===

The process we're going to use for demonstration is a classical example so you could already
be familiar with it. So let's say you are a bank granting loans. You have sales offices all
over the world who can create new customer contracts. You also have a web site and customers
can directly ask for a loan online for small amounts. But before accepting a contract with
a customer, some verifications are necessary. Those verifications are done using a risk assessment
system maintained by a third party and by having the customer's file checked by one of your
staff specialists who can undertake additional verifications.
So here is, step by step, the process that must be followed:

   1. A loan request is issued, either from your web site of from one of your agencies. This
request is made for a customer and for a certain amount.
   2. A risk assessment system must be contacted to check wether the risk associated with
the customer asking for the loan is high or low.
         1. If the loan amount is lower than $10,000 and the risk associated to the customer
is low, the loan is directly approved.
         2. Otherwise, the loan request must be examined by one of your loan specialists who
take the final decision.
   3. The response is sent to the customer.

This is a very simple process, however it has the merit to illustrate the major types of interaction
with Agila BPEL.

===  Creating necessary users, groups and roles ===

To simulate the action of a loan specialist, we will first create a new user and give him
the role he needs to examine loan requests.

Once Agila BPEL is running, open a web browser to http://localhost:8080/agila-web (replace
localhost with the server name or IP Agila BPEL is installed on and 8080 by the port Tomcat
is running on if you changed it). With a default installation, an administrator user is created
with username 'admin' and password 'admin'. Just use these credentials to log in.

The Administration menu is only visible to users having the 'admin' role. Other users only
see the General menu. Click on the 'Roles' element and 'New role'. You just need to give a
role name, just type 'loanmanager' here to create our manager role. Then click 'Create'. When
this is done, you will have to create a group of users. Just name it as you like, it doesn't
matter, but attribute it the 'loanmanager' role. Finally create a new user by giving it a
login and password (like 'petesmith' and 'pass') and select the group you just create for
the user. That's it!

Agila BPEL user structures uses the notion of groups and roles. Groups are made to reflect
your organizational structure and hierarchy, it usually match people titles. But as to what
people exactly do, this is handled by roles. Now your company may have its own way to cope
with users, groups and roles so your own component can be plugged in instead of using Agila
BPEL one.

===  Deploying the process description ===

Then you have to deploy the demonstration process in Agila BPEL engine so the process can
start being executed.

Choose the deployer item in the menu. There is a list of already deployed processes, WSDL
documents and resources (empty when you use Agila BPEL for the first time) and an area to
deploy new documents. Get the loan approval process web services definition and process description
files, they are available in Agila BPEL distribution in AGILA_BPEL_HOME/samples/exemple1 or
online for the process description and for web services definitions. Select and submit the
BPEL and the WSDL documents one after another (uncheck the validate checkbox). The loan approval
process should appear in the 'Already deployed processes' list and you can have a look at
deployed definitions by following the hyperlinks.

Agila BPEL lets you deploy general resources (basically XML schema definitions), WSDL documents
and WS-BPEL documents separately. The idea here is to be able to reuse elements defined in
other documents from their namespace. Just note that right now WSDL imports won't work so
you will still have to build your WSDL document by aggregating services definitions but this
feature should come shortly.

When a WSDL or a WS-BPEL document is deployed, Agila BPEL validates it to make sure the execution
will be okay (or at least as sure as possible). For your tests you may want to execute process
with having a really valid WSDL document (for example if you're not really invoking web services).
If so just uncheck the 'validate' checkbox and WSDL validation will be turned off. WS-BPEL
validation can't be turned off and is mandatory.

A given process can be deployed several times, each deployment will generate a new version,
process definitions are never physically deleted. If you have pending executions that aren't
finished yet, they will finish according to the original process version they've been created
on. New executions will be started using your new process description.

Now that the loan manager process has been deployed any incoming loan request message will
result in the creation of a new loan process execution.

===  Initiating the business transaction ===

In a real business interaction the initiating message would be sent by another service. In
our example, either from the web site application or from one of the agencies' software.

To simulate such an interaction, we already built an example message that could be sent by
a service and that you will send it manually. This initiating message is in a file located
in Agila BPEL distribution in AGILA_BPEL_HOME/samples/example1 named ask5000.xml , it's a
simple XML document. This message contains a new loan request of $5000 for a customer named
John Doe.

<?xml version="1.0" encoding="UTF-8"?>
<agila-msg xmlns="">

To send it to the engine, click the 'Send a message' menu item, select the ask5000.xml file
and submit. A new process execution (also called process instance) has been created and will
manage the loan request process for our new customer John Doe. The existence of this new instance
can be checked by using to the 'Instance' menu, a new instance should be listed with the customer's
name. Clicking on the 'Audit' link will take you to a detailed view that lets you see the
execution history of this instance.

You can come back to this view regularly to see how your process executions evolve.

=== Faking a service response ===

After the creation of the new process instance, Agila BPEL engine has sent a message to the
risk assessment service to require the risk associated with our new customer. This message
can be seen in the 'Sent messages' menu item (Note: sent messages are only retained in memory
so if you shutdown Agila BPEL, this list will be cleared. We also recommend to deactivate
this feature if you're using Agila BPEL in a non-development environment). It's very similar
to the first message (only the destination is different).

Now, you will have to provide the answer by sending a message that gives the risk assessment
for the the loan request of John Doe. The message is in a file named assessHighRisk.xml in
the same location as previous message. Here is its content:

<?xml version="1.0" encoding="UTF-8"?>
<agila-msg xmlns="">

As you probably guessed, the answer states that our new customer has a high loan risk.

===  Doing some work ===

When the risk is high, even if the customer requires less than $10000, the final decision
can't be made automatically and must be done by a loan specialist. Therefore, in response
to the high risk message, Agila BPEL has created a work item (a task) that a loan specialist
must complete. To see the work item , logout (in the 'General menu') and login again using
the loan manager profile you created (petesmith/pass). As the new user doesn't have the administration
rights, only the 'General' menu is visible.

When you select the WorkList item, one work item should appear in the loan manager's worklist.
When clicking on the 'View' link, more specific information is displayed. In our example,
the first name and last name of the user are provided (right now, it's simply formatted as
a XML tree but we're planning on improving that) but anything necessary for the loan manager
could be added.

To avoid having two persons in the same role completing the same work item at the same time
or even two persons doing the job twice without knowing it, a work item must be acquired before
it can be completed. Once a person acquired a work item, only him (or her) can complete it.
He can also choose to release it so that somebody else can acquire it again. If an unexpected
event occurs, an administrator (role admin) can also release work items. So acquire the work
item that has been created and the click again on the 'view' link.

Below the work item, a dynamically generated form lets the user provide his answer or the
output of the work he has accomplished. This form is generated from the message the engine
is expected in return of the work item, so when the process description is written, it's possible
to specify which information the user will have to provide.
Here, the only expected answer is wether the loan request is accepted or not. Just type yes
or no in the corresponding text field and click 'Complete'.

=== Finishing ===

Once the work item has been completed, the answer is sent to the service that initiated the
business transaction and the process instance finishes its execution. You can check the message
that has been sent by relogging as admin/admin and checking the 'Sent messages'. It should
look like:

<?xml version="1.0" encoding="UTF-8" ?>

In the 'Instance' screen, the process instance corresponding to John Doe's request should
be listed as terminated.

=== Conclusion ===

This simple example gave you a global view of all Agila BPEL functionalities and illustrates
how a process is executed. By changing the first name and last name of the customer, you can
try other executions and see how Agila BPEL is reacting (by construction of this process,
only one execution for each customer is possible).

Agila BPEL doesn't support all WS-BPEL structures yet but we believe it's already very functional.
Just don't forget that nothing has been 'hardcoded' to manage the process we just studied,
when the process is deployed, Agila BPEL just follows the description, analyze received messages
and reacts accordingly, all at runtime. This could give a lot of flexibility to any business
and very complex business interactions will be managed just the same way.

View raw message