Communicate with a runtime

You can connect to an instance of Semarchy xDI Runtime from other xDI tools to perform operations on the runtime. The runtime uses HTTPS for its connections by default, or HTTP if explicitly configured to do so.

If you use a self-signed SSL/TLS certificate, you may also need to perform extra steps to make the connection work.

This article explains how to configure different clients to connect to a runtime. It also explains how to make them work in scenarios with self-signed certificates.

Prerequisites

Before you set up communications to a runtime, set up access security and SSL/TLS certificates.

Access security

See this article to configure access security.

SSL/TLS certificates

In most cases, the runtime needs an SSL/TLS certificate to be open to connections.

If your SSL/TLS certificates are issued by a certificate authority (CA), you probably do not need to do anything else. Your operating system handles these certificate validations. If you sign your SSL/TLS certificates yourself, add the certificates to your environment so your applications can recognize their validity.

Add a self-signed certificate to your environment by saving it to a keystore, and making your clients aware of it in two different ways:

  • You can import the certificate to your Java Virtual Machine, which makes it available to all Java software globally.

  • You can also import the certificate into an application for its use only. This article explains this method.

Both options have their pros and cons. The approach you should choose depends on what you prefer to configure.

When adding a certificate to a keystore, you have the option to password-protect the certificate entry. If you do this, make sure it has the same password as the keystore itself.

Connect from xDI Designer

When you want to connect to an instance of xDI Runtime from Designer, define this instance in a runtime metadata object. Defining a runtime in this way allows you to execute mappings and processes on that runtime from within Designer.

Follow these instructions to create runtime metadata.

Use your own certificates

To let Designer use your self-signed certificates, add startup options to the semarchy-xdi-designer-*.ini file to let Designer find your keystore. This INI file is in the Designer installation directory.

The semarchy-xdi-designer.ini file is sensitive to extra spaces or line breaks. You should make a backup the file before making any changes. You can also find a default version in the Designer download.

Open the file appropriate to your operating system in a text editor, and add these lines at the end of the file:

-Djavax.net.ssl.trustStore=<keystore file path>
-Djavax.net.ssl.trustStoreType=<keystore_type>
-Djavax.net.ssl.trustStorePassword=<keystore and key password>

Replace the values in angled brackets by the full path to your keystore, the keystore type, and the password. Here is an example:

-Djavax.net.ssl.trustStore="D:/certificates/mykeystore.jks"
-Djavax.net.ssl.trustStoreType=jks
-Djavax.net.ssl.trustStorePassword=keystorepass

Turn off certificate checking

You can disable certificate checking for debugging or testing purposes. The runtime still encrypts the connection, but Java does not perform any certificate validity checks.

Add these options to the INI file instead:

-Dcom.stambia.runtime.https.ignoreCertCheck=true
-Dcom.stambia.runtime.https.ignoreCertCheckProtocol=SSL

Connect from Designer process actions

In Designer, you can also connect to an instance of xDI Runtime from the Start Delivery process action. Connecting to a runtime from the process action allows you to execute deliveries on a runtime other than the one you use in Designer by default.

See the Start Delivery reference page for more information.

Use your own certificates

To let the process action use your self-signed certificates, you must configure the related runtime’s files directly.

Navigate to the runtime installation directory. Open initvariables.bat for Windows, or initvariables.sh for Linux or macOS. Find the line that contains XDI_RUNTIME_STARTENGINE_VM_PROPERTIES=, and add the following options to the other ones in quotation marks:

-Djavax.net.ssl.trustStore=<keystore file path> -Djavax.net.ssl.trustStoreType=<keystore_type>-Djavax.net.ssl.trustStorePassword=<keystore and key password>

Replace the values in angled brackets by the full path to your keystore, the keystore type, and the password. Here is an example for initvariables.sh:

