apamax.eplapplications.smartrules¶

SmartRule¶

class apamax.eplapplications.smartrules.SmartRule(ruleType, configuration, smartRulesManager)[source]¶

Bases: object

Class representing a smart rule object.

An instance of this class must be created by calling the appropriate build method of the class SmartRulesManager.

Call the deploy method to deploy a smart rule to Cumulocity IoT and call the delete method on a previously deployed smart rule to delete it from Cumulocity IoT.

Any updates to the object are not deployed on Cumulocity IoT until the deploy method is called.

delete(**kwargs)[source]¶: Delete the smart rule from Cumulocity IoT.

deploy(**kwargs)[source]¶: Deploy the smart rule to Cumulocity IoT.

getConfiguration()[source]¶

Get the configuration of the smart rule instance.

Returns: The configuration.
Return type: dict

getDisabledSources()[source]¶

Get the list of device IDs for which this smart rule is disabled.

Returns: The list of device IDs.
Return type: list

getEnabledSources()[source]¶

Get the list of device IDs for which this smart rule is enabled.

The list will be empty for a global smart rule that is enabled for all devices.

Returns: The list of device IDs.
Return type: list

getID()[source]¶

Get the ID of the smart rule.

Returns None if the smart rule is deleted or not yet deployed.

Returns: ID of the smart rule.
Return type: str

getRuleName()[source]¶

Get the name of the smart rule.

Returns: The name of the smart rule.
Return type: str

isEnabled()[source]¶

Check if the smart rule is enabled.

Returns: True if the smart rule is enabled, False otherwise.
Return type: bool

isGlobal()[source]¶

Check if the smart rule is global.

Returns: True if the smart rule is global, False otherwise.
Return type: bool

isLocal()[source]¶

Check if the smart rule is local to a device or a group.

Returns: True if the smart rule is local to a device or a group, False otherwise.
Return type: bool

setDisabledSources(deviceList)[source]¶

Set the list of device IDs for which this smart rule must be disabled.

The disabled sources list will be ignored if the enabled sources list is also set.

Parameters: deviceList (list) – The list of devices or device IDs.
Returns: The updated smart rule object.
Return type: SmartRule

setEnabled(enabled=True)[source]¶

Enable or disable the smart rule.

Parameters: enabled (bool) – The smart rule is enabled if True, otherwise it is disabled.
Returns: The updated smart rule object.
Return type: SmartRule

setEnabledSources(deviceList)[source]¶

Set the list of device IDs for which this smart rule must be enabled.

If the smart rule is local to a group, all devices must be part of the group.

Parameters: deviceList (str) – The list of devices or device IDs.
Returns: The updated smart rule object.
Return type: SmartRule

setGlobal()[source]¶

Set the smart rule to be global.

If a smart rule is previously set to be local to a device or group, it cannot be changed to be global.

Returns: The updated smart rule object.
Return type: SmartRule

setLocal(deviceOrGroupId)[source]¶

Set the smart rule to be local to the specified device or group.

If a smart rule is previously set to be global, it cannot be changed to be local to a device or group.

Parameters: deviceOrGroupId (str) – The ID of the device or group.
Returns: The updated smart rule object.
Return type: SmartRule

setRuleName(name, addTestPrefix=True)[source]¶

Set the name of the smart rule.

Parameters

name (str) – The name.
addTestPrefix (bool) – Add a test prefix to the name of the smart rule so that it can be identified and cleaned up as part of the test setup.

Returns

The updated smart rule object.

Return type

SmartRule

updateConfiguration(configuration)[source]¶

Update the configuration of the smart rule instance.

Parameters: configuration (dict[str,any]) – A dictionary of the updated configuration values.
Returns: The updated smart rule object.
Return type: SmartRule

SmartRulesManager¶

class apamax.eplapplications.smartrules.SmartRulesManager(tenant, log)[source]¶

Bases: object

Class responsible for building smart rules objects that can be deployed on Cumulocity IoT.

See the methods in the SmartRule class to customize a smart rule object and deploy it.

Parameters

tenant (CumulocityTenant.) – The Cumulocity IoT tenant.
log – The logger instance to use for logging.

