HttpTargetConnector - HTTP Target Connector

The HttpTargetConnector is the most common “Target Connector” that used to contact non-PeopleSoft systems from the integration broker. This is where PeopleSoft is acting as the HTTP Client.

For outbound integrations, I generally like to use Apache HttpClient from PeopleCode if possible. However, there are times when you need to rely on the integration broker to send information to external systems. A few examples of this:

• Using some vendor delivered integration
• Posting delivered “%_SYNC” messages to external systems (PERSON_BASIC_SYNC, DEPT_SYNC, etc)

This “target connector” enables the PeopleSoft system to “speak” HTTP and form HTTP operation to external systems. Generally, this is an HTTP POST but other operation are supported.

The configuration steps for connecting to an external HTTP URL is the following:

• Configure a new PeopleSoft Node representing the external system.
• Get your system administrators to import the external TLS certificates
• Test Connectivity
• Create Service Operation (if new)
• Configure Service Operation routing

Defining the Node

For outbound HTTP integrations, a node defines the existence of the external system. Think of this node as a placeholder for the external system. Each unique external system should have their own node representing that system. Do NOT share nodes.

Two places exist where you can define the URLs and any authentication tokens for the external system.

• Node level
  • If your external integration server only has one URL where PeopleSoft is posting to, I would recommend putting all your URL and connection information on the node that represents the external system.
  • I like putting things at the node level because most PeopleSoft administrators retain these tables in dev/test when refreshing from production. This means that after a database refresh your DEV system will NOT try to connect to external production systems.
    • PSMSGNODEDEFN
    • PSNODECONPROP
    • PSNODEPROP
    • PSNODETRX
    • PSNODEURITEXT
    • PSNODTRXCONPROP

Here is an image of an external node. A few things to note about node setup in addition to what is documented in the Node Best Practices section

• Node Type = “External”
• Authentication = None - For outbound nodes only, then this is OK.
• Default User ID: Use a fake user that has zero permission. This is a required field. Do NOT put a superuser account here.

The “connectors” tab has a few items that you can fill in.

• HTTPPROPERTY - Method - Post: Here we are defining that the node is always going to do an “HTTP POST” method.
• PRIMARYURL - URL - https://httpbin.org/anything - This is where we are telling the IB to post to. This can be overridden at the Service Operation level routing.
  • For a Ping test, this is the URL that will be used. The target end point needs to actually reply to an HTTP GET with a 200 or the PING test will not work. Even though we said “HTTP POST” in the configuration here there are times when PeopleSoft will always perform an HTTP GET to test if it can connect.

• Service Operation routing level
  • You can also place URLs and authentication tokens at the service operation routing level.
  • If your system administrators retain the following tables during database refreshes and do NOT take the production values, then your DEV system will NOT try to connect to production end-points
    • PSIBRTNGDEFN
    • PSIBRTNGSUBDEFN
    • PSRTNGDFNPARM

This article cannot anticipate your integration specifics and exactly how and where your URLs are set up. However, it is generally desirable to have a base URL setup on the node connector properties, so you can test the connection (after your system administrators complete the steps below.)

Trusting the TLS certificates

One of the most frustrating parts of using the HttpTargetConnector is that it is NOT able to automatically connect to HTTPS/TLS end-points. Your system administrators must import the external systems certificates into the Integration broker key store (pskey). Additionally, as certificates expire your administrators must import those updated certificates. These often expire on a yearly basis (or every 90 days with Let’s Encrypt), so you must keep on top of the certificates using some internal ticketing system.

This will generally manifest in an error in the errorLog.html log with message catalog 158, 10721 (“Integration Gateway - External System Contact Error”) and one or both of these exceptions:

• javax.net.ssl.SSLHandshakeException: java.security.cert.CertificateException: Untrusted Server Certificate Chain
• HttpTargetConnector:ExternalSystemContactException unknown certificate

The following Oracle Support document explains how to do this:

Oracle Support Doc ID 658744.1 - Error “Integration Gateway - External System Contact Error (158,10721)” with “Untrusted Server Certificate Chain” or “unknown certificate” on HTTPS URL (Doc ID 658744.1)

