platform-settings.json Configuration Details

Installation and Upgrade > Installing ThingWorx > Manual Installation > Installation Appendices > platform-settings.json Configuration Details

The platform-settings.json file is available for administrators to adjust settings for fine-tuning and is available in the software download. For settings specific to high availability clustering, see Platform Settings for ThingWorx HA.

The sample below contains all options. Only one persistence provider is required.

{
"PlatformSettingsConfig": {
"BasicSettings": {
"BackupStorage": "/ThingworxBackupStorage",
"DatabaseLogRetentionPolicy": 7,
"DatabaseWriteRetryAttempts": 10,
"EnableBackup": true,
"EnableClusteredMode": false,
"EnableContentSecurityPolicyFilter": false,
"EnableSystemLogging": false,
"EnableSSO": false,
"FileRepositoryRoot": "/ThingworxStorage",
"FileTransferLockType" : "LOCAL"
"HTTPRequestHeaderMaxLength": 2000,
"HTTPRequestParameterMaxLength": 2000,
"InternalAesCryptographicKeyLength": 128,
"MashupWebsocketConnectionAliveAfterTimeout": false,
"MetricsLoggingFrequency": 30,
"MetricsLoggingLevel": "WARN",
"MetricsReportingEnabled": true,
"NonceKeyTimeout": 15,
"SessionUpdateDelay": 60,
"Storage": "/ThingworxStorage",
"ScriptTimeout": 30,
"MaxSearchItems": 100000
},
"DomainConfiguration": {
"trustedDomains":[
"www.example1.com",
"www.example2.com",
"images.example3.com",
"localhost"
],
"ignoreTrustedDomains": false
}
"SolutionCentralSettings": {
"SolutionCentralHost": "<Solution Central host name>",
"KeyStorePath": "<Path for your keystore>",
"KeyStorePass": "<Password for your keystore>"
},
"AdministratorUserSettings": {
"InitialPassword": "changeme"
},
"ContentTypeSettings": {
"supportedMediaEntityContentTypes" : ["image/svg+xml","image/png","image/gif","image/bmp","image/jpeg","application/pdf","image/vnd.microsoft.icon"]
},
"OrchestrationSettings": {
"EnableOrchestration": true,
"QueueHost": "localhost",
"QueuePort": 5672,
"QueueName": "256mb",
"QueueUsername": "flowuser",
"QueuePassword": "encrypt.queue.password",
"QueueVHost": "orchestration",
"TurnOffScopesApprovalPopup": true
},
"ExtensionPackageImportPolicy": {
"importEnabled": false,
"allowJarResources": false,
"allowJavascriptResources": false,
"allowCSSResources": false,
"allowJSONResources": false,
"allowWebAppResources": false,
"allowEntities": false,
"allowExtensibleEntities": false,
"haCompatibilityImportLevel": "WARN"
},
"LicensingConnectionSettings": {
"username": "<username>",
"password": "<password>",
"timeout":"60",
"useProxy": false,
"proxyHost": "<proxyHost>",
"proxyPort" : "<proxy port>",
"proxyScheme": "<http or https>",
"proxyUseNTLM": true,
"proxyUsername": "<user>",
"proxyPassword": "<user password>",
"proxyWorkstation": "<dummyWorkstation>",
"proxyDomain": "<dummyDomain>"
},
"MetricsUserSettings": {
"InitialPassword": "<password>"
}
},
"PersistenceProviderPackageConfigs": {
"H2PersistenceProviderPackage": {
"ConnectionInformation": {
"acquireIncrement": 5,
"acquireRetryAttempts": 30,
"acquireRetryDelay": 1000,
"checkoutTimeout": 2000,
"networkTimeout": 900000,
"idleConnectionTestPeriod": 6,
"initialPoolSize": 10,
"maxConnectionAge": 0,
"maxIdleTime": 0,
"maxIdleTimeExcessConnections": 36000,
"maxPoolSize": 100,
"maxStatements": 0,
"maxStatementsPerConnection": 50,
"minPoolSize": 10,
"numHelperThreads": 6,
"password": "password",
"tableLockTimeout": 10000,
"testConnectionOnCheckout": false,
"unreturnedConnectionTimeout": 0,
"username": "twadmin"
},
"StreamProcessorSettings": {
"maximumBlockSize": 2500,
"maximumQueueSize": 250000,
"maximumWaitTime": 10000,
"numberOfProcessingThreads": 5,
"scanRate": 5,
"sizeThreshold": 1000,
"producerTimeout": 30000
},
"ValueStreamProcessorSettings": {
"maximumBlockSize": 2500,
"maximumWaitTime": 10000,
"maximumQueueSize": 500000,
"numberOfProcessingThreads": 5,
"scanRate": 5,
"sizeThreshold": 1000,
"producerTimeout": 30000
},
"PersistentPropertyProcessorSettings": {
"maximumBlockSize": 2500,
"maximumWaitTime": 1000,
"maximumQueueSize": 100000,
"numberOfProcessingThreads": 20,
"scanRate": 25,
"sizeThreshold": 1000,
"producerTimeout": 30000
}
},
"PostgresPersistenceProviderPackage": {
"ConnectionInformation": {
"acquireIncrement": 5,
"acquireRetryAttempts": 3,
"acquireRetryDelay": 10000,
"checkoutTimeout": 1000000,
"networkTimeout": 900000,
"queryTimeout": 600000,
"driverClass": "org.postgresql.Driver",
"fetchSize": 5000,
"idleConnectionTestPeriod": 60,
"initialPoolSize": 5,
"jdbcUrl": "jdbc:postgresql://localhost:5432/thingworx",
"maxConnectionAge": 0,
"maxIdleTime": 0,
"maxIdleTimeExcessConnections": 300,
"maxPoolSize": 100,
"maxStatements": 100,
"minPoolSize": 5,
"numHelperThreads": 8,
"password": "password",
"testConnectionOnCheckout": false,
"unreturnedConnectionTimeout": 0,
"username": "twadmin"
},
"StreamProcessorSettings": {
"maximumBlockSize": 2500,
"maximumQueueSize": 250000,
"maximumWaitTime": 10000,
"numberOfProcessingThreads": 5,
"scanRate": 5,
"sizeThreshold": 1000,
"producerTimeout": 30000
},
"ValueStreamProcessorSettings": {
"maximumBlockSize": 2500,
"maximumQueueSize": 500000,
"maximumWaitTime": 10000,
"numberOfProcessingThreads": 5,
"scanRate": 5,
"sizeThreshold": 1000,
"producerTimeout": 30000
},
"PersistentPropertyProcessorSettings": {
"maximumBlockSize": 2500,
"maximumWaitTime": 1000,
"maximumQueueSize": 100000,
"numberOfProcessingThreads": 20,
"scanRate": 25,
"sizeThreshold": 1000,
"producerTimeout": 30000
}
},
"MssqlPersistenceProviderPackage": {
"ConnectionInformation": {
"acquireIncrement": 5,
"acquireRetryAttempts": 3,
"acquireRetryDelay": 10000,
"checkoutTimeout": 1000000,
"networkTimeout": 900000,
"queryTimeout": 600000,
"driverClass": "com.microsoft.sqlserver.jdbc.SQLServerDriver",
"fetchSize": 5000,
"idleConnectionTestPeriod": 60,
"initialPoolSize": 5,
"jdbcUrl": "jdbc:sqlserver://localhost:1433;databaseName=thingworx;applicationName=Thingworx;",
"maxConnectionAge": 0,
"maxIdleTime": 0,
"maxIdleTimeExcessConnections": 300,
"maxPoolSize": 100,
"maxStatements": 100,
"minPoolSize": 5,
"numHelperThreads": 8,
"password": "Password@123",
"testConnectionOnCheckout": false,
"unreturnedConnectionTimeout": 0,
"username": "msadmin"
},
"StreamProcessorSettings": {
"maximumBlockSize": 2500,
"maximumQueueSize": 250000,
"maximumWaitTime": 10000,
"numberOfProcessingThreads": 5,
"scanRate": 5,
"sizeThreshold": 1000,
"producerTimeout": 30000
},
"ValueStreamProcessorSettings": {
"maximumBlockSize": 2500,
"maximumWaitTime": 10000,
"maximumQueueSize": 500000,
"numberOfProcessingThreads": 5,
"scanRate": 5,
"sizeThreshold": 1000,
"producerTimeout": 30000
},
"PersistentPropertyProcessorSettings": {
"maximumBlockSize": 2500,
"maximumWaitTime": 1000,
"maximumQueueSize": 100000,
"numberOfProcessingThreads": 20,
"scanRate": 25,
"sizeThreshold": 1000,
"producerTimeout": 30000
}
}
},
"cache": {
"provider-type": "com.thingworx.cache.ignite.IgniteCacheProvider",
"ignite": {
"instance-name": "twx-core-server",
"client-mode": false,
"address-resolver": {
"type": "zookeeper",
"connection": "localhost:2181"
}
}
}
}

