Working With the HTTP Connectors

PeopleSoft HTTP Message Parameters

You must specify several required parameters in messages that you send to the HTTP listening connector. There are also several optional parameters.

These parameters, also known as credentials, are metadata specific to each message that the HTTP listening connector processes. These parameters supply authentication information and descriptive details about how the message is processed. For each message that you send to the connector, PeopleSoft Integration Broker uses the parameters that you supply to create an IBRequest that it uses to process and service the request internally. The following table describes the parameters:

The PeopleSoft HTTP message parameters can be passed with inbound messages to the HTTP listening connector using several methods, and they are transmitted with outbound messages by the HTTP target connector.

See Complying With Message Formatting and Transmission Requirements.

Using External Message IDs

You can specify an external message ID as a parameter in the HTTP listening connector to uniquely identify a message in PeopleSoft Integration Broker, thus ensuring that no duplicate messages are delivered to the system. The ExternalMessageID parameter is optional, but if you do specify this parameter, it must be unique and contain no more than 70 characters.

The HTTP listening connector can receive an external message ID in:

• Query strings.

• HTTP headers.

• SOAPAction headers.

• PeopleSoft IBRequest XML.

The following example shows passing an external message ID in a query string:

http://localhost/PSIGW/HttpListeningConnector?From=QE_UNDERDOG&To=
QE_LOCAL&Operation=QE_SYNC_MSG.VERSION_1
ExternalMessageID=UniqueId0006

The following example shows passing an external message ID in an HTTP header:

ExternalMessageID: UniqueId0006

The following example shows passing an external message ID in a SOAPAction header:

http://peoplesoft.com/QE_SYNC_MSG/QE_UNDERDOG/password/QE_LOCAL/
UniqueId0006

The following example shows passing an external message ID in PeopleSoft IBRequest XML:

<?xml version="1.0"?>
<IBRequest>
    <From>
        <RequestingNode>QE_UNDERDOG</RequestingNode>
        <OrigTimeStamp>2003-09-29T00:37:30.790-0800</OrigTimeStamp>
        <ExternalMessageID>UniqueId0006</ExternalMessageID>
    /From>
    <ExternalOperationName>QE_SYNC_MSG.VERSION_1</ExternalOperationName>
    <OperationType>sync</OperationType>
    <To>
        <DestinationNode>QE_LOCAL</DestinationNode>
    </To>
    <ContentSections>
        <ContentSection>
            <Headers>
            <version>VERSION_1</version>
            </Headers>
            <Data><![CDATA[<?xml version="1.0"?><QE_SYNC_MSG/>]]></Data>
        </ContentSection>
    </ContentSections>
</IBRequest>

Using the HTTP Listening Connector to Receive Message Segments

The HTTP listening connector is segment-aware and you may use it to receive message segments from integration partners.

See Working With Message Segments.

IBInfo Data Contained in HTTP Headers

A message has two parts—the transaction data and the IBInfo header that is the routing envelope used by PeopleSoft Integration Broker. In the event that a receiving system wants to make use of the IBInfo data, IBInfo header information is included when publishing messages to non-PeopleSoft systems when using the HTTP target connector or the JMS target connector.

When using the HTTP target connector to send messages to non-PeopleSoft systems, the following IBInfo data is contained in the HTTP headers. The content of the message (message body) is not impacted.

• ExternalOperationName

• OperationType

• OrigTimeStamp

• NonRepudiation

• To

• From

Gateway-Level Connector Properties

The HTTP target connector provides the option of routing through proxy servers. To enable this capability, you must set the domain name of the proxy server and the port number of the proxy server in the integrationGateway.properties file:

See Running Integration Gateways Behind Proxy Servers.

Node-Level Connector Properties

The HTTP target connector features properties that correspond to standard HTTP 1.1 header fields, as well as several custom properties that are documented in the following table. The World Wide Web Consortium (W3C) web site provides complete documentation for the standard header fields.

See World Wide Web Consortium

Using the Content-Type Property

One of the optional gateway-level properties you can set for the HTTP target connector is Content-Type.

When the HTTP target connector property Content-Type is application/x-www-form-urlencoded, the connector converts the content string to MIME format.

Encoding Strings

When encoding a string, the following rules apply:

• The alphanumeric characters "a" through "z", "A" through "Z" and "0" through "9" remain the same.

• The special characters ".", "-", "*", and "_" remain the same.

• The space character " " is converted into a plus sign "+".

• All other characters are unsafe and are first converted into one or more bytes. Then each byte is represented by the three-character string "%xy," where xy is the two-digit hexadecimal representation of the byte.

Using the HTTP Target Connector to Send Message Segments

The HTTP target connect is segment-aware and you may use it to send message segments to integration partners.

