Displaying a Form in a Pageflow

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

See Progressing a Work Item for more information about opening a work item.

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 opens a work item from the user interface:

Procedure

  1. Call openWorkItem. Use the following items in the baseWorkRequest element to specify form-related inputs to the call:
    • channelId specifies the presentation channel to which the client is bound. (If channelId is not specified, the default channel will be used.)
    • channelType specifies the type of the channelId.
    • responsePayloadMode specifies the format in which the work item data should be returned. This must be JSON.

      If the work item is associated with a pageflow (rather than a single form), the following items in the workResponse element contain the information needed to render each page of the pageflow:

    • pageFlowDetail.page-activity.page-reference.formIdentifier identifies the JSON form artifact that is to be used to display the data for the first page.
    • pageFlowDetail.page-activity identifies the JSON form artifact to be used to display the page data.

      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:baseWorkRequest>
         <resourceId>A2DF6C05-AECA-4D59-A553-A7D029920D51</resourceId>
         <channelId > openspaceGWTPull_DefaultChannel</channelId > <channelType > openspaceChannel</channelType >          <responsePayloadMode > JSON</responsePayloadMode
         <workItem id="14" version="-1"></workItem>
</api:baseWorkRequest>
   </soapenv:Body>
</soapenv:Envelope>
      		 
      <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <workResponse xmlns="http://api.wp.n2.tibco.com">
         <payloadModel payloadMode="JSON" xmlns="">
            <serializedPayload>{items:[]}</serializedPayload>
         </payloadModel>
         <workTypeDetail pilingLimit="0" typePiled="false" uid="WT__lgyB-MP5EeC3yLAVrheurQ" version="1.0.0.201108111305" xmlns="">
            <dataModel/>
         </workTypeDetail>
         <presentation formIdenitifier="http://localhost:8080/bpm/" type="FORM" xmlns=""/>
         <workItem id="14" version="1" xmlns=""/>
         <pageFlowDetail id="_sFSQwMP5EeC3yLAVrheurQ" moduleName="/APH_WelcomeUsersImplementSolution/Process Packages/aph_test.xpdl" moduleVersion="1.0.0.201108111305" name="GetName" url="APH_WelcomeUsersImplementSolution/.bpm/.processOut/pageflow/aph_test.xpdl/GetName.bpel" xmlns="">
            <page-activity id="_faDz8MP8EeC3yLAVrheurQ" name="ShowCustName" xmlns="http://service.archive.wp.n2.tibco.com" > <page-reference guid="" name="ShowCustName.gwt.json" version="1.0.0.201108111305" > <relative-path > 1.0.0.201108111305/openspaceGWTPull_DefaultChannel/.default/aphMyPackage/GetName/ShowCustName</relative-path > <base-path > http://localhost:8080/bpm</base-path > </page-reference > </page-activity
            <page-activity id="_s1Q8MMP5EeC3yLAVrheurQ" name="getFirstName" xmlns="http://service.archive.wp.n2.tibco.com">
               <page-reference guid="" name="getFirstName.gwt.json" version="1.0.0.201108111305">
                  <relative-path>1.0.0.201108111305/openspaceGWTPull_DefaultChannel/.default/aphMyPackage/GetName/getFirstName</relative-path>
                  <base-path>http://localhost:8080/bpm</base-path>
               </page-reference>
            </page-activity>
            <page-activity id="_tTg-cMP5EeC3yLAVrheurQ" name="getSecondName" xmlns="http://service.archive.wp.n2.tibco.com">
               <page-reference guid="" name="getSecondName.gwt.json" version="1.0.0.201108111305">
                  <relative-path>1.0.0.201108111305/openspaceGWTPull_DefaultChannel/.default/aphMyPackage/GetName/getSecondName</relative-path>
                  <base-path>http://localhost:8080/bpm</base-path>
               </page-reference>
            </page-activity>
         </pageFlowDetail>
      </workResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
  2. Call startPageFlow to open the first page in the pageflow. Use the following items in the startPageFlow element to specify form-related inputs to the call:
    • formalParams specifies any data that needs to be passed to the pageflow 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 startPageFlowResponse element is returned:

    • executionState indicates if the pageflow contains further pages (IN_PROGRESS) or if this is the last 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:pag="http://pageflow.api.pfe.n2.tibco.com">
   <soapenv:Header/>
   <soapenv:Body>
      <pag:startPageFlow>
         <pageFlowDefinition moduleName="/APH_WelcomeUsersImplementSolution/Process Packages/aph_test.xpdl" processName="GetName" version="1.0.0.201108111305"/>
        <responsePayloadMode>JSON</responsePayloadMode>
        </pag:startPageFlow>
   </soapenv:Body>
