Complying With Message Formatting and Transmission Requirements

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>]]>

Note:

Psft_message_name is the name of the message definition in the PeopleSoft database.

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>]]>

Note:

Any_tag can be any tag that you want to use. This is an XML-DOM-compliant method of transmitting non-XML data.

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>

Note:

Psft_message_name and psft_node_name are the names of the message definition and the sending system's node definition in the PeopleSoft database.

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

WARNING:

Whether you send message parameters in the message wrapper or in the HTTP header, those parameters—including the password—aren't secure if you don't encrypt the message. You can secure messages by implementing SSL encryption.

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

WARNING:

URL query strings are always transmitted in clear text, so your parameters are visible to the world. This means that using a query string to send message parameters—such as a password—is highly insecure. Consequently, it is not recommended.

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.

Note:

If using SOAP, PeopleSoft Integration Broker takes all IBInfo from the SOAPAction field, not from the HTTP header 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>

Note:

Any_tag can be any tag that you want to use, such as My_NR_Message.

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

Important:

In PeopleSoft Integration Broker, all signatures use line feeds for newlines, so the nonrepudiation signature cannot include any carriage return and line feed (CR/LF) pairs. A non-PeopleSoft application must strip out the carriage returns before inserting the signature and sending the message.

Note:

To handle nonrepudiated messages, you must install node-based digital certificates on the sending and receiving systems and configure the message and channel definitions to use the nonrepudiation feature.

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 Integration Broker: 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://example.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://example.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.

WARNING:

When you send message parameters in the SOAP header, those parameters—including the password—aren't secure if you don't encrypt the message. You can secure messages by implementing SSL encryption.

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>