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.
This utility is a part of the Windchill+ installation. It can be copied from an existing Windchill+ installation on a Linux system and can be used on any other Linux system, independent of Windchill+. On a Windows system, this utility can function with Linux application sets such as MSYS2 and Cygwin. When you request a new instance of a Windchill template on the PTC cloud portal, the instance includes MSYS2 by default.
Like some of the other Windchill+ utilities, the captureExternalConnections is a shell script that uses secrets provided in the JSON file and certificates from the file system For more information, see the section Steps to Run the Utility below. The utility encrypts information using the PTC-supplied public key and uploads a YAML package to a deployment-specific (either development or production) Azure container.
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}/prog_examples/IntegrationsExample/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}/prog_examples/IntegrationsExample/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": "/path/to/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": "/path/to/asymmetric_encryption_public_key_<***>.txt"",
"apply_at": "2024-03-30T12:24"
}
"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": "/path/to/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": "/path/to/asymmetric_encryption_public_key_<***>.txt"",
"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/asymmetric_encryption_public_key_<dev***>.txt", "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/asymmetric_encryption_public_key_<Prod***>.txt", "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
|
Specify the unique connection name. You can add one or more connections as required.
For example:
sample.connection.alpha
sample.connection.bravo
erp.dev
|
|
baseurl
|
Mandatory
|
Specify a base URL for each connection. Only the following characters are allowed as the base URL name: a-z 0-9 . _
For example:
|
|
client_cert
|
Optional
|
Specify the path to the client certificate or chain, and the password-less key. For example: /path/to/client.keycertchain
|
|
secret.name
|
Optional
|
Specify 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 . _
For example:
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, specify the path to the server certificate or chain.
For example: /path/to/server.certchain
|
|
url_fragments
|
Optional
|
If multiple endpoints share the same identities, server, or client secrets, you can specify the URL fragments associated with the same base URL.
Only the following characters are allowed as the fragment name: a-z 0-9 . _
For example: /inventory/api
|
|
public_key_for_encrypting_custom_secrets
|
Mandatory
|
Specify the path to the public key for encryption. The public key file is provided by PTC through an email.
For example: /path/to/asymmetric_encryption_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
|
|
|
Even though there is a minimum delay of one hour between the submission of new secrets to PTC and the ability to utilize these secrets, you have the option to schedule the rollout of new secret values in advance. However, until the rollout schedule of the new secret values begins, the Windchill+ customization code will continue to use the old secret values. If you expect the external endpoint integration to work within this timeframe, you must modify the customization code in CCD accordingly. Alternatively, you may rollout new secret values and phaseout old secret values with an overlapping timeline.
|