ThingWorx Extensibility > Integration Connectors > Integration Connectors Prerequisites > Initial Setup of Integration Runtime Service for Integration Connectors
  
Initial Setup of Integration Runtime Service for Integration Connectors
After installing ThingWorx, follow the steps below to download and configure the ThingWorx Runtime Service. If you are in a Docker environment, you can use an installer to set up a basic configuration for the Integration Connectors. The installer includes a logging file where you can modify some configuration as described below.
Downloading Integration Runtime
The Integration Runtime Service is available for download from the ThingWorx Marketplace.
Configuring Integration Runtime
* 
Do not create a Thing from the IntegrationRuntime Thing Template.
1. Create an application key in ThingWorx for the Integration Runtime to use for communication to the ThingWorx platform.
2. Launch Integration Services as a Java process using one of the following options:
external configuration file specifying connection parameters.
java -DconfigFile=<path to IntegrationRuntime settings>-jar <path to IntegrationRuntime-8.0.4>.jar
3. (Optionally) Create custom logback settings file and specify the path to it on the command line using the following: -Dlogs.includedLogback=<path to logback include>
4. If you are encrypting entries in the integrationRuntime-settings.json configuration file or encrypting the entire configuration file, you must specify the path to the security-common encryption configuration on the command line using the following:
* 
-Dencrypted.config.file=true is required in the examples below if you are encrypting the entire configuration file, and it must point to the encrypted Integration Runtime configuration file. If you are only encrypting entries in the file, omit the setting or set it to false.
java -Dsecret.management.config.file=<Path to encryption.conf> -Dencrypted.config.file=true -DconfigFile=<path to encrypted integrationRuntime-settings.json.encrypted>
An example command is provided below:
java -Dsecret.management.config.file=C:\Integ_runtime\encryption.conf -Dencrypted.config.file=true -DconfigFile=integrationRuntime-settings.json.encrypted -jar C:\Integ_runtime\integration-runtime-8.0.4-bXXX.jar
Sample Configuration File (integrationRuntime-settings.json)
{
"traceRoutes": "false",
"Thingworx": {
"appKey": "1234abcd-xxxx-yyyy-zzzz-5678efgh",
"host": "localhost",
"port": "8443",
"basePath": "/Thingworx",
"sslEnable": "true",
"ignoreSSLErrors": "false"
},
"SSL": {
"verbose": "true",
"Keystore": {
"path": "/usr/security/keystore.jks",
"password": "encrypt.keystore.password"
},
"Truststore": {
"path": "/usr/security/truststore",
"password": "encrypt.truststore.password"
}
},
"RetryPolicy": {
"MaximumRetries": 2,
"RetryDelay": 2000,
"BackoffMultiplier": 1
},
"RedirectPolicy": {
"MaximumRedirects": 3,
"EnableRedirect": true
}
}
Configuration File Settings
As explained in the descriptions, some configuration settings can be specified or override configuration file settings using Java system properties (for example, -D<name>=<value>).
Integration Runtime Settings
Setting
Default
Description
traceRoutes
false
Specifies whether the route execution should log messages as each processor in the route is invoked.
Thingworx
Specifies the settings for connecting to the ThingWorx platform in JSON format.
SSL
Specifies the Secure Sockets Layer (SSL) settings in JSON format.
ThingWorx Settings
Setting
Default
Description
appKey
Specifies the Application Key from the ThingWorx platform that has been configured for use by this Integration Runtime. This setting can be overridden with a Java system property.
* 
See section below for encryption steps.
basePath
/Thingworx
Specifies the base path in the URI to the ThingWorx platform. This setting can be overridden with a Java system property.
host
localhost
Specifies the host in the URI to the ThingWorx platform. This setting can be overridden with a Java system property.
port
443
Specifies the port in the URI to the ThingWorx platform. This setting can be overridden with a Java system property.
sslEnable
true
Specifies whether SSL should be used to connect to the ThingWorx platform via WebSocket. If true, then "wss" protocol is used for the URI. Otherwise, "ws" protocol is used.
ignoreSSLErrors
false
Specifies whether SSL errors should be ignored. This value should not be set to true in a production environment.
SSL Settings
Setting
Default
Description
verbose
false
Specifies whether Java handshake protocol will output verbose messages. If true, then Java system property javax.net.debug is set to ssl:handshake:verbose.
Keystore
Specifies the SSL keystore settings in JSON format.
Truststore
Specifies the SSL truststore settings in JSON format.
Keystore Settings
Setting
Description
path
Specifies the path to the SSL keystore file. Using this setting is equivalent to setting the Java system property javax.net.ssl.keyStore.
password
Specifies the password for to the SSL keystore file. Using this setting is equivalent to setting the Java system property javax.net.ssl.keyStorePassword. To avoid storing the password as plain text, use the value encrypt.keystore.password. See the Encrypting Password Settings section below.
Truststore Settings
Setting
Description
path
Specifies the path to the SSL truststore file. Using this setting is equivalent to setting the Java system property javax.net.ssl.trustStore.
password
Specifies the password for to the SSL truststore file. Using this setting is equivalent to setting the Java system property javax.net.ssl.trustStorePassword. To avoid storing the password as plain text, use the value encrypt.truststore.password. See the Encrypting Password Settings section below.
Retry Policy Settings
Setting
Default
Description
MaximumRetries
2
Specifies the number of times to re-attempt a request that could have failed due to system availability.
In the case of HTTP requests, retries occur with a 503 response from the server.
RetryDelay
1000
When a request fails but can be retried, RetryDelay represents how long, in milliseconds, to wait before attempting to retry. RetryDelay will be used in conjunction with BackoffMultiplier when determining subsequent retries.
BackoffMultiplier
1
Specifies how long to multiply the RetryDelay on subsequent retries. For example, if the BackoffMultiplier was set to2 and MaximumRetries was set to 3, the first retry would occur at 1 second; the second retry would occur 2 seconds after the first; the third would occur 4 seconds after and so on.
UnauthorizedRetries
2
Specifies the number of times to re-attempt a request that failed due to an unauthorized request. This setting applies to an HTTP request with a 401 response from the server.
Redirect Policy Settings
Setting
Default
Description
MaximumRedirects
3
Specifies the number of times to re-attempt a redirect.
EnableRedirect
true
Specifies if redirect is enabled for requests resulting in a redirect status code 3xx.
Encrypting the Configuration File
To provide greater security, you can encrypt the entire configuration file and optionally, individual values within the file. This feature is provided in version 8.0.4 of Integration Runtime. The installation of the Integration Runtime includes the security-common library. The jar for this library is included in the Integration Runtime installation. It provides the back-end tool that does the encrypting and decrypting of the configuration file.
A Command Line Interface (CLI) is available to interact with the security library, which includes encrypting the configuration file. For complete information about this CLI, reference Security Management Tool. This topic explains where to obtain the tool and how to use it. For your convenience, steps specific to Integration Runtime are provided in the sections below. You can download the CLI from the PTC Support Site.
1. The security-common library requires its own configuration file. Using a text editor, create the following file and save it as encryption.conf:
{
security {
secret-provider = "com.thingworx.security.provider.keystore.KeyStoreProvider"
default-encryption-key-length = 128

keystore {
password-file-path = "/ThingworxPlatform"
password-file-name = "keystore-password"
path = "/ThingworxStorage"
name = "keystore.jks"
}
}
}
2. Create the password-file-path and path directories specified in the encryption.conf file. In the example above, the password-file-path directory is /ThingworxPlatform (Linux). On a Windows computer, it would be C:\\ThingworxPlatform.
* 
You can store the encrypted configuration file anywhere you choose. Just make sure that the encryption configuration file and the environment variables point to the correct path.
3. Assuming that you have downloaded and extracted the CLI distribution, you can encrypt the configuration file. Open a Command Prompt or shell, and navigate to the securitycommon-cli-x.x.x.xx/bin directory, where x.x.x.xx represents the version of the tool.
4. Run the CLI, as appropriate to your operating system:
Linux — security-common-cli
Windows — security-common-cli.bat
5. When prompted, enter the name of the security configuration file to initialize. The following is a Linux example of the sequence:
../security-common-cli-1.x.x.xx/bin$ ./security-common-cli
Not initialized, use 'init <config-file>' to initialize
> init [pathTo]encryption.conf
Loading config from file encryption.conf
Secret Provider: com.thingworx.security.provider.keystore.KeyStoreProvider
KeyStore
Path: /ThingworxPlatform/keystore.jks
Password File: /ThingworxStorage/keystore-password
Keystore Password: 336974503775017XXXX
>
6. While still in the security CLI, encrypt the configuration file of the Integration Runtime. In this example, it is integrationRuntime-settings.json using the encryptFile command, as shown below:
encryptFile C:\Integ_runtime\integrationRuntime-settings.json C:\Integ_runtime\integrationRuntime-settings.json.encrypted
integrationRuntime-settings.json.encrypted is your encrypted configuration file.
7. Verify that the encryption was successful by using the decryptFile command:decryptFile C:\Integ_runtime\integrationRuntime-settings.json.encrypted C:\Integ_runtime\integrationRuntime-settings.json.decrypted
* 
The content of the integrationRuntime-settings.json.decrypted should match the content of the original integrationRuntime-settings.json file.
* 
Remove the unencrypted versions of the file.
8. To close the CLI, type exit at the prompt.
Encrypting Entries in the Configuration File
Passwords or other entries in the configuration file can be encrypted in Integration Runtime 8.0.4+. Use the same encryption mechanism for the ThingWorx platform that is used for encrypting the PostgreSQL database password.
Follow the instructions in Encrypting Passwords, but use the values encrypt.app.key instead of encrypt.db.password or encrypt.licensing.password, and using the integrationRuntime-settings.json instead of platform-settings.json. If your ThingWorx system is already using encryption for the PostgreSQL database password, then these new passwords will be added to the same keystore file; otherwise, a new keystore file is created.
Migrating the Keystore and Keystore Password
When installing ThingWorx, you have the option to encrypt your database and licensing passwords. If you exercised that option and are performing a migration, you need to move the keystore and password files:
Copy /twx/config to /ThingworxPlatform/keystore-password
Copy /ThingworxStorage/keyStore to /ThingworxStorage/keystore.jks
Configuring for SSL
By default, the Integration Runtime will connect to ThingWorx using SSL. The following table describes the ThingWorx platform configurations and the associated Integration Runtime configuration settings needed to connect successfully. The keystore settings are not necessary for connecting to the ThingWorx platform; they provide a client certificate from the Integration Runtime in a two-way SSL negotiation.
ThingWorx Configuration
Integration Runtime Settings
ThingWorx is not configured for SSL
Specify thingworxUri using a Java system property and use ws protocol or specify sslEnable=false in SSL settings.
ThingWorx is configured for SSL using self-signed certificate
Specify sslEnable=true and ignoreSSLErrors=true in SSL settings.
ThingWorx is configured for SSL with a self-signed certificate and the certificate is trusted
ThingWorx is configured for SSL with a certificate signed by a Certificate Authority (CA) and it was not configured to provide the entire CA Certificate Chain.
Export the certificate from the keystore file and import it to a truststore file.
Specify enable=true and Trustore in SSL settings.
Truststore password may be encrypted.
Alternatively, add the certificate to the Integration Runtime JVM default truststore (usually located here:$JAVA_HOME/lib/security/cacerts). In this case, it is not necessary to explicitly specify Truststore in SSL settings.
ThingWorx is configured for SSL with a certificate signed by a Certificate Authority (CA) and it was configured to provide the entire CA Certificate Chain.
Specify enable=true in SSL settings. This is the default setting.
SSL Configuration Example: Non-Productions Configuration
If ThingWorx is configured for SSL using a self-signed certificate, use the following integrationRuntime-settings.json.
{
"Thingworx": {
"appKey": "1234abcd-xxxx-yyyy-zzzz-5678efgh",
"host": "localhost",
"port": "8443",
"sslEnable": "true",
"ignoreSSLErrors": "true"
}
}
SSL Configuration Example: Production Configuration
If ThingWorx is configured for SSL using a self-signed certificate, use the following steps to create a truststore.
1. Fetch the server's self-signed certificate. It is used in the next step to force the IntegrationRuntime to trust it.
If you don’t have the certificate stored locally, this is one way to acquire ThingWorx Platform's self-signed certificate.
openssl s_client -connect your-ThingWorx-platform:8443< /dev/null| sed -ne'/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p'twx-platform-public.crt
2. Create local copy of truststore that the IntegrationRuntime will use to trust the server's self-signed certificate.
Rather than add the missing certificate directly to the JVM's stock truststore, we will first make a copy of it, and add the missing certificate to the copy.
cp $JAVA_HOME/jre/lib/security/cacerts /etc/opt/java/security/cacerts-customized
$JAVA_HOME/bin/keytool -importcert -alias somealias -keystore /etc/opt/java/security/cacerts-customized -file twx-platform-public.crt
3. Change the password the truststore.
The default password for the JVM cacerts file is changeit. Similar to changing the password of any other keystore, we could change the password of cacerts-customized by issuing the following:
keytool storepasswd keystore /etc/opt/java/security/cacerts-customized
Enter keystore password: changeit
New keystore password: new-password
Re-enter new keystore password: new-password
4. Use the following integrationRuntime-settings.json.
{
"Thingworx": {
"appKey": "1234abcd-xxxx-yyyy-zzzz-5678efgh",
"host": "localhost",
"port": "8443",
"sslEnable": "true",
"ignoreSSLErrors": "false"
}
"SSL": {
"Truststore": {
"path": "/etc/opt/java/security/cacerts-customized",
"password": "new-password"
}
}
}
Sample Log Configuration File (integrationRuntime-logback.xml)
<?xml version="1.0"?>
<included>