The parameters networkTimeout, queryTimeout, and producerTimeout must be used only from ThingWorx 9.2.8 and later, and ThingWorx 9.3.3 and later.

The NonceKeyTimeout value can only be set between 1–30 seconds, with a default value of 15 seconds.

platform-settings.json Settings

Basic Settings

Setting

Default

Description

BackupStorage

/ThingworxBackupStorage

The directory name where all backups are written to.

EnableContentSecurityPolicyFilter

false

When EnableContentSecurityPolicyFilter is set to FALSE, the Content Security Policy (CSP) filter is Enabled programmatically. If ClickjackFilters are defined in web.xml, they are Enabled. Clickjack Filter’s behavior will be per its configuration in web.xml.

When EnableContentSecurityPolicyFilter is set to TRUE, the CSP filter is Enabled programmatically. If ClickjackFilters are defined in web.xml, they are Disabled. The CSP secure defaults defined in ThingWorx Platform are in effect.

For more information, see Allowing Embedded Mashups in iFrames.

DatabaseLogRetentionPolicy

The number of days that database logs are retained.

DatabaseWriteRetryAttempts

Maximum attempts made by the system to retry persisting entries in the database in case of connection loss.

EnableBackup

true

Determines whether backups are retained.

EnableClusteredMode

false

Determines whether ThingWorx will run as a cluster or standalone server.

EnableSystemLogging

false

Determines whether system logging is enabled.

Do not turn this on unless instructed by ThingWorx Support.

EnableSSO

false

Set to true to enable SSO for ThingWorx Platform. When SSO is enabled, all authentication is redirected to the central authorization server that is configured in the sso-settings.json file. Edge WebSocket authentication is not affected.

FileRepositoryRoot

/ThingworxStorage

