9.2. Creating an Orchestration Diagram

  1. Select FileNewOther.
  2. Choose JBoss jBPM Process Definition from the Selection wizard.
  3. Save the process definition. Use a separate directory for each process definition to avoid confusion.
  4. Start to "drag-and-drop" items from the jBPM Integrated Development Environment 's menu palette into the Process Design view. You can switch between the design and source modes to check XML elements as you add them.
  5. Add the XML fragments that are needed for the integration.
  6. Before building the order process diagram, create and test the three services. These are ordinary ESB services and they are defined in the jboss-esb.xml file. An example configuration with service names and categories is shown below:
    <services>
      <service category="BPM_orchestration4_Starter_Service" 
      name="Starter_Service"
      description="BPM Orchestration Sample 4: Use this service to start a 
    process instance">
    			<!-- .... -->						
      </service>
      <service category="BPM_Orchestration4" name="IntakeService"
      description="IntakeService: transforms, massages, calculates priority">
    			<!-- .... -->
      </service>		
      <service category="BPM_Orchestration4" name="DiscountService"
        description="DiscountService">					
      </service>		
      <service category="BPM_Orchestration4" name="ShippingService"
        description="ShippingService">			
    			<!-- .... -->
      </service>		 	
    </services>
    
  7. Refer to these services by using either the EsbActionHandler or EsbNotifier action handler. (Choose the EsbActionHandler in cases where the JBoss Business Process Manager expects a response, and the EsbNotifier when none is required.)
  8. Now that the ESB services are known, drag the Start state node into the design view. A new process instance will begin at this node.
  9. Drag in a node and name it Intake Order.
  10. Connect the Start and the Intake Order nodes by selecting Transition from the menu and then clicking on each of them. An arrow connecting them will appear. It will be pointing towards the first Intake Order.
  11. Add the Service and Category names to the Intake Node. Select the Source view. You will be able to see the source code for the Intake Order node. It should look like this:
    <node name="Intake Order">
    	<transition name="" to="Review Order"></transition>
    </node>
    
  12. Add the EsbActionHandler class reference, followed by the sub-element configuration settings for the service category and name, BPM_Orchestration4 and the IntakeService. It should look like this:
    <node name="Intake Order">
    	<action name="esbAction" class=
    		"org.jboss.soa.esb.services.jbpm.actionhandlers.EsbActionHandler">
    			<esbCategoryName>BPM_Orchestration4</esbCategoryName>
    			<esbServiceName>IntakeService</esbServiceName>
    			<!-- async call of IntakeService -->
    	</action>
    <transition name="" to="Review Order"></transition>
    </node>
    
  13. Send some JBoss Business Process Manager context variables along with the service call using the following code. (In the example below, there is a variable named entireOrderAsXML which is to be set in the default position in the message body.)
    			
    <bpmToEsbVars>
    	<mapping bpm="entireOrderAsXML" esb="BODY_CONTENT" />
    </bpmToEsbVars>
    
    This will cause the XML-based contents of the entireOrderAsXML variable to end up in the body of the message. Now the IntakeService can access the message and process it by letting it flow through each action in the pipeline. When the last action is reached, the replyTo property is checked and the message is sent to the JBpmCallBack service.
    This makes a call back into the JBoss Business Process Manager, signaling the transition from the Intake Order node to the next one (in this case, Review Order).
  14. Next, send some variables from the message to the node. Note that entire objects can be sent, as long both contexts can load the object's class. To retain the ability to "map back" to the JBoss Business Process Manager, add an esbToEsbVars element:
    <node name="Intake Order">
    <action name="esbAction" class=
    "org.jboss.soa.esb.services.jbpm.actionhandlers.EsbActionHandler">
    <esbCategoryName>BPM_Orchestration4</esbCategoryName>
    <esbServiceName>IntakeService</esbServiceName>
    <bpmToEsbVars>
    <mapping bpm="entireOrderAsXML" esb="BODY_CONTENT" />
    </bpmToEsbVars>
    <esbToBpmVars>
    <mapping esb="body.entireOrderAsXML" bpm="entireOrderAsXML"/>
    <mapping esb="body.orderHeader" bpm="entireOrderAsObject" />
    <mapping esb="body.customer" bpm="entireCustomerAsObject" />
    <mapping esb="body.order_orderId" bpm="order_orderid" />
    <mapping esb="body.order_totalAmount" bpm="order_totalamount" />
    <mapping esb="body.order_orderPriority" bpm="order_priority" />
    <mapping esb="body.customer_firstName" bpm="customer_firstName" />
    <mapping esb="body.customer_lastName" bpm="customer_lastName" />
    <mapping esb="body.customer_status" bpm="customer_status" />
    </esbToBpmVars>
    </action>
    <transition name="" to="Review Order"></transition>
    </node>
    
    When this service returns, the following variables are then stored in the JBoss Business Process Manager's context:
    • entireOrderAsXML
    • entireOrderAsObject
    • entireCustomerAsObject
    In addition, for demonstration purposes, there are also some flattened variables:
    • order_orderid
    • order_totalAmount
    • order_priority
    • customer_firstName
    • customer_lastName
    • customer_status
  15. You must now review the order process manually. Add a task node with the task called Order Review. These jobs need to be performed by someone with the actor_iduser.
    Make sure the XML fragment looks like this:
    <task-node name="Review Order">
    <task name="Order Review">
    <assignment actor-id="user"></assignment>
    <controller>
    <variable name="customer_firstName"
    access="read,write,required"></variable>
    <variable name="customer_lastName" access="read,write,required">
    <variable name="customer_status" access="read"></variable>
    <variable name="order_totalamount" access="read"></variable>
    <variable name="order_priority" access="read"></variable>
    <variable name="order_orderid" access="read"></variable>
    <variable name="order_discount" access="read"></variable>
    <variable name="entireOrderAsXML" access="read"></variable>
    </controller>
    </task>
    <transition name="" to="Calculate Discount"></transition>
    </task-node>
    
  16. Create an XHTML data form to display these variables in a form in the jbpm-console.

    Note

    See the bpm_orchestration4 quick start's Review_Order.xhtml file for more information about this.
  17. Link this data form to the task node by adding these settings to the forms.xml file:
    <forms>
    <form task="Order Review" form="Review_Order.xhtml"/>
    <form task="Discount Review" form="Review_Order.xhtml"/>
    </forms>
    
  18. In this case, the same form is applied to two task nodes. There is a reference to the variables in the Review Order form as shown in the following sample code. (This, in turn, refers to the variables that are set in the JBoss Business Process Manager's context.)
    <jbpm:datacell>
    <f:facet name="header">
    <h:outputText value="customer_firstName"/>
    </f:facet>
    <h:inputText value="#{var['customer_firstName']}" />
    </jbpm:datacell>
    
  19. When the process reaches the Review Node, you can log into the jBPM Console and click on Tasks to see a list of items.
  20. Click on a task to examine it in detail. A form will appear. You can then update some of the values.
  21. Conclude by clicking Save and Close, at which point the process will move to the next node.
  22. This one is the Calculate Discount node. It is, once again, an ESB service node, the configuration file for which looks like this:
    <node name="Calculate Discount">
    <action name="esbAction" class="
    org.jboss.soa.esb.services.jbpm.actionhandlers.EsbActionHandler">
    <esbCategoryName>BPM_Orchestration4</esbCategoryName>
    <esbServiceName>DiscountService</esbServiceName>
    <bpmToEsbVars>
    <mapping bpm="entireCustomerAsObject" esb="customer" />
    <mapping bpm="entireOrderAsObject" esb="orderHeader" />
    <mapping bpm="entireOrderAsXML" esb="BODY_CONTENT" />
    </bpmToEsbVars>
    <esbToBpmVars>
    <mapping esb="order"
    bpm="entireOrderAsObject" />
    <mapping esb="body.order_orderDiscount" bpm="order_discount" />
    </esbToBpmVars>
    </action>
    <transition name="" to="Review Discount"></transition>
    </node>
    
    The service receives the customer, orderHeader and the entireOrderAsXML data. It then computes a discount. The response maps the body.order_orderDiscount value onto a JBoss Business Process Manager context variable called order_-discount. The process is signaled, which tells it to move to the Review Discount node.
  23. Review the discount, which is set to a value of 8.5. Click on Save and Close. The process will move to the Ship It node, which is also an ESB service.
    To circumvent the order process before the Ship It service completes, use the EsbNotifier action handler by attaching it to the outgoing transition as shown below:
    <node name="ShipIt">
    <transition name="ProcessingComplete" to="end">
    <action name="ShipItAction" class=
    "org.jboss.soa.esb.services.jbpm.actionhandlers.EsbNotifier">
    <esbCategoryName>BPM_Orchestration4</esbCategoryName>
    <esbServiceName>ShippingService</esbServiceName>
    <bpmToEsbVars>
    <mapping bpm="entireCustomerAsObject" esb="customer" />
    <mapping bpm="entireOrderAsObject" esb="orderHeader" />
    <mapping bpm="entireOrderAsXML" esb="entireOrderAsXML" />
    </bpmToEsbVars>
    </action>
    </transition>
    </node>
    
    After notifying the ShippingService, the order process moves to the end state and terminates. (The ShippingService itself may still be finishing.)
    In the bpm_orchestration4 quick start, the JBoss Rules engine is used to determine whether this order is to be shipped via the normal or the express method.