Injecting a Business Service Event

You can inject data to a business service multiple times while it is in progress, regardless of whether the flow from any previous occurrence is still in progress.

You can use an event handler to do so. An event handler is a catch intermediate event with no specific trigger and incoming flow that can be triggered by an external client application using the BPM API. Note that the event handler does not have to happen for the business service to complete.

The example here illustrates injecting a business service event. It involves listing all the deployed business services, starting a business service, and while it is running, injecting a business event.

Injecting a Business Service Event

The following step-by-step descriptions correspond to the numbered steps in the illustration above. Note that the descriptions are from a web service operation point of view, and provide an example of performing the operations using the web service API (SOAP). (For an equivalent example using the Service Connector API (Java), see Injecting a Business Service Event — Service Connector API Example (Java).)

Procedure

  1. Find out the list of deployed business services by calling the listBusinessServices operation. This operation returns the module version number, which is required as an input when calling the startBusinessService operation. 
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:bus="http://business.api.busserv.n2.tibco.com">
   <soapenv:Header/>
   <soapenv:Body>
      <bus:listBusinessServices getTotalCount="true" numberOfItems="10" startPosition="0">
         <!--Optional:-->
         <includeFormalParameters>true</includeFormalParameters>
      </bus:listBusinessServices>
   </soapenv:Body>
</soapenv:Envelope
    		 
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <listBusinessServicesResponse xmlns="http://business.api.busserv.n2.tibco.com">
         <startPosition xmlns="">0</startPosition>
         <totalItems xmlns="">1</totalItems>
         <businessCategory name="EventHandler" xmlns="">
            <ChildBusinessCategory name="EventHandler">
               <BusinessServiceTemplate hasFormalParameters="true" moduleName="/EventHandler/Process Packages/EventHandler.xpdl" processName="EventHandlerProcess" version="1.0.0.201108111140"/>
               <BusinessServiceTemplate hasFormalParameters="false" moduleName="/EventHandler/Process Packages/EventHandler.xpdl" processName="dummyprocess" version="1.0.0.201108111140"/>
            </ChildBusinessCategory>
         </businessCategory>
      </listBusinessServicesResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
  2. You can choose to start one of the business services returned in Step 1. Call the startBusinessService operation and specify the parameters module name and process name to start the selected business service. This operation returns the instance ID which is required for the next step, injecting a business service event. 
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:bus="http://business.api.busserv.n2.tibco.com">
   <soapenv:Header/>
   <soapenv:Body>
      <bus:startBusinessService>
         <businessServiceDefinition moduleName="/EventHandler/Process Packages/EventHandler.xpdl" processName="EventHandlerProcess" version="1.0.0.201108161235"/>
         <responsePayloadMode>XML</responsePayloadMode>
      </bus:startBusinessService>
   </soapenv:Body>
</soapenv:Envelope>
    		 
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <startBusinessServiceResponse xmlns="http://business.api.busserv.n2.tibco.com">
         <pageResponse executionState="IN_PROGRESS" xmlns="">
            <context>
               <pageFlowTemplate hasFormalParameters="false" moduleName="/EventHandler/Process Packages/EventHandler.xpdl" processName="EventHandlerProcess" version="1.0.0.201108161235"/>
               <processReference>
                  <id>pvm:0a1022</id>
                  <name>EventHandlerProcess</name>
               </processReference>
            </context>
            <pageData>
               <pageReference activityId="pvm:001g22.8" activityModelId="_NeC_EL0REeCCNPLAO2IuzQ" activityName="UserTask" moduleName="/EventHandler/Process Packages/EventHandler.xpdl" moduleVersion="1.0.0.201108161235" processName="EventHandlerProcess"/>
               <payload payloadMode="XML">
                  <XmlPayload>
                     <inouts array="false" name="Field" optional="true" type="String">
                        <simpleSpec/>
                     </inouts>
                  </XmlPayload>
               </payload>
            </pageData>
         </pageResponse>
      </startBusinessServiceResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
  3. While the business service is running, you can inject a business service event using the injectBusinessServiceEvent operation. The request message requires you to provide the following parameters: moduleName, processName, eventName, processInstanceId (optional), formal parameters, payload, and optionally, the responsePayloadMode. This operation updates the value of the specified parameter(s) with the value(s) injected by the intermediate event. 
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:bus="http://business.api.busserv.n2.tibco.com">
   <soapenv:Header/>
   <soapenv:Body>
      <bus:injectBusinessServiceEvent>
         <eventDefinition moduleName="/EventHandler/Process Packages/EventHandler.xpdl" processName="EventHandlerProcess" eventName="ReceiveINOUT" processInstanceId="pvm:0a1022"/>
         <formalParams payloadMode="XML">
            <XmlPayload>
               <inouts array="false" name="Parameter9" optional="false" type="String">
		<simpleSpec length="50">
                     <value>TIBCO Software</value>
                  </simpleSpec>
               </inouts>
            </XmlPayload>
         </formalParams>
         <responsePayloadMode>XML</responsePayloadMode>
      </bus:injectBusinessServiceEvent>
   </soapenv:Body>
</soapenv:Envelope>
    		 
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <injectBusinessServiceEventResponse xmlns="http://business.api.busserv.n2.tibco.com">
         <pageResponse executionState="IN_PROGRESS" xmlns="">
            <context>
               <pageFlowTemplate hasFormalParameters="false" moduleName="/EventHandler/Process Packages/EventHandler.xpdl" processName="EventHandlerProcess" version="1.0.0.201108161235"/>
               <processReference>
                  <id>pvm:0a1022</id>
                  <name>EventHandlerProcess</name>
               </processReference>
            </context>
            <pageData>
               <pageReference activityId="pvm:001g22.d" activityModelId="_agO3UL6jEeCKPY5rB9JBjQ" activityName="UserTask5" moduleName="/EventHandler/Process Packages/EventHandler.xpdl" moduleVersion="1.0.0.201108161235" processName="EventHandlerProcess"/>
               <payload payloadMode="XML">
                  <XmlPayload>
                     <inouts array="false" name="Parameter9" optional="true" type="String">
                        <simpleSpec>
                           <value>[Ljava.lang.String;@73e1829d</value>
                        </simpleSpec>
                     </inouts>
                  </XmlPayload>
               </payload>
            </pageData>
         </pageResponse>
      </injectBusinessServiceEventResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>