The directory where the root file repository is created. The default location is sufficient for standalone deployments. For ThingWorx HA deployments, the repository should be located on a shared file system where all ThingWorx servers have access.

FileTransferLockType

LOCAL

This parameter allows to set the locking type for the File Transfer functionality. This setting applicable to all the functionalities that makes use of FileRepositoryThing and its services.

Value can be one of the following:

• LOCAL—indicates file operations is synchronized on particular ThingWorx instance. This is the default option and works for most of the use scenarios.

• NOLOCK—indicates file operations are non-synchronized. The NOLOCK option does not lock the files or directories while performing the File Transfer related operations. Use the NOLOCK option after ensuring the use does not concurrently update the same file or directory.

PTC does not recommend having a large number of files copied or moved into the same directory concurrently.

HTTPRequestHeaderMaxLength

2000

The maximum allowable length for HTTP Request Headers values.

HTTPRequestParameterMaxLength

2000

The maximum allowable length for HTTP Request Parameter values.

InternalAesCryptographicKeyLength

128

Key length used when generating a symmetric AES key. Supported values are 128, 192, and 256.

Encryption and decryption will fail if the key length is higher than 128 and the Java policies are not configured to use that key size.

MashupWebsocketConnectionAliveAfterTimeout

false

Determines how mashup WebSocket connections are managed when a mashup is not in an active browser tab or window.

When set tofalse, connections are automatically disconnected when a mashup is not visible for more than 5 minutes.

When set totrue, connections are maintained when a mashup is running in a background tab or window. The mashup visibility state is ignored.

MetricsLoggingFrequency

Frequency in minutes at which the metrics collected by the platform will get logged to the Application Log.

MetricsLoggingLevel

WARN

Log level at which metrics collected by the platform will get logged to the Application Log. Value can be one of the following: WARN, DEBUG, TRACE, INFO, or ERROR.

MetricsReportingEnabled

n/a

Determines whether performance metrics data is sent to PTC. You can also configure this option in the Platform Subsystem. For more information on data collection in ThingWorx, see Data Collection in ThingWorx.

NonceKeyTimeout

The amount of time for the Nonce Key expiration time. Default value of is 15 seconds.

The acceptable values for this parameter are between 15 seconds to 30 seconds.

SessionUpdateDelay

The amount of time, in seconds, added to the lastUpdateTime, after which the session’s lastUpdateTime will be updated. If multiple requests are received during the delay, only the first request will update the lastUpdateTime. The default value is 60 seconds.

Storage

/ThingworxStorage

The directory where all storage directories are created/located (excluding Backup Storage).

ScriptTimeout

The maximum number of seconds that a script may execute before the ThingWorx platform terminates the script.

Scripts on the platform are terminated automatically if the script executes for longer than the number of seconds configured for this timeout.

Please consider the sensitivity and/or importance of the information handled by scripts when configuring their timeout duration. Although it is important to terminate scripts after a given period of time for security reasons, doing so prematurely can lead to a loss of data. Due to the flexibility of the ThingWorx platform, there are use cases that could potentially require timeout periods shorter or longer than the default.

MaxSearchItems

100000

Allow the users to increase the default search limit according to the number of entities present in the environment.

The MaxSearchItems set by the SearchFunctions resource group APIs in ThingWorx Composer will take precedence over the value set in platform-settings.json.

If the MaxSearchItems is set to greater than 100k, pass appropriate search criteria according to the use case to reduce the search time for fetching the required number of entities.

Set the MaxSearchItems parameter based on the number of entities in ThingWorx Platform. Do not set to max integer value: 2,147,483,647.

Restart your ThingWorx environment to apply the new MaxSearchItems value.

Domain Configuration Settings

Setting

Default

Description

ignoreTrustedDomains

true

If this flag if set to true, all the external HTTP calls via media entities are allowed. And if set to false, only HTTP calls to the domains listed under trustedDomains are allowed.

trustedDomains

List of verified and trusted domains that users can use to access media on Mashup via Media-Entity Object.

Currently, only HTTP and HTTPS protocols are supported. Requests to external media via any other protocol will be rejected at all time

Solution Central Settings

Setting

Default

Description

SolutionCentralHost

sc.thingworx.com

Solution Central host name.

SolutionCentralPort

443

Solution Central port details.

Do not set SolutionCentralPort if it has a default value.

KeyStorePath

/ThingworxPlatform/sc-keystore

Path for your keystore.

KeyStorePass

None

Password for your keystore.

For encrypting your password, set KeyStorePass to encrypt.sc.password.

ThingWorx Flow Settings

These properties are applicable only if ThingWorx Flow is installed on ThingWorx Foundation. These values must be defined, both in ThingWorx Flow and RabbitMQ configuration files and must not be edited unless changed across both applications.

Setting

Default

Description

EnableOrchestration

true

Indicates if ThingWorx Flow is enabled in ThingWorx Foundation.

QueueHost

localhost

RabbitMQ host name

QueuePort

5672

RabbitMQ port

QueueName

256mb

RabbitMQ queue name

QueueUsername

flowuser

RabbitMQ queue username

QueuePassword

encrypt.queue.password

RabbitMQ queue password

The password is automatically encrypted while installing ThingWorx Flow on the same machine as ThingWorx Foundation.

If ThingWorx Flow is installed on a different machine than ThingWorx Foundation, you need to encrypt this password.

QueueVHost

orchestration

RabbitMQ VHost name

TurnOffScopesApprovalPopup

false

Set the value to true to stop getting grant approval windows during the login process.

