Apama 10.15.0 | Connecting Apama Applications to External Components | Standard Connectivity Plug-ins | The Cumulocity IoT Transport Connectivity Plug-in | Configuring the Cumulocity IoT transport
 
Configuring the Cumulocity IoT transport
When you add the Cumulocity Client connectivity bundle in Software AG Designer, a .properties configuration file is created. You have to provide all required information in that file in order to connect to Cumulocity IoT.
Note: 
It is strongly recommended that you do not change the YAML configuration file which also comes with the bundle. You should always set the properties in the .properties configuration file, which defines the substitution variables to be used in the YAML configuration file.
The following is an example of a filled out .properties configuration file:
# Username and password must be provided for authentication
CUMULOCITY_USERNAME=MYNAME
CUMULOCITY_PASSWORD=MYPW

# Application key and the URL of the application
CUMULOCITY_APPKEY=MYAPP
CUMULOCITY_SERVER_URL=https://myserver.cumulocity.com

# TLS certificate authority file
CUMULOCITY_AUTHORITY_FILE=

# Allow connection to Cumulocity IoT instance with unknown certificate
CUMULOCITY_ALLOW_UNAUTHORIZED_SERVER=false

# Set this to the tenant ID if you don't have a per-tenant hostname
CUMULOCITY_TENANT=

# Set Cumulocity IoT measurement format
CUMULOCITY_MEASUREMENT_FORMAT=BOTH

CUMULOCITY_FORCE_INITIAL_HOST=true

# Proxy server host and port to start using HTTP proxy
CUMULOCITY_PROXY_HOST=proxy_host
CUMULOCITY_PROXY_PORT=

# Proxy username and password must be provided for basic authentication
CUMULOCITY_PROXY_USERNAME=ProxyUser
CUMULOCITY_PROXY_PASSWORD=ProxyPW

