HttpListeningConnector

The HttpListeningConnector has been the work horse for 3rd party integrations with PeopleSoft for years. You can use it to post both asynchronous and synchronous service operations. This is the connector you use if you are NOT using SOAP and NOT using REST.

Then general characteristics of the listener:

• All service operations are invoked using the same URL.
  • URL Pattern: https://host:port/PSIGW/HttpListeningConnector
• The HttpListeningConnector accepts all data via an HTTP POST method.
  • It cannot handle any other HTTP method.
• The client sets HTTP headers to tell PeopleSoft what web service operation should be invoked
• The client sets HTTP headers to pass security information and identify who it is.
• HTTP header parameters are case-sensitive
• URL query string parameters can be sent and the handler code can parse them.
• Cookies can be set and the handler code can parse them.
• HTTP Form posts (application/x-www-form-urlencoded) are NOT supported.
• Generally the request body contains XML but other formats can be accepted.
• Warning: The HttpListeningConnector almost always returns an HTTP status code of 200 (success) even when there is an error. There will generally always be an XML response on the HTTP body, so it is a good idea to actually log that and also parse it for error messages. This can be confusing as heck so be warned that the HTTP status codes coming from the PSIGW HttpListeningConnector are meaningless.
  • The handler code cannot set HTTP Status codes.
• Most of the parameters passed in HTTP Headers can also be passed in the query string instead of headers. However, I find it is easier to pass headers and items like passwords are less likely to get caught in logs by using headers.

High Level Steps

The high level steps to integrate with this connector are as follows. There is a full example in Synchronous HTTP Post to PeopleSoft Integration Broker

• Set up a new OPRID that will have access to only the service operations your client will invoke. I like to use a naming standard of {NODE_NAME}_NODE_USER.`
• Create a new “External” node in your PeopleSoft database that will represent your client application. Create a new node for each application. Do not re-use an existing node. Setup a “node password”.
  • Add the user created above to the “default user id”
• Create Message Objects
• Create Service
• Create Service Operation
• Create Handler Code
• Add Handler code to Service Operation
• Add routing to your “default local node” to the new node you created.
• Test with your client.

Listening Connector Parameters

You have to submit different parameters to this connector.

The most use parameters are:

• OperationName (required): External Alias. This is the service operation name and it is case-sensitive. If you are using a “from node” make sure the routing for your node matches what you are submitting. This is a common mistake.
• From (required): The node defined to represent the client application.
• To (required): The PeopleSoft node name that is the target of the message.
• Password: If you have defined a node password on the From node that value is passed here. It is NOT encoded in any way. Do not include this if there is no node password.
• ExternalMessageID: This allows you to pass an ID of the external messaging system. This might be better to pass in the payload.

There are some other parameters that are not used very often.

• OrigUser: When messages pass across different nodes, the original user who sent the request may need to be passed as meta-data. This can be accessed in the handler using the IBInfo PeopleCode class.
• OrigNode: When messages pass across different nodes, the original node who sent the request may need to be passed as meta-data. This can be accessed in the handler using the IBInfo PeopleCode class.
• OrigProcess: When messages pass across different nodes, the original process who send the request may need to be passed as meta-data. This can be accessed in the handler using the IBInfo PeopleCode class.
• OrigTimeStamp: When messages pass across different nodes, the original time stamp of the request may need to be passed as meta-data. This can be accessed in the handler using the IBInfo PeopleCode class.
• FinalDestination: When messages pass across different nodes, the final node that this should go to may need to be passed as meta-data. This can be accessed in the handler using the IBInfo PeopleCode class.
• SubQueue: This applies to asynchronous message. This can be used to set a subqueue if the queue is partitioned.
• NonRepudiation: (Y|N) - Allows you to set the non-repudiation flag. Consult Peoplebooks. I have never seen this used.
• OperationType: (sync|async|ping) These allow you to tell what type of operation it is. I have never seen this used.

Ways to Pass Parameters

• Header
• Query String
• IBRequest Wrapper

HTTP Header Example

Here is an HTTP example of submitting a service operation passing all the parameters using HTTP Header.

POST https://ib.cedarhillsgroup.com/PSIGW/HttpListeningConnector HTTP/1.1
OperationName: CHG_SYNC_TEST.v1
Content-Type: text/xml
From: CHG_TEST_NODE
To: PSFT_CS
Password: vase-lawless-realty

<?xml version="1.0"?> <helloworld/>

HTTP Query String Example

You can also pass the parameters using URL query string. That HTTP example would look like this.

POST https://nusmsg.soar.cci.nu.edu/PSIGW/HttpListeningConnector?Operation=CHG_SYNC_TEST.v1&From=CHG_TEST_NODE&To=PSFT_CS&%20Password=vase-lawless-realty HTTP/1.1
Content-Type: text/xml
Accept: */*

<?xml version="1.0"?> <helloworld/>

IBRequest Wrapper

You can wrap your message in a special XML message called the IBRequest. This is very similar to SOAP. If PeopleSoft sees this wrapper it will pull all the parameters out of that wrapper. I don’t recommend doing this but it is possible for strange edge cases.

See Working With the HTTP Connectors

POST https://ib.cedarhillsgroup.com/PSIGW/HttpListeningConnector HTTP/1.1
Content-Type: text/xml

<?xml version="1.0"?>
<IBRequest>
    <From>
        <RequestingNode>CHG_TEST_NODE</RequestingNode>
        <Password>vase-lawless-realty</Password>
    </From>
    <ExternalOperationName>CHG_SYNC_TEST.v1</ExternalOperationName>
    <OperationType>sync</OperationType>
    <To>
        <DestinationNode>PSFT_CS</DestinationNode>
    </To>
    <ContentSections>
        <ContentSection>
            <Headers>
            <version>VERSION_1</version>
            </Headers>
            <Data><![CDATA[<?xml version="1.0"?> <helloworld/>]]></Data>
        </ContentSection>
    </ContentSections>
</IBRequest>

Testing Connectivity

Before you can test any integration with this connector you should check if your integration client can connect. If you know your integration broker server hostname then you would perform a test like this:

Standard HTTP GET

GET https://ib.cedarhillsgroup.com/PSIGW/HttpListeningConnector

Curl Version:

curl https://ib.cedarhillsgroup.com/PSIGW/HttpListeningConnector

The response you are looking for would look something like the following HTTP Response.

Even though the response says Integration Gateway failed while processing the message which looks like error it is NOT. If you are just testing connectivity then the message proves you are hitting the PeopleSoft integration broker. Since we did NOT sent a POST request with a body message, the listener stopped the requested and returned an error. However, for just testing connectivity that message means you have connected.

HTTP/1.1 200 OK
connection: close
content-length: 365
content-type: text/xml; charset=UTF-8
date: Sun, 22 May 2022 13:49:30 GMT
strict-transport-security: max-age=31536000; includeSubDomains; preload

<?xml version="1.0"?>
<IBResponse type="error">
  <DefaultTitle>Integration Broker Response</DefaultTitle>
  <StatusCode>20</StatusCode>
  <MessageSet>158</MessageSet>
  <MessageID>10403</MessageID>
  <DefaultMessage> Integration Gateway failed while processing the message. </DefaultMessage>
  <MessageParameters>
    <Parameter>ContentSection</Parameter>
  </MessageParameters>
</IBResponse>

Security options

• Node Password
• PS_TOKEN - Refer to Why Exclude PSFT Auth Tokens in Integration Broker?
• Mutual TLS
• Anonymous Node