Extension Package Import Policy Settings

Extension import is disabled by default for all users. Use the following settings to configure extension import functionality. For more information, see Importing Extensions.

Setting

Description

Default

Examples

importEnabled

The top level control that represents the ability to import (=true) or not import (=false) extensions.

false

• "importEnabled": false - Extensions cannot be imported, even if other ExtensionPackageImportPolicy settings are set to true.

• "importEnabled": true - Passes the extension import to the next set of allow<Content>Resources settings (see rows below).

If the allow<Content>Resources settings are false, then an empty extension (no entities, extensible entities, or resources) can be imported. Since this is likely not a useful configuration, if importEnabled is set to true, at least one other allow<Content>Resources setting should also be set to true.

allowJarResources

Allows extensions with Jar Resources to be imported.

false

• "allowJarResources": true - allows extensions that declare jar files in their manifest as jar resources to be imported.

• "allowJarResources": false -will not allow extensions that declare jar files in their manifest as jar resources to be imported.

allowJavascriptResources

Allows extensions with JavaScript Resources to be imported.

false

• "allowJavascriptResources": true -allows extensions that declare JavaScript UI file resources of JS type in their manifest as JavaScript resources to be imported.

• "allowJavascriptResources": false - will not allow extensions that declare JavaScript UI file resources of JS type in their manifest as JavaScript resources to be imported.

allowCSSResources

Allows extensions with CSS Resources to be imported.

false

• "allowCSSResources": true -allows extensions that contain CSS UI file resources to be imported.

• "allowCSSResources": false -will not allow extensions that contain CSS UI file resources to be imported.

allowJSONResources

Allows extensions with JSON Resources (for example, localization files) to be imported.

false

• "allowJSONResources": true - allows extensions that contain JSON UI file resources to be imported.

• "allowJSONResources": false - will not allow extensions that contain JSON UI file resources to be imported.

allowWebAppResources

Allows extensions with Web Resources to be imported.

false

• "allowWebAppResources": true - allows extensions that contain WebApp UI file resources to be imported.

• "allowWebAppResources": false - will not allow extensions that contain WebApp UI file resources to be imported.

allowEntities

Allows extensions with non-extensible entities to be imported. Examples of non-extensible entities include:

• Application Key

• Authenticator

• Dashboard

• Data Analysis Definition

• Data Shape

• GenericContentEntity and derived child classes like State Definition, Style Definition, Style Theme

• Group

• Localization Table

• Log

• Mashup

• Media Entity

• Menu

• ModeledServiceProviderEntity and child classes like Notification Content

• Network

• Notification Definition

• Organization

• Persistence Provider

• PersistenceProviderPackage and derived child classes

• Project

• Thing Shape

• Thing Template

• User

• Vocabulary and derived child classes like DataTagVocabulary, ModelTagVocabulary

false

• "allowEntities": true - allows extensions that declare non-extensible entities in their manifest to be imported.

• "allowEntities": false - will not allow extensions that declare non-extensible entities in their manifest to be imported.

allowExtensibleEntities

Allows extensions with non-extensible entities to be imported. Examples of extensible entities include:

• DirectoryService and derived child classes

• ExtensionPackage

• Resource and derived child classes that contain custom functions/services used as resources similar to OOTB Resources such as InfoTableFunctions, EntityServices, and EncryptionServices.

The OOTB Subsystems that are not part of extensions are not affected.

• ScriptFunctionLibrary and derived child classes.

• Subsystem and derived child classes.

The OOTB Subsystems that are not part of extensions are not affected.

• Thing Package

• Widget

false

• "allowExtensibleEntities": true - allows extensions that declare extensible entities in their manifest to be imported.

• "allowExtensibleEntities": false - will not allow extensions that declare extensible entities in their manifest to be imported.

haCompatibilityImportLevel

When running ThingWorx in cluster mode, you can restrict the import of extensions to only those that have the haCompatibility flag set to true in the extension metadata. The default setting is WARN, which allows the import but generates a warning message in the application log. You can change the setting to DENY; in this case, the import fails and an error is generated in the application log.

WARN

• "haCompatibilityImportLevel": "WARN" - extension imports succeed and warnings are generated for extensions that do not have "haCompatible" : "TRUE" set.

• "haCompatibilityImportLevel": "DENY" - only extensions with "haCompatible" : "TRUE" will be imported. All other extension imports will fail, and error messages are generated.

Administrator User Settings

Setting	Default	Description
InitialPassword	n/a	The initial Administrator password that is required to log into ThingWorx for the first time. The minimum length can be configured in the User Management Subsystem (minimum 10 characters, default is 14 characters). See for more information.

Content Type Settings

Setting

Default

Description

supportedMediaEntityContentTypes

"image/svg+xml","image/png","image/gif","image/bmp","image/jpeg","application/pdf","image/vnd.microsoft.icon"

Comma-delimited list of valid MIME content types that can be dynamically linked to Media entities. Additional types can be added.

If the content type that is coming from a different server not a supported media entity type, then the content is downloaded as a file on the client machine instead of streamed with the media entity.

Licensing Connection Settings

Setting

Default

Description

username

n/a

PTC Support site username

password

n/a

PTC Support site password

timeout (in seconds)

After the timeout period, the following error is logged in the Application Log:

License Server could not process request

useProxy

false

Enables proxy settings for licensing. If true, proxy settings are used to connect to the licensing server.

proxyHost

The name of the proxy host.