build_calculateEnergyConsumption(inputFragment='c8y_EnergyCounter', inputSeries='E', timeIntervalMinutes=1.0, outputFragment='c8y_EnergyConsumption', outputSeries='E')[source]¶

Build a smart rule object for the rule “Calculate energy consumption”.

To deploy it to Cumulocity IoT, call the deploy method.

Parameters

inputFragment (str) – The name of the fragment for incoming measurements.
inputSeries (str) – The name of the series for incoming measurements.
timeIntervalMinutes (float) – The interval for which to calculate consumption values.
outputFragment (str) – The name of the fragment for generated measurements.
outputSeries (str) – The name of the series for generated measurements.

Returns

A smart rule object.

Return type

SmartRule

build_onAlarmDurationIncreaseSeverity(alarmTypes, alarmDurationMinutes=1.0)[source]¶

Build a smart rule object for the rule “On alarm duration increase severity”.

To deploy it to Cumulocity IoT, call the deploy method.

Parameters

alarmTypes (str or list[str]) – The types of alarms that trigger the rule.
alarmDurationMinutes (float) – The duration (in minutes) an alarm must be active before increasing the severity.

Returns

A smart rule object.

Return type

SmartRule

build_onAlarmEscalateIt(alarmTypes, escalationSteps)[source]¶

Build a smart rule object for the rule “On alarm escalate it”.

To deploy it to Cumulocity IoT, call the deploy method.

Call the build_onAlarmEscalateStepSendEmail or build_onAlarmEscalateStepSendSMS methods to create escalation steps.

Parameters

alarmTypes (str or list[str]) – The types of alarms that trigger the rule.
escalationSteps (list) – Escalation steps.

Returns

Return type

SmartRule

build_onAlarmEscalateStepSendEmail(sendTo, sendCC=None, sendBCC=None, replyTo=None, subject='New #{severity} alarm from #{source.name}', message='New #{severity} alarm has been received from #{source.name}. Alarm text is: "#{text}".')[source]¶

Build an escalation step to send an email for the rule “On alarm escalate it”.

Parameters

sendTo (str) – The recipients of the email.
sendCC (str, optional) – The recipients that are to receive a copy of the email.
sendBCC (str, optional) – The recipients that are to receive a blind copy of the email.
replyTo (str, optional) – The reply-to address for the email.
subject (str) – The subject of the email.
message (str) – The text of the email.

Returns

An escalation step object.

build_onAlarmEscalateStepSendSMS(smsTo, smsText='New #{severity} alarm has been received from #{source.name}. Alarm text is: "#{text}".')[source]¶

Build an escalation step to send an SMS for the rule “On alarm escalate it”.

Parameters

smsTo (str) – The target phone number for the SMS.
smsText (str) – The text of the SMS.

Returns

An escalation step object.

build_onAlarmExecuteOperation(alarmTypes, operation)[source]¶

Build a smart rule object for the rule “On alarm execute operation”.

To deploy it to Cumulocity IoT, call the deploy method.

Parameters

alarmTypes (str or list[str]) – The types of alarms that trigger the rule.
operation (dict[str,any]) – The operation that will be sent. It must be a dictionary representing a JSON description of the operation.

Returns

A smart rule object.

Return type

SmartRule

build_onAlarmSendEmail(alarmTypes, sendTo, sendCC=None, sendBCC=None, replyTo=None, subject='New #{severity} alarm from #{source.name}', message='New #{severity} alarm has been received from #{source.name}. Alarm text is: "#{text}".')[source]¶

Build a smart rule object for the rule “On alarm send email”.

To deploy it to Cumulocity IoT, call the deploy method.

Parameters

alarmTypes (str or list[str]) – The types of alarms that trigger the rule.
sendTo (str) – The recipients of the email.
sendCC (str, optional) – The recipients that are to receive a copy of the email.
sendBCC (str, optional) – The recipients that are to receive a blind copy of the email.
replyTo (str, optional) – The reply-to address for the email.
subject (str) – The subject of the email.
message (str) – The text of the email.

Returns

A smart rule object.

Return type

SmartRule

build_onAlarmSendSMS(alarmTypes, smsTo, smsText='Alarm occurred')[source]¶

Build a smart rule object for the rule “On alarm send SMS”.

