Troubleshoot External Endpoints Failures with CustomIntegrationHelper
Summary
If your CustomIntegrationHelper connection to an external endpoint fails in Windchill+ due to incomplete certificate chains or missing trusted certificates, provide a complete PEM certificate bundle (root + intermediate certificates) in the connection configuration using the server_cert property. Windchill+ requires a full certificate chain to create a custom trust store for each connection.
Symptoms
You may encounter one or more of the following issues when invoking external endpoints:
• External connection fails during orchestration
• TLS or SSL handshake errors
• Connection works outside Windchill+ but fails within orchestration
• Failures occur even though the endpoint certificate is issued by a trusted CA
What Causes This Issue
Even when an endpoint uses a trusted certificate authority, Windchill+ does not automatically inherit the system trust store.
During orchestration, Windchill+:
• Creates a custom trust store per external connection
• Requires explicit input of trusted certificates
• Fails if the certificate chain is incomplete
Common causes include:
• Missing intermediate CA certificates
• Missing root CA certificate
• Certificate bundle not provided during connection setup
Resolution Overview
To resolve external endpoint failures:
1. Collect the full certificate chain from the endpoint
2. Combine certificates into a single PEM bundle
3. Reference the PEM bundle in the connection JSON
4. Re-run the captureExternalConnections utility
5. Allow orchestration and rollout to complete
Step‑by‑Step Resolution
Follow these steps to resolve the failures:
Step 1: Collect Certificates from the Endpoint
Retrieve the certificate chain directly from the external endpoint using OpenSSL:
openssl s_client -connect <endpoint-host>:443 -showcerts </dev/null 2>/dev/null \| sed -n '/BEGIN CERTIFICATE/,/END CERTIFICATE/p'
This command outputs:
• Leaf (server) certificate
• Intermediate CA certificates (if provided by the webserver)
• Root CA certificate (if provided by the webserver)
Step 2: Identify Missing Certificates
Review the output and verify whether:
• All intermediate CA certificates are present (if applicable)
• The root CA certificate is included
If any certificates are missing:
Step 3: Create a PEM Bundle
Combine the required certificates into one PEM file, in this order (recommended):
1. Intermediate CA certificates
2. Root CA certificate
3. (Optional) Server certificate
Example file: server_cert_bundle.pem
Step 4: Update the Connection JSON Configuration
1. Store the PEM bundle on the system where you run the utility.
2. In the JSON configuration, locate the relevant connection.
3. Add the server_cert property.
Example:
"server_cert": "/path/to/server_cert_bundle.pem"
Step 5: Rerun the captureExternalConnections Utility
• Resubmit the updated JSON file
• Rerun the captureExternalConnections utility
• Ensure apply_at is:
◦ In ISO 8601 format
◦ Set at least an hour in the future to allow rollout
Step 6: Allow Orchestration to Complete
During orchestration, Windchill+ automatically:
• Creates a custom trust store for the connection
• Applies the updated certificate configuration
• Restarts Windchill as part of normal orchestration behavior
• Completes changes during the rollout window
Additional Guidance
• If multiple endpoints use the same issuer or root certificates:
◦ You can reuse the same PEM bundle for those connections
◦ The bundle does not need to include the leaf certificate in such cases
• If you update connection details:
◦ Submit a new JSON file with an updated apply_at timestamp
◦ Allow the orchestration process to apply the changes