proxyPort

The port number of the proxy host.

proxyScheme

http

http or https.

proxyUsername

The username for authentication if the proxy server connection requires authentication.

proxyPassword

The password for authentication if the proxy server connection requires authentication.

See Encrypting Passwords for information on encrypting this value.

proxyUseNTLM

false

Option to use the NTLM protocol.

proxyWorkstation

The name of the user's computer on the network, if NTLM authentication is required.

proxyDomain

The name of the user's domain, if NTLM authentication is required.

Metrics User Settings

Setting	Default	Description
InitialPassword		Creates the MetricsUser during system startup and is used by the Prometheus server to scrape metrics information from a ThingWorx instance. It’s required for all MSAI deployments, but optional for all other types of deployments.

Persistence Provider Settings

For all databases listed below, the following guidelines should be followed for value stream processor settings and stream processor settings :

StreamProcessorSettings.numberOfProcessingThreads + ValueStreamProcessorSettings.numberOfProcessingThreads < 50% of DB connection pool
And
ValueStreamProcessorSettings.numberOfProcessingThreads >= StreamProcessorSettings.numberOfProcessingThreads

H2PersistenceProviderPackage

Setting

Default

Description

Connection Information

acquireIncrement

Determines how many connections at a time the ThingWorx will try to acquire when the pool is exhausted.

acquireRetryAttempts

Defines how many times ThingWorx will try to acquire a new connection from the database before giving up.

acquireRetryDelay

1000

The time (in milliseconds) ThingWorx will wait between acquire attempts.

checkoutTimeout

1000000

The number of milliseconds a client calling getConnection() will wait for a connection to be checked-in or acquired when the pool is exhausted.

Network Timeout

900000

The amount of time (in milliseconds) for a thread to wait for response from database.

If no response is received within this configured time, platform will close the underlying connection and will release the thread waiting for the response.

idleConnectionTestPeriod

Time period (in seconds) where connections will be tested so that idle connections won’t be closed from outside processes such as firewalls, etc. If this is a number greater than 0, ThingWorx will test all idle, pooled but unchecked-out connections, every x number of seconds.

If you are experiencing “No connection to model provider” errors, review this setting. Compare to firewall defaults. Lowering the default will alleviate disconnection issues.

initialPoolSize

Initial number of database connections created and maintained within a pool upon startup. Should be between minPoolSize and maxPoolSize.

maxConnectionAge

Seconds, effectively a time to live. A connection older than maxConnectionAge will be destroyed and purged from the pool.

maxIdleTime

Seconds a connection can remain pooled but unused before being discarded. Zero means idle connections never expire.

maxIdleTimeExcessConnections

36000

The number of seconds that connections in excess of minPoolSize are permitted to remain in idle in the pool before being culled. Intended for applications that wish to aggressively minimize the number of open connections, shrinking the pool back towards minPoolSize if, following a spike, the load level diminishes and connections acquired are no longer needed. If maxIdleTime is set, maxIdleTimeExcessConnections should be smaller to have any effect. Setting this to zero means no enforcement and excess connections are not idled out.

maxPoolSize

100

Maximum number of connections a pool will maintain at any given time.

maxStatements

The size of the ThingWorx global PreparedStatement cache.

maxStatementsPerConnection

The size of the ThingWorx global PreparedStatement cache for each connection.

minPoolSize

Minimum number of connections a pool will maintain at any given time.

numHelperThreads

The number of helper threads to spawn. Slow JDBC operations are generally performed by helper threads that don't hold contended locks. Spreading these operations over multiple threads can significantly improve performance by allowing multiple operations to be performed simultaneously.

password

n/a

Database password.

username

twadmin

Database username.

tableLockTimeout

10000

The number of milliseconds a client will wait for a database table to be unlocked.

testConnectionOnCheckout

false

If true, an operation will be performed at every connection checkout to verify that the connection is valid.

unreturnedConnectionTimeout

The number of seconds to wait for a response from an unresponsive connection before discarding it. If set, if an application checks out but then fails to check-in a connection within the specified period of time, the pool will discard the connection. This permits applications with occasional connection leaks to survive, rather than eventually exhausting the connection pool. Zero means no timeout, and applications are expected to close their own connections.

StreamProcessorSettings

maximumBlockSize

2500

The maximum number of stream writes to process in one block.

maximumQueueSize

250000

The maximum number of stream entries to queue (will be rejected after that).

maximumWaitTime

10000

The maximum wait time (in milliseconds) before flushing stream buffer.

numberOfProcessingThreads

The number of threads to use when processing properties.

scanRate

The rate (in milliseconds) at which to check the buffer status.

sizeThreshold

1000

The maximum number of items to accumulate before flushing stream buffer.

Producer Timeout

3000

This setting applies to the Stream Entry Processors and is currently only effective for Persistent Property Processor.

In the event that a queue is full and does not have space for a new entry, this is the maximum time (milliseconds) a producer will wait to put entry on the queue. Once this wait time is over, if still the queue is full and space cannot be made available, then the entry will fail to be added to queue.

ValueStreamProcessorSettings

maximumBlockSize

2500

The maximum number of stream writes to process in one block.

maximumQueueSize

250000

The maximum number of stream entries to queue (will be rejected after that).

maximumWaitTime

10000

The maximum wait time (in milliseconds) before flushing the stream buffer.

numberOfProcessingThreads

The number of threads to use when processing properties.

scanRate

The rate (in milliseconds) at which to check the buffer status.