Step-by-Step: Importing Root and Intermediate CA Certificates into pskey

To trust an external HTTPS endpoint, you must download its Root CA and any Intermediate CA certificates in Base-64 encoded X.509 (.cer / .pem) format and import them into the Integration Broker gateway keystore (pskey) on the PIA WebLogic web server using pskeymanager.

Download the Certificate Chain

Option A — Using Java keytool directly on the PeopleSoft Web Server (Easiest): Java’s keytool can fetch the entire certificate chain (Root + Intermediates) directly from the remote host in PEM format without needing a web browser:

keytool -printcert -rfc -sslserver api.example.com:443 > chain.pem

Save each -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- block for the Root CA and Intermediate CA into separate files (root_ca.cer and intermediate_ca.cer) so each gets its own clean alias in the keystore.

Option B — From Chrome or Edge Browser:

• Open https://api.example.com in your web browser.
• Click the tune / padlock icon in the address bar > Connection is secure > Certificate is valid.
• Go to the Details tab.
• Under Certificate Hierarchy, select the top-level Root CA, click Export, and choose Base64-encoded ASCII, single certificate (*.pem, *.crt).
• Repeat for the Intermediate CA directly underneath the Root CA.

Import into pskey using pskeymanager

On the Integration Broker Web Server (where WebLogic / PIA runs), PeopleSoft provides pskeymanager in piabin, which is a wrapper around keytool pre-configured to point to <PIA_HOME>/webserv/<DOMAIN>/piaconfig/keystore/pskey (or the path configured in integrationGateway.properties under secureFileKeystorePath).

Navigate to piabin on the web server:

# Linux
cd $PS_CFG_HOME/webserv/peoplesoft/piabin

# Windows
cd %PS_CFG_HOME%\webserv\peoplesoft\piabin

List existing certificates first (this also verifies your keystore password; the delivered default password is password):

# Linux
./pskeymanager.sh -list

# Windows
pskeymanager.cmd -list

Import both the Root CA and Intermediate CA certificates with unique -alias names:

# Linux - Import Root CA
./pskeymanager.sh -import -alias example_root_ca -file /path/to/root_ca.cer

# Linux - Import Intermediate CA
./pskeymanager.sh -import -alias example_intermediate_ca -file /path/to/intermediate_ca.cer

REM Windows - Import Root CA
pskeymanager.cmd -import -alias example_root_ca -file C:\path\to\root_ca.cer

REM Windows - Import Intermediate CA
pskeymanager.cmd -import -alias example_intermediate_ca -file C:\path\to\intermediate_ca.cer

When prompted:

• Enter the keystore password (default is password, unless changed in integrationGateway.properties under secureFileKeystorePasswd).
• Type yes when asked Trust this certificate? [no]:.

Automated Windows PowerShell Script (Download, Split, and Import)

To automate this entire process on a Windows PIA web server—downloading the remote TLS certificate chain, splitting out Intermediate and Root CAs, and non-interactively importing each certificate into pskey via pskeymanager.cmd—use the Import-PsftTlsChain.ps1 script provided in the TLS, SNI & Keystore Troubleshooting Guide.

Restart the Web Server

Because WebLogic caches the pskey truststore in memory at startup, you must restart the PIA WebLogic web server for the Integration Gateway to pick up the newly imported certificates:

# Linux
cd $PS_CFG_HOME/webserv/peoplesoft/bin
./stopPIA.sh
./startPIA.sh

REM Windows (or restart the PeopleSoft PIA Windows Service)
cd %PS_CFG_HOME%\webserv\peoplesoft\bin
stopPIA.cmd
startPIA.cmd

I hope Oracle improves this at some point in the future to make these automatically trusted.

SNI Certificates - Using HostName Instead of IP Address