See Working With Message Segments.

The PeopleSoft XML Message Wrapper

At a minimum, when you submit message content to the HTTP listening connector, you submit it—preceded by the following XML version declaration—inside a simple XML wrapper:

<?xml version="1.0"?><![CDATA[your_message_content]]>

Upon receiving the message, the integration gateway strips off the outer elements, leaving the message content with its original XML version declaration to be handled by PeopleSoft Integration Broker:

<?xml version="1.0"?>your_message_content

The message content can comply with the PeopleSoft rowset-based message format, which you can manipulate using the PeopleCode Rowset class. It can also be nonrowset-based XML-DOM-compliant data, which you can manipulate with nonrowset PeopleCode. Both formats are compatible with Application Engine transform programs, in which you can manipulate the message content using both PeopleCode and Extensible Stylesheet Language Transformation (XSLT) code.

The following template shows how a message in PeopleSoft rowset-based message format fits into the XML wrapper (data omitted for readability):

<?xml version="1.0"?><![CDATA[<?xml version="1.0"?>
      <psft_message_name><FieldTypes>...</FieldTypes><MsgData>...</MsgData>
      </psft_message_name>]]>

The PeopleSoft Non-XML Message Element

If you’re submitting a non-XML message, you must insert the message content into a special element containing its own CDATA tag, as follows:

<?xml version="1.0"?><![CDATA[<?xml version="1.0"?>
      <any_tag psnonxml="yes">
         <![CDATA[your_nonXML_message_content]]>
      </any_tag>]]>

The following restrictions apply to the content of non-XML messages, such as those in comma-separated value (CSV) or PDF format:

• If the message content is non-XML text, it must be encoded as characters that are compliant with Unicode Transformation Format 8 (UTF-8).

• If the message content is non-text (binary), it must be encoded in base64 format.

Upon receiving the message, the integration gateway strips off the outer elements, leaving the non-XML message content inside a valid XML-DOM-compliant wrapper with its original XML version declaration.

Passing HTTP Parameters

You can pass parameters to the HTTP listening connector in:

• The PeopleSoft message wrapper, through an HTTP POST.

• The HTTP header, through an HTTP GET or POST.

• The URL query string, through an HTTP GET or POST.

The only HTTP parameters that you must provide for basic messaging are MessageName and RequestingNode. If you pass them in the PeopleSoft message wrapper, you must embed them in an XML structure along with the CDATA element containing the message content. Following is the minimum wrapper structure required to pass the parameters this way:

<?xml version="1.0"?>
<IBRequest>
   <ExternalOperationName>psft_operation_name</ExternalOperation
    Name>
   <From><RequestingNode>psft_node_name</RequestingNode>
   </From>
   <ContentSections>
      <ContentSection>
         <Data><![CDATA[<?xml version="1.0"?>your_message_content]]>
         </Data>
      </ContentSection>
   </ContentSections>
</IBRequest>

If you want to pass all of the HTTP message parameters in the PeopleSoft message wrapper, you embed them in the XML wrapper structure as follows (required parameters are shown emphasized, and element values are omitted for readability):

<?xml version="1.0"?>
<IBRequest>
   <ExternalOperationName/>
   <OperationType/>
   <From><RequestingNode/>
      <Password/>
      <OrigUser/>
      <OrigNode/>
      <OrigProcess/>
      <OrigTimeStamp/>
   </From>
   <To>
      <FinalDestination/>
      <DestinationNode/>
      <SubChannel/>
   </To>
   <ContentSections>
      <ContentSection>
         <NonRepudiation/>
         <MessageVersion/>
         <Data><![CDATA[<?xml version="1.0"?>your_message_content]]>
         </Data>
      </ContentSection>
   </ContentSections>
</IBRequest>

The following template shows the format for passing HTTP message parameters in the HTTP message header. The optional parameters can be omitted if not needed. The HTTP header format is as follows (required parameters are shown emphasized):

OperationName: OperationName
OperationType: sync|async|ping
From: RequestingNode
Password: Password
OrigUser: OrigUser
OrigNode: OrigNode
OrigProcess: OrigProcess
OrigTimeStamp: OrigTimeStamp
FinalDestination: FinalDestination
To: DestinationNode
SubQueue:  SubQueue
NonRepudiation: Y|N

The following template shows the format for passing HTTP message parameters in a URL query string. Include all of the parameter variables, even if you don't supply values for some of them. With only the required parameters, the URL query string looks like the following (required parameters are emphasized):

http://gatewayserver/PSIGW/HttpListeningConnector?&Operation=Operation
Name&OperationType=&From=RequestingNode&Password=&OrigUser=&OrigNode=
&OrigProcess=&OrigTimeStamp=&FinalDestination=&To=&SubQueue=
&NonRepudiation=&MessageVersion=

