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 and call the delete method on a previously deployed smart rule to delete it from Cumulocity.

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

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

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

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.

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

Parameters:

tenant (CumulocityTenant.) – The Cumulocity 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, 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, 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, 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, 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, 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, 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, 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, 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, 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, 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, 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.

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