Displaying a Form in a Business Service

This topic provides an example that shows the sequence of calls a client application should make to display a form in a business service.

See Starting a Business Service for more information about starting a business service.

Note: The following step-by-step descriptions correspond to the numbered steps in the diagram. 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).

When a user starts a business service from the user interface:

Procedure

  1. Call startBusinessService to obtain the page data for the first page in the business service. Use the following items in the startBusinessService element to specify form-related inputs to the call:
    • formalParams specifies any data that needs to be passed to the business service as formal parameters.
      Note: You cannot determine which data fields are formal parameters programmatically. Instead, you must obtain this information directly from TIBCO Business Studio.
    • responsePayloadMode specifies the format in which the page data should be returned. This must be JSON.

      When the startBusinessServiceResponse element is returned:

    • executionState indicates if the business service contains further pages (IN_PROGRESS) or if this is the only page (COMPLETED).
    • pageData.payload.serializedPayload contains the page data as a JSON payload

      For example: 

      <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="/APH_WelcomeUsersImplementSolution/Process Packages/aph_test.xpdl" processName="aphStartProc" version="1.0.0.201108111305"/>
         <responsePayloadMode>JSON</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="/APH_WelcomeUsersImplementSolution/Process Packages/aph_test.xpdl" processName="aphStartProc" version="1.0.0.201108111305"/>
               <processReference>
                  <id>pvm:0a1012</id>
                  <name>aphStartProc</name>
               </processReference>
            </context>
            <pageData>
               <pageReference activityId="pvm:001g12.3" activityModelId="_9IfurcQDEeC3yLAVrheurQ" activityName="UserTask" moduleName="/APH_WelcomeUsersImplementSolution/Process Packages/aph_test.xpdl" moduleVersion="1.0.0.201108111305" processName="aphStartProc"/>
               <payload payloadMode="JSON">
                  <serializedPayload>{"items":[{"$param":"UserName","$value":[],"type":"String","mode":"INOUT"},{"$param":"PhoneNumber","$value":[],"type":"String","mode":"INOUT"}]}</serializedPayload>
               </payload>
            </pageData>
         </pageResponse>
      </startBusinessServiceResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
  2. Call getBusinessServiceDetailsByModule to get the details of the forms used by the page activity in the business service.

    The page-activity.page-reference element in the businessServiceDetailsResponse identifies the JSON form artifact to be used to display the page data for each page in the business service.

    For example: 

    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.wp.n2.tibco.com">
   <soapenv:Header/>
   <soapenv:Body>
      <api:businessServiceDetailsRequest>
         <moduleName>/APH_WelcomeUsersImplementSolution/Process Packages/aph_test.xpdl</moduleName>
         <processName>aphStartProc</processName>
      </api:businessServiceDetailsRequest>
   </soapenv:Body>
</soapenv:Envelope>
    		 
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <businessServiceDetailsResponse id="_86Cb0MQDEeC3yLAVrheurQ" moduleName="/APH_WelcomeUsersImplementSolution/Process Packages/aph_test.xpdl" moduleVersion="1.0.0.201108111305" name="aphStartProc" url="APH_WelcomeUsersImplementSolution/.bpm/.processOut/pageflow/aph_test.xpdl/aphStartProc.bpel" xmlns="http://api.wp.n2.tibco.com">
         <page-activity id="_9IfurcQDEeC3yLAVrheurQ" name="UserTask" xmlns="http://service.archive.wp.n2.tibco.com">
            <page-reference guid="" name="UserTask.gwt.json" version="1.0.0.201108111305">
               <relative-path>1.0.0.201108111305/openspaceGWTPull_DefaultChannel/.default/aphMyPackage/aphStartProc/UserTask</relative-path>
               <base-path>http://localhost:8080/bpm</base-path>
            </page-reference>
         </page-activity>
      </businessServiceDetailsResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
  3. Pass the page data and form details to the Forms Runtime Adapter, which renders the form and handles the user’s interaction with it. (See Rendering a TIBCO Business Studio Form.)

    When the user submits or cancels the form, the Forms Runtime Adapter notifies the client application that this has happened and returns the data from the form.

  4. If the executionState returned by startBusinessService was IN_PROGRESS, call updateBusinessService to a) update the business service with any data added or changed by the user and b) open the next page in the business service. Use the following items in the updateBusinessService element to specify form-related inputs to the call:
    • context.processReference.id specifies the business service (pageflow) process instance that is to be updated. This value can be obtained from the previous startBusinessServiceResponse element.
    • context.activityReference.activityId specifies the business service activity that is to be updated. This value can be obtained from the pageData.pageReference.activityId item in the previous startBusinessServiceResponse element.
    • pageFields contains the page data that is to be updated, as returned by the form.
    • responsePayloadMode specifies the format in which the page data should be returned for the next page. This must be JSON.

      When the updateBusinessServiceResponse element is returned:

    • executionState indicates if the business service contains further pages (IN_PROGRESS) or if this is the last page (COMPLETED).
    • pageData.payload.serializedPayload contains the page data for the next page as a JSON payload.
  5. Loop through steps 3 and 4, making further updateBusinessService calls until a COMPLETED executionState is returned.

    For example: 

    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:bus="http://business.api.busserv.n2.tibco.com">
   <soapenv:Header/>
   <soapenv:Body>
      <bus:updateBusinessService>
         <context>
            <processReference>
               <id>pvm:0a10t</id>
            </processReference>
            <activityReference activityId="pvm:001gt.3"/>
         </context>
         <responsePayloadMode>JSON</responsePayloadMode>
      </bus:updateBusinessService>
   </soapenv:Body>
</soapenv:Envelope>
    		 
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <updateBusinessServiceResponse xmlns="http://business.api.busserv.n2.tibco.com">
         <pageResponse executionState="COMPLETED" xmlns="">
            <context>
               <pageFlowTemplate hasFormalParameters="false" moduleName="/APH_WelcomeUsersImplementSolution/Process Packages/aph_test.xpdl" processName="aphStartProc" version="1.0.0.201108111305"/>
               <processReference>
                  <id>pvm:0a10t</id>
                  <name>aphStartProc</name>
               </processReference>
            </context>
            <pageData>
               <payload payloadMode="JSON">
                  <serializedPayload>{"items":[]}</serializedPayload>
               </payload>
            </pageData>
         </pageResponse>
      </updateBusinessServiceResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>