When PeopleSoft makes an outbound connection (PeopleSoft acting as HTTP Client), PeopleSoft Integration Broker will resolve the IP address of the host name in the URL. Then the integration broker will use the IP address to connect to the external system. This can cause problems with modern cloud hosted apps that are behind cloud firewalls or on cloud hosted PAASes. Many of these systems use SNI certificates. This is a certificate that is tied to the host name and NOT the IP address. This is a security feature that allows multiple SSL certificates to be hosted on the same IP address.

It is NOT obvious when a server you are trying to integrate with uses SNI. You can google around for various tricks to find out or ask the server administrators.

What Happens When You Hit an SNI Error

For SNI URLs, PeopleSoft will NOT connect because psft.pt8.pshttp.https.HttpsClient initiates the TLS handshake using the resolved IP address rather than the domain name, omitting the SNI server_name extension in the TLS ClientHello. The remote reverse proxy or cloud load balancer immediately drops the connection during the handshake.

In errorLog.html, this looks like:

• Description: HttpTargetConnector:ExternalSystemContactException Remote host terminated the handshake
• Exception: PeoplesoftListeningConnector: GeneralFrameworkException
• MessageCatalog: MessageSet: 158, MessageID: 10721 (“Integration Gateway - External System Contact Error”)
• MessageParms: IOException: The host couldn't be resolved. (Note: this parameter text is a misleading default string populated by PeopleSoft when HttpTargetConnector throws an ExternalSystemContactException—DNS actually resolved fine, and the failure happened during the TLS handshake).
• Stack Trace:

javax.net.ssl.SSLHandshakeException: Remote host terminated the handshake
	at java.base/sun.security.ssl.SSLSocketImpl.handleEOF(SSLSocketImpl.java:1562)
	at java.base/sun.security.ssl.SSLSocketImpl.decode(SSLSocketImpl.java:1391)
	at java.base/sun.security.ssl.SSLSocketImpl.readHandshakeRecord(SSLSocketImpl.java:1296)
	at java.base/sun.security.ssl.SSLSocketImpl.startHandshake(SSLSocketImpl.java:416)
	at java.base/sun.security.ssl.SSLSocketImpl.startHandshake(SSLSocketImpl.java:388)
	at psft.pt8.pshttp.https.HttpsClient.doConnect(HttpsClient.java:248)
	...
	at com.peoplesoft.pt.integrationgateway.targetconnector.HttpTargetConnector.send(HttpTargetConnector.java:921)
Caused by: java.io.EOFException: SSL peer shut down incorrectly
	at java.base/sun.security.ssl.SSLSocketInputRecord.read(SSLSocketInputRecord.java:489)

How to Make PeopleSoft Use the Host Name Instead of the IP Address

You have to set the ig.UseDomainName.ExternalOperationNames property in the integrationGateway.properties file.

You can list out the service operations that you want to use the domain name in the URL. This is a comma separated list. For example, ig.UseDomainName.ExternalOperationNames=IB_GENERIC.V1,ping. This makes the Integration Gateway use the host name when performing the SSL negotiation. This is important because the certificate is tied to the domain name and not the IP address.

• Always include both the external operation name (matching <ExternalOperationName> in the errorLog.html request XML, which is <RoutingAlias>.<Version> or <OperationName>.<Version>) and ping.
• Here I am using the IB_GENERIC.V1 and ping service operations. The ping is important because both manual Ping Node tests and automatic asynchronous PSNODESDOWN retry checks send <OperationType>ping</OperationType> requests.

This really should be on by default in PeopleTools. It is a common issue that I see when integrating with modern cloud hosted systems.

Test Connectivity - Ping Node

There are a few ways that you can test connectivity. You can read more on ping in the Node Ping Deep Dive

The main connection test can come from the “node ping”.

• This assumes that you have a URL setup in the node “connection properties”.
• A successful test will look like this:
• The “Ping” will do an HTTP GET using the information on the connector properties. Even if you have HTTP POST configured, a PING will always do an HTTP GET.
  • The server end-point must reply to HTTP GET with a HTTP 200 status code.
  • If the GET requires a Authentication header, then you will have to put that in the routing properties and it will be sent with the GET.

• An error response would look like this:

If you have a connection error the best thing to do is look in the errorLog.html file (see troubleshooting section below).

The other alternative to test connectivity is to actually send a message after you complete the steps below.

Your PeopleSoft server must be able to resolve the DNS entry and be allowed to connect to that IP. Some server admins limit what servers can be communicated with for security reasons. You will have to work with your server team to determine this.

Create Service Operations

Next you need to create your service operation setup. This could be outbound synchronous or asynchronous. For this example, we are just going to use the delivered PERSON_BASIC_SYNC.

Configure Service Operation routing

For this article, we are going to be configuring the PERSON_BASIC_SYNC asynchronous service operation to deliver to my new node. This is as easy as creating a new routing that delivers from the “local node” to my new external node.

In the image below we have the “Sender” and “receiver” nodes set.

In the connector properties, it will look like this by default. If you want to rely on the URL and other properties from the node configuration, then leave it this way. If you set the “Connector ID” field to “HTTPTARGET” then the IB will expect your URL and any authentication to come from this routing. If they are blank, then it will not be able to deliver by you “node” will still respond to a ping.

If you want to rely on the URL and authorization to be on the routing because the URL may be different from the NODE, then your routing connector properties will look something like this.

Troubleshooting HttpTargetConnector

• Pinging Node
  • External Integration
• Asynchronous Publication contracts stay in “new” status
  • select * from PSNODESDOWN

errorLog.html and msgLog.html

On the integration broker gateway web server, there are two useful files for debugging. These are the errorLog.html and msgLog.html.

• PS_HOME\webserv\peoplesoft\applications\peoplesoft\PSIGW.war\WEB-INF\errorLog.html
• PS_HOME\webserv\peoplesoft\applications\peoplesoft\PSIGW.war\WEB-INF\msgLog.html

If you are having issues connecting or pinging, then there will be very useful information in errorLog.html. This will have errors for different service operations. In this file, you will find “requests” and responses. This file can be confusing so take your time to find the correct message that corresponds to your connection attempt.

In one of the “request” section you will find some XML that will NOT be formatted nicely like this:

