Configuring the eMessage Connector
After installing the eMessage Connector, you need to customize the configuration, providing the following key pieces of information:
• The application key that this eMessage Connector will use to access ThingWorx Platform. For information about setting up an application key, refer to Create Security Entities in ThingWorx for a Connector and for Remote Access.
• The URL for the ThingWorx Platform
• SSL/TLS information
 |
You should back up the original configuration file before you modify it. Alternatively, you can create your own configuration file, as long as you use the Typesafe config format and the extension, .conf.
|
Format of the Configuration File
The structure of the configuration file for a Connector is hierarchical, based on the type-safe configuration library for JVM languages (refer to https://github.com/typesafehub/config for more information). This library differentiates between strings and numbers. The configuration file for the Connector consists of groups and properties. Groups can contain other groups or properties. The configuration file also supports multi-value arrays [].
The top-level group in the configuration file is called cx-server. This expression:
cx-server {
...
thing {
name = "eMessageConnector1"
num = 1
}
...
}
is equivalent to this expression:
cx-server.thing.name = "eMessageConnector1"
cx-server.thing.num = 1
The sample configuration files contain comments to guide you through the configuration. The comments may be prefixed with // or #. Two sample configuration files are provided in the installation. It is strongly recommended that you start with the shorter version (emessage.conf). Later you can copy/paste from the longer version (emessage-all.conf) as needed. Here are descriptions of the two files:
• emessage.conf — This sample file contains all the basics for getting started with the eMessage Connector.
• emessage-all.conf — This sample file contains all the configuration values, including values for file upload, token authentication, and an explicit name for the eMessage Connector (cx-server.Thing.name).
The instructions below assume that you are using the short, sample configuration file, emessage.conf, as your starting point.
To configure the eMessage Connector:
1. Navigate to the directory, emessage-connector_<version>, where <version> stands for the version of the eMessage Connector.
2. Copy the sample configuration file (emessage.conf), using backup in the name of the new file.
3. Using a text editor, open the original emessage.conf.
4. In the cx-server.Thing group, leave the default setting "AxedaProtocolAdapter" for the template-name property.
5. OPTIONAL. The Connector automatically assigns a name to the instance on startup, in the format, <protocol>-cxserver-<uuid>, where <protocol> is the eMessage protocol that your devices use to communicate with the eMessage Connector and <uuid> is a unique identification number. If your environment requires that you use a specific naming scheme, add the name property with the desired name:
cx-server {
thing {
template-name = "AxedaProtocolAdapter"
name = "myConnector_emsg1"
}
When choosing a naming scheme, keep in mind that ThingWorx Platform will not create a Thing for the eMessage Connector (allowing it to connect) if it detects that the name is a duplicate.
6. Skip the lines for the hub-Thing group and for the protocol.name and protocol.classname properties. The default values should be used. As long as port 8081 is open on the computer where the eMessage Connector will run, leave the default value for the protocol.port property.
7. To configure SSL/TLS for the connections between this eMessage Connector and ThingWorx Platform, complete the following steps:
a. Enable ThingWorx Platform for SSL/TLS connections. For information about how you can do this, search for the installation guide for your version of ThingWorx (8.2.x and earlier) at ThingWorx Reference Documents,and for ThingWorx 8.3 and later, the installation information is in the ThingWorx Help Center.
b. Modify the value of the cx-server.transport.websockets.platforms configuration property to the URL of the secured ThingWorx Platform port and protocol. If you have used port 8443 while setting up ThingWorx Platform for TLS, the value would be as follows:
cx-server {
...
transport.websockets {
...
platforms = "wss://your-ThingWorx-platform:8443/Thingworx/WS"
...
}
...
}
Ensure that you use wss at the beginning of the URL.
If you are using a non-secure connection (HTTP), specify ws at the beginning of the URL and change the port number to a non-secure port, for example, 8080.
c. If the Tomcat server that runs the ThingWorx Platform was configured to provide the entire CA Certificate Chain to the Connector, you do not need to create a TrustStore to ensure that the eMessage Connector trusts all certificates in the chain back to the Certificate Authority (CA). However, if the Tomcat server that runs ThingWorx Platform is not configured to provide the entire CA Certificate Chain to the Connector, you must create the TrustStore. Refer to Creating a TrustStore for the steps.
 |
You will need to set the EMESSAGE_OPTS environment variable to use the SSL/TLS options that you have configured. For now complete the configuration of the eMessage Connector.
|
8. To enable secure connections to the eMessage Connector from the eMessage assets and other Connector clients, set the following properties in the cx-server.protocol group:
cx-server {
protocol {
name = "eMessage"
classname = "com.thingworx.protocol.emessage.EmessageProtocol"
port = 443 // <-- just an example, put your edge-facing Connector port here.
ssl {
// Whether SSL is enabled for the eMessage protocol.
// If SSL is disabled, the rest of the SSL properties are ignored.
enabled = true
key-store {
// Path to the keystore file containing the SSL certificate(s).
file = "/path/to/the/keystore/to/be/used/to/serve/certificates/to/connector/clients/keystore.jks"
// The password for the keystore.
password = "the password for keystore.jks"
}
} // end of ssl section
} // end of protocol section
...
} // end of cx-server section
 |
Pay particular attention to the exact spelling of the names of the keys in the configuration file. Making a simple mistake such as leaving the dash off of the key-store tag, for example, can result in obscure errors, depending on how the Connector handles HTTP/S calls from Axeda eMessage agents. For information on configuring SSL/TLS for the connection between an Axeda Global Access Server (GAS) and an eMessage Connector, refer to Configuring the Connector for Remote Access. For information on configuring the GAS itself to use SSL/TLS refer to the Axeda Global Access Server Reference, v.6.9.2, which is available on the Reference Documents page of the PTC Support site.
|
9. If you plan to download files to Axeda agent devices from the ThingWorx Platform, you must configure the location of the download endpoint on the eMessage Connector where the downloaded files can be accessed by the Axeda agent devices. The Agent will use this URL to download a file. The url property is in the emessage.file-transfer.download group:
emessage {
file-transfer {
download {
url = "https://eMessageConnector:8443/download"
10. OPTIONAL If you plan to upload files from Axeda agent devices to the ThingWorx Platform, you can, but do not need to, configure the location of the upload endpoint on the eMessage Connector where the files from the agents will be sent. The value should be the URL of the eMessage Connector. Add this property and the upload sub-group to the emessage.file-transfer group, as follows:
emessage {
file-transfer {
upload {
url = "https://eMessageConnector:8443/upload"
Additional properties are available to configure file downloads, including settings for retries and chunk size. They all have default values and are optional. For more information about them, refer to Configuring Additional Properties for File Transfers.
11. Users can change the ping rate of an agent from ThingWorx by invoking the SetPingRate service. The default minimum, acceptable rate is 5000 ms (5 seconds). If you want to change this minimum, set the minimum-ping-rate property in the emessage group. The following example sets the minimum ping rate to 60 seconds (60000 ms):
emessage {
. . .
minimum-ping-rate = 60000
}
}
12. The properties of the platform-binding group control the maximum number of egress messages that the Connector can accept per Thing and the number of seconds that the Connector waits for them.
◦ max-messages-per-Thing — This property controls the maximum number of egress messages per request to obtain for a Thing.
◦ message-fulfillment-timeout — This property controls the number of seconds that the Connector must wait for any expected messages from theThingWorx Platform to arrive upon receiving a poll from an agent.
The default values of platform-binding are:
platform-binding {
max-messages-per-thing = 10
message-fulfillment-timeout = 10000
}
13. If port 9009 is free for the Health Check Monitor to listen on, the default configuration will suffice, so continue to the next step. Otherwise, add the following lines to your configuration file (in the cx-server group, at the same level as the emessage group) and change the number of the port for the health check monitor to an available port.
cx-server {
. . .
health-check {
port = 9009
}
...
}
14. Skip the platform group (leave the default settings) and for now, skip the metrics group.
15. In the transport.websockets group, enter the application key that was created for this eMessage Connector in the app-key property:
...
transport.websockets {
app-key = "<some_application_key>"
}
...
16. Leave the default settings for the other properties in the transport.websockets group. If you later want to adjust a timeout setting for the connection (e.g., how long to wait for the ThingWorx Platform to respond to a request), refer to Configuring Additional Properties for the Connection.
17. Save the file.
18. At this point, you have the following choices:
◦ Configure additional properties for features of the eMessage Connector:
▪ Reporting of metrics — Configuring Metrics Reporting
▪ Key/Value Pair (KVP) Stores (caches) — Configuring Key/Value Pair Stores for the eMessage Connector
▪ File transfers — Configuring Additional Properties for File Transfers
▪ Remote access (Axeda Global Access Server connections) — Configuring the Connector for Remote Access
◦ Save and close the file. Then:
a. Configure the TokenPropertyAuthenticator, as explained in Configuring the TokenPropertyAuthenticator (eMessage Connector) .
b. Set the environment variable to point to your configuration file and, if using SSL/TLS, to your TrustStore, as explained in Setting the Environment Variable.
|
|
Be sure to configure logging in the logback.xml file for your eMessage Connector. You specify the location in which you want to store log files in the logback.xml file (<property name="LOGS_DIR" value="logs" />). For additional information about logging, refer to Log Messages.
|