Configuring the EMS
This topic takes you through the basic steps for a simple configuration that establishes a connection to your ThingWorx Platform in the following sections. Click the title of a section to display its content; click the titla again to hide the content:
Create the EMS Configuration File
The configuration file of EMS is a text file that uses the JSON format. It is separated into multiple groups. Each group contains sets of name/value pairs (properties) that control different aspects of the configuration. To connect to a ThingWorx Platform instance, only a few properties are required.
To view an example of a basic configuration file and create your own configuration file:
1. From the EMS installation directory, change to the directory, /etc. This directory contains the following configuration files for EMS:
◦ config.json.complete — A valid JSON file, with no comments. If you want to use this file, you need to provide information relevant to your environment for such properties as the application key (appKey), and the ws_servers.host and ws_servers.port for the instance of ThingWorx Platform to which the EMS will connect.
◦ config.json.documented — A copy of the config.json.complete file with many comments to explain the properties to set. This file is NOT a valid JSON file. Do NOT attempt to run the EMS with this configuration file.
◦ config.json.minimal — A file that provides (in valid JSON) the essential properties that need to be set to communicate with a ThingWorx Platform.
The fourth configuration file in this directory is a sample configuration file for the Lua Script Resource (config.lua.example). Refer to Configuring a Lua Script Resource for more information.
2. To run the EMS, you need to create a separate configuration file, called config.json. To begin with a basic configuration, open config.json.minimal in a text editor. This file contains the minimum set of configuration settings required to connect to a ThingWorx Platform.
3. Create a new file in your editor, and save it as config.json.
4. Copy the settings from config.json.minimal into your config.json file.
5. Follow the instructions in the next section to configure the connection between the EMS and an instance of ThingWorx Platform.
Configure the Connection to ThingWorx Platform
To connect to a ThingWorx Platform instance, you must configure the ws_servers group in the configuration file. This group contains the properties that define the connection between the EMS and a ThingWorx Platform instance. You need to provide an IP address or host name and port for one instance of ThingWorx Platform.
 | Previous releases of the EMS allowed you to configure an array that contained multiple addresses. However, the EMS no longer checks for another address if it fails to connect with the first address in the array. If you previously specified multiple addresses, you do NOT have to change your configuration file. The EMS will use the first address in the ws_servers array and ignore the rest. |
As long as you have created your own config.json file, follow these steps to set up the connection:
1. Copy the first two lines from the config.json.minimal file and paste them in your file:
{
"ws_servers" : [{
"ws_servers" : [{
You are ready to add the properties that define the connection.
2. Under "ws_servers", add the "host" and "port" properties. Then, for the "host" property, replace "localhost" with the URL of your ThingWorx Platform instance. For the "port" property, enter the number of the port on the host to use for the connection. If the connection is to be secure, use port 443. For example:
{
"ws_servers": [{
"host" : "some_host_url",
"port": 443
}
],
"resource": "/Thingworx/WS",
"appKey" : "some_encrypted_application_key",
"ws_servers": [{
"host" : "some_host_url",
"port": 443
}
],
"resource": "/Thingworx/WS",
"appKey" : "some_encrypted_application_key",
For development purposes, you may want to use a ThingWorx Platform instance that is running on the same computer where you installed your EMS. "localhost" can be used as the value for "host" for these purposes only.
Next set the application key for the EMS to use to access the ThingWorx Platform. A platform administrator can generate application keys using ThingWorx Composer. The application key is associated with a user account that determines the privileges that the EMS will have when accessing the instance. Best security practices require encrypting the application key and any passwords that you may be using. For example, the password for a certificate or the passphrase for a private key.
 | If you are using EMS 5.4.8 or later, your version of EMS automatically encrypts secret strings such as the application key or a certificate password on the first startup. You can skip to Step 5. For information on the automatic encryption, refer to Automatic Configuration Encryption. |
3. If you are using an earlier version of the EMS, you need to manually encrypt the application key and passwords. To do this, open a shell or command prompt, navigate to the EMS installation, and enter the following:
wsems.exe -encrypt myPasswordString
where myPasswordString is the application key or a password.
4. Once the encryption generates output, copy the encrypted application key and paste it so that it replaces the current value of the appKey property. Using the example configuration properties shown in Step 2, replace some_encrypted_application_key with the encrypted key you just generated. Make sure that it is enclosed in the double quotation marks.
5. Save the configuration file.
If you want to try running the EMS to check the connection, refer to Running the ThingWorx EMS and then Verifying Your Connection.
For information about configuration required for using ThingWorx Software Content Management (SCM) with ThingWorx Utilities, refer to Setting Up to Use ThingWorx Software Content Management (SCM) with EMS Devices.