sizeThreshold

1000

The maximum number of items to accumulate before flushing stream buffer.

Producer Timeout

3000

This setting applies to the Stream Entry Processors and is currently only effective for Persistent Property Processor.

PersistentPropertyProcessorSettings

maximumBlockSize

2500

The maximum number of property writes to process in one block.

maximumWaitTime

1000

The maximum wait time (in milliseconds) before flushing the property buffer.

maximumQueueSize

100000

The maximum number of property entries to queue (will be rejected after that).

numberOfProcessingThreads

The number of threads to use when processing properties.

scanRate

The rate (in milliseconds) at which to check the buffer status.

sizeThreshold

1000

The maximum number of items to accumulate before flushing the property buffer.

Producer Timeout

3000

This setting applies to the Stream Entry Processors and is currently only effective for Persistent Property Processor.

PostgresPersistenceProviderPackage

Setting

Default

Description

ConnectionInformation

acquireIncrement

Determines how many connections at a time the platform will try to acquire when the pool is exhausted.

acquireRetryAttempts

Defines how many times ThingWorx will try to acquire a new connection from the database before giving up.

acquireRetryDelay

10000

The time (in milliseconds) ThingWorx will wait between acquire attempts.

checkoutTimeout

10000000

The number of milliseconds a client calling getConnection()will wait for a connection to be checked-in or acquired when the pool is exhausted.

Query Timeout

600000

The amount of time (in milliseconds) a query will wait to complete before it is cancelled.

Network Timeout

900000

The amount of time (in milliseconds) for a thread to wait for response from database.

If no response is received within this configured time, platform will close the underlying connection and will release the thread waiting for the response.

driverClass

org.postgresql.Driver

The fully-qualified class name of the JDBC driverClass that is expected to provide Connections.

fetchSize

5000

The count of rows to be fetched in batches instead of caching all rows on the client side.

idleConnectionTestPeriod

If this is a number greater than 0, ThingWorx will test all idle, pooled but unchecked-out connections, every x number of seconds.

initialPoolSize

Initial number of database connections created and maintained within a pool upon startup. Should be between minPoolSize and maxPoolSize.

jdbcUrl

jdbc:postgresql://localhost:5432/thingworx

The JDBC URL used to connect to PostgreSQL.

If the default schema name is changed (from public), you must add <databasename>?currentSchema=<name of schema>. For example, if the schema name is mySchema, it would be: jdbc:postgresql://<DBServer>:<DBPort>/<databasename>?currentSchema=mySchema

If you are configuring an HA solution, this should reflect the server IP that the pgPool process is running on. Change the port to the port that pgPool is serving.

maxConnectionAge

Seconds, effectively a time to live. A Connection older than maxConnectionAge will be destroyed and purged from the pool.

maxIdleTime

Seconds a connection can remain pooled but unused before being discarded. Zero means idle connections never expire.

maxIdleTimeExcessConnections

300

maxPoolSize

100

Maximum number of connections a pool will maintain at any given time.

maxStatements

100

The size of ThingWorx’s global PreparedStatement cache.

minPoolSize

Minimum number of Connections a pool will maintain at any given time.

numHelperThreads

password

The password used to log into the database.

sslMode

prefer

The SSL mode to connect to PostgreSQL. See PostgreSQL Documentation for more information about different SSL modes.

sslRootCert

The certificate to connect to PostgreSQL. This is mandatory for verify-ca and verify-full SSL modes. For more information about secure communication with Azure PostgreSQL Flex Server and to download the certificate, see Encrypted connectivity using TLS/SSL in Azure Database for PostgreSQL — Flexible Server.

testConnectionOnCheckout

false

If true, an operation will be performed at every connection checkout to verify that the connection is valid.

unreturnedConnectionTimeout

The number of seconds to wait for a response from an unresponsive connection before discarding it. If set, if an application checks out but then fails to check-in a connection within the specified period of time, the pool will discard the connection. This permits applications with occasional connection leaks to survive, rather than eventually exhausting the Connection pool. Zero means no timeout, and applications are expected to close their own connections.

username

twadmin

The user that has the privilege to modify tables. This is the user created on the database for the ThingWorx server.

To change the PostgreSQL password: Change this user's password, and also change the unencrypted password setting in the platform-settings.json file or the encrypted value in the /ThingworxStorage/keystore.jks keystore.

Stream Processor Settings

maximumBlockSize

2500

The maximum number of stream writes to process in one block.

maximumQueueSize

250000

The maximum number of stream entries to queue (will be rejected after that).

maximumWaitTime

10000

Number of milliseconds the system waits before flushing the stream buffer.

numberOfProcessingThreads

The number of processing threads.

scanRate

The buffer status is checked at the specified rate value in milliseconds.

sizeThreshold

1000

Maximum number of items to accumulate before flushing the stream buffer.

Producer Timeout

3000

This setting applies to the Stream Entry Processors and is currently only effective for Persistent Property Processor.

Value Stream Processor Settings

maximumBlockSize

2500

Maximum number of value stream writes to process in one block.

maximumQueueSize

500000

Maximum number of value stream entries to queue (will be rejected after that).

maximumWaitTime

10000

Number of milliseconds the system waits before flushing the value stream buffer.

numberofProcessingThreads

The number of processing threads.

scanRate

The rate (in milliseconds) before flushing the stream buffer.

sizeThreshold

1000

Maximum number of items to accumulate before flushing the value stream buffer.

