Agila BPEL User Guide
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
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:
- 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.
- A risk assessment system must be contacted to check wether the risk associated with the customer asking for the loan is high or low.
- If the loan amount is lower than $10,000 and the risk associated to the customer is low, the loan is directly approved.
- Otherwise, the loan request must be examined by one of your loan specialists who take the final decision.
- 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="http://www.smartcomps.org/agila/types/message/"> <partner>loaner</partner> <port>loanServicePT</port> <operation>request</operation> <message> <firstName>john</firstName> <lastName>doe</lastName> <amount>5000</amount> </message> </agila-msg>
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="http://www.smartcomps.org/agila/types/message/"> <partner>assessmentReceiver</partner> <port>riskReceiverPT</port> <operation>receiveRisk</operation> <message> <firstName>john</firstName> <lastName>doe</lastName> <level>high</level> </message> </agila-msg>
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'.
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" ?> <message> <firstName>john</firstName> <lastName>doe</lastName> <accept>yes</accept> </message>
In the 'Instance' screen, the process instance corresponding to John Doe's request should be listed as terminated.
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.