The full URL query string format is:

http://gatewayserver/PSIGW/HttpListeningConnector?&Operation=Operation
Name&OperationType=[sync|async|ping]&From=RequestingNode&Password=
Password&OrigUser=OrigUser&OrigNode=OrigNode&OrigProcess=OrigProcess&
OrigTimeStamp=OrigTimeStamp&FinalDestination=FinalDestination&To=DestinationNode&SubQueue=SubQueue&NonRepudiation=[Y|N]&MessageVersion=MessageVersion

Using an HTTP POST is the only way that you can send message content to PeopleSoft Integration Broker through the HTTP listening connector. However, you can use an HTTP GET when you don't need to post message content. In this case, you pass the HTTP connector properties in the URL query string or in the HTTP header, but you don't insert any message content or XML wrapper. For example, you might have requests for information (queries), such as a request for a customer list. In this case, you need to specify only the message name (for example, CUSTOMER_LIST_REQUEST) and the name of the requesting node in the URL query string or the HTTP header.

Specifying Message Destinations in HTTP Headers

When message credentials are supplied in HTTP headers, the "To:" (destination node) specification is ignored. PeopleSoft Integration Broker uses the Default Application Server node entry in the integrationGateway.properties file as the destination node, not the "To:" entry from the headers. If no default application server entry is specified in the integrationGateway.properties file, the follow error is generated:

<?xml version="1.0"?>
<IBResponse type="error">
<DefaultTitle>Integration Broker Response</DefaultTitle>
<StatusCode>20</StatusCode>
<MessageID>10201</MessageID>
<DefaultMessage>null</DefaultMessage>
</IBResponse>

You can specify destination node information in the SOAPAction field or HTTP query string.

Adding Nonrepudiation Signatures

If you’re working with a nonrepudiated message, its signature must be located at the same level as the message data.-The message doesn’t need to be formatted with the PeopleSoft rowset hierarchy, as long as it's enclosed in valid XML and has the signature section as specified by the W3C. The following template describes a nonrepudiation signature alongside the PeopleSoft rowset-based format message it represents, within the ContentSection element of the PeopleSoft XML message wrapper (the tags you must add for nonrepudiation are in bold):

<ContentSections>
   <ContentSection>
      <NonRepudiation>Y</NonRepudiation>
          <Data><?xml version="1.0"?><any_tag><data>
               <![CDATA[<?xml version="1.0"?>your_message_content]]></data><Signature><SignedInfo><CanonicalizationMethod/><SignatureMethod/><Reference><DigestMethod><DigestValue>...</DigestValue></DigestMethod></Reference></SignedInfo><SignatureValue>...</SignatureValue></Signature></any_tag>
      </Data>
   </ContentSection>
</ContentSections>

You can find more information about the proposed standard for XML signature syntax and processing at the W3C web site.

See XML Signature Syntax and Processing

See Implementing Nonrepudiation.

Submitting Cookies in HTTP Headers

The HTTP listening connector supports cookies. Cookies that are passed as part of a message request to the HTTP listening connector are processed, read, and manipulated by the receiving PeopleCode in the application. You enter cookies in the HTTP message header. For example:

Cookie: favoritecolor=green; path=/; expires Mon, 10-Dec-2007 13:46:00 GMT

In this example, the header entry would result in a cookie named favoritecolor. The value of favoritecolor is green. This cookie has a path of /, meaning that it is valid for the entire site, and it has an expiration date of December 10, 2007 at 1:46 p.m. Greenwich Mean Time (GMT).

See Handling Cookies.

Responses to Inbound Requests

PeopleSoft Integration Broker responds to inbound requests in one of three ways:

• For a successfully received synchronous transmission, the integration gateway passes the request to the integration engine.

  The integration engine generates and passes back through the listening connector a response in a format determined by the applicable node, service operation definition and routing definition for the request.

• For a successfully received asynchronous transmission, the integration gateway immediately returns a simple XML acknowledgment message.

  The following example shows a successful asynchronous acknowledgment:

  <?xml version="1.0"?>
  <IBResponse type="success">
     <DefaultTitle>Integration Broker Response</DefaultTitle>
     <StatusCode>0</StatusCode>
     <TransactionID>UNDERDOG.QE_SALES_ORDER_ASYNC_CHNL.20</TransactionID>
  </IBResponse>

• For an unsuccessful transmission, the integration gateway immediately returns a simple XML error message in a standard XML error format for all requests (except SOAP requests), if error handling is invoked in the integration gateway.

  The following is an example of this standard error response:

  <?xml version="1.0"?>
  <IBResponse type="error">
     <DefaultTitle>Integration Broker Response</DefaultTitle>
     <StatusCode/>
     <MessageID/>
     <DefaultMessage/>
     <MessageParameters>
        <Parameter/>
     </MessageParameters>
  </IBResponse>