To deploy it to Cumulocity IoT, call the deploy method.

Parameters

alarmTypes (str or list[str]) – The types of alarms that trigger the rule.
smsTo (str) – The target phone number for the SMS.
smsText (str) – The text of the SMS.

Returns

A smart rule object.

Return type

SmartRule

build_onGeofenceCreateAlarm(geofence, triggerAlarmOn='leaving', alarmType='c8y_GeofenceAlarm', alarmSeverity='MAJOR', alarmText='Geofence violation')[source]¶

Build a smart rule object for the rule “On geofence create alarm”.

To deploy it to Cumulocity IoT, call the deploy method.

Parameters

geofence (list[dict]) – The polygon that defines the boundaries of a region. It should be a list of dictionaries containing “lng” and “lat” keys.
triggerAlarmOn (str) – The reason for triggering the alarm - one of “entering”, “leaving”, or “both”. The default is “leaving”.
alarmType (str) – The type of raised alarms.
alarmSeverity (str) – The severity of raised alarms.
alarmText (str) – The alarm message.

Returns

A smart rule object.

Return type

SmartRule

build_onGeofenceSendEmail(geofence, sendTo, sendCC=None, sendBCC=None, replyTo=None, subject='New geofence violation from #{source.name}', message='New geofence violation from #{source.name}')[source]¶

Build a smart rule object for the rule “On geofence send email”.

To deploy it to Cumulocity IoT, call the deploy method.

Parameters

geofence (list[dict]) – The polygon that defines the boundaries of a region. It should be a list of dictionaries containing “lng” and “lat” keys.
sendTo (str) – The recipients of the email.
sendCC (str, optional) – The recipients that are to receive a copy of the email.
sendBCC (str, optional) – The recipients that are to receive a blind copy of the email.
replyTo (str, optional) – The reply-to address for the email.
subject (str) – The subject of the email.
message (str) – The text of the email.

Returns

A smart rule object.

Return type

SmartRule

build_onMeasurementExplicitThresholdCreateAlarm(fragment, series, rangeMin=90, rangeMax=100, alarmType='c8y_ThresholdAlarm', alarmText='Threshold exceeded')[source]¶

Build a smart rule object for the rule “On measurement explicit threshold create alarm”.

To deploy it to Cumulocity IoT, call the deploy method.

Parameters

fragment (str) – Measurement fragment the smart rule listens for.
series (str) – Measurement series the smart rule listens for.
rangeMin (float) – The minimum value of measurements for which an alarm is raised.
rangeMax (float) – The maximum value of measurements for which an alarm is raised.
alarmType (str) – The type of raised alarms.
alarmText (str) – The alarm message.

Returns

A smart rule object.

Return type

SmartRule

build_onMeasurementThresholdCreateAlarm(dataPointObjectID=None, alarmType='c8y_ThresholdAlarm', alarmText='Thresholds exceeded')[source]¶

Build a smart rule object for the rule “On measurement threshold create alarm”.

To deploy it to Cumulocity IoT, call the deploy method.

Parameters

dataPointObjectID (str) – The ID of the Data Point Library object to use to find the values for the red and yellow ranges.
alarmType (str) – The type of raised alarms.
alarmText (str) – The alarm message.

Returns

A smart rule object.

Return type

SmartRule

build_onMissingMeasurementsCreateAlarm(measurementType, timeIntervalMinutes=60, alarmType='c8y_MissingMeasurementsAlarm', alarmSeverity='MAJOR', alarmText='Missing measurements of type: #{type}')[source]¶

Build a smart rule object for the rule “On missing measurements create alarm”.

To deploy it to Cumulocity IoT, call the deploy method.

Parameters

measurementType (str) – The type of measurement.
timeIntervalMinutes (float) – Time (in minutes) to wait for missing measurements.
alarmType (str) – The type of raised alarms.
alarmSeverity (str) – The severity of raised alarms.
alarmText (str) – The alarm message.

Returns

A smart rule object.

Return type

SmartRule

getAllSmartRules(withLocalRules=False)[source]¶

Get all smart rules deployed on Cumulocity IoT.

Parameters: withLocalRules – If True, also include smart rules local to a device or group.
Returns: List of smart rule objects.
Return type: list[SmartRule]