# Number of concurrent REST connections to use
CUMULOCITY_NUM_CLIENTS=3
In order to connect to Cumulocity IoT, it is required that you set the following properties.
Property
Description
CUMULOCITY_USERNAME
Username for authentication. This can be specified either as a username alone or in the form of tenantID/username. In recent versions of Cumulocity IoT, the tenant ID is visible in the web applications in the user menu in the top right.
Type: string.
CUMULOCITY_PASSWORD
Password for authentication.
Type: string.
CUMULOCITY_APPKEY
Unique key for the application defined on the Cumulocity IoT instance.
The application key is defined in Cumulocity IoT. Log in to your account in Cumulocity IoT, and use the Administration application to add an external application. You can then specify the application key and the URL of the application. See the Cumulocity IoT documentation at http://cumulocity.com/guides/ for more information.
Type: string.
CUMULOCITY_SERVER_URL
URL of the Cumulocity IoT tenant.
Type: string.
Under normal conditions in the cloud, the above properties are all you need to set. The properties listed below may be useful for custom on-premises installations of Cumulocity IoT or for Cumulocity IoT Edge.
Property
Description
CUMULOCITY_AUTHORITY_FILE
The TLS certificate authority file. If you are using your own server and it is not signed by a trusted Certificate Authority (CA), provide the certificate of your signing authority here.
Type: string.
CUMULOCITY_ALLOW_UNAUTHORIZED_SERVER
Set this to true when the user is connecting to a Cumulocity IoT platform whose certificate is not signed by a trusted CA authority. This generally happens in the Cumulocity IoT Edge instance where the installation is using a self-signed certificate.
Default: false.
CUMULOCITY_TENANT
Unique name of the application tenant. This configuration option is useful in the case of Cumulocity IoT Edge.
Type: string.
CUMULOCITY_MEASUREMENT_FORMAT
The measurement format mode used by the tenant. Two modes are available: MEASUREMENT_ONLY and BOTH. For more information, see Turning measurement fragments on/off.
Type: string.
Default: BOTH.
CUMULOCITY_FORCE_INITIAL_HOST
If set to false, the endpoint details returned by the Cumulocity IoT platform are used. If set to true, the Cumulocity IoT SDK always uses the URL provided during session initialization instead of the endpoint details. This is helpful in deployment scenarios where the Cumulocity IoT instance is reachable only with an IP address.
Type: boolean.
Default: true.
CUMULOCITY_PROXY_HOST
The name of the proxy server to connect to.
Type: string.
CUMULOCITY_PROXY_PORT
The port number of the proxy server to connect to.
Both host and port are required to enable an HTTP proxy.
Type: integer.
CUMULOCITY_PROXY_USERNAME
Optional proxy user name for HTTP basic authentication.
Type: string.
CUMULOCITY_PROXY_PASSWORD
Optional proxy password for HTTP basic authentication.
Provide both user name and password if the proxy server has basic authentication enabled.
Type: string.
CUMULOCITY_NUM_CLIENTS
The number of simultaneous client connections to use for handling queries to the platform.
Type: integer.
Default: 3.
CUMULOCITY_REQUEST_ALL_DEVICES
Deprecated. Request all assets at startup.
Type: boolean.
Default: false.
Note: 
You should explicitly request for all available devices on startup using the com.apama.cumulocity.FindManagedObject API. For more information, see Sample EPL.
CUMULOCITY_SUBSCRIBE_ALL_MEASUREMENTS
Subscribe to measurements, events and alarms of all devices during startup.
Type: boolean.
Default: true.
CUMULOCITY_SUBSCRIBE_DEVICES
Subscribe to all device-related updates.
Type: boolean.
Default: true.
CUMULOCITY_SUBSCRIBE_OPERATIONS
Subscribe to all device operations.
Type: boolean.
Default: true.
CUMULOCITY_MULTI_TENANT_APPLICATION
Set this to true when developing an application that will be deployed using MULTI_TENANT isolation in Cumulocity IoT. It is used only when running as an external project and connecting to remote Cumulocity IoT. See also Working with multi-tenant deployments.
Type: boolean.
Default: false.
CUMULOCITY_MULTI_TENANT_MICROSERVICE_NAME
The name of the multi-tenant microservice to use. It is used only when running as an external multi-tenant project and connecting to remote Cumulocity IoT. It is required when developing a MULTI_TENANT microservice application and is ignored if the CUMULOCITY_MULTI_TENANT_APPLICATION property is not already set.
If a multi-tenant microservice does not already exist, either upload a multi-tenant microservice or create a microservice with a valid manifest. Subscribe the microservice to tenants for which you want to run the project.
Type: string.
The following properties are not provided by default in the .properties configuration file. If you add them, they will be used.
Property
Description
CUMULOCITY_INITIAL_DELAY_SECS
The initial delay (in seconds) that can be set for querying tenant subscriptions.
Type: float.
Default: 0 seconds.
CUMULOCITY_MAX_BATCH_SIZE
The maximum number of Apama events that can be batched as a single request before sending to Cumulocity IoT. The only event type that supports batching is com.apama.cumulocity.Measurement.
Type: integer.
Default: 1000.
CUMULOCITY_LATENCY_SLOW_THRESHOLD_SECS
Update the mostRecentSlowRequestDetails status (see Monitoring status for Cumulocity IoT) if the time for fetching one page of response multiplied by the number of total pages is greater than this threshold.
Set this to 0 to disable updates.
Type: integer.
Default: 1 second.
CUMULOCITY_LATENCY_LOG_THRESHOLD_SECS
Log a warning if a single-paged or multi-paged request takes more time to complete than defined by this threshold.
Set this to 0 to disable logging.
Type: integer.
Default: 10 seconds.
CUMULOCITY_LATENCY_BATCH_THRESHOLD_SECS
Log a warning if a batch of requests takes more time to complete than defined by this threshold. If a warning for an individual request of the batch has already been logged with CUMULOCITY_LATENCY_LOG_THRESHOLD_SECS, then a warning for this batch is not logged.
Set this to 0 to disable logging.
Type: integer.
Default: 50 seconds.
CUMULOCITY_SMS_SENDER_NAME
The sender name to be used as the default if it is not specified in the SendSMS event and not configured in the messaging/sms.senderName tenant option of Cumulocity IoT.
The tenant option is given preference over the value of CUMULOCITY_SMS_SENDER_NAME. The tenant option is checked for every SendSMS event. If the check does not find it in Cumulocity IoT, then only the value of CUMULOCITY_SMS_SENDER_NAME is used as the default sender name.
Type: string.
Default: Apama.
CUMULOCITY_SMS_SENDER_ADDRESS
The sender address to be used as the default if it is not specified in the SendSMS event and not configured in the messaging/sms.senderAddress tenant option of Cumulocity IoT.
The tenant option is given preference over the value of CUMULOCITY_SMS_SENDER_ADDRESS. The tenant option is checked for every SendSMS event. If the check does not find it in Cumulocity IoT, then only the value of CUMULOCITY_SMS_SENDER_ADDRESS is used as the default sender address.
You can provide a sender address in the following formats: PROTOCOL:NUMBER or just NUMBER. Valid protocols include tel, SHORT, ICCID and ACR. If the protocol is missing or invalid, tel is used as the default protocol.
Type: string.
Default: apama.
CUMULOCITY_CONCURRENCY_MODE
If set to auto (default), the transport tries to order requests across multiple clients to avoid races between multiple updates relating to the same managed object. For more information, see Optimizing requests to Cumulocity IoT with concurrent connections. If set to always, no attempt to preserve order is made.
Type: string.
Default: auto.
See also Receiving update notifications.