Preparing for Process Deployment

Before deploying a business process in the WSO2 BPS, all relevant deployment artifacts need to be bundled in a zip file. At the minimum, the zip should contain

• The deployment descriptor
• One or more process definitions (BPEL), WSDL and XSDs

Additionally, the zip file can also contain other files such as SVGs or XSLs.

Deployment Descriptor

The deployment descriptor is a file named deploy.xml which resides at the root of the zip file. During deployment, the process engine loads all documents from this file. Loading documents allows it to reference processes, service and schema definitions using fully-qualified names, and import based on namespaces instead of locations. WSO2 BPS and Apache ODE use deploy.xml to configure one or several processes to use specific services.

The deploy.xml file configures one or more processes to use specific services. For each process, deploy.xml must supply binding information for partner links to concrete WSDL services.

Every partner link used with a <receive/> activity must be matched with a <provide/> element, and every partner link used in an <invoke/> activity must be matched with an <invoke/> element in the deploy.xml, unless that partnerLink has initializePartnerRole="false". Without a deploy.xml, a BPEL engine cannot determine the concrete-level details of the partner services. In the deploy.xml, the <service/> element determines the concrete-level details of all partner services that interact with the BPEL process.

An example of a deploy.xml configuration is shown below:

<?xml version="1.0" encoding="UTF-8"?>
<deploy xmlns="http://www.apache.org/ode/schemas/dd/2007/03" xmlns:FunctionProcess.bpel="http://FunctionProcess.bpel" 
        xmlns:FunctionProcessService.wsdl="http://FunctionProcessService.wsdl" xmlns:AdderService.wsdl="http://AdderService.wsdl" 
        xmlns:MultiplierService.wsdl="http://MultiplierService.wsdl" xmlns:SquareService.wsdl="http://SquareService.wsdl">
  <process name="FunctionProcess.bpel:FunctionProcess">
    <process-events generate="all"/>
    <provide partnerLink="FunctionProcessPartnerLink">
      <service name="FunctionProcessService.wsdl:FunctionProcessServiceService" port="FunctionProcessServicePort"/>
    </provide>
    <invoke partnerLink="SquarePartnerLink">
      <service name="SquareService.wsdl:SquareService" port="SquareServiceSOAP11port_http"/>
    </invoke>
    <invoke partnerLink="MultiplierPartnerLink">
      <service name="MultiplierService.wsdl:MultiplierService" port="MultiplierServiceSOAP11port_http"/>
    </invoke>
    <invoke partnerLink="AdderPartnerLink">
      <service name="AdderService.wsdl:AdderService" port="AdderServiceSOAP11port_http"/>
    </invoke>
  </process>
</deploy>

Note that, in the above example, every process and service is namespace-qualified, and the locations of each .bpel or .wsdl are not mentioned. The deploy.xml supplies binding information for each partnerLink, to create WSDL services with the <service/> element for each <provide/> and <invoke/> element. During the deployment of a process in the BPEL engine, it loads all required documents from the deployment descriptor.

Formal Definition

The XML schema describing the deployment descriptor is available here. The root element, deploy, contains a list of all deployed processes from the deployment directory:

<deploy><process ...>*
 { other elements }
 </process></deploy>

Each process is identified by its qualified name and specifies bindings for provided and invoked services:

<process name = QName fileName = String? bpel11wsdlFileName = String? >
 (<provide> | <invoke>)*
 { other elements }
</process>

Each process element must provide a name attribute with the qualified name of the process. Optionally, a fileName attribute can be used to specify the location of the BPEL process definition (the .bpel file). The fileName attribute does not need to be provided unless non-standard compilation options are used or the bpel11wsdlFileName attribute is used to specify a WSDL document for a BPEL 1.1 process.

Each <process> element must enumerate the services provided by the process and bind each service to an endpoint. This is done through <provide> elements, which associate partnerLinks with endpoints:

<providepartnerLink=NCName><service name = QName port = NCName?></provide>

 For example, a simple process that will only be invoked will typically use a deploy.xml configuration similar to the following:

<deploy xmlns="http://www.apache.org/ode/schemas/dd/2007/03"xmlns:pns="http://ode/bpel/unit-test" xmlns:wns="http://ode/bpel/unit-test.wsdl">   
    <processname="pns:HelloWorld2">
       <active>true</active>
       <providepartnerLink="helloPartnerLink">
           <servicename="wns:HelloService"port="HelloPort"/>
       </provide>
    </process>
</deploy>

The complete example can be downloaded from here.

A deployment including two processes typically look as follows:

<?xmlversion="1.0"encoding="UTF-8"?>
<deploy xmlns="http://www.apache.org/ode/schemas/dd/2007/03" xmlns:wns="http://wso2.org/bps/samples/LoanService" xmlns:dins="http://wso2.org/bps/samples/DILoanService" xmlns:xkns="http://wso2.org/bps/samples/XKLoanService">
    <processname="dins:DILoanService">
       <active>true</active>
       <providepartnerLink="LoanServicePL">
           <servicename="wns:DILoanService"port="LoanServicePort"/>
       </provide>
       <invokepartnerLink="LoanServicePL">
           <servicename="wns:LoanServiceCallback"port="LoanServiceCallbackPort"/>
       </invoke>
    </process>

    <processname="xkns:XKLoanService">
       <active>true</active>
       <providepartnerLink="XKLoanServicePL">
           <servicename="wns:XKLoanService"port="LoanServicePort"/>
       </provide>
       <invokepartnerLink="XKLoanServicePL">
           <servicename="wns:LoanServiceCallback"port="LoanServiceCallbackPort"/>
       </invoke>
    </process>
</deploy>

Download the complete example from here.

Process Container Structure

In both WSO2 BPS and Apache ODE, the exact same flat file structure is used for a process container. XSDs may be contained in directories inside the process container. For example, the structure of the "FunctionProcess" is shown below.

FunctionProcess
       |->AdderService.wsdl
       |->deploy.xml
       |->FunctionProcess.bpel
       |->FunctionProcessService.wsdl
       |->MultiplierService.wsdl
       |->SquareService.wsdl