HTTP Client Method Service

The HTTP Client Method service sends HTTP requests to a trading partner's HTTP server via the perimeter server. The HTTP Client Method Service supports POST, GET, HEAD, or other valid HTTP request types that follow the normal HTTP request/response model.

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

System name HTTP Client Method Service
Graphical Process Modeler (GPM) categories All Services, B2B Protocols > HTTP Client
Description The HTTP Client Method service sends HTTP requests to a trading partner's HTTP server via the perimeter server. The HTTP Client Method Service supports POST, GET, HEAD, or other valid HTTP request types that follow the normal HTTP request/response model. The actual HTTP methods available depend on the support provided by the remote/origin 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 Method service to either retrieve or send data from Sterling B2B Integrator to a trading partner when the HTTP protocol is required as the transport mechanism.
Usage example A Sterling B2B Integrator business process is executed that generates a document that must be sent to a trading partner using HTTP. Sterling B2B Integrator initiates a session with the trading partner using the HTTP Client adapter and uses the HTTP Client Method Service, to place the document on the trading partner's HTTP server.
Preconfigured? No
Requires third-party files? No
Platform availability All supported Sterling B2B Integrator platforms
Related services Related services:
  • HTTP Client adapter
  • HTTP Client Begin Session service
  • HTTP Client End Session service
  • HTTP Client GET service
  • HTTP Client POST service
Application requirements An HTTP server at the external trading partner location.
Initiates business processes? No
Invocation This 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 System 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 Method Service

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

Configuring the HTTP Client Method Service

To configure the HTTP Client Method service, you must specify field settings in the GPM:

Field Description
Config Name of the service configuration.
DocumentId A document ID to use with this instance of the HTTP Client Method service. Optional.
MethodType Specifies the HTTP request type. Required. The HTTP Client Method Service supports POST, GET, HEAD, or other valid HTTP request types that follow the normal HTTP request/response model. The actual HTTP method available depends on the support provided by the remote/origin server.
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.
LineBreak Allows you to specify what type of line break is used in the message. Optional. Valid values:
  • LF - use linefeed
  • SYSTEM - use LF (linefeed) if Sterling B2B Integratoroperating system is Linux or UNIX. Use CR+LF (carriage return + linefeed) if the operating system is Microsoft Windows.
  • CR+LF - use carriage return plus linefeed. Default is CR+LF.
URI Uniform Resource Indicator (URI) representing the HTTP server. Required.
Cookie Identifies the cookie to use in cases where the previous POST or GET needs page redirection (returns 300 range response). The cookie value is passed from the response header Set-Cookie. The Method Service will use the Cookie parameter and create the Cookie header in the next request. Valid values are cookies separated by semi-colon (cookie1;cookie2;cookie3). Optional.

Output from Business Process to Service

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

Field Description
DocumentId A document ID to use with this instance of the HTTP Client Method service. Optional.
MethodType Specifies the HTTP request type. Required. The HTTP Client Method Service supports POST, GET, HEAD, or other valid HTTP request types that follow the normal HTTP request/response model. The actual HTTP method available depends on the support provided by the remote/origin server. Valid values include:
  • GET – Retrieves whatever information is identified by the URI in the request line.
  • POST – Requests that the server accept the entity enclosed in the request as a new subordinate of the resource identified by the URI in the request line.
  • HEAD – Retrieves the header of whatever information is identified by the URI in the request line.
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.
LineBreak Allows you to specify what type of line break is used in the message. Optional. Valid values:
  • LF - use linefeed
  • SYSTEM - use LF (linefeed) if Sterling B2B Integratoroperating system is Linux or UNIX. Use CR+LF (carriage return + linefeed) if the operating system is Microsoft Windows.
  • CR+LF - use carriage return plus linefeed. Default is CR+LF.
URI Uniform Resource Indicator (URI) representing the HTTP server. Required.
Cookie Identifies the cookie to use in cases where the previous POST or GET needs page redirection (returns 300 range response). The cookie value is passed from the response header Set-Cookie. The Method Service will use the Cookie parameter and create the Cookie header in the next request. Valid values are cookies separated by semi-colon (cookie1;cookie2;cookie3). Optional.

Business Process Examples

The following example business process illustrates by using commands supported by the HTTP Client Method service:

 <process name="HTTPClientMethodServiceExample">
  <sequence>
  [[Insert Begin session operation here]] 
    <operation name="HTTP Client Method Service">
      <participant name="HTTPClientMethodService"/>
      <output message="HTTPClientMethodServiceTypeInputMessage">
        <assign to="DocumentId">DocumentID</assign>
        <assign to="MethodType">HEAD</assign>
        <assign to="RawRequest">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 provides an example of using the GetDocumentInfoService to set the content-type/subtype of the request document. It is important to put the output parameters of GetDocumentInfoService into a parent node, such as "docInfo".

The GetDocumentInfoService returns a node called DocumentId to the process data. This is the ID of the original document object without the content-type and sub-type set. If this node is directly under the root of Process Data, the HTTP Client Post service will attempt to retrieve the original document object using the document ID instead of the Primary Document. If DocumentId node is returned under "docinfo" node, the HTTP Client Post service does not use the document from DocumentId. Instead the service retrieves the correct document that was set with the correct content-type/subtype from the primary document.

<process name="HttpClient_SetContentType">
  <sequence>
    <!-- Set document content type/subtype -->
    <operation name="SetContenType">
      <participant name="GetDocumentInfoService"/>
      <output message="xout">
        <assign to="." from="*"></assign>
        <assign to="DocumentContentType">text</assign>
        <assign to="DocumentContentSubType">xml</assign>
      </output>
      <input message="xin">
        <assign to="docInfo" from="*"></assign>
      </input>
    </operation>
    <operation name="HTTP Client Begin Session Service">
      <participant name="HTTPClientBeginSession"/>
      <output message="HTTPClientBeginSessionServiceTypeInputMessage">
        <assign to="HTTPClientAdapter">HTTPClientAdapter</assign>
        <assign to="RemoteHost">10.235.18.103</assign>
        <assign to="RemotePort">37133</assign>
        <assign to="." from="*"></assign>
      </output>
      <input message="inmsg">
        <assign to="HTTPClientBeginSessionServiceResults" from="*"></assign>
      </input>
    </operation>
    <operation name="Http Client Method Service">
      <participant name="HTTPClientMethod"/>
      <output message="HTTPClientMethodServiceTypeInputMessage">
        <assign to="SessionToken" from="HTTPClientBeginSessionServiceResults/
                SessionToken/text()"></assign>
        <assign to="MethodType">POST</assign>
        <assign to="URI">/hello</assign>
        <assign to="RawRequest">false</assign>
        <assign to="RawResponse">true</assign>
        <assign to="." from="*"></assign>
      </output>
      <input message="inmsg">
        <assign to="HTTPClientMethodServiceResults" 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>

Activity Types for the HTTP Client Method Service

The HTTP Client Method service reports the following activities to the Services Controller for service/method service monitoring:
  • GET – Retrieves whatever information is identified by the URI in the request line.
  • POST – Requests that the server accept the entity enclosed in the request as a new subordinate of the resource identified by the URI in the request line.
  • HEAD – Retrieves the header of whatever information is identified by the URI in the request line.

The actual HTTP methods available depends on the support provided by the remote/origin server.