Submitting SOAP Messages

SOAP messages support a subset of the HTTP message parameters— two required parameters and two optional parameters. You pass them to the HTTP listening connector in a SOAP-specific HTTP header. Concatenate them in a string, with each parameter preceded by a forward slash (/). They must appear in the following order:

http://peoplesoft.com/OperationName/RequestingNode/Password/DestinationNode

The following example shows where the parameter string belongs in a SOAP HTTP header:

POST /get_BindingDetail HTTP/1.1
Host: www.someOperator.com
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
SOAPAction: http://peoplesoft.com/PURCHASE_ORDER/MY_NODE/
PSFT_PASS/PSFT_NODE

Because the last two parameters are optional, you can exclude them; however, you must still include the forward slashes. This example excludes the password:

SOAPAction: http://peoplesoft.com/PURCHASE_ORDER/MY_NODE//PSFT_NODE

Consider the following points when submitting SOAP messages:

• The SOAPAction must always be in the HTTP header, not contained within the IBRequest XML.

• The SOAPAction format from previous PeopleTools releases is still supported. The format from previous releases has the parameters concatenated in a string separated by pound signs ("#"): SOAPAction: #PURCHASE_ORDER#MY_NODE#PSFT_PASS#PSFT_NODE

• For SOAP 1.2 requests the value is taken from the "action" in the Content-Type Content-type: application/soap+xml; action=<value used for SOAPAction> since the SOAPAction HTTP header is not used in SOAP 1.2.

If an error occurs on the integration gateway during processing, a SOAP-specific XML error is generated instead of a standard XML error. Following is an example of an error in SOAP-specific XML format:

<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Body>
      <SOAP-ENV:Fault>
         <faultcode>SOAP-ENV:Server</faultcode>
         <faultstring>Server Error</faultstring>
         <detail>
            <IBResponse type="error">
               <DefaultTitle>Integration Broker Response</DefaultTitle>
               <StatusCode>10</StatusCode>
               <MessageID>10731</MessageID>
               <DefaultMessage></DefaultMessage>
            </IBResponse>
         </detail>
      </SOAP-ENV:Fault>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Status Codes for Non-SOAP Messages

The following list summarizes HTTP status codes for non-SOAP messages:

• For an asynchronous message, HTTP status codes 200 to 299 indicate a message status of Success.

• For a synchronous message, the HTTP status code 200 indicates a message status of Success.

• HTTP status code 404 indicates that the server has not found anything matching the Request-URI. In this case, an ExternalSystemContactException is generated on the integration gateway and the message status goes to Retry.

• HTTP status code 503 indicates that the server is currently unable to handle the request due to temporary server overload or maintenance. In this case, an ExternalSystemContactException is generated on the integration gateway and the message status goes to Retry.

• All other HTTP status codes generate an ExternalApplicationException. The status of these messages goes to Error.

Status Codes for SOAP Messages

This section summarizes HTTP status codes for SOAP messages.

If you are following SOAP 1.1 standards, the HTTP status code 500 indicates an Error.

If you are following SOAP 1.2 standards, the following HTTP status codes apply:

• HTTP status code 400 can mean any of the following:

  • InvalidMessageException

  • MessageMarshallingException

  • MessageUnmarshallingException

  • Malformed HTTP/XML

• HTTP status code 405 indicates that the method is not POST.

• HTTP status code 415 indicates the content type is not text/xml.

• HTTP status code 500 can mean any of the following:

  • ExternalSystemContactException

  • ExternalApplicationException

  • GeneralFrameworkException

Setting Proxy Web Server Properties

To run the integration gateway behind a proxy server:

1. Set the gateway-level properties.

   Uncomment and add values for the properties in the integrationGateway.properties file section labeled Proxy webserver section.

   Property	Description
   ig.proxyHost	Enter the domain name of the proxy web server; for example: proxy.peoplesoft.com
   ig.proxyPort	Enter the port number of the proxy web server; for example: 80
   ig.nonProxyHost	Enter a list of hosts that should be accessed directly, instead of through the proxy server. The values can be a list of hosts, each seperated by a |, and in addition a wildcard character (*) can be used for matching. For example: For example: ig.nonProxyHosts=*.google.com|finance.yahoo.com

   The HTTP target connector reads these two properties and calls the setProxy function. In an outbound transaction, the request is redirected to the proxy server and the proxy server forwards the request to the destination URL.

2. Set the node-level property.

   You set the user ID and password required by the proxy server in the HEADER, Proxy-Authorization connector property. The integration gateway encodes the values that you provide, adds the required formatting, and sends it. The format is:

   userid:password