<?xml version="1.0"?>
<IBInfo>
  <ExternalOperationName><![CDATA[PERSON_BASIC_SYNC.INTERNAL]]></ExternalOperationName>
  <OperationType>ping</OperationType>
  <From>
    <WebServerInfo><![CDATA[]]></WebServerInfo>
    <RequestingNode><![CDATA[PSFT_CS]]></RequestingNode>
    <Protocol>http</Protocol>
    <NodePassword>***deleted for security purposes****</NodePassword>
    <ExternalUserName><![CDATA[CHG_EXTERNAL_TEST_USER]]></ExternalUserName>
    <WS-Security>
      <WSTokenType><![CDATA[]]></WSTokenType>
      <WSTokenEncrypted></WSTokenEncrypted>
      <WSTokenSigned></WSTokenSigned>
      <WSTokenEncryptLevel></WSTokenEncryptLevel>
      <WSRequestAliasName><![CDATA[]]></WSRequestAliasName>
    </WS-Security>
    <SAML-CertAlias><![CDATA[]]></SAML-CertAlias>
    <SAML-QualifierName><![CDATA[]]></SAML-QualifierName>
    <SAML-Issuer><![CDATA[]]></SAML-Issuer>
    <SAML-SubjectName><![CDATA[]]></SAML-SubjectName>
    <SAML-Signature><![CDATA[]]></SAML-Signature>
    <SAML-TokenData>***deleted for security purposes****</SAML-TokenData>
    <OAUTH2-TokenData><![CDATA[]]></OAUTH2-TokenData>
    <OAUTH2-CloudSite><![CDATA[]]></OAUTH2-CloudSite>
    <OAUTH2-PublicSignKey><![CDATA[]]></OAUTH2-PublicSignKey>
    <OAUTH2-Issuer><![CDATA[]]></OAUTH2-Issuer>
    <OAUTH2-ClientID><![CDATA[]]></OAUTH2-ClientID>
    <OAUTH2-Subject><![CDATA[]]></OAUTH2-Subject>
    <OAUTH2-ServerType><![CDATA[]]></OAUTH2-ServerType>
    <OAUTH2-Audience><![CDATA[]]></OAUTH2-Audience>
    <OAUTH2-Tenant><![CDATA[]]></OAUTH2-Tenant>
    <OAUTH2-RefToken><![CDATA[]]></OAUTH2-RefToken>
    <URIResourceIndex>-1</URIResourceIndex>
    <SegmentsUnOrder>N</SegmentsUnOrder>
    <DeviceInfo>
      <Width>0</Width>
      <Height>0</Height>
      <PixelRatio>0</PixelRatio>
      <Touch>0</Touch>
      <GeoLocation>0</GeoLocation>
      <WebSockets>0</WebSockets>
      <WebWorkers>0</WebWorkers>
      <DatePicker>0</DatePicker>
      <DtPicker>0</DtPicker>
      <TimePicker>0</TimePicker>
      <Dnd>0</Dnd>
      <SessionStorage>0</SessionStorage>
      <LocalStorage>0</LocalStorage>
      <History>0</History>
      <Canvas>0</Canvas>
      <SVG>0</SVG>
      <PostMessages>0</PostMessages>
      <HC>0</HC>
    </DeviceInfo>
  </From>
  <To>
    <DestinationNode><![CDATA[CHG_EXTERNAL_TEST]]></DestinationNode>
  </To>
  <ContentSections>
    <ContentSection>
      <ID>ContentSection0</ID>
      <ContentType>text/plain; charset=UTF-8</ContentType>
      <ContentTransfer>8bit</ContentTransfer>
      <NonRepudiation>N</NonRepudiation>
    </ContentSection>
  </ContentSections>
  <Connector>
    <ConnectorClassName><![CDATA[HttpTargetConnector]]></ConnectorClassName>
    <ConnectorParameters>
      <ConnectorParam>
        <Name>%3c!%5bCDATA%5bMethod%5d%5d%3e</Name>
        <Value>%3c!%5bCDATA%5bGET%5d%5d%3e</Value>
      </ConnectorParam>
      <ConnectorParam>
        <Name>%3c!%5bCDATA%5bURL%5d%5d%3e</Name>
        <Value>%3c!%5bCDATA%5bhttps%3a%2f%2fwww.cedarhillsgroup.com%5d%5d%3e</Value>
      </ConnectorParam>
    </ConnectorParameters>
    <ConnectorHeaders>
      <Header>
        <Name>%3c!%5bCDATA%5bsendUncompressed%5d%5d%3e</Name>
        <Value>%3c!%5bCDATA%5bY%5d%5d%3e</Value>
      </Header>
    </ConnectorHeaders>
  </Connector>
  <AttachmentSection ResponseAsAttachment="N"></AttachmentSection>
</IBInfo>

Lets look at the “Connector” section which actually has URL encoded values which are hard to read.

 <Connector>
    <ConnectorClassName><![CDATA[HttpTargetConnector]]></ConnectorClassName>
    <ConnectorParameters>
      <ConnectorParam>
        <Name>%3c!%5bCDATA%5bMethod%5d%5d%3e</Name>
        <Value>%3c!%5bCDATA%5bGET%5d%5d%3e</Value>
      </ConnectorParam>
      <ConnectorParam>
        <Name>%3c!%5bCDATA%5bURL%5d%5d%3e</Name>
        <Value>%3c!%5bCDATA%5bhttps%3a%2f%2fwww.cedarhillsgroup.com%5d%5d%3e</Value>
      </ConnectorParam>
    </ConnectorParameters>
    <ConnectorHeaders>
      <Header>
        <Name>%3c!%5bCDATA%5bsendUncompressed%5d%5d%3e</Name>
        <Value>%3c!%5bCDATA%5bY%5d%5d%3e</Value>
      </Header>
    </ConnectorHeaders>
  </Connector>

