Access Keys:
Skip to content (Access Key - 0)

Workflow


BPEL Administrators Guide


This Administrator's Guide provides the information and procedures necessary for installing and deploying a BPEL-based workflow service. A BPEL-based workflow service has two main components: the WSRF wrapper and the workflow engine.

The BPEL Workflow Service is a WSRF implementation that wraps the BPEL engine as a WS Resource and exposes the available operations such as Create, Start, Pause, Restart, getStatus, getDetailedStatus, and getOutput for user-submitted workflows.

The ActiveBPEL Workflow Engine is what actually runs the workflows once they are submitted to the service.

Table of Contents


Before You Begin


Prerequisite Software


In order to install and run a BPEL-based workflow service, the following software must be installed first:

Make sure the JAVA_HOME, ANT_HOME, and GLOBUS_LOCATION environment variables are set and point to the correct respective locations of the downloaded software programs listed above.

Optionally, if you want to deploy services to Tomcat, you will need to download Tomcat 5.0.28. You can download this version from the following location: http://archive.apache.org/dist/tomcat/tomcat-5/v5.0.28/bin/

NOTE: Other versions of Tomcat will work, but they are not officially supported or tested by the caGrid team.

For a list of officially supported versions of the pre-requisite software, refer to the latest caGrid release documentation: http://www.cagrid.org/wiki/CaGrid:Software:Release:1.3#Prerequisites.
or at: CaGrid Software

Install and Configure Tomcat Container


In the list of prerequisite software is the optional use of Tomcat version 5.0.28.. If you are planning to use Tomcat, download the appropriate version as noted in the section above.

The sections below provide instructions for installing and configuring the Tomcat container for use.

Install Tomcat Container

After you have downloaded Tomcat, you must set the $CATALINA_HOME variable to point to the location of the downloaded Tomcat files. The command shown below provides an example:

%> export CATALINA_HOME=/Users/sulakhe/Desktop/jakarta-tomcat-5.0.28

Configure Tomcat Container

After verifying that both the $CATALINA_HOME and $GLOBUS_LOCATION variables are pointing to the correct locations, execute the following commands:

%> cd $GLOBUS_LOCATION 
%> ant \-f share/globus_wsrf_common/tomcat/tomcat.xml deployTomcat 
-Dtomcat.dir=$CATALINA_HOME


When complete, you should receive a BUILD SUCCESSFUL message as shown in the figure below.

For detailed instructions on configuring Tomcat with and without security, refer to Configure Tomcat

Start Tomcat Container

In order to download and configure the BPEL workflow service with Tomcat, you must start the Tomcat service. Use the following commands to start the Tomcat service:

%> cd $CATALINA_HOME/bin 
%> ./startup.sh

As the service starts, you should see lines similar to those shown in the figure below:

When finished, the Tomcat service is started. You can now validate that the service has started using the instructions below.

Validate Tomcat Installation and Service Startup

Once the Tomcat service has started, you can validate proper deployment and startup using your browser.

Assuming that you are using the default 8080 port, enter the following URL into your browser address bar:

http://localhost:8080/

If you are not using the default port, you must change the URL you enter to reflect the port you used to configure Tomcat:

https://localhost:<port_number>/

So for example, if you are using a secure port instead of the default port, the URL you enter may instead be:

https://localhost:8443/

When the URL opens, you should see the following page in your browser window:

Download and Deploy Workflow Service


Download BPEL Workflow Service


BPEL Workflow Service is distributed as one of the projects in the caGrid Software Release. caGrid Software can be downloaded using a variety of methods:

Using one of the three listed methods, download the latest release of the caGrid software. All three methods install the CaGrid software in a directory called "cagrid-1-0". From this point forward, we will refer to this location as $CAGRID_HOME.

Build BPEL Workflow Service


If you used the Automated Installer or Source Release methods identified in the previous step to download and build the current caGrid software release, you can skip this section. These methods automatically build the BPEL Workflow Service along with caGrid.

