Apama 10.7.2 | 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
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.
The following properties are not provided by default in the .properties configuration file. If you add them, they will be used.
Property
Description
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 MSISDN, SHORT, ICCID and ACR. If the protocol is missing or invalid, MSISDN is used as the default protocol.
Type: string.
Default: apama.
For advanced use cases, it is possible to edit the following configuration options directly in the YAML configuration file. There are no corresponding entries in the .properties file.
Configuration option
Description
requestAllDevices
Deprecated. Request all assets at startup.
Type: boolean.
Default: true.
Note:
requestAllDevices is set to false in the YAML configuration file. You should explicitly request for all available devices on startup using the com.apama.cumulocity.FindManagedObject API. For more information, see Sample EPL.
subscribeToAllMeasurements
Subscribe to measurements, events and alarms of all devices during startup.
Type: boolean.
Default: true.
subscribeToDevices
Subscribe to all device-related updates.
Type: boolean.
Default: true.
subscribeToOperations
Subscribe to all device operations.
Type: boolean.
Default: false.
Note:
subscribeToOperations is set to false by default when it is not explicitly specified in the YAML configuration file. However, for your convenience, when you add a new Cumulocity Client connectivity bundle in Software AG Designer or by using the apama_project tool, this option is already set to true in the resulting YAML configuration file.
See also Receiving update notifications.