</soapenv:Envelope>
      		 
      <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <startPageFlowResponse xmlns="http://pageflow.api.pfe.n2.tibco.com">
         <pageResponse executionState="IN_PROGRESS" xmlns="">
            <context>
               <pageFlowTemplate hasFormalParameters="false" moduleName="/APH_WelcomeUsersImplementSolution/Process Packages/aph_test.xpdl" processName="GetName" version="1.0.0.201108111305"/>
               <processReference>
                  <id>pvm:0a10s</id>
                  <name>GetName</name>
               </processReference>
            </context>
            <pageData>
               <pageReference activityId="pvm:001gs.4" activityModelId="_s1Q8MMP5EeC3yLAVrheurQ" activityName="getFirstName" moduleName="/APH_WelcomeUsersImplementSolution/Process Packages/aph_test.xpdl" moduleVersion="1.0.0.201108111305" processName="GetName"/>
               <payload payloadMode="JSON">
                  <serializedPayload>{"items":[{"$param":"FirstName","$value":[],"type":"String","mode":"INOUT"},{"$param":"SecondName","$value":[],"type":"String","mode":"INOUT"}]}</serializedPayload>
               </payload>
            </pageData>
         </pageResponse>
      </startPageFlowResponse>
   </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 startPageFlow was IN_PROGRESS, call updatePageFlow to a) update the pageflow with any data added or changed by the user and b) open the next page in the pageflow. Use the following items in the updatePageFlow element to specify form-related inputs to the call:
    • context.processReference.id specifies the pageflow process instance that is to be updated. This value can be obtained from the previous startPageFlowResponse element.
    • context.activityReference.activityId specifies the pageflow activity that is to be updated. This value can be obtained from the pageData.pageReference.activityId item in the previous startPageFlowResponse 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 updatePageFlowResponse element is returned:

    • executionState indicates if the pageflow 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.

      For example: 

      <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pag="http://pageflow.api.pfe.n2.tibco.com">
   <soapenv:Header/>
   <soapenv:Body>
      <pag:updatePageFlow>
         <context>
            <processReference>
               <id>pvm:0a10s</id>
            </processReference>
            <activityReference activityId="pvm:001gs.4"/>
         </context>
         <pageFields payloadMode="JSON">
           <serializedPayload>{"items":[{"$param":"FirstName","$value":["Gerald"],"type":"String","mode":"INOUT"},{"$param":"SecondName","$value":["Durrel"],"type":"String","mode":"INOUT"}]}</serializedPayload>
         </pageFields>
         <responsePayloadMode>JSON</responsePayloadMode>
      </pag:updatePageFlow>
   </soapenv:Body>
</soapenv:Envelope>
      		 
      <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <updatePageFlowResponse xmlns="http://pageflow.api.pfe.n2.tibco.com">
         <pageResponse executionState="IN_PROGRESS" xmlns="">
            <context>
               <pageFlowTemplate hasFormalParameters="false" moduleName="/APH_WelcomeUsersImplementSolution/Process Packages/aph_test.xpdl" processName="GetName" version="1.0.0.201108111305"/>
               <processReference>
                  <id>pvm:0a10s</id>
                  <name>GetName</name>
               </processReference>
            </context>
            <pageData>
               <pageReference activityId="pvm:001gs.5" activityModelId="_tTg-cMP5EeC3yLAVrheurQ" activityName="getSecondName" moduleName="/APH_WelcomeUsersImplementSolution/Process Packages/aph_test.xpdl" moduleVersion="1.0.0.201108111305" processName="GetName"/>
               <payload payloadMode="JSON">
                  <serializedPayload>{"items":[{"$param":"FirstName","$value":["Gerald"],"type":"String","mode":"INOUT"},{"$param":"SecondName","$value":["Durrel"],"type":"String","mode":"INOUT"}]}</serializedPayload>
               </payload>
            </pageData>
         </pageResponse>
      </updatePageFlowResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
  5. Loop through steps 3 and 4, making further updatePageFlow calls until a COMPLETED executionState is returned.

    For example: 

    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pag="http://pageflow.api.pfe.n2.tibco.com">
   <soapenv:Header/>
   <soapenv:Body>
      <pag:updatePageFlow>
         <context>
            <processReference>
               <id>pvm:0a10s</id>
            </processReference>
            <activityReference activityId="pvm:001gs.7"/>
         </context>
         <pageFields payloadMode="JSON">
           <serializedPayload>{"items":[{"$param":"FirstName","$value":["Gerald"],"type":"String","mode":"INOUT"},{"$param":"SecondName","$value":["Fisher"],"type":"String","mode":"INOUT"}]}</serializedPayload>
         </pageFields>
         <responsePayloadMode>JSON</responsePayloadMode>
      </pag:updatePageFlow>
   </soapenv:Body>
</soapenv:Envelope>
    		 
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <updatePageFlowResponse xmlns="http://pageflow.api.pfe.n2.tibco.com">
         <pageResponse executionState="COMPLETED" xmlns="">
            <context>
               <pageFlowTemplate hasFormalParameters="false" moduleName="/APH_WelcomeUsersImplementSolution/Process Packages/aph_test.xpdl" processName="GetName" version="1.0.0.201108111305"/>
               <processReference>
                  <id>pvm:0a10s</id>
                  <name>GetName</name>
               </processReference>
            </context>
            <pageData>
               <payload payloadMode="JSON">
                  <serializedPayload>{"items":[{"$param":"FirstName","$value":["Gerald"],"type":"String","mode":"INOUT"},{"$param":"SecondName","$value":["Fisher"],"type":"String","mode":"INOUT"}]}</serializedPayload>
               </payload>
            </pageData>
         </pageResponse>
      </updatePageFlowResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
  6. Call completeWorkItem to complete the pageflow’s parent work item. In the workRequest element, use payloadDetails to pass the final state of the pageflow data back to the work item.

    (If the pageflow was cancelled, call cancelPageFlow and then cancelWorkItem instead.)

    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:workRequest>
         <resourceId>A2DF6C05-AECA-4D59-A553-A7D029920D51</resourceId>
         <channelId>openspaceGWTPull_DefaultChannel</channelId>
         <channelType>openspaceChannel</channelType>
         <responsePayloadMode>JSON</responsePayloadMode>
         <workItem id="14" version="-1"></workItem>
<payloadDetails payloadMode="JSON">
                  <serializedPayload>{"items":[{"$param":"FirstName","$value":["Gerald"],"type":"String","mode":"INOUT"},{"$param":"SecondName","$value":["Fisher"],"type":"String","mode":"INOUT"}]}</serializedPayload>
         </payloadDetails>
      </api:workRequest>
   </soapenv:Body>
</soapenv:Envelope>
    		 
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <workResponse isSuccessful="true" xmlns="http://api.wp.n2.tibco.com"/>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>