If you downloaded the CaGrid software from SVN using the caGrid SVN Install method, use the following steps to build the caGrid software along with the BPEL Workflow Service.

  1. From $CAGRID_HOME, cd to caGrid.
  2. Run 'ant all'.

This should build the complete CaGrid software release, including the BPEL Workflow Service.

Once the build is complete, you can find the BPEL Workflow Service at $CAGRID_HOME/caGrid/projects/workflow/WorkflowFactoryService.

From this point forward, we will refer to this location as $BWS_HOME .

Deploy Workflow Service


Once you have ActiveBPEL installed into the Tomcat container, you must deploy the BPEL workflow service that interacts with the BPEL workflow engine.

The next sections provide instructions for deploying the BPEL workflow service.

Edit the BPEL service.properties File


Before performing the actual deployment, you may need to modify the BPEL service.properties file, located in the $BWS_HOME directory.

Specifically, it is likely you will need to edit the abEndPoint property in the service.properties file, to make sure the port and protocol are correct for the way you are deploying the service.

For example, if you are deploying the service in a secure container, then you may need to change the protocol from http to https and the port from 8080 to 8443. Otherwise you can use the default port and protocol (http://localhost:8080/...).

The figure below shows an example of the change needed if you are deploying the service in a secure container:

When you are finished editing the service.properties file, you can deploy the BPEL workflow service as described in the next section.

Executing the Deployment


Running the ant deployTomcat command deploys the BPEL workflow service in the Tomcat container. Assuming that you have already set the $CATALINA_HOME environment variable, from within $BWS_HOME, run the following command:

%> ant deployTomcat

When finished, you should receive a Deploy Successful message. You can then validate the deployment using the instructions shown below.

If you have not set the $CATALINA_HOME environment variable, refer to the Install Tomcat Container section of this guide.

VALIDATION: Validate BPEL Workflow Service Deployment.

Validating the Deployment


After installing and deploying the BPEL workflow service, you should validate that the deployment has occurred properly.

If you are using the default port, enter the following URL into your Web browser:

http://localhost:8080/wsrf/services/cagrid/WorkflowFactoryService?wsdl/

If you are not using the default port, you must change the URL you enter to reflect the port you used to configure Tomcat:

https://localhost:<port_number>/wsrf/services/cagrid/WorkflowFactoryService?wsdl/

So for example, if you are using a secure port instead of the default port, the URL you enter may instead be:

https://localhost:8443/wsrf/services/cagrid/WorkflowFactoryService?wsdl/

When the URL opens, you should see the following page in your browser window:

If installation and deployment were successful, you will see the WSDL for the deployed service as shown in the figure above.

Install ActiveBPEL in Tomcat


The process of installing ActiveBPEL in Tomcat includes downloading the ActiveBPEL software from GForge, installing the software, and then opening the local ActiveBPEL web page, in order to create the required directories in the Tomcat webapp directory.

The sections that follow provide detailed instructions for performing each of these steps.

Download and Install ActiveBPEL


Use the following steps to download and install the ActiveBPEL software:

  1. Download the ActiveBPEL software from ActiveBPEL.
  2. Run install.sh

When the installation is complete, you will see a congratulations message on the screen, as shown in the figure above.

Open ActiveBPEL Admin Page


After installing the ActiveBPEL software, you must open the ActiveBPEL Admin page in a Web browser. This step is very important as it creates the required BPELAdmin directories in the Tomcat webapp directory.

To open the ActiveBPEL Admin page, enter the following URL into your Web browser:

http://localhost:8080/BpelAdmin/

If you are not using the default port, you must change the URL you enter to reflect the port you used to configure Tomcat:

https://localhost:<port_number>/BpelAdmin/

So for example, if you are using a secure port instead of the default port, the URL you enter may instead be:

https://localhost:8443/BpelAdmin/

When the URL opens, you should see the following page in your browser window:

The act of opening the browser page both creates the necessary directories and verifies the proper installation and configuration of ActiveBPEL. If there is a problem with the installation, you will likely receive a Page Not Found error in the browser. If this happens, retry the installation and configuration steps.

Enable logging in ActiveBPEL Engine


After opening the ActiveBPEL Admin page in the browser, you need to enable logging. On the Admin page, click on the "Configuration" link available on the left hand side. This should show and list of properties that you can set. Make sure the " Logging Enabled: " is checked.

VALIDATION: Validate ActiveBPEL Installation.

Adding Security to ActiveBPEL Admin page


When you deploy BPEL to the Tomcat container, the BPEL Admin can be accessed using the URL:

http://localhost:8080/BpelAdmin/

If you used a non-default port, the URL you use should reflect the appropriate port number and protocol. This is the same URL used to validate the ActiveBPEL deployment.

Since, however, this URL provides access to the Administration page for ActiveBPEL, you need to configure security for the page.

The sections below provide the steps necessary to manually configure security for the ActiveBPEL administration page. For instructions on autmatically configuring security, see Using Ant Targets to Add Security Context.

NOTE: Both the manual and automatic steps are provided here in order to educate users on the changes and steps required to configure security on the ActiveBPEL administration page. Both methods complete the same actions.

Step 1: Configure BpelAdmin web.xml File


The first step for configuring security is to edit the $CATALINA_HOME/webapps/BpelAdmin/WEB-INF/web.xml file.

Add the XML stub shown below to the end of the web.xml file (or replace any existing stub so that it appears as shown). When making the change, replace the bpel.admin.role shown here with admin for the administrative role.

<security-constraint>
   <web-resource-collection>
     <web-resource-name>BpelAdmin</web-resource-name>
     <url-pattern>/*</url-pattern>
   </web-resource-collection>
   <auth-constraint>
     <role-name>$[bpel.admin.role}</role-name>
   </auth-constraint>
</security-constraint>
<login-config>
   <auth-method>DIGEST</auth-method>
</login-config>
<security-role>
   <role-name>${bpel.admin.role}</role-name>
</security-role>

When finished, be sure to save your changes.

Step 2: Create BpelAdmin Context


The second step in configuring security adds an Amin Context (displayName and path to the BPEL Admin) and points to the file that will contain the "user" information.  This user information is added in the next step.

To complete these actions, you must edit the $CATALINA_HOME/conf/Catalina/localhost/BpelAdmin.xml file.

Open the BpelAdmin.xml file to see if the lines shown below exist in the file. If they do not, add them into the file.

<?xml version='1.0' encoding='utf-8'?> 
<Context reloadable="false"displayName="ActiveBPEL Administrative Console"path="/BpelAdmin">
  <Realm className="org.apache.catalina.realm.MemoryRealm"
        pathname="conf/BpelAdmin-users.xml"/>
</Context>

If the above lines already exist in the file, ignore this step and move on to Step 3.

Step 3: Create BpelAdmin users


In the first step Configure BpelAdmin Web.xml file, you added an admin role (bpel.admin.role) called admin to the system. In this step, you will add login credentials for the admin user.
This is done by adding the appropriate information into the file $CATALINA_HOME/conf/BpelAdmin-users.xml.

Below is an example of how this fie should look. Replace the changeMe entries with an appropriate username and password for the admin user.

<tomcat-users>
 <user name="changeMe"
       password="changeMe"
       roles="admin"/>
</tomcat-users>

The value entered for "roles" must match the bpel.admin.role you entered in Step 1. If you followed the instructions provided here, that role is called admin.

NOTE: You can add multiple administrative users using Step 1 and Step 3 of these procedures. Edit the BpelAdmin web.xml file to create multiple role names, and then edit the BpelAdmin-users.xml file to create usernames and passwords for the additional role names.

Using Ant Targets to Automatically Add Security Context


Once you understand how the security context is being added to the ActiveBPEL administrative page, you can use the available Ant targets to add the security context automatically.

NOTE: This step is optional and should be followed only if the above three steps to manually add the security context were not performed.

The BPEL Workflow Service provides ant targets that allow you to automatically add security context to the ActiveBPEL administration page. These ant targets reside in the dev-buid.xml file.

Before running the ant targets, however, you must set the username and password properties in the dev-buid.xml file, so that the targets can assign the login credentials when the targets are run.

  1. Open the dev-build.xml file for editing.
  2. Scroll to the end of the file and find the ant target entry for create-bpel-admin-users.
  3. Within the create-bpel-admin-users entry, edit the bpel.admin.username and bpel.admin.password properties, changing them to the username and password values you want to use for administrative login.

The figure below shows this section of the dev-build.xml file, including the default value of "changeMe" for these properties.

Be sure to save your changes when you are finished.

Once you have configured the username and password for the admin login, from $BWS_HOME you can run the following ant targets:

  • ant configure-bpel-admin-web-xml
  • ant create-bpel-admin-context
  • ant create-bpel-admin-users

Verify Addition of ActiveBPEL Security Context


When you are finished configuring security, regardless of whether you used the manual steps or the automated process, you should verify that the security context has been added to your ActiveBPEL installation.

You can easily verify the existence of security on the Admin page by opening the following URL:

http://localhost:8080/BpelAdmin/

If you used a non-default port, the URL you use should reflect the appropriate port number and protocol. This is the same URL used to validate the ActiveBPEL deployment.

The ActiveBPEL administration web page should appear as it did before, however now it should prompt you to enter an Admin User Name and Password in order to proceed. The figure below provides and example of the authentication prompt.

Enter the username and password you provided for the admin login to be sure the system accepts the values you provided during configuration.  If you cannot log in using those credentials, retry the steps and be careful to note the value entries you use.

Validating the Installation


This section reiterates the validation steps for the actions performed in this guide. This information is provided simply as a reference. If you have already validated each step as it was performed, you may not need to re-validate your configuration.

Validate Tomcat Installation


After installing the Tomcat container and setting the variable $CATALINA_HOME, start the container as follows:

In order to verify the Tomcat installation, you must start the Tomcat service (if it is not already started). If necessary, use the following commands to start the Tomcat service:

%> cd $CATALINA_HOME/bin 
%> ./startup.sh

As the service starts, you should see lines similar to those shown in the figure below:

When finished, the Tomcat service is started. Once the Tomcat service has started, you can validate proper deployment and startup using your browser.

Assuming that you are using the default 8080 port, enter the following URL into your browser address bar:

http://localhost:8080/

If you are not using the default port, you must change the URL you enter to reflect the port you used to configure Tomcat:

https://localhost:<port_number>/

So for example, if you are using a secure port instead of the default port, the URL you enter may instead be:

https://localhost:8443/

When the URL opens, you should see the following page in your browser window:

Validate ActiveBPEL Deployment


Validating ActiveBPEL deployment is done when the ActiveBPEL administrative page opens in a Web browser. To open the ActiveBPEL Admin page, enter the following URL into your Web browser:

http://localhost:8080/BpelAdmin/

If you are not using the default port, you must change the URL you enter to reflect the port you used to configure Tomcat:

https://localhost:<port_number>/BpelAdmin/

So for example, if you are using a secure port instead of the default port, the URL you enter may instead be:

https://localhost:8443/BpelAdmin/

When the URL opens, you should see the following page in your browser window:

The act of opening the browser verifies the proper installation and configuration of ActiveBPEL. If you configured a security context for your ActiveBPEL installation, you should also be prompted to enter the administrative login credentials you configured.

If there is a problem with the installation, you will likely receive a Page Not Found error in the browser, or you may not receive the administrative authentication prompt. If either of these things happens, retry the installation and configuration steps.

Validate BPEL Workflow Service Deployment


After installing and deploying the BPEL workflow service, you should validate that the deployment has occurred properly.

If you are using the default port, enter the following URL into your Web browser:

http://localhost:8080/wsrf/services/cagrid/WorkflowFactoryService?wsdl/

If you are not using the default port, you must change the URL you enter to reflect the port you used to configure Tomcat:

https://localhost:<port_number>/wsrf/services/cagrid/WorkflowFactoryService?wsdl/

So for example, if you are using a secure port instead of the default port, the URL you enter may instead be:

https://localhost:8443/wsrf/services/cagrid/WorkflowFactoryService?wsdl/

When the URL opens, you should see the following page in your browser window:

If installation and deployment were successful, you will see the WSDL for the deployed service as shown in the figure above.

Validating the Installation with a Test workflow


Prerequisites.

Make sure you performed the following steps in the same order:

  1. Installed the Prerequisite Software
  2. Installed the latest Tomcat container
  3. Installed the Workflow service
  4. Installed ActiveBPEL
  5. Started the Tomcat Container

Launch the Client GUI

From the BWS_HOME directory (the BPEL Workflow service directory), run:

ant ui

Once the GUI is launched click on Window -> Preferences Menu option. Browse to the WorkflowFactoryService(s) endpoint option and make sure it points to the Workflow service that needs to be validated.Use Add/Remove buttons to add new Workflow services endpoints. Use the Move up/Decrease keys to move the endpoint up and down.

Submitting a Workflow

Click on "Submit Workflow" Button and the following window will open. The user can enter the path to the BPEL document inside the BPEL File text field or the user can browse to the location of the BPEL document. Select Test1.bpel workflow document that is under WorkflowFactoryService (BWS_HOME) folder.

The workflow name should be the name of the BPEL doc (Test1 in this case) . Once the user is done with having valid values for both the text fields, press Add Partner Links button.

Adding PartnerLinks

When this button is presses the following GUI opens. This GUI is used to enter Endpoints of the services taking part in this workflow. In this example we have hosted a service at http://140.254.126.41:8080 and this one service is invoked twice in the workflow. Enter appropriate values to the fields in the PartnerLinkFrame GUI. For this test the values are as follows:

Select Type: Static
Service Endpoint: http://140.254.126.41:8080/wsrf/services/cagrid/WorkflowTestService1
WSDL Location : http://140.254.126.41:8080/wsrf/share/schema/WorkflowTestService1/WorkflowTestService1.wsdl
Namespace: http://sample1.tests.workflow.cagrid.nci.nih.gov/WorkflowTestService1

Click Add.

Click Close.

Submitting the Workflow

Now you are ready to submit the Workflow. Click on Submit.This would submit the workflow to a pre-configured Workflow Factory Service. After this step the BPEL document is validated and submitted to the Workflow Engine. If there are no errors the Status is changed from Pending - > Submitted.

Execution of the Workflow

The next step is to execute the submitted workflow with some input. In the current implementation the user has to paste the input XML in to the text area and press the Start button. If the workflow is started without problems then the Status is changed to Active.

Copy the following XML blob into the input XML Text area:

<ns1:InvokeRequest xmlns:ns1="http://sample1.tests.workflow.cagrid.nci.nih.gov/WorkflowTestService1"><ns1:invokeInput>Test</ns1:invokeInput></ns1:InvokeRequest>

Click Start. This will Start the workflow and change the status from Submitted to Active.

Querying for Status / Getting Workflow Output

Press the Get Status button and if the status is different from the existing status that is on the left hand corner of the GUI, the status changes to the latest status.

Getting Workflow Output: Press the Get Status button and if the status of workflow is Done the workflow output is displayed in the output text area.

Getting Detailed Status

If you submit a long workflow you would like to see which portion of Workflow is currently being executed. Press the Get Details button to see where the current workflow execution is taking place. The GUI displays XPath expression of the node in Workflow Document and its status.

Congratulations! You have successfully installed, deployed and tested a BPEL-based Workflow Service.

Last edited by
Sarah Honacki (1286 days ago)
Adaptavist Theme Builder Powered by Atlassian Confluence