HTTP Client GET Service

The HTTP Client GET service sends HTTP GET requests to a trading partner's HTTP server via the perimeter server. This service works with the HTTP Client Begin service and the HTTP Client End service, and through an instance of the HTTP Client adapter.

The following table provides an overview of the HTTP Client GET service:

System name HTTP Client GET Service
Graphical Process Modeler (GPM) categories All Services, B2B Protocols > HTTP Client
Description The HTTP Client GET service sends HTTP GET requests to a trading partner's HTTP server via the perimeter server. This service works in conjunction with the HTTP Client Begin service and the HTTP Client End service, and through an instance of the HTTP Client adapter.
Business usage A business user would use the HTTP Client GET service to retrieve documents from a trading partner's HTTP server.
Usage example A Sterling B2B Integrator business process is executed that must retrieve a specified file from the external trading partner. Sterling B2B Integrator uses the HTTP Client GET Service, working through the HTTP Client Adapter, to retrieve the file from the trading partner's HTTP server. The data is passed to the business process.
Preconfigured? No
Requires third-party files? No
Platform availability All supported platforms for Sterling B2B Integrator
Related services Related services:
  • HTTP Client adapter
  • HTTP Client Begin Session service
  • HTTP Client End Session service
  • HTTP Client Method service
  • HTTP Client POST service
Application requirements An HTTP server at the external trading partner location.
Initiates business processes? No
Invocation The HTTP Client GET service is invoked from a business process.
Business process context considerations None
Returned status values Returned status values:
  • 100s – Informational parameters and more status parameters will follow.
  • 200s – Request was OK.
  • 300s – Request failed and more status codes will follow.
  • 400s – Client Request Failed. This is a client error.
  • 500s – Server failed to handle a valid request. This is a server error.
Restrictions None
Persistence level Default
Testing considerations To test this service, run the HTTPClientDemoAllServices business process and verify that it completes successfully. For more information about the HTTPClientDemoAllServices business process, see the HTTP Client adapter. Debug information for this service can be found in the HTTP Client adapter and services log files.

Implementing the HTTP Client GET Service

To implement the HTTP Client GET service, complete the following tasks:
  1. Create an HTTP Client GET service configuration. For information, see Managing Services and Adapters.
  2. Configure the HTTP Client GET service. For information, see Configuring the HTTP Client GET Service.
  3. Use the HTTP Client GET service in a business process.

Configuring the HTTP Client GET Service

To configure the HTTP Client GET service, you must specify field settings in the Graphical Process Modeler (GPM):

Field Description
Config Name of the service configuration.
DocumentId A document ID to use with this instance of the HTTP Client GET service. Optional.
RawRequest Whether to include the HTTP header metadata in the primary document. Optional. Valid values:
  • true – HTTP header metadata is included in the primary document. If set to true, the request document must contain headers inside its message body.
  • false – HTTP header metadata is not included in the primary document. The headers are not available to the business process.

The default value is false.
RawResponse Whether to include the HTTP Server response headers in the response document. Optional. Valid values:
  • true – Both the HTTP headers and the entity body are copied to the body of the business process document.
  • false – Just the HTTP entity body is copied to the body buffer of the business process document. The headers are not available to the business process.

The default value is false.
ResponseTimeout Number of seconds the HTTP Client adapter will wait for a response. Optional. Any numeric value is valid.
Note: The value entered for this parameter overrides the Timeout setting in the HTTP Client adapter configuration.
SessionToken Specifies the identifier for the session established between the HTTP Client Adapter and an HTTP server. Required.
ShowResponseCode Whether to include the HTTP response status code as the first line in the primary document. Optional. Valid values:
  • true – Metadata will be included.
  • false – Metadata will not be included. Default is false.
URI Uniform Resource Indicator (URI) representing the HTTP server. Required.
Cookie Identifies the cookie to use in cases where the previous GET needs page redirection (returns 300 range response). The cookie value is passed from the response header Set-Cookie. The Get Service uses the Cookie parameter and creates the Cookie header in the next request. Valid values are cookies separated by semi-colon (cookie1;cookie2;cookie3). Optional.
stripDefaultPortFromRequestHostHeader Whether to include the port information in the HTTP host header if the port is the default port (port 80 for HTTP, port 443 for HTTPS). Optional. Valid values:
  • true – Port information will not be included in the HTTP host header if the port is the default port.
  • false – Port information will be included. Default is false.

Output from Business Process to Service

The following table contains the parameters passed from the business process to the HTTP Client GET service:

Field Description
DocumentId A document ID to use with this instance of the HTTP Client GET service. Optional.
RawRequest Whether to include the HTTP header metadata in the primary document. Optional. Valid values:
  • true – HTTP header metadata is included in the primary document. If set to true, the request document must contain headers inside its message body.
  • false – HTTP header metadata is not included in the primary document. The headers are not available to the business process.

The default value is false.
RawResponse Whether to include the HTTP Server response headers in the response document. Optional. Valid values:
  • true – Both the HTTP headers and the entity body are copied to the body of the business process document.
  • false – Just the HTTP entity body is copied to the body buffer of the business process document. The headers are not available to the business process.