After we “URL Decode” them with your text editor or online tool, then the values will become apparent.

 <Connector>
    <ConnectorClassName><![CDATA[HttpTargetConnector]]></ConnectorClassName>
    <ConnectorParameters>
      <ConnectorParam>
        <Name><![CDATA[Method]]></Name>
        <Value><![CDATA[GET]]></Value>
      </ConnectorParam>
      <ConnectorParam>
        <Name><![CDATA[URL]]></Name>
        <Value><![CDATA[https://httpbin.orgx/anything]]></Value>
      </ConnectorParam>
    </ConnectorParameters>
    <ConnectorHeaders>
      <Header>
        <Name><![CDATA[sendUncompressed]]></Name>
        <Value><![CDATA[Y]]></Value>
      </Header>
    </ConnectorHeaders>
  </Connector>

In this case, I had a typo in the URL and I had orgx where org should have been. This is the only way to really debug these connection issues.

Depending on the integrationGateway.properties value for ig.log.level, you may also have detailed request/reply information for each message happening in the gateway. You don’t want to log too much information in production. However, it is common for a non-production to have a more robust logging setting.

Publication Contracts stay in “NEW” or “RETRY” status

For asynchronous integrations to external nodes, publication contracts in PSAPMSGPUBCON can get stuck in RETRY (PUBCONSTATUS = 5) and subsequent contracts stay in NEW (PUBCONSTATUS = 1), and nothing you do on the main monitor page will resolve it.

When an outbound connection fails (for example, due to an SNI handshake error, an untrusted certificate, or a temporary network outage), Integration Broker:

• Places the failed publication contract(s) in RETRY status (PUBCONSTATUS = 5) and leaves newer queued contracts in NEW status (PUBCONSTATUS = 1).
• Inserts a row into PSNODESDOWN for that MSGNODENAME, TRXTYPE, IB_OPERATIONNAME, VERSIONNAME, and ROUTINGDEFNNAME.
• Periodically sends an automated <OperationType>ping</OperationType> (HTTP GET) to the target URL with exponential backoff (e.g., every 1, 2, 4, 5, 8, 9 minutes), which you will see repeating in errorLog.html if the connection is still failing.
• Will NOT attempt to deliver the queued POST messages again until the HTTP GET ping returns an HTTP 200 status code. If your endpoint does not support HTTP GET, or if ping is missing from ig.UseDomainName.ExternalOperationNames on an SNI host, the node remains marked down indefinitely.

You can check for down nodes and stuck publication contracts with SQL:

-- Check if any external nodes/operations are marked down
SELECT MSGNODENAME, TRXTYPE, IB_OPERATIONNAME, VERSIONNAME, ROUTINGDEFNNAME, EXTOPERATIONNAME
  FROM PSNODESDOWN;

-- Inspect publication contracts stuck in RETRY (5) or NEW (1)
SELECT IBTRANSACTIONID, QUEUENAME, IB_OPERATIONNAME, VERSIONNAME, SUBNODE,
       ROUTINGDEFNNAME, PUBCONSTATUS, STATUSSTRING, RETRYCOUNT, LASTUPDDTTM
  FROM PSAPMSGPUBCON
 WHERE PUBCONSTATUS IN (1, 5)
 ORDER BY CREATEDTTM DESC;

There is a documented way to try to force these to retry that often works:

• PeopleTools > Integration Broker > Service Operations Monitor
  • Go to the “Publication Contracts” tab
  • There is a link labeled “Transaction Retry Queue”.
  • You can force a retry from there.

If that does NOT work, then delete the rows from PSNODESDOWN and bounce the IB application server. This assumes of course that PeopleSoft can connect to the external system and that the external system is up and running.

See Also

• TLS, SNI & Keystore Troubleshooting — Dedicated step-by-step runbook for diagnosing 158, 10721 SSL handshake errors, importing Root/Intermediate CAs with pskeymanager, configuring SNI (ig.UseDomainName.ExternalOperationNames), and clearing PSNODESDOWN retry loops.
• PeopleSoft as HTTP Client
• Node Ping Deep Dive
• IB Server Cheat Sheet