Customization > Integration to External Systems > Support to Allow Outbound HTTPs Calls to Public Endpoints > Share Deployment-Specific External Connection Information with PTC
Share Deployment-Specific External Connection Information with PTC
Using the captureExternalConnections utility, you can share deployment-specific external connection information with PTC. This allows multiple Windchill+ deployments to connect to separate URLs of external systems. All deployment-specific external URLs and secrets are available at runtime and can be populated specifically for each Windchill+ deployment such as development, test, and production.
When a Windchill+ production deployment is cloned to create a development or test environment, the external endpoint URLs specified in the production may become operational in the development or testing environment and lead to data corruption. To prevent such cross-environment connections, it is important to share deployment-specific external connection information with PTC.
This external connection information is then used by your Windchill+ customization, created using the CustomIntegrationHelper API, to communicate with the provided endpoints. When you submit separate connection information for each Windchill+ deployment, the same customization code can be used for different Windchill+ deployments. You can submit your customization using the Code and Configuration (CCD) Utility. Refer to the applicable Windchill Javadoc for more information on the APIs available in CustomIntegrationHelper.
The same customization code submitted using the CCD utility can be used with different Windchill+ deployments but the external connections information (json parameters) shared using the captureExternalConnections utility is specific to each Windchill+ deployment.
To run this utility, ensure that you have the following information available,
• Access to the captureExternalConnections utility.
• BLOB_SAS_URL provided by PTC through email.
• Public key for encrypting secrets provided by PTC through email.
• client-keycertchain — A client key chain is required only when your endpoint requires a client certificate.
• server-certchain — A server certificate chain is required only when your endpoint is a non-public endpoint.
* 
When a Windchill+ deployment is requested, a Blob SAS URL to the blob containing encrypted connection information is received as an email attachment from PTC, along with the Public Key for the encryption of connection information. You may receive other emails containing Blob SAS URLs, but in the capture external connections utility, you must enter the Blob SAS URL that is received along with the Public Key.
Steps to Run the Utility
1. Run the following command to generate a template JSON file:
${WT_HOME}/bin/captureExternalConnections.sh -t <template-file-path>
In <template-file-path>, specify the path to the JSON file.
2. Create a JSON file based on the instructions and constraints mentioned in the template file. The JSON file should contain connection information about your deployment-specific endpoints. For more information, see section Information to be Provided in the JSON File below.
3. In the same terminal, execute the following command to capture the secrets locally:
${WT_HOME}/bin/captureExternalConnections.sh -f <json-file-path>
In <json-file-path>, specify the path to the JSON file containing your external connection information.
On successful execution of the script, the following message appears: “Connection information submitted successfully.”
* 
• Providing a BLOB_SAS_URL and public key for encryption are mandatory even for capturing connection information locally.
• For capturing external endpoints, using the apply_at parameter in the JSON file is optional. If this parameter is skipped, the connection information rollout to PTC will not be executed. However, you can configure your local Windchill deployment to use the provided connection information.
Template JSON File
{
"blob_sas_url": "http://samplestorageaccount.blob.core.windows.net/connection-yaml-tests/connectionInfo.yaml",
"external_connections": {
"sample_connection.alpha": {
"baseurl": "https://acme.com"
},
"sample_connection.bravo": {
"baseurl": "https://bravo.com",
"secrets": {
"client_cert": "externalEndpoint/client.keycertchain",
"secret.username": "alpha27",
"secret.age": "24"
}
},
"url_fragments": {
"get_user_name": "users/username",
"get_user_age": "users/age"
}
},
"public_key_for_encrypting_custom_secrets": "receivedFromPTC/wnc-dev1.rsa.pub.pem",
"apply_at": "2024-03-30T12:24"
}
You can submit a customization code that contains the external endpoint names, endpoint1 and endpoint2. The same customization code can be used for both, Windchill+ development and production deployments by specifying different connection information using captureExternalConnections utility. Refer to the following deployment-specific JSON files.
Parameter file for Windchill+ deployment on Development: devConnections.json
Parameter file for Windchill+ deployment on Production: prodConnections.json
{
"blob_sas_url": "...deployment specific URL as received from PTC...",
"external_connections": {
"endpoint1": {
"baseurl": https://foo-dev.acme.com
},
"endpoint2": {
"baseurl": https://bar-dev.acme.com,
"secrets": {
"client_cert": "/path/to/client-dev.keycertchain",
"secret.username": "user1",
"secret.age": "5"
}
},
"url_fragments": {
"get_user_name": "users/username",
"get_user_age": "users/age"
}
},
"public_key_for_encrypting_custom_secrets": "/path/to/dev.pem",
"schedule_at": "2024-03-30T12:24+5:30"
}
{
"blob_sas_url": "...deployment specific URL as received from PTC...",
"external_connections": {
"endpoint1": {
"baseurl": https://foo-prod.acme.com
},
"endpoint2": {
"baseurl": https://bar-prod.acme.com,
"secrets": {
"client_cert": "/path/to/client-prod.keycertchain",
"secret.username": "user2",
"secret.age": "4"
}
},
"url_fragments": {
"get_user_name": "users/username",
"get_user_age": "users/age"
}
},
"public_key_for_encrypting_custom_secrets": "/path/to/prod.pem",
"schedule_at": "2024-03-30T17:56+5:30"
}
For information on how the connection information is used by CustomIntegrationHelper and an example of the customization, see Integrations Example.
Information to be Provided in the JSON File
Parameter
Mandatory or Optional
Description
blob_sas_url
Mandatory
Specify the Blob SAS URL provided by PTC through an email. It should point to connectionInfo.yaml. For example:
https://somestorageaccount.blob.core.windows.net/somecontainer/connectionInfo.yaml?sp=rw&st=2024-03-11T11:05:43Z&se=2024-03-12T19:05:43Z&spr=https&sv=2022-11-02&sr=b&sig=XHIXmZAL5b4wBxWg17AqS27Yvn8pa%2B8ZNPafxNoU0pE%3D
connection.name
Mandatory
Provide a unique connection name. You can add one or more connections as needed.
For example:
sample.connection.alpha
sample.connection.bravo
erp.dev
baseurl
Mandatory
Provide a base URL for each connection. Only the following characters are allowed as the base URL name: a-z 0-9 . _
Examples of a base URL:
client_cert
Optional
Provide a client certificate or chain, and password-less key in a PEM bundle. Example of a bundle path: /home/windchill/client.keycertchain.pem
secret.name
Optional
Provide any other secrets such as API tokens, credentials, and so on. Only the following characters are allowed as the secret name: a-z 0-9 . _
Examples of secret value:
k>#=B3*jKX!Fa)e(;TsygY6P72Rd%:Ar
x-acme-header=AcmeMaterial
server_cert
Optional
If server SSL certificate is issued by a lesser-known certification agency, capture the certificate or chain in a PEM bundle.
Example of a bundle path: /home/windchill/server.certchain.pem
url_fragments
Optional
If multiple endpoints share the same identities, server, or client secrets, you can capture the URL fragments associated with the same base URL.
Only the following characters are allowed as the fragment name: a-z 0-9 . _
Example of a url fragment value: /inventory/api
public_key_for_encrypting_custom_secrets
Mandatory
Provide a public key for encryption. The public key file is provided by PTC through an email.
Example of a public key: /home/windchill/public_key.txt
apply_at
Optional
Provide an ISO 8601 timestamp to commence the rollout of connection information. The timestamp must be at least one hour later than the current time. If the apply_at parameter is skipped, the connection information rollout will not be executed. However, you can configure your local Windchill deployment to use the provided connection information.
For example: 2024-03-11T11:24+00:00
Was this helpful?