The default value is false.
ResponseTimeout Number of seconds the HTTP Client adapter will wait for a response. Optional. Any numeric value is valid.
Note: The value entered for this parameter overrides the Timeout setting in the HTTP Client adapter configuration.
SessionToken Specifies the identifier for the session established between the HTTP Client Adapter and an HTTP server. Required.
ShowResponseCode Whether to include the HTTP response status code as the first line in the primary document. Optional. Valid values:
  • true – Metadata will be included.
  • false – Metadata will not be included. Default is false.
URI Uniform Resource Indicator (URI) representing the HTTP server. Required.
Cookie Identifies the cookie to use in cases where the previous GET needs page redirection (returns 300 range response). The cookie value is passed from the response header Set-Cookie. The Get Service uses the Cookie parameter and creates the Cookie header in the next request. Valid values are cookies separated by semi-colon (cookie1;cookie2;cookie3). Optional.

Business Process Examples

The following BPML example illustrates by using commands supported by the HTTP Client GET service. 

<process name="HTTPClientGETServiceExample"> 
  <sequence> 
  [[Insert begin session operation here]] 
    <operation name="HTTP Client GET Service">
    <participant name="HTTPClientGETService"/>
    <output message="HTTPClientGetServiceTypeInputMessage">
      <assign to="DocumentId">DocumentID</assign>
      <assign to="RawResponse">true</assign>
      <assign to="ResponseTimeout">60</assign>
      <assign to="SessionToken">SessionToken</assign>
      <assign to="ShowResponseCode">true</assign>
      <assign to="URI">URI</assign>
      <assign to="." from="*"></assign>
    </output>
    <input message="inmsg">
      <assign to="." from="*"></assign>
    </input>
    </operation> 
  [[Insert end session operation here]] 
  </sequence> 
</process>

The following business process provides an example of using the Cookie parameter:

<process name="HTTP_To_advancepcsrx">
  <!-- Loop Invariant. -->
  <rule name="haveMoreCookie1">
	<condition> string(counterCookie) &lt;= count(HTTPClientPostServiceResults/
     ServerResponse/Headers/Set-Cookie/node()) </condition>
  </rule>
  <sequence>
    <operation name="HTTP Client Begin Session Service">
      <participant name="HTTPClientBeginSession"/>
      <output message="HTTPClientBeginSessionServiceTypeInputMessage">
        <assign to="CACertificateId">sgmillenia:13582d:10682043f1d:-73bd</assign>
        <assign to="CipherStrength">all</assign>
        <assign to="HTTPClientAdapter">HTTPClientAdapter</assign>
        <assign to="SSL">Must</assign>
        <assign to="RemoteHost">webtransport.advancepcsrx.com</assign>
        <assign to="RemotePort">443</assign>
        <assign to="." from="*"></assign>
      </output>
      <input message="inmsg">
        <assign to="HTTPClientBeginSessionServiceResults" from="*"></assign>
      </input>
    </operation>
    <!-- Use FSA to pick up the input file -->
    <operation name="Import Document Request">
      <participant name="TEST_FILE_SYSTEM_ADAPTER"/>
      <output message="FileSystemInputMessage">
        <assign to="Action">FS_COLLECT</assign>
        <assign to="collectionFolder" from="'/ais_local/share/sli'"></assign>
        <assign to="filter" from="'AdvancePCS_URI.txt'"></assign>
        <assign to="useSubFolders">false</assign>
        <assign to="bootstrap">false</assign>
        <assign to="deleteAfterCollect">false</assign>
        <assign to="." from="*"></assign>
      </output>
      <input message="FileSystemOutputMessage">
        <assign to="." from="*"></assign>
      </input>
    </operation>
    <!-- Set document content type/subtype -->
    <operation name="SetContenType">
      <participant name="GetDocumentInfoService"/>
      <output message="xout">
        <assign to="." from="*"></assign>
        <assign to="DocumentContentType">application</assign>
        <assign to="DocumentContentSubType">x-www-form-urlencoded</assign>
      </output>
      <input message="xin">
        <assign to="docInfo" from="*"></assign>
      </input>
    </operation>
           <!-- POST to URI /template/login to login the webpage -->
    <operation name="Http Client Post Service">
      <participant name="HTTPClientPost"/>
      <output message="HTTPClientPostServiceTypeInputMessage">
        <assign to="SessionToken" from="HTTPClientBeginSessionServiceResults/
             SessionToken/text()"></assign>
        <assign to="URI">/template/login</assign>
        <assign to="RawResponse">true</assign>
        <assign to="ResponseTimeout">120</assign>
        <assign to="." from="*"></assign>
      </output>
      <input message="inmsg">
        <assign to="HTTPClientPostServiceResults" from="*" append="true"></assign>
      </input>
    </operation>
    <!-- concat the cookie from the POST Response -->
    <assign to="counterCookie">1</assign>
    <assign to="Cookie" from="''"/>
    <choice> 