<property name="logs.dir" value="/ThingworxStorage/IRlogs" />
<property name="logs.uniqueId" value="${processId}" />
<property name="logs.maxFileSize" value="1MB" />
<property name="logs.maxIndex" value="5" />

<logger name="com.twx.integration" level="DEBUG" />
<logger name="org.apache.camel" level="DEBUG" />

</included>
Log Configuration File Settings
A standard logback.xml configuration file is included in the IntegrationRuntime.jar. For more information on logback configuration, see Logback Project. This file sets up the root logger with logging to the console and a rolling log file. An optional include file can be specified using this Java system property: logs.includedLogback. The include file is used for enabling other loggers and specifying properties. The rolling log file is configured with a fixed window and size-based triggering policies and can be customized by setting the properties below:
Setting
Default
Description
logs.dir
Specifies the location where log files will be generated. The default is the current working directory.
logs.maxFileSize
5MB
Specifies the maximum log file size that triggers a rollover to a new log file.
logs.maxIndex
9
Specifies the maximum index of the fixed size rollover window. The initial index starts at 1.
logs.timestampPattern
yyyy-dd-MM HH:mm:ss.SSS
Specifies the timestamp pattern to use for each log event.
logs.uniqueId
<processId>
Specifies a value that is appended to the log file name. This is used to generate unique file names. The default value is obtained via a Java callback to return the JVM's process ID.