XDI_RUNTIME_STARTENGINE_VM_PROPERTIES="-Dxdi.runtime.client.configuration.file.path=$XDI_RUNTIME_PROPERTIES_LOCATION/xdi-runtime-client-configuration.xml -Djavax.net.ssl.trustStore="/home/semarchy/mykeystore.jks" -Djavax.net.ssl.trustStoreType=jks -Djavax.net.ssl.trustStorePassword=keystorepass"

Turn off certificate checking

You can disable certificate checking for debugging or testing purposes. The runtime still encrypts the connection, but Java does not perform any certificate validity checks.

Add these options to the runtime’s initvariables file instead:

-Dcom.stambia.runtime.https.ignoreCertCheck=true -Dcom.stambia.runtime.https.ignoreCertCheckProtocol=SSL

Connect from xDI Analytics

When you want to connect to an instance of xDI Runtime from Analytics, define this instance from the Administration panel. Defining a runtime in this way allows you to execute deliveries on that runtime from within Analytics.

Follow these instructions to create a runtime entry in Analytics.

Use your own certificates

To let Analytics use your self-signed certificates, add startup options to Apache Tomcat to let Analytics find your keystore.

The recommended way of adding Java options to Apache Tomcat is by adding the options to the CATALINA_OPTS or JAVA_OPTS environment variables when launching Tomcat. You can do this either in a separate script that launches Tomcat, or directly from a command line. Refer to the catalina.bat or catalina.sh files from an Apache Tomcat installation for more information.

Add these java options to the environment variable:

-Djavax.net.ssl.trustStore=<keystore file path> -Djavax.net.ssl.trustStoreType=<keystore_type> -Djavax.net.ssl.trustStorePassword=<keystore and key password>

Replace the values in angled brackets by the full path to your keystore, the keystore type, and the password. Here is an example:

-Djavax.net.ssl.trustStore="D:/certificates/mykeystore.jks" -Djavax.net.ssl.trustStoreType=jks -Djavax.net.ssl.trustStorePassword=keystorepass

Turn off certificate checking

You can disable certificate checking for debugging or testing purposes. The runtime still encrypts the connection, but Java does not perform any certificate validity checks.

Add these options to the CATALINA_OPTS or JAVA_OPTS environment variables instead:

-Dcom.stambia.runtime.https.ignoreCertCheck=true
-Dcom.stambia.runtime.https.ignoreCertCheckProtocol=SSL

Connect from command line scripts

When you want to control an instance of xDI Runtime directly from a command line, you can use the Runtime startcommand script with the connect command. This command takes arguments to let you select the runtime to connect to.

See the reference page for more information about runtime commands.

Example 1. Example command
> connect to localhost port 42000
Connecting to localhost on port 42000
Connected

Use your own certificates

To let the runtime use your self-signed certificates, you must configure the related runtime’s files directly.

Navigate to the runtime installation directory. Open initvariables.bat for Windows, or initvariables.sh for Linux or macOS. Find the line that contains XDI_RUNTIME_STARTENGINE_VM_PROPERTIES=, and add the following options to the other ones in quotation marks:

-Djavax.net.ssl.trustStore=<keystore file path> -Djavax.net.ssl.trustStoreType=<keystore_type>-Djavax.net.ssl.trustStorePassword=<keystore and key password>

Replace the values in angled brackets by the full path to your keystore, the keystore type, and the password. Here is an example for initvariables.sh:

XDI_RUNTIME_STARTENGINE_VM_PROPERTIES="-Dxdi.runtime.client.configuration.file.path=$XDI_RUNTIME_PROPERTIES_LOCATION/xdi-runtime-client-configuration.xml -Djavax.net.ssl.trustStore="/home/semarchy/mykeystore.jks" -Djavax.net.ssl.trustStoreType=jks -Djavax.net.ssl.trustStorePassword=keystorepass"

Turn off certificate checking

You can disable certificate checking for debugging or testing purposes. The runtime still encrypts the connection, but Java does not perform any certificate validity checks.

Add these options to the runtime’s initvariables file instead:

-Dcom.stambia.runtime.https.ignoreCertCheck=true -Dcom.stambia.runtime.https.ignoreCertCheckProtocol=SSL