<select> 
  <case ref="haveMoreCookie1" activity="AppendCookie1"/> 
  </select>          
    <sequence name="AppendCookie1"> 
   <assign to="Cookie" from="concat(string(Cookie), substring-before
    (//HTTPClientPostServiceResults/ServerResponse/Headers/Set-Cookie
    [number(//counterCookie)],';'), '; ')"/> 
   <assign to="counterCookie" from="number(counterCookie) + 1"/> 
  <choice> 
<select> 
    <case ref="haveMoreCookie1" activity="Repeat1"/> 
  </select> 
<repeat name="Repeat1" ref="AppendCookie1"/> 
</choice>    
 </sequence>
    </choice>
    <!-- release Primary Document before GET -->
    <operation> 
    <participant name="ReleaseService"/> 
    <output message="releaseRequest"> 
      <assign to="TARGET" from="'PrimaryDocument'"/> 
    </output> 
    <input message="releaseResponse"/>
    </operation>    
    <!-- GET URI / to reach the final page -->      
    <operation name="Http Client Get Service">
      <participant name="HTTPClientGet"/>
      <output message="HTTPClientGetServiceTypeInputMessage">
        <assign to="SessionToken" from="HTTPClientBeginSessionServiceResults/
              SessionToken/text()"></assign>
        <assign to="URI">/</assign>
        <assign to="RawResponse">true</assign>
        <assign to="ResponseTimeout">1200</assign>
        <assign to="." from="*"></assign>
      </output>
      <input message="inmsg">
        <assign to="HTTPClientGetServiceResults" from="*" append="true"></assign>
      </input>
    </operation>    
    <operation name="HTTP Client End Session Service">
      <participant name="HTTPClientEndSession"/>
      <output message="HTTPClientEndSessionServiceTypeInputMessage">
        <assign to="SessionToken" from="HTTPClientBeginSessionServiceResults/
             SessionToken/text()"></assign>
        <assign to="." from="*"></assign>
      </output>
      <input message="inmsg">
        <assign to="HTTPClientEndSessionServiceResults" from="*" append="true">
            </assign>
      </input>
    </operation>
    <onFault>
      <sequence name="End Session">
        <operation name="HTTP Client End Session Service">
          <participant name="HTTPClientEndSession"/>
          <output message="HTTPClientEndSessionServiceTypeInputMessage">
            <assign to="SessionToken" from="HTTPClientBeginSessionServiceResults/
                  SessionToken/text()"></assign>
            <assign to="." from="*"></assign>
          </output>
          <input message="inmsg">
            <assign to="HTTPClientEndSessionServiceResults" from="*"></assign>
          </input>
        </operation>
      </sequence>
    </onFault>
  </sequence> 
</process>

The following business process is an example of using the URI parameter in the HTTP Client GET service. The URI is:

/s/ref=nb_ss_b/102-0129027-9554536?url=search-alias%3Dstripbooks&field-keywords=Computers&Go.x=6&G0.y=4

This URI has the following parameters:

Parameter Description
url search-alias%3Dstripbooks
field-keywords Computers
Go.x 6
G0.y 4 
<process name = "test_http_get">
  <sequence>
    <operation name="HTTP Client Begin Session Service">
      <participant name="HTTPClientBeginSession"/>
      <output message="HTTPClientBeginSessionServiceTypeInputMessage">
        <assign to="HTTPClientAdapter">HTTPClientAdapter</assign>
        <assign to="RemoteHost">www.amazon.com</assign>
        <assign to="RemotePort">80</assign>
        <assign to="." from="*"></assign>
      </output>
      <input message="inmsg">
        <assign to="." from="*"></assign>
      </input>
    </operation>
    <operation name="HTTP Client GET Service">
      <participant name="HTTPClientGet"/>
      <output message="HTTPClientGetServiceTypeInputMessage">
         <assign to="SessionToken" from="/ProcessData/SessionToken/text()"></assign>
        <assign to="URI">/s/ref=nb_ss_b/
             102-0129027-9554536?url=search-alias%3Dstripbooks&amp;field-keywords=
             Computers&amp;Go.x=6&amp;Go.y=4</assign>
        <assign to="." from="*"></assign>
      </output>
      <input message="inmsg">
        <assign to="." from="*"></assign>
      </input>
    </operation>
    <operation name="HTTP Client End Session Service">
      <participant name="HTTPClientEndSession"/>
      <output message="HTTPClientEndSessionServiceTypeInputMessage">
        <assign to="SessionToken" from="/ProcessData/SessionToken/text()"></assign>
        <assign to="." from="*"></assign>
      </output>
      <input message="inmsg">
        <assign to="." from="*"></assign>
      </input>
    </operation>
  </sequence> 
</process>

The resulting document in process data is the link to the Amazon page with the search requested.

Activity Types for the HTTP Client GET Service

The HTTP Client GET service reports the following activities to the Services Controller for service/GET service monitoring:
  • GET – Retrieves whatever information is identified by the URI in the request line.