Producer Timeout

3000

This setting applies to the Stream Entry Processors and is currently only effective for Persistent Property Processor.

PersistentPropertyProcessorSettings

maximumBlockSize

2500

The maximum number of property writes to process in one block.

maximumWaitTime

1000

The maximum wait time (in milliseconds) before flushing the property buffer.

maximumQueueSize

100000

The maximum number of property entries to queue (will be rejected after that).

numberOfProcessingThreads

The number of threads to use when processing properties.

scanRate

The rate (in milliseconds) at which to check the buffer status.

sizeThreshold

1000

The maximum number of items to accumulate before flushing the property buffer.

Producer Timeout

3000

This setting applies to the Stream Entry Processors and is currently only effective for Persistent Property Processor.

MssqlPersistenceProviderPackage

Setting

Default

Description

ConnectionInformation

acquireIncrement

Determines how many connections at a time ThingWorx will try to acquire when the pool is exhausted.

acquireRetryAttempts

Defines how many times ThingWorx will try to acquire a new connection from the database before giving up.

acquireRetryDelay

10000

The time (in milliseconds) ThingWorx will wait between acquire attempts.

checkoutTimeout

1000000

The number of milliseconds a client calling getConnection() will wait for a connection to be checked-in or acquired when the pool is exhausted.

driverClass

com.microsoft.sqlserver.jdbc.SQLServerDriver

The fully-qualified class name of the JDBC driverClass that is expected to provide connections.

fetchSize

5000

The count of rows to be fetched in batches instead of caching all rows on the client side.

idleConnectionTestPeriod

If you are experiencing “No connection to model provider” errors, review this setting. Compare to firewall defaults. Lowering the default will alleviate disconnection issues.

initialPoolSize

Initial number of database connections created and maintained within a pool upon startup. Should be between minPoolSize and maxPoolSize.

jdbcUrl

jdbc:sqlserver://localhost:1433;databaseName=thingworx;applicationName=Thingworx;

The jdbc url used to connect to MSSQL.

maxConnectionAge

Seconds, effectively a time to live. A connection older than maxConnectionAge will be destroyed and purged from the pool.

maxIdleTime

Seconds a connection can remain pooled but unused before being discarded. Zero means idle connections never expire.

maxIdleTimeExcessConnections

300

The number of seconds that connections in excess of minPoolSize are permitted to remain in idle in the pool before being culled. Intended for applications that wish to aggressively minimize the number of open connections, shrinking the pool back towards minPoolSize if, following a spike, the load level diminishes and Connections acquired are no longer needed. If maxIdleTime is set, maxIdleTimeExcessConnections should be smaller to have any effect. Setting this to zero means no enforcement and excess connections are not idled out.

maxPoolSize

100

Maximum number of Connections a pool will maintain at any given time.

maxStatements

100

The size of the ThingWorx global PreparedStatement cache.

minPoolSize

Minimum number of Connections a pool will maintain at any given time.

numHelperThreads

password

The password to log into the database.

testConnectionOnCheckout

false

If true, an operation will be performed at every connection checkout to verify that the connection is valid.

unreturnedConnectionTimeout

The number of seconds to wait for a response from an unresponsive connection before discarding it. If set, if an application checks out but then fails to check-in a connection within the specified period of time, the pool will discard the connection. This permits applications with occasional connection leaks to survive, rather than eventually exhausting the Connection pool. Zero means no timeout, and applications are expected to close their own connections.

username

msadmin

This is the user ID that owns the TWSCHEMA schema and is used for authentication to MSSQL in the JDBC connection string.

Query Timeout

600000

The amount of time (in milliseconds) a query will wait to complete before it is cancelled.

Network Timeout

900000

The amount of time (in milliseconds) for a thread to wait for response from database.

If no response is received within this configured time, platform will close the underlying connection and will release the thread waiting for the response.

Stream Processor Settings

maximumBlockSize

2500

The maximum number of stream writes to process in one block.

maximumQueueSize

250000

The maximum number of stream entries to queue (will be rejected after that).

maximumWaitTime

10000

Number of milliseconds the system waits before flushing the stream buffer.

numberOfProcessingThreads

The number of processing threads.

scanRate

The buffer status is checked at the specified rate value in milliseconds.

sizeThreshold

1000

Maximum number of items to accumulate before flushing the stream buffer.

Producer Timeout

3000

This setting applies to the Stream Entry Processors and is currently only effective for Persistent Property Processor.

Value Stream Processor Settings

maximumBlockSize

2500

Maximum number of value stream writes to process in one block.

maximumWaitTime

10000

Number of milliseconds the system waits before flushing the value stream buffer.

maximumQueueSize

500000

Maximum number of value stream entries to queue (will be rejected after that).

numberofProcessingThreads

The number of processing threads.

scanRate

The rate (in milliseconds) before flushing the stream buffer.

sizeThreshold

1000

Maximum number of items to accumulate before flushing the value stream buffer.

Producer Timeout

3000

This setting applies to the Stream Entry Processors and is currently only effective for Persistent Property Processor.

PersistentPropertyProcessorSettings

maximumBlockSize

2500

The maximum number of property writes to process in one block.

maximumWaitTime

1000

The maximum wait time (in milliseconds) before flushing the property buffer.

maximumQueueSize

100000

The maximum number of property entries to queue (will be rejected after that).

numberOfProcessingThreads

The number of threads to use when processing properties.

scanRate

The rate (in milliseconds) at which to check the buffer status.

sizeThreshold

1000

The maximum number of items to accumulate before flushing the property buffer.

Producer Timeout

3000

This setting applies to the Stream Entry Processors and is currently only effective for Persistent Property Processor.

Cache Settings

The cache settings are only required when running ThingWorx Platform in cluster mode.

If you are running single-server mode, exclude the cache settings from the configuration. If they are included for single-server mode, they will run the distributed caching mode using Apache Ignite, which is less performant than running the default local memory caching.

Setting	Default	Description
provider-type	[The cache provider for running in single-server mode.]	In cluster mode, the value should always be set to com.thingworx.cache.ignite.IgniteCacheProvider.
instance-name	none	Sets the cache’s local instance name.
client-mode	true	Determines if the embedded Ignite runs as a client (default) or server. In server mode, it participates in storing data and will use more memory.
address-resolver type	static	Determines how other Ignite nodes will be discovered. The recommended setting is zookeeper.
connection	none	For an address-resolver type of zookeeper, a comma-delimited list of the Apache ZooKeeper servers used to coordinate ThingWorx leader election. The string pattern is IP:port (for example, 127.0.0.1:2181, 127.0.0.2:2181).
endpoints	none	For an address-resolver type of static, an array of static addresses where Ignite is running.

Adding an Audited Event Section to platform-settings.json

When the ThingWorx Platform is restarted, all Things trigger the ThingStart event. Auditing all these events increases the startup time of the platform. To avoid that situation, the ThingStart event is disabled by default. If you still want to audit this action, it is possible to enable and disable events in the platform-settings.json file.

The platform-settings.json file does not contain a section for Audit. To enable or disable categories and messages, you need to add a JSON structure to the file. For the ThingWorx Platform instance for which you want audit messsages, you need to be an Administrator that has permissions to locate and edit the platform-settins.json file and add the appropriate configuration.

The Audit section must be added as a sibling node to the JSON entry of PlatformSettingsConfig. It can be located before or after the PlatformSettingsConfig node, but it must be at the same node level.

Here is an example of an Audit structure placed after the PlatformSettingsConfig node in the platform-settings.json file:

"PlatformSettingsConfig:: {
"BasicSettings":( . . .
}
}
"Audit": {
"Disabled": [{
"CategoryKey": "audit.AuditCategory.Collaboration",
"MessageKeys": ["ALL"]
}, {
"CategoryKey": "audit.AuditCategory.Authentication",
"MessageKeys": [
"com.thingworx.things.security.SecurityMonitorThing.LoginSucceeded.Audit",
"com.thingworx.things.security.SecurityMonitorThing.ApplicationKeyFailed.Audit"
]
}
],
"Enabled": [{
"CategoryKey": "audit.AuditCategory.RemoteAccess",
"MessageKeys": ["ALL"]
}, {
"CategoryKey": "audit.AuditCategory.Authentication",
"MessageKeys": [
"thingworx.things.security.SecurityMonitorThing.LoginFailed.Audit" ]
], {
"CategoryKey": "audit.AuditCategory.ThingGroupMemberships",
"MessageKeys": [
"com.thingworx.thinggroups.ThingGroup.AddedThingAsChildMember",
"com.thingworx.thinggroups.ThingGroup.DeletedThingAsChildMember",
"com.thingworx.thinggroups.ThingGroup.AddedThingGroupAsChildMember",
"com.thingworx.thinggroups.ThingGroup.DeletedThingGroupAsChildMember",
"com.thingworx.thinggroups.ThingGroup.DeletedAllChildMembers"
]
}
]
}

In this example, the COLLABORATION category and ["ALL"] of its events/messages are disabled. For the AUTHENTICATION category, two events/messages are disabled, LoginSucceeded and ApplicationKeyFailed. The REMOTE_ACCESS and ["ALL"] of its events/messages are enabled. For the AUTHENTICATION category, the LoginFailed event/message is enabled. For he THINGGROUPMEMBERSHIPs, all of the audit messages are enabled. Instead of using ["ALL"], these messages are listed separately. You may want to choose this method of entering audit messages so that you can determine after running the platform instance for a while whether you need them all.

The audit.AuditCategory.ThingGroupMemberships category provides audit messages about changes in the membership of a Thing Group. This category of audit messages is disabled by default because not all configurations/deployments require such audit messages nor do system administrators want to incur the computation and persistence impact of these changes. If your configurations/deployments require audit messages for changes in Thing Group membership, you can enable them as shown in the example above. The setting for each audit message can be enabled or disabled without needing to enable or disable other audit messages. You may want to audit only certain membership changes, for example. The audit messages for Thing Group memberships are listed in the table, Table 128, in the topic, ThingWorx Audit Messages in this help center.

The audit messages for the following two message types are always enabled and do not require explicit enabling. They provide audit messages when the Visibility Permission Delegation feature for Thing Groups is enabled or disabled:

com.thingworx.thinggroups.ThingGroup.VisibilityPermissionDelegationEnabled
com.thingworx.thinggroups.ThingGroup.VisibilityPermissionDelegationDisabled

To enable or disable any category and audit message, you can copy the structure shown above and add the appropriate keys to the "Disabled" and/or "Enabled" groups. For a step-by-step procedure, refer to Enabling and Disabling Audit Events. To find the appropriate keys for categories and event messages, refer to the table, Table 128, in the topic, ThingWorx Audit Messages, in this help center.

Was this helpful?