Analytics Builder block reference

Overview of all blocks

The following table gives a brief description of all blocks that can be selected from the palette of the model editor, sorted alphabetically (excluding custom blocks that you have created yourself).

Block Name Description
Alarm Input Receives Alarm objects from a device, asset, devices in a group, or all input sources and reorders them based on the timestamp.
Alarm Output Creates a new Alarm object for a specified device, asset or for the trigger device with a pre-configured alarm name and parameters.
AND Performs a logical 'and' on the inputs.
Average (Mean) Calculates the mean of the values over time.
Combiner Calculates the output based on the selected mode and the connected inputs.
Constant Value Outputs a value, either when the Trigger input port receives a signal or at startup.
Counter Gives a count of the total inputs and repeated inputs.
Cron Timer Sends a signal output based on cron-like periodic timer syntax.
Crossing Counter Detects and counts the number of threshold crossings in the specified direction.
Delta Calculates the difference between successive input values.
Difference Calculates the absolute and signed differences between the connected inputs.
Direction Detection Detects whether the input value changes direction.
Discrete Statistics Generates statistics of sum, count, average (mean), standard deviation, minimum and maximum for discrete input values.
Duration Measures the time elapsed from a set start time.
Event Input Receives Event objects from a device, asset, or devices in a group and reorders them based on the timestamp.
Event Output Creates a new Event object for a specified device, asset or for the trigger device.
Expression Evaluates an expression to perform arithmetic or logical calculations or string operations.
Extract Property Extracts the specified property from the input value and converts it to the specified type.
From Base N Converts a base N string to a float.
Gate Blocks the input from going to output unless the gate is open and enabled.
Geofence Compares the input value against the defined geofence value to detect whether the device is within the geofence, and whether the device entered or exited the geofence.
Gradient Calculates the weighted linear regression gradient for the values.
Group Statistics Generates periodic aggregate values across all the devices in a group for which the block has received input values.
Integral Calculates the integral of the input value over time.
KPI Compares a value against either a KPI (Key Performance Indicator) or the data point of a device, asset or group of devices.
Latch Values Latches the latest input value received while the block is enabled.
Limit Outputs a value that is kept within the defined upper and lower limits.
Managed Object Input Receives ManagedObject objects from a device, asset, devices in a group, or all input sources.
Managed Object Output Updates a ManagedObject object for a specified device, asset or for the trigger device.
Measurement Input Receives Measurement objects from a device, asset, devices in a group, or all input sources and reorders them based on the timestamp.
Measurement Output Creates a new Measurement object for a specified device, asset or for the trigger device.
Minimum / Maximum Calculates the minimum and maximum of a value over time.
Missing Data Generates an output if the input has not occurred for a set amount of time.
NOT Performs a logical 'not' on the input.
Operation Input Receives Operation objects from a device, asset, devices in a group, or all input sources.
Operation Output Creates a new Operation object for a specified device, asset or for the trigger device.
OR Performs a logical 'or' on the inputs.
Position Input Receives Event objects from a device, asset, devices in a group, or all input sources and extracts the c8y_Position fragment into a Value object.
Pulse Converts a non-pulse input into a pulse output.
Range Compares the input value against the defined lower and upper range values to detect whether the input is within or out of the range, or whether it crosses the range.
Range Lookup Finds the range in which the input value lies.
Rounding Rounds the input to a specified number of decimal points or to an integer, using a selectable rule.
Selector Outputs a parameter value depending on which input port has a true value, lowest number taking precedence.
Send Email Sends an email to the specified email addresses.
Send SMS Sends an SMS (Short Message Service) to the specified phone number.
Set Properties Outputs a pulse with properties set from values on the input ports.
Standard Deviation Calculates the standard deviation and variance of the values over time.
Switch Outputs the values from a given input, or acts as a circuit breaker.
Text Substitution Substitutes identifiers marked with a hash and braces (for example, #{name}) in the text template with corresponding entries from the input values.
Threshold Compares the input value against the defined threshold value to detect whether the input breaches the threshold or whether it crosses the threshold.
Time Delay Delays the input by the specified amount of time.
To Base N Converts a float to a base N string.
Toggle Converts two pulse inputs to a boolean output based on the set and reset signals, with optional delays.

Input

This category contains the following blocks:

Block Name Description
Alarm Input Receives Alarm objects from a device, asset, devices in a group, or all input sources and reorders them based on the timestamp.
Event Input Receives Event objects from a device, asset, or devices in a group and reorders them based on the timestamp.
Managed Object Input Receives ManagedObject objects from a device, asset, devices in a group, or all input sources.
Measurement Input Receives Measurement objects from a device, asset, devices in a group, or all input sources and reorders them based on the timestamp.
Operation Input Receives Operation objects from a device, asset, devices in a group, or all input sources.
Position Input Receives Event objects from a device, asset, devices in a group, or all input sources and extracts the c8y_Position fragment into a Value object.

Alarm Input

apama.analyticskit.blocks.cumulocity.AlarmInput

Receives Alarm objects from a device, asset, devices in a group, or all input sources and reorders them based on the timestamp.

If the Alarm Status parameter is Active, then the alarms are reordered based on the timestamp (and dropped if they are too old), unless the Ignore Timestamp parameter is set. Otherwise, data is processed as it is received.

The parameters that define the input stream of the block are "Input Source" and "Alarm Type". If this block is configured with the same "Input Source" and "Alarm Type" parameters as an Alarm Output block in another model, then a connection between the models is formed, as each block refers to the same stream of Alarm objects.

Note: When running in simulation mode, because only the creation time of the alarm is stored, the alarm status must be Active.

Parameters

Name Description Type Notes
Alarm Type The alarm type the block is listening for. string
Input Source Defines the source from which the alarm has been received.

This can be a single device, an asset, an object that references or contains a group of devices, or all input sources.

any
Severity The severity of the alarm. If not specified, the block listens for all alarm severities.

Option - one of:

  • Critical
  • Major
  • Minor
  • Warning
Optional
Alarm Status The status of the alarm. If not specified, the block listens for alarms with any status.

Option - one of:

  • Active
  • Acknowledged
  • Cleared
Optional
Notification Mode Filters Alarm events such that only new alarms, updated alarms, or all alarms are processed. The default is that all alarms are processed.

Option - one of:

  • All
  • Updates only
  • New alarms only
Default: All
Ignore Timestamp If selected, the timestamp of the incoming alarm is ignored. Note: When running in simulation mode, because historical input data is used, timestamps are not ignored. boolean Default: False

Output Port Details

Name Description Type
Alarms Generates a pulse output for each Alarm object received, with extra properties. pulse

Event Input

apama.analyticskit.blocks.cumulocity.DeviceEventInput

Receives Event objects from a device, asset, or devices in a group and reorders them based on the timestamp.

If the Ignore Timestamp parameter is set, the block ignores the timestamp of the event and processes the events as they are received. Otherwise, it drops old events.

The parameters that define the input stream of the block are "Input Source" and "Event Type". If this block is configured with the same "Input Source" and "Event Type" parameters as an Event Output block in another model, then a connection between the models is formed, as each block refers to the same stream of Event objects.

Note: When running in simulation mode, because historical input data is used, timestamps are not ignored.

Note: A history of changes is not maintained for Event objects, and it is thus not possible to retrieve the original objects from the inventory. For this reason, a model which contains this input block type may behave differently in simulation mode than it would in production mode.

Parameters

Name Description Type Notes
Input Source Defines the source from which the event has been received.

This can be a single device, an asset, an object that references or contains a group of devices, or all input sources.

any
Event Type The event type the block is listening for. string
Notification Mode Filters Event events such that only new events, updated events, or all events are processed. The default is that all events are processed.

Option - one of:

  • All
  • Updates only
  • New events only
Default: All
Ignore Timestamp If selected, the timestamp of the incoming event is ignored. Note: When running in simulation mode, because historical input data is used, timestamps are not ignored. boolean Default: False

Output Port Details

Name Description Type
Events Generates a pulse output for each Event object received, with extra properties. pulse

Managed Object Input

apama.analyticskit.blocks.cumulocity.ManagedObjectInput

Receives ManagedObject objects from a device, asset, devices in a group, or all input sources.

The block does not reorder the received ManagedObject objects and processes them as they are received. If the Property Name parameter is supplied, then the block does not produce new output if the value of the specified property has not changed since the last output, even if other properties on the same ManagedObject object have changed.

The Value output from the block contains all properties on the ManagedObject object, including the property specified by the Property Name parameter. Property values can be accessed using the Extract Property block.

Properties with values of type string, boolean or float can be accessed by specifying the name of the property in the Extract Property block. For example, if the name of the property is ap_State, then specify ap_State as the value for the Property Path parameter of the Extract Property block.

If a property value is of type JSON object or sequence, then nested values can be accessed by specifying the full path to the nested values as the name of the property.

For example, if the name of the property is c8y_SpeedMeasurement and the value is { "Speed": { "value": 1234, "unit": "km/h" } } (in JSON form), then specify c8y_SpeedMeasurement.Speed.unit as the value for the Property Path parameter of the Extract Property block to extract the value of the unit.

Any position data associated with the ManagedObject object is available as a c8y_Position property and can be extracted using the Extract Property block.

If the value of the property specified by the Property Name parameter of this block is of type string, boolean or float, then the value is also directly available in the Value output port and can be directly consumed by blocks consuming values of that type without using the Extract Property block, for example, the Expression or Difference blocks.

The parameters that define the input stream of the block are "Input Source" and "Property Name".

Parameters

Name Description Type Notes
Input Source Defines the source from which the managed object has been received.

This can be a single device, an asset, an object that references or contains a group of devices, or all input sources.

any
Property Name The name of the property for which to listen.

The ManagedObject object must have a property of this name. Otherwise, it is ignored. If not set, the objects are not filtered. Every update generates a pulse output with all of the properties from the ManagedObject.

string Optional
Capture Start Value Outputs the initial value when the model is activated. This parameter must not be selected if the Input Source parameter is set to "All Inputs". boolean Default: False

Output Port Details

Name Description Type
Value Generates an output for each ManagedObject object received.

All properties of the managed object are available as extra properties. You can use the Extract Property block to access their values.

any

Measurement Input

apama.analyticskit.blocks.cumulocity.DeviceMeasurementInput

Receives Measurement objects from a device, asset, devices in a group, or all input sources and reorders them based on the timestamp.

If the Ignore Timestamp parameter is set, the block ignores the timestamp of the measurement and processes the measurements as they are received. Otherwise, it drops old measurements.

If using a group for input, select a device within the group to select the fragment and series, and then change to the desired group.

The parameters that define the output stream of the block are "Input Source" and "Fragment and Series". If this block is configured with the same "Input Source" and "Fragment and Series" parameters as a Measurement Output block in another model, then a connection between the models is formed, as each block refers to the same stream of Measurement objects.

Note: When running in simulation mode, because historical input data is used, timestamps are not ignored.

Parameters

Name Description Type Notes
Input Source Defines the source from which the measurement has been received.

This can be a single device, an asset, an object that references or contains a group of devices, or all input sources.

any
Fragment and Series The fragment the block is listening for.

This only shows fragments and series for measurements associated with the object (device or group) selected. Any measurements on a device within a group are only shown when a device is selected (unless there are measurements with the group as the source). For example, if a temperature measurement is sent in Celsius, the fragment is T and the series is C(Celsius). This means, that this parameter can be set as T.C or T=>C.

string
Ignore Timestamp If selected, the timestamp of the incoming measurement is ignored. Note: When running in simulation mode, because historical input data is used, timestamps are not ignored. boolean Default: False

Output Port Details

Name Description Type
Value The numeric value from the measurement object. float

Operation Input

apama.analyticskit.blocks.cumulocity.OperationInput

Receives Operation objects from a device, asset, devices in a group, or all input sources.

The block does not reorder the received Operation objects and processes the operations as they are received. The block can be optionally configured to only process operations having a specified status or property.

The output from the block contains all properties on the Operation object. Property values can be accessed using the Extract Property block.

Properties with values of type string, boolean or float can be accessed by specifying the name of the property in the Extract Property block. For example, if the name of the property is ap_State, then specify ap_State as the value for the Property Path parameter of the Extract Property block.

If a property value is of type JSON object or sequence, then nested values can be accessed by specifying the full path to the nested values as the name of the property.

For example, if the name of the property is c8y_SpeedMeasurement and the value is { "Speed": { "value": 1234, "unit": "km/h" } } (in JSON form), then specify c8y_SpeedMeasurement.Speed.unit as the value for the Property Path parameter of the Extract Property block to extract the value of the unit.

The parameter that defines the input stream of the block is Input Source.

Note: A history of changes is not maintained for Operation objects, and it is thus not possible to retrieve the original objects from the inventory. For this reason, a model which contains this input block type may behave differently in simulation mode than it would in production mode.

Parameters

Name Description Type Notes
Input Source Defines the source from which the operation has been received.

This can be a single device, an asset, an object that references or contains a group of devices, or all input sources.

any
Operation Name The name of the operation the block is listening for.

If specified, the Operation object must have a property of this name. Otherwise, it is ignored.

string Optional
Operation Status The status for which to listen.

If not specified, the block listens for operations with any status.

Option - one of:

  • SUCCESSFUL
  • FAILED
  • EXECUTING
  • PENDING
Optional
Notification Mode Filters Operation events such that only new operations, updated operations, or all operations are processed. The default is that all operations are processed.

Option - one of:

  • All
  • Updates only
  • New operations only
Default: All

Output Port Details

Name Description Type
Operations Generates a pulse output for each Operation object received.

All properties of the Operation object are available as extra properties. You can use the Extract Property block to access their values.

pulse

Position Input

apama.analyticsbuilder.blocks.PositionInput

Receives Event objects from a device, asset, devices in a group, or all input sources and extracts the c8y_Position fragment into a Value object.

If no c8y_Position fragment is present, the event is ignored. If the fragment does not contain at least a valid latitude and valid longitude, the event is ignored. If the Primary Value parameter is set to Altitude and the fragment does not contain an altitude, the event is ignored. Latitudes must be between -90 and 90 degrees inclusive. Longitudes must be between -180 and 180 degrees inclusive.

The primary value of the output Value object can be set to be the latitude, longitude or altitude. All members of the c8y_Position fragment are added to the properties dictionary of the Value object.

If the Ignore Timestamp parameter is set, the block ignores the timestamp of the event and processes the measurements as they are received. Otherwise, it reorders the events and drops old measurements.

The parameter that defines the input stream of the block is Input Source, and Event Type if set.

Note: When running in simulation mode, because historical input data is used, timestamps are not ignored.

Note: A history of changes is not maintained for Event objects, and it is thus not possible to retrieve the original objects from the inventory. For this reason, a model which contains this input block type may behave differently in simulation mode than it would in production mode.

Parameters

Name Description Type Notes
Input Source Defines the source from which the position is received.

This can be a single device, an asset, an object that references or contains a group of devices, or all input sources.

any
Event Type The event type for which the block listens. If left unset, then there is no filtering by type.

To consume events from another model, this property must be set.

string Optional
Notification Mode Filters Event events such that only new events, updated events, or all events are processed.

The default is that all events are processed.

Option - one of:

  • All
  • Updates only
  • New events only
Default: New events only
Ignore Timestamp If selected, the timestamp of the incoming measurement is ignored. Note: When running in simulation mode, because historical input data is used, timestamps are not ignored. boolean Default: False
Primary Value The primary value to be output by the block: latitude, longitude or altitude, or empty if not set.

Option - one of:

  • Latitude
  • Longitude
  • Altitude
Optional

Output Port Details

Name Description Type
Position An object containing at least latitude and longitude. any

Output

This category contains the following blocks:

Block Name Description
Alarm Output Creates a new Alarm object for a specified device, asset or for the trigger device with a pre-configured alarm name and parameters.
Event Output Creates a new Event object for a specified device, asset or for the trigger device.
Managed Object Output Updates a ManagedObject object for a specified device, asset or for the trigger device.
Measurement Output Creates a new Measurement object for a specified device, asset or for the trigger device.
Operation Output Creates a new Operation object for a specified device, asset or for the trigger device.
Send Email Sends an email to the specified email addresses.
Send SMS Sends an SMS (Short Message Service) to the specified phone number.

Alarm Output

apama.analyticskit.blocks.cumulocity.CreateAlarm

Creates a new Alarm object for a specified device, asset or for the trigger device with a pre-configured alarm name and parameters.

This block produces synchronous output. The parameters that define the output stream are "Output Destination" and "Alarm Type".

If "Create Alarm" is provided repeatedly, then the count of the alarm is increased (unless it has been cleared). If the severity or message has changed, then the count is not increased - the existing alarm is modified instead. If the alarm has been acknowledged, the status of the alarm is only made active on an increase in severity. Use the Always Activate Alarm parameter to make every modification of an existing alarm reactivate the alarm.

The default behavior of the Alarm Output block is to produce a synchronous output and the Analytics Builder framework explicitly disallows models that can cause a loop when synchronous outputs are produced. However, such validations are disabled when asynchronous outputs are produced. Therefore, special care must be taken when using the Create Asynchronous Output parameter. This may result in infinite loops during model execution (for the same model or across multiple models), leading to performance degradation or the application running out of memory. For example, a loop can occur if the model consumes an alarm input of a given type and produces an alarm output of the same type for the same device; the output generated by the model is then consumed by the same model as an input, resulting in a loop.

Parameters

Name Description Type Notes
Output Destination The device (or for models handling group of devices, trigger device or asset) that the alarm is associated with. Assets can be used only for sending cross-device aggregates.

The model editor uses the device name. This is mapped internally to the device identifier.

any
Alarm Type Identifies the type of this alarm, for example "com_cumulocity_events_TamperEvent". string
Message The text that is displayed if the alarm is triggered. The message is set either by parameter or input. If both are not set, the model name is used. You cannot set both. string Optional
Severity The severity of the alarm. The severity is set either by this parameter or the input port. You must set only one of them.

Option - one of:

  • Critical
  • Major
  • Minor
  • Warning
Optional
Params Fragment If this parameter is set, then the incoming properties on the Properties input port are added to this fragment in the generated Alarm. If this is not set, the properties are copied to the top level of the Alarm params. string Optional
Create Asynchronous Output Allow Create Alarm or Clear Alarm to be done asynchronously.

Asynchronous output events are events that do not have source timestamps and can only be consumed by another model in a time-asynchronous manner when they are received back from the platform.

Caution: The default behavior of the Alarm Output block is to produce a synchronous output and the Analytics Builder framework explicitly disallows models that can cause a loop when synchronous outputs are produced. However, such validations are disabled when asynchronous outputs are being produced. Therefore, special care must be taken when using the Create Asynchronous Output parameter. This may result in infinite loops during model execution (for the same model or across multiple models), leading to performance degradation or the application running out of memory. For example, a loop can occur if the model consumes an alarm input of type foo and produces an alarm output of type foo for the same device; the output generated by the model is then again consumed by the same model as an input, resulting in a loop.

boolean Optional
Always Activate Alarm If selected, all alarms produced by the block are set to ACTIVE. By default (unselected), if an alarm has been acknowledged, the alarm is only reactivated if the severity has increased. boolean Optional

Input Port Details

Name Description Type
Create Alarm Creates an alarm when a signal is received and a severity value is set. pulse
Clear Alarm Updates the status of an existing alarm to CLEARED when a signal is received. pulse
Severity The severity of the alarm - should be one of the severity values (WARNING, MINOR, MAJOR, CRITICAL) or CLEARED. string
Message The message for the alarm. string
Time Sets the timestamp of the alarm. If not connected, the current model time is used. float
Properties The properties to set on the alarm. any

Event Output

apama.analyticskit.blocks.cumulocity.CreateEvent

Creates a new Event object for a specified device, asset or for the trigger device.

The text of the event is determined by the Text Input input port or by the Message parameter. You must not set both. If neither are set, the model name is used as the text.

This block produces synchronous output. The parameters that define the output stream of the block are "Output Destination" and "Event Type".

Parameters

Name Description Type Notes
Output Destination The device (or for models handling group of devices, trigger device or asset) to which the event is to be sent. Assets can be used only for sending cross-device aggregates.

The model editor uses the current device name. This is mapped internally to the device identifier.

any
Event Type Identifies the type of this event. string
Message The text that is displayed when the event is created.

This requires that the Text Input input is not connected. If neither are set, the model name is used as the text.

string Optional
Params Fragment If this parameter is set, then the incoming properties on the Properties input port are added to this fragment in the generated Event. If this is not set, the properties are copied to the top level of the Event params. string Optional

Input Port Details

Name Description Type
Create Event Creates an event when a signal is received. pulse
Text Input Sets the text of the event. The Message parameter must not be set if this is used. string
Time Sets the timestamp of the event. If not connected, the current model time is used. float
Properties The properties to set on the event. any

Managed Object Output

apama.analyticskit.blocks.cumulocity.ManagedObjectOutput

Updates a ManagedObject object for a specified device, asset or for the trigger device.

If the Property Name parameter is set, then the Value input port (or its properties if it has an empty value) is used to set that property on the managed object.

If the Property Name parameter is not set, then all properties from the Value input port are used to update the managed object.

Note: The following reference properties on a managed object cannot be updated using this block: childDeviceIds, childAssetIds, deviceParentIds and assetParentIds.

This block does not participate in time-synchronous model-to-model communication. Multiple blocks can be used in a single model or multiple models to update the same property of the same device. Cycles among models can be formed because of this block, so care must be taken not to introduce indefinite cyclic execution of models.

This block produces asynchronous output. The parameter that defines the output stream of the block is "Output Destination".

Parameters

Name Description Type Notes
Output Destination The device (or for models handling group of devices, trigger device or asset) that the managed object is associated with. Assets can be used only for sending cross-device aggregates.

The model editor uses the current device name. This is mapped internally to the device identifier.

any
Property Name The name of the property to update.

If not set, then the properties from the Value input port are mapped to the top level properties of the managed object.

string Optional

Input Port Details

Name Description Type
Value The value of the property to set. any
Update Property Signals that the property is to be updated. If not connected, every new value from the Value input port updates the property. pulse

Measurement Output

apama.analyticskit.blocks.cumulocity.CreateMeasurement

Creates a new Measurement object for a specified device, asset or for the trigger device.

This block sends a new measurement for the Value input port. If the Send input port is connected, this block only sends an output on receiving a send signal. The measurement is sent to the current device or the device specified.

This block produces synchronous output. The parameters that define the output stream of the block are "Output Destination", "Fragment Name" and "Series Name".

Non-finite values are ignored.

Parameters

Name Description Type Notes
Output Destination The device (or for models handling group of devices, trigger device or asset) to which the measurement is to be sent. Assets can be used only for sending cross-device aggregates.

The model editor uses the current device name. This is mapped internally to the device identifier.

any
Fragment Name The name of the fragment in the measurement. string
Series Name The name of the series in the measurement. string
Unit The name of the unit of measurement (for example, "mm" or "lux"). string Optional
Params Fragment If this parameter is set, then the incoming properties on the Properties input port are added to this fragment in the generated Measurement. If this is not set, the properties are copied to the top level of the Measurement params. string Optional

Input Port Details

Name Description Type
Value The measurement to be sent. float
Send Signals that a new measurement is to be created. If not connected, every new Value input creates a measurement. pulse
Time Sets the timestamp of the measurement. If not connected, the current model time is used. float
Properties The properties to set on the measurement. any

Operation Output

apama.analyticskit.blocks.cumulocity.CreateOperationStaticValue

Creates a new Operation object for a specified device, asset or for the trigger device.

If none of the Operation Name, Parameter Name or Parameter Value parameters are set, then the operation uses the Properties input port to populate the Operation object.

The block does not participate in time-synchronous model-to-model communication. Multiple blocks can be used in a single model or multiple models to create new operations for the same device. Cycles among models can be formed because of this block, so care must be taken not to introduce indefinite cyclic execution of models.

The block produces asynchronous output. The parameter that defines the output stream of the block is "Output Destination".

Parameters

Name Description Type Notes
Output Destination The device (or for models handling group of devices, trigger device or asset) to which the operation is to be sent. Assets can be used only for sending cross-device aggregates.

The model editor uses the device name. This is mapped internally to the device identifier.

any
Operation Name The name of the property to create on the Operation object. string Optional
Parameter Name The name of the parameter for the operation. string Optional
Parameter Value The value of the parameter for the operation. string Optional
Description The description of the operation to create. string Optional

Input Port Details

Name Description Type
Create Operation Creates an operation when a signal is received. pulse
Properties The properties to set on the operation. any

Send Email

apama.analyticskit.blocks.cumulocity.Send_Email

Sends an email to the specified email addresses.

The subject and text must each be provided using either a parameter or via an input port, not both.

Note: When running in simulation or test mode, the block logs the output instead of sending an email.

Parameters

Name Description Type Notes
Subject The subject of the email. string Optional
Text The text of the email, which is processed as HTML. For example, if you want to insert a new line, use the <br> tag. string Optional
Reply to The reply-to address for the email. string Optional
To The recipients of the email. One or more email addresses separated by commas. string Optional
CC (Carbon copy) The recipients that are to receive a copy of the email. One or more email addresses separated by commas. string Optional
BCC (Blind carbon copy) The recipients that are to receive a blind copy of the email. One or more email addresses separated by commas. Recipients listed in To and CC are not able to see the BCC list. string Optional

Input Port Details

Name Description Type
Send Sends an email when a signal is received. pulse
Subject Subject of the email. string
Text Text of the email. string

Send SMS

apama.analyticskit.blocks.cumulocity.Send_SMS

Sends an SMS (Short Message Service) to the specified phone number.

If the Send SMS input port is connected, this block sends an output to the specified phone number when receiving a signal.

Note: When running in simulation or test mode, the block logs the output instead of sending an SMS.

Parameters

Name Description Type Notes
Phone Number The phone number to which the SMS is to be sent. string
Text The content of the SMS. The maximum length is 160 characters. Do not specify this parameter if using the SMS Text input port. string Optional

Input Port Details

Name Description Type
Send SMS Triggers sending an SMS. pulse
SMS Text Content of the SMS. If not connected, specify the content in the Text parameter. string

Logic

This category contains the following blocks:

Block Name Description
AND Performs a logical 'and' on the inputs.
NOT Performs a logical 'not' on the input.
OR Performs a logical 'or' on the inputs.

AND

apama.analyticskit.blocks.core.And

Performs a logical 'and' on the inputs.

If all the connected inputs are true, then the output is true, else false. If any of the inputs is of type pulse, then the output is a pulse. Any combination of pulse and boolean inputs is valid. The block functions even if some inputs are not connected.

Input Port Details

Name Description Type
Value 1 First input value to the block. boolean
Value 2 Second input value to the block. boolean
Value 3 Third input value to the block. boolean
Value 4 Fourth input value to the block. boolean
Value 5 Fifth input value to the block. boolean

Output Port Details

Name Description Type
AND The logical 'and' of the inputs. pulseOrBoolean(value1, value2, value3, value4, value5)

NOT

apama.analyticskit.blocks.core.Not

Performs a logical 'not' on the input.

If the connected input is true, the output is false. If the connected input is false, the output is true.

Input Port Details

Name Description Type
Value Input value to the block. boolean

Output Port Details

Name Description Type
NOT The logical 'not' of the input. boolean

OR

apama.analyticskit.blocks.core.Or

Performs a logical 'or' on the inputs.

If any of the connected inputs is true, the output is true, else false. If all the inputs are of type pulse, the output is a pulse. Inputs must be of the same type. The block functions even if some inputs are not connected.

Input Port Details

Name Description Type
Value 1 First input value to the block. boolean
Value 2 Second input value to the block. boolean
Value 3 Third input value to the block. boolean
Value 4 Fourth input value to the block. boolean
Value 5 Fifth input value to the block. boolean

Output Port Details

Name Description Type
OR The logical 'or' of the inputs. sameAsAll(value1, value2, value3, value4, value5)

Calculation

This category contains the following blocks:

Block Name Description
Crossing Counter Detects and counts the number of threshold crossings in the specified direction.
Delta Calculates the difference between successive input values.
Difference Calculates the absolute and signed differences between the connected inputs.
Direction Detection Detects whether the input value changes direction.
Expression Evaluates an expression to perform arithmetic or logical calculations or string operations.
From Base N Converts a base N string to a float.
KPI Compares a value against either a KPI (Key Performance Indicator) or the data point of a device, asset or group of devices.
Limit Outputs a value that is kept within the defined upper and lower limits.
Range Compares the input value against the defined lower and upper range values to detect whether the input is within or out of the range, or whether it crosses the range.
Range Lookup Finds the range in which the input value lies.
Rounding Rounds the input to a specified number of decimal points or to an integer, using a selectable rule.
Threshold Compares the input value against the defined threshold value to detect whether the input breaches the threshold or whether it crosses the threshold.
To Base N Converts a float to a base N string.

Crossing Counter

apama.analyticskit.blocks.core.CrossingCounter

Detects and counts the number of threshold crossings in the specified direction.

Crossing is defined as a change in the input value from one side of the threshold to the other side of the threshold (that is, from less than to greater than or vice versa).

The block can operate over a time-bounded window that is specified with the Window Duration parameter. If this parameter is not specified, it uses an unbounded window. The Reset input clears the window contents.

If a window is configured, the block uses a set of 20 buckets, so the time of expired values is an approximation to the nearest bucket interval.

Parameters

Name Description Type Notes
Threshold Value This value is compared against the input value. float Default: 0.5
Direction The direction in which to check for a threshold crossing: whether to detect a crossing in the upwards direction, in the downwards direction, or in both directions.

Option - one of:

  • Upwards
  • Downwards
  • Both
Window Duration (secs) If present, the amount of time (in seconds) for which values are to be kept in the window.

This must be a finite and positive number.

float Optional

Input Port Details

Name Description Type
Value The input value for which to detect a crossing. float
Reset Resets the count of crossings. pulse
Sample Forces re-evaluation of the current value and sends the output. boolean

Output Port Details

Name Description Type
Crossing Count The number of crossings. float
Crossing Sends a pulse when a crossing is detected. pulse

Delta

apama.analyticskit.blocks.core.Delta

Calculates the difference between successive input values.

The block generates an output after getting at least two input values.

Input Port Details

Name Description Type
Value Value to calculate the delta. float
Reset Resets the state of the block. pulse

Output Port Details

Name Description Type
Delta Value The delta value. float

Difference

apama.analyticskit.blocks.core.Difference

Calculates the absolute and signed differences between the connected inputs.

Only generates an output if both inputs receive a value.

Input Port Details

Name Description Type
Value 1 First input to the block. float
Value 2 Second input to the block. float

Output Port Details

Name Description Type
Absolute Difference The absolute difference of the inputs. float
Signed Difference The signed difference of the inputs. Positive if the Value 1 input is larger than the Value 2 input. float

Direction Detection

apama.analyticskit.blocks.core.DirectionDetector

Detects whether the input value changes direction.

Outputs the change in direction and the last significant inflection point, ignoring minor variations if the changes are less than the defined hysteresis value. Repeated inputs of the same value are ignored.

Parameters

Name Description Type Notes
Hysteresis Only counts a change in direction if the input value changes by the defined hysteresis value since the point of changing direction.

Must either be zero (meaning all changes of direction are counted) or a a positive number.

float Default: 0.0

Input Port Details

Name Description Type
Value Numeric value for which to detect the change in direction. float
Reset Resets the state of the block. pulse

Output Port Details

Name Description Type
Upward Direction Is true if the input value changes towards the upward direction, else false. boolean
Inflection Point The last inflection point detected by the block. float

Expression

apama.analyticskit.blocks.core.Expression

Evaluates an expression to perform arithmetic or logical calculations or string operations.

On change of input values (once all in-use inputs have been received), the expression specified in the parameter is re-calculated.

The expression language is much like EPL (see EPL reference), but is restricted to float, integer, string and boolean types.

Note: All numeric literals are treated as float type values, even if they have no fractional part. Integer values can only be obtained as the result of functions such as floor(). Similar to EPL, integer and float are not implicitly convertible within an expression. If the result of an expression is an integer value, it is converted to a float automatically (there might be a loss of precision).

Boolean values can be specified using the Boolean literals true and false. Boolean literals are case insensitive, so for example, TRUE and True are allowed. String values can be specified by enclosing string literals in double quotes, for example "my value". Special characters are encoded with a backslash (\). The following special characters (along which their encoding) are supported in string literals:
  • Double quotes - \"
  • Backslash - \\
  • Newline - \n
  • Tab - \t

Similar to EPL, each value type can be concatenated with a string type. The non-string value is first converted to a string and then appended to the string value.

The values of the inputs are available as input1, input2, input3, input4 and input5. The input values can be of type float, string, boolean and any. Logical, relational, numerical and equality operators can be used on the values of the supported types. Logical operators are case insensitive, so for example, AND and And are allowed. Built-in methods on the float, integer, string and boolean types can be called, including x.abs() (absolute value of x), x.pow(y) (raise x to the power y), x.sin() (sine of x in radians), x.round() (rounds x to the nearest integer), and s.ltrim() (remove whitespace from the start of the string s). Built-in static methods of the supported types can be called by specifying the type name, followed by a dot (.) and the method name, for example, float.max(input1, input2) (find the larger of two input values). Built-in constants on the supported types can be accessed by specifying the type name, followed by a dot (.) and the constant name, for example, float.E (Euler's constant). Values of type any are unpacked at runtime to evaluate the expression. After unpacking, the value must be of type float, string or boolean. The type checker tries to validate the expressions during the validation phase, but this is not always possible with the any type. So if an expression contains the any type, even if it passes the validation phase, it can still fail at runtime due to a wrong type of variable being passed or an unsupported operation being performed. For a full list of built-in methods and constants, consult the API Reference for EPL (ApamaDoc).

Some examples:
  • Convert Fahrenheit to Celsius: (input1 - 32) * 5/9
  • Convert days to seconds: input1 * 86400
  • Average of 4 inputs: (input1 + input2 + input3 + input4) / 4
  • Threshold comparison: input1 > 3.1412 (but also see the Threshold block)
  • Pythagoras to compute the hypotenuse of a right-angled triangle: (input1.pow(2) + input2.pow(2)).sqrt()
  • Comparison to 3 decimal places: (input1 * 1000 - (input1 * 1000).fractionalPart()) = (input2 * 1000 - (input2 * 1000).fractionalPart())
  • Range check: input1 >= 1 and input1 <= 10
  • String comparison: input1 = "my value"
  • Larger value: float.max(input1, float.PI)
  • Remainder of integer division: input1.round() % input2.round()
  • Left shift of integer value: input1.round() << 4.round()
  • Right shift of integer value: input1.round() >> 2.round()
  • Bitwise not of integer value: not input1.round()
  • Bitwise or of integer values: input1.round() or input2.round()
  • Bitwise and of integer values: input1.round() and input2.round()
  • Bitwise xor of integer values: input1.round() xor input2.round()
  • String and non-string concatenation: "Current temperature is " + input1 + " degrees Celsius"

Parameters

Name Description Type Notes
Expression An expression - a string representation of an EPL expression.

Similar to EPL expressions, but with the differences as described above.

string

Input Port Details

Name Description Type
input1 First input, to be used as input1 in the expression. any
input2 Second input, to be used as input2 in the expression. any
input3 Third input, to be used as input3 in the expression. any
input4 Fourth input, to be used as input4 in the expression. any
input5 Fifth input, to be used as input5 in the expression. any

Output Port Details

Name Description Type
Result Result of the expression. any

From Base N

apama.analyticsbuilder.blocks.FromBaseN

Converts a base N string to a float.

The input string can be in any integer base from 2 to 36, where letters of the English alphabet are used as digits for bases above 10. Common bases are 2 (binary), 8 (octal), 10 (decimal) and 16 (hexadecimal). The number being converted can contain a radix point.

Conversion between two arbitrary bases can be achieved by chaining this block with the To Base N block.

Parameters

Name Description Type Notes
Input Base The number base of the input stream, in the range 2 to 36. integer Default: 16
Radix Character The character to use as the radix point. Expected to be a dot or a comma.

Option - one of:

  • Dot
  • Comma
Default: Dot

Input Port Details

Name Description Type
Base N String input in base N. string

Output Port Details

Name Description Type
Float Numeric output. float

KPI

apama.analyticskit.blocks.cumulocity.KPI

Compares a value against either a KPI (Key Performance Indicator) or the data point of a device, asset or group of devices.

This block uses data from the KPI input port or from the device, asset or group of devices which contains data points. It extracts the units, label, and the red and yellow ranges. The output indicates whether the value is within the red or yellow range specified by the KPI or data point.

The KPI input can provide properties, typically from a KPI-managed object, which include the red and yellow ranges, the unit and the label. If the device contains a data point for the specified fragment and series, then the values from the data point override those from the KPI.

Parameters

Name Description Type Notes
Input Source The device, group, or asset which contains a data point. If specified, then this source (typically the same as the measurement source) is checked to see if it contains a data point for the specified fragment and series. If it contains a data point, the red and yellow range values from the source object are used in place of the KPI values.

For the KPI block, this parameter must not be set to "All Inputs".

any Optional
Data Point Fragment and Series This parameter must be specified if the Input Source parameter is specified. It specifies a data point from the source object. This is typically the same as the fragment and series of the measurement source.

The data point fragment and series must be specified as fragment.series.

string Optional
Upper end of yellow range exclusive If set, the upper end of the yellow range is treated as being exclusive. boolean Default: False
Upper end of red range exclusive If set, the upper end of the red range is treated as being exclusive. boolean Default: False

Input Port Details

Name Description Type
Value Numeric value to compare with the defined ranges. float
KPI Object containing the c8y_Kpi property. pulse

Output Port Details

Name Description Type
Red Is set to true when the value is in the red range (if a red range is defined). boolean
Yellow Is set to true when the value is in the yellow range (if a yellow range is defined). boolean
Unit The unit name from the data point. string
Label The label name from the data point. string

Limit

apama.analyticsbuilder.blocks.Limit

Outputs a value that is kept within the defined upper and lower limits.

The input value is limited so that the output does not exceed the boundaries defined by the Lower Limit and Upper Limit parameters. If the input violates either limit, then the output is set to the parameter value, otherwise the value is passed through unchanged.

It is only mandatory to provide one of the limits. If this is the case, then the input is only limited in the direction of the specified parameter.

Parameters

Name Description Type Notes
Upper Limit Any input above this value results in the output being capped at this value. float Optional
Lower Limit Any input below this value results in the output being capped at this value. float Optional

Input Port Details

Name Description Type
Value The input value. float

Output Port Details

Name Description Type
Output The input value, if it is within the limits defined by the Lower Limit and Upper Limit parameters. If the input value exceeds one of the limit parameters, it is set to the value of that parameter. float

Range

apama.analyticsbuilder.blocks.Range

Compares the input value against the defined lower and upper range values to detect whether the input is within or out of the range, or whether it crosses the range.

By default, the range includes the value for the lower range but excludes the value for the upper range. For example, if the lower range is 100 and the upper range is 200, then all values from 100 to 199 are within the range. 200 is considered to be out of the range.

A pulse is sent when the defined range is crossed. That is, when either the lower or upper range is crossed, or if the value goes from below the range to over the range (or vice versa) without ever being within the range.

Parameters

Name Description Type Notes
Lower Range The lower range value. float Optional
Include Lower Range If selected, an input value equal to the lower range is considered to identify whether it is within or out of the range. If not selected, an input value equal to the lower range is not considered. boolean Default: True
Upper Range The upper range value. float Optional
Exclude Upper Range If selected, an input value equal to the upper range is not considered to identify whether it is within or out of the range. If not selected, such an input value is considered to identify whether it is within or out of the range. boolean Default: True

Input Port Details

Name Description Type
Value The input value to validate against the defined range. float
Reset Resets the state of the block. pulse

Output Port Details

Name Description Type
Out of Range Is set to true when the input value is not within the defined range. boolean
In Range Is set to true when the input value is within the defined range. boolean
Crossed Sends a pulse when the range is crossed. pulse

Range Lookup

apama.analyticskit.blocks.core.RangeLookup

Finds the range in which the input value lies.

Ranges are defined using a list of unique upper bound values in increasing order. The lower bound of the first range depends on the value of the Minimum Value parameter. The lower bound of each subsequent range is defined by the upper bound of the previous range. The range to which an input value equal to a boundary value belongs depends on the Exclude Upper parameter. The block outputs the mapped value for the range the input lies within, or a failed flag if the input value is not within any of the ranges.

Parameters

Name Description Type Notes
Minimum Value The lower bound of the first range (first row). If nothing is specified, negative infinity is taken as the minimum value. float Optional
Ranges A boundary and mapped value pair for the upper bound of a range for which to look up the input value and a mapped value that is to be used as the output value if the input value lies within the range. List of Upper Bound value and Mapped Value
Exclude Upper If selected, an input value equal to the upper bound of a row is considered to be part of the range of the next row. If not selected, such an input value is considered to be part of the range of the current row. boolean Default: True
Type The type that is to be used for the output value.

Option - one of:

  • Float
  • Boolean
  • String
Optional

Input Port Details

Name Description Type
Value The input value for which the range is to be found. float

Output Port Details

Name Description Type
Mapped The Mapped Value for the range that is matched. any
Failed Is true when the input does not lie in any range. Otherwise it is false. boolean

Rounding

apama.analyticskit.blocks.core.Rounding

Rounds the input to a specified number of decimal points or to an integer, using a selectable rule.

Rounding a numerical value means replacing it by another value that is approximately equal but has a shorter and simpler representation.

The rules available for use are:
  • Up (or take the ceiling, or round towards plus infinity) rounds the input up to the nearest target number.
  • Down (or take the floor, or round towards minus infinity) rounds the input down to the nearest target number.
  • Towards Zero (or truncate, or round away from infinity) rounds the input towards zero to the nearest target number.
  • Nearest (or round half up, or round half towards positive infinity) rounds to the nearest target number. Numbers that are equidistant from the two nearest target numbers are always rounded up. For example, value 23.5 gets rounded to 24, but -23.5 gets rounded to -23.
  • Even or Nearest rounds to the nearest target number. Numbers that are equidistant from the two nearest target numbers are always rounded to the nearest even target. For example, 0.5 rounds down to 0 and 1.5 rounds up to 2. Also known as Bankers Rounding.

The value is rounded to the nearest 'target number' - this is a whole number (if the number of decimal points is zero), or rounded to the number of decimal points specified. If the number of decimal points is negative, it is rounded to a power of 10. For example, if the number of decimal points is 2, it is rounded to the nearest 0.01 (that is, hundredths). If the number of decimal points is -3, it is rounded to the nearest 1000 (that is, thousands).

Parameters

Name Description Type Notes
Rule The rounding rule to be applied.

Option - one of:

  • Up
  • Down
  • Towards Zero
  • Nearest
  • Even or Nearest
Number of Decimal Points The number of decimal points the input is to be rounded to. integer Default: 0

Input Port Details

Name Description Type
Value The input value which is to be rounded. float

Output Port Details

Name Description Type
Rounded Value The input value rounded to a specified number of decimal points or to an integer. float

Threshold

apama.analyticskit.blocks.core.Threshold

Compares the input value against the defined threshold value to detect whether the input breaches the threshold or whether it crosses the threshold.

A breach occurs when the direction has been set to 'Above' and the input value is greater than the defined threshold value, or when the direction has been set to 'Below' and the input value is less than the defined threshold, or when the direction has been set to 'Above or Equal' and the input value is greater than or equal to the defined threshold value, or when the direction has been set to 'Below or Equal' and the input value is less than or equal to the defined threshold value.

A pulse is sent when the defined threshold value is crossed from any direction.

Parameters

Name Description Type Notes
Threshold Value This value is compared against the input value. float
Direction The direction in which to look: whether the input value is above, below or equal to the defined threshold, or whether it crosses the defined threshold.

Option - one of:

  • Above
  • Above or Equal
  • Below
  • Below or Equal
  • Crossing
Default: Above

Input Port Details

Name Description Type
Value The input value to compare against the defined threshold value. float
Reset Resets the state of the block. pulse

Output Port Details

Name Description Type
Breached Threshold Is set to true when the threshold is breached. boolean
Within Threshold Is set to true when the threshold is not breached. boolean
Crossed Threshold Sends a pulse when the threshold is crossed. pulse

To Base N

apama.analyticsbuilder.blocks.ToBaseN

Converts a float to a base N string.

The output string can be in any integer base from 2 to 36, where letters of the English alphabet are used as digits for bases above 10. Common bases are 2 (binary), 8 (octal), 10 (decimal) and 16 (hexadecimal). The number being converted can contain a radix point. The output is calculated to a maximum precision of 16 radix places.

Conversion between two arbitrary bases can be achieved by chaining this block with the From Base N block.

Parameters

Name Description Type Notes
Output Base The number base of the output stream, in the range 2 to 36. integer Default: 16
Radix Character The character to use as the radix point. Expected to be a dot or a comma.

Option - one of:

  • Dot
  • Comma
Default: Dot

Input Port Details

Name Description Type
Float Numeric input. float

Output Port Details

Name Description Type
Base N String output in base N. string

Aggregate

This category contains the following blocks:

Block Name Description
Average (Mean) Calculates the mean of the values over time.
Counter Gives a count of the total inputs and repeated inputs.
Discrete Statistics Generates statistics of sum, count, average (mean), standard deviation, minimum and maximum for discrete input values.
Gradient Calculates the weighted linear regression gradient for the values.
Group Statistics Generates periodic aggregate values across all the devices in a group for which the block has received input values.
Integral Calculates the integral of the input value over time.
Minimum / Maximum Calculates the minimum and maximum of a value over time.
Standard Deviation Calculates the standard deviation and variance of the values over time.

Average (Mean)

apama.analyticskit.blocks.core.Mean

Calculates the mean of the values over time.

This block is suitable for continuous values, even if they are irregularly sampled. The time between inputs or samples is significant, while the number of samples is not. Use this block, for example, if the input is a physical property, such as temperature, that is sampled either regularly or irregularly (for example, only generating measurement values on a change in temperature). Use the Discrete Statistics block instead of the Average (Mean) block for independent measurements, such as ticket sales, where the number of measurements is significant, but the time between measurements is not.

The mean is defined as the sum of the input's value multiplied by how long the input has stayed at that value, within an optional window, divided by the window duration or the time since the block was started or last reset, whichever is smallest.

The block can operate over a time-bounded window that is specified with the Window Duration parameter. If this parameter is not specified, the block uses an unbounded window. The Reset input port clears the window contents. Output is generated on any new input or, if the Output Threshold parameter is set, only when the output changes by more than the specified output threshold (which includes if no further input occurs, or the value only changes due to old entries expiring). The Sample input port can be used to force re-evaluation and generate the latest value.

See also the "Value types" topic in the Analytics Builder documentation for more details and an example of the frequency of output from this block and how values in windows behave.

If a window is configured, the block uses a set of 20 buckets, so the expired value is an approximation of the average value across a bucket.

Note: The Average (Mean) block generates the mean for an individual device. If the input comes from a range of devices, the mean is generated separately for each device in that group. To calculate and generate aggregate values for the group as a whole (not for individual devices), use the Group Statistics block.

Parameters

Name Description Type Notes
Window Duration (secs) If present, the amount of time (in seconds) for which values are to be kept in the window.

This must be a finite and positive number.

float Optional
Output Threshold If present, the output to be sent at the point when it changes by at least this value.

This must be a finite and positive number.

float Optional

Input Port Details

Name Description Type
Value Input for which the mean is to be calculated. float
Reset Clears the content of the window. pulse
Sample Forces re-evaluation of the current mean value and sends the output. pulse

Output Port Details

Name Description Type
Average The sum of the value multiplied by how long it stays at that value divided by the total time. float

Counter

apama.analyticskit.blocks.core.Counter

Gives a count of the total inputs and repeated inputs.

If two consecutive input values have different types, they are not evaluated as repeat values. For example, a float value of 1.0 will not evaluate as a repeat of an integer value of 1. All other evaluations for whether two values are equal follow the same rules as EPL. For more information, refer to Types.

You can specify a maximum value for each count independently. By default, each counter returns to one, counting the first input after the maximum has been reached. This is useful, for example, if you want to trigger an action on every nth input, or if the input has repeated more often than expected. You can also set each counter to stop once it reaches the maximum value. In this mode, a pulse on the Reset input port is required to reset the count, although this resets both counters at the same time. If this dual reset is an issue, you must use a separate Counter block to deal with each count independently.

Parameters

Name Description Type Notes
Maximum Count The maximum value the Count output port can take. A negative or zero value is interpreted as float.MAX (~2e308). This only affects the Count output port. If the counter is looping, this can be useful for triggering an action on every nth input. float Default: 0.0
Loop Count If selected, the Count output port resets to one when the maximum value is exceeded. If not selected, the counter stops counting when the maximum value is reached and must be reset manually. This only affects the Count output port. boolean Default: True
Maximum Number Same The maximum value the Number Same output port can take. A negative or zero value is interpreted as float.MAX (~2e308). This only affects the Number Same output port. This can be useful for assessing whether a value has remained static for an unexpectedly long time, such as positions within a GPS measurement. float Default: 0.0
Loop Number Same If selected, the Number Same output port resets to one when the maximum value is exceeded. If not selected, the counter stops counting when the maximum value is reached and must be reset manually. This only affects the Number Same output port. boolean Default: True

Input Port Details

Name Description Type
Value The input to be counted. any
Reset Resets both counters. boolean

Output Port Details

Name Description Type
Count The total count of all the inputs. float
Number Same The current count of repeated inputs with the same value.

On a change of value, this is reset to one.

float

Discrete Statistics

apama.analyticsbuilder.blocks.DiscreteStatistics

Generates statistics of sum, count, average (mean), standard deviation, minimum and maximum for discrete input values.

This block is suitable for discrete time inputs, where the number of samples (or inputs) is significant, while the time between them is not. The Average (Mean) and Standard Deviation blocks are more suitable for continuous values that may be irregularly sampled, such as temperature readings. Use this block, for example, if each sample represents a transaction such as a ticket being sold.

If the Sample input port is not connected, every value is sampled. If a new value is received during the same activation period as a reset, the value is sampled after the reset, otherwise it is ignored. As every value is used, the standard deviation uses the generic formula: σ² = ∑(x - µ)² / N.

If the Sample input port is connected, the block only samples the data when the Sample input port receives a signal. In this case, the sampling standard deviation uses the formula: σ² = ∑(x - µ)² / (N-1).

If reset and sample signals are received together, the reset is processed first.

Input Port Details

Name Description Type
Value The current value. float
Sample Use the current value in generating statistics. If left unconnected, all values are used. pulse
Reset Reset the state of the block. pulse

Output Port Details

Name Description Type
Sum Sum of the sampled input values, ∑x. float
Count Count of the number of sampled input values, N. float
Average Average (mean) of the sampled input values, µ = ∑x / N. float
Standard Deviation Standard deviation of the sampled input values. If all values are being sampled, with the Sample input port disconnected, the generic standard deviation, σ² = ∑(x - µ)² / N, is used. Otherwise the sampling standard deviation, σ² = ∑(x - µ)² / (N-1), is used. float
Minimum Minimum of the sampled input values. float
Maximum Maximum of the sampled input values. float

Gradient

apama.analyticskit.blocks.core.Gradient

Calculates the weighted linear regression gradient for the values.

A gradient measures the rate of change of a value over time. A positive gradient indicates an increase of the input values, and a negative gradient indicates a decrease of the input values. The magnitude of the gradient signifies the scale of change.

The block can operate over a time-bounded window that is specified with the Window Duration parameter. If this parameter is not specified, it uses an unbounded window and the block re-evaluates for every 1 second, and uses 1-second buckets. If a window is configured, the block uses a set of 20 buckets, so the time of expired values is an approximation to the nearest bucket interval. The first gradient output is generated only when a minimum of two buckets is available for computation.

The Reset input clears the content of the window. Sample input can be used to force re-evaluation and generate the latest value.

Parameters

Name Description Type Notes
Window Duration (secs) If present, the amount of time (in seconds) for which values are to be kept in the window.

This must be a finite and positive number.

float Optional

Input Port Details

Name Description Type
Value The input value for which the gradient is to be calculated. float
Reset Clears the content of the window. pulse
Sample Forces re-evaluation of the current value and sends the output. pulse

Output Port Details

Name Description Type
Gradient The gradient of the input values. float

Group Statistics

apama.analyticskit.blocks.core.GroupStatistics

Generates periodic aggregate values across all the devices in a group for which the block has received input values.

This block generates the following aggregate values:

  • Minimum
  • Maximum
  • Device Count
  • Average
  • Standard Deviation
  • Variance

The block can operate over a time-bounded window that is specified with the Window Duration parameter. If this parameter is not specified, the block uses an unbounded window. Output is generated periodically as specified by the Output Period parameter.

If a window is configured, the block uses a set of 20 buckets, so the expired value is an approximation to the nearest bucket interval.

Note: The Group Statistics block calculates and generates aggregate values for the group as a whole (not for individual devices). To generate aggregates for an individual device in a group, use the Average (Mean), Standard Deviation, or Minimum/Maximum blocks. The Group Statistics block only considers devices from which it has received input values.

Parameters

Name Description Type Notes
Window Duration (secs) If present, the amount of time (in seconds) for which values are to be kept in the window.

This must be a finite and positive number.

float Optional
Output Period (secs) The amount of time (in seconds) between each output.

This must be a finite and positive number.

float Default: 5.0

Input Port Details

Name Description Type
Value Input value for which the aggregate values are to be calculated. float

Output Port Details

Name Description Type
Minimum The smallest input value (closest to negative infinity) across all the devices in a group. float
Maximum The largest input value (closest to positive infinity) across all the devices in a group. float
Device Count The number of devices in a group for which input values have been received so far. float
Average The sum of the value multiplied by how long it stays at that value divided by the total time and the device count. float
Standard Deviation The standard deviation of the input values across all the devices in a group. float
Variance The variance of the input values across all the devices in a group. float

Integral

apama.analyticskit.blocks.core.Integral

Calculates the integral of the input value over time.

Integral is defined as the sum of the input's value multiplied by how long the input has stayed at that value, within an optional window, since the block was started or last reset.

The block can operate over a time-bounded window that is specified with the Window Duration parameter. If this parameter is not specified, it uses an unbounded window. The Reset input clears the window contents. Output is generated on any new input or, if the Output Threshold parameter is set, only when the output changes by more than the specified output threshold (which includes if no further input occurs, or the value only changes due to old entries expiring). The Sample input can be used to force re-evaluation and generate the latest value.

If a window is configured, the block uses a set of 20 buckets, so the expired value is an approximation of the average value across a bucket.

Parameters

Name Description Type Notes
Window Duration (secs) If present, the amount of time (in seconds) for which values are to be kept in the window.

This must be a finite and positive number.

float Optional
Output Threshold If present, the output to be sent at the point when it changes by at least this value.

This must be a finite and positive number.

float Optional

Input Port Details

Name Description Type
Value Input for which the integral is to be calculated. float
Reset Clears the content of the window. pulse
Sample Forces re-evaluation of the current integral value and sends the output. pulse

Output Port Details

Name Description Type
Integral Value The sum of the value multiplied by how long it stays at that value. float

Minimum / Maximum

apama.analyticskit.blocks.core.MinMax

Calculates the minimum and maximum of a value over time.

The minimum is defined as the smallest value (closest to negative infinity) of the input values in the window, and the maximum is defined as the largest value (closest to positive infinity) of the input values in the window.

The block can operate over a time-bounded window that is specified with the Window Duration parameter. If this parameter is not specified, the block uses an unbounded window. The Reset input clears the window contents. Output is generated on any new input that exceeds the current minimum or maximum, or, if the Window Duration parameter is set, when a previous minimum or maximum expires.

If a window is configured, the block uses a set of 20 buckets, so the time of expired values is an approximation to the nearest bucket interval.

Note: The Minimum/Maximum block generates the minimum and maximum for an individual device. If the input comes from a group of devices, these values are generated separately for each device in that group. To calculate and generate aggregate values for the group as a whole (not for individual devices), use the Group Statistics block.

Parameters

Name Description Type Notes
Window Duration (secs) If present, the amount of time (in seconds) for which values are to be kept in the window.

This must be a finite and positive number.

float Optional

Input Port Details

Name Description Type
Value Input for which the minimum and maximum is to be calculated. float
Reset Clears the content of the window. pulse

Output Port Details

Name Description Type
Minimum The smallest value in the window (closest to negative infinity). float
Maximum The largest value in the window (closest to positive infinity). float

Standard Deviation

apama.analyticskit.blocks.core.StandardDeviation

Calculates the standard deviation and variance of the values over time.

This block is suitable for continuous values, even if they are irregularly sampled. The time between inputs or samples is significant, while the number of samples is not. Use this block, for example, if the input is a physical property, such as temperature, that is sampled either regularly or irregularly (for example, only generating measurement values on a change in temperature). Use the Discrete Statistics block instead of the Standard Deviation block for independent measurements, such as ticket sales, where the number of measurements is significant, but the time between measurements is not.

Standard deviation is a measure that is used to quantify the amount of variation or dispersion of a set of data values. A low standard deviation indicates that the data points tend to be close to the mean of the set, while a high standard deviation indicates that the data points are spread out over a wider range of values.

The block can operate over a time-bounded window that is specified with the Window Duration parameter. If this parameter is not specified, the block uses an unbounded window. The Reset input port clears the window contents. The Sample input port can be used to force re-evaluation and generate the latest value. Output is generated on any new input or, if the Window Duration parameter is set, output is generated periodically on every new bucket that is added to the window.

If a window is configured, the block uses a set of 20 buckets, so the time of expired values is an approximation to the nearest bucket interval.

Note: The Standard Deviation block generates the standard deviation and variance for an individual device. If the input comes from a group of devices, these values are generated separately for each device in that group. To calculate and generate aggregate values for the group as a whole (not for individual devices), use the Group Statistics block.

Parameters

Name Description Type Notes
Window Duration (secs) If present, the amount of time (in seconds) for which values are to be kept in the window.

This must be a finite and positive number.

float Optional

Input Port Details

Name Description Type
Value Input for which the standard deviation and variance is to be calculated. float
Reset Clears the content of the window. pulse
Sample Forces re-evaluation of the current value and sends the output. pulse

Output Port Details

Name Description Type
Standard Deviation The standard deviation of the input values. float
Variance The variance of the input values. float

Flow Manipulation

This category contains the following blocks:

Block Name Description
Combiner Calculates the output based on the selected mode and the connected inputs.
Gate Blocks the input from going to output unless the gate is open and enabled.
Latch Values Latches the latest input value received while the block is enabled.
Pulse Converts a non-pulse input into a pulse output.
Selector Outputs a parameter value depending on which input port has a true value, lowest number taking precedence.
Switch Outputs the values from a given input, or acts as a circuit breaker.
Time Delay Delays the input by the specified amount of time.

Combiner

apama.analyticskit.blocks.core.Combiner

Calculates the output based on the selected mode and the connected inputs.

Available modes are:

  • Minimum: Outputs the minimum of the connected inputs which have received a value. All numeric literals are treated as float type.
  • Maximum: Outputs the maximum of the connected inputs which have received a value. All numeric literals are treated as float type.
  • Average (Mean): Outputs the average (mean) of the connected inputs for which a value has been received. All numeric literals are treated as float type.
  • Latest Changed: Outputs the latest changed value. If multiple values change in a single activation, then the input port with the highest number is used. For example, if Value 1 and Value 2 get an updated value, Value 2 is selected for output. Inputs must be of the same type. When using the Latest Changed mode, a value is not considered changed if the actual value does not change. For example, when using the Latest Changed mode with temperature sensors, it outputs the sensor value whose temperature was most recently changed.
  • Latest Input: Outputs the latest input value even if the actual value is unchanged. If multiple values update in a single activation, then the input port with the highest number is used. For example, if you have a number of sensors that measure the temperature periodically at different intervals and you want to get the latest temperature received by the block by all of those sensors, you can use the Combiner block with the Latest Input mode. This provides the latest published temperature, even if a sensor measures and publishes the same temperature.

Parameters

Name Description Type Notes
Mode The mode to be selected.

Option - one of:

  • Minimum
  • Maximum
  • Average (Mean)
  • Latest Changed
  • Latest Input

Input Port Details

Name Description Type
Value 1 First input value to the block. any
Value 2 Second input value to the block. any
Value 3 Third input value to the block. any
Value 4 Fourth input value to the block. any
Value 5 Fifth input value to the block. any

Output Port Details

Name Description Type
Combined Value The calculated combined value. sameAsAll(value1, value2, value3, value4, value5)

Gate

apama.analyticskit.blocks.core.Gate

Blocks the input from going to output unless the gate is open and enabled.

The block starts disabled if the Enable input is connected. Otherwise, the block is always enabled. The block starts closed if the Open input is connected. Otherwise, the block starts open.

Parameters

Name Description Type Notes
Null Value The value to use as output value when the gate is either disabled or closed.

The exact type of the value depends on the Null Value Type parameter. If the Null Value Type parameter is specified then the string value is parsed as the specified type. If the Null Value Type parameter is not specified, and the value is parsable into a float or a boolean value then it is parsed into the corresponding value type, otherwise it is used as a string value.

string Optional
Null Value Type The type of the value specified by the Null Value parameter. If specified, the null value is parsed into the specified type.

Option - one of:

  • Float
  • Boolean
  • String
Optional
Close Duration (secs) The amount of time (in seconds) the gate should be closed when a close signal is received.

If the parameter is not specified, then after a close signal is received, the gate remains closed until an open signal is received. If the parameter is specified, then the gate automatically opens after the specified number of seconds, unless another open or close signal is received before the time has elapsed. On opening, if the gate is also enabled, then the latest input value is sent out as output.

This must be a finite and positive number.

float Optional

Input Port Details

Name Description Type
Value The value to pass to output. any
Enable Enables the gate. If the gate is always to be enabled, then leave this port unconnected. boolean
Open Opens the gate. If the gate is to be open at the start, then leave this port unconnected. pulse
Close Closes the gate. If the Close Duration parameter is specified, then the gate is closed only for the specified number of seconds. pulse

Output Port Details

Name Description Type
Gated Value Same as the input value when the gate is open and enabled. Otherwise the value specified by the Null Value parameter. input(value)
Activated Output pulse. Generated when the gate becomes active. The gate is active when it is both open and enabled. pulse
Deactivated Output pulse. Generated when the gate becomes inactive. The gate is inactive when it is either closed or disabled. pulse

Latch Values

apama.analyticskit.blocks.core.Latch

Latches the latest input value received while the block is enabled.

Only generates an output if the input value changes and the block is enabled. The block starts disabled if the Enable input is connected. Otherwise, the block is always enabled.

Input Port Details

Name Description Type
Value The input value to be monitored. any
Enable Enables the block. If the block is always to be enabled, then leave this unconnected. boolean

Output Port Details

Name Description Type
Latched Value Same as the input value. Generated only if the input has changed while the block was enabled. input(value)
Changed Output pulse. Generated only if the input has changed while the block was enabled. pulse
Enabled Output pulse. Generated when the block is enabled but was previously disabled. pulse
Disabled Output pulse. Generated when the block is disabled but was previously enabled. pulse

Pulse

apama.analyticskit.blocks.core.Pulse

Converts a non-pulse input into a pulse output.

This is useful with blocks which consume both pulse and non-pulse values, and where the input value is treated as non-pulse without the explicit conversion.

For example, a numeric value passed to the OR block is treated as true if non-zero (as described in the "Type conversions" topic of the Analytics Builder documentation). However, when passing a numeric value to the Pulse block and then connecting the output of the Pulse block to the OR block, the numeric value is converted to a pulse so the OR block sends a pulse. The block can be configured to send a pulse if the value changes (default pulse conversion behavior), on every input, or on every non-zero value.

Parameters

Name Description Type Notes
Mode Controls when the block sends a pulse.

Option - one of:

  • On value change
  • On every input
  • On non-zero values
Default: On value change

Input Port Details

Name Description Type
Value The input to treat as pulse. any

Output Port Details

Name Description Type
Pulse The output pulse value converted from the input value. pulse

Selector

apama.analyticsbuilder.blocks.Selector

Outputs a parameter value depending on which input port has a true value, lowest number taking precedence.

You specify the output value that is to be sent using the parameters of this block. Only one of the parameter values is sent in the output. It is sent when the corresponding input port receives a true value. If more than one input port receives a true value, then the input port is used which has the lowest number in its name. For example, Input 1 has a higher priority than Input 2.

If all input values are false, then the value specified with the No Input parameter is sent.

Example: Input 1 has "high", Input 2 has "medium", Input 3 has "low", and the No Input parameter has the value "off". If none of the input ports receives a true value, then "off" is sent as the output value. If both the Input 2 and Input 3 ports receive a true value and Input 1 receives a false value, then "medium" is sent as the output value. This is because Input 2 has a higher priority than Input 3.

Parameters

Name Description Type Notes
Input 1 The output to be sent when the Input 1 port receives a true value. string
Input 2 The output to be sent when the Input 2 port receives a true value, but only if this is the port with the lowest number in its name. string Optional
Input 3 The output to be sent when the Input 3 port receives a true value, but only if this is the port with the lowest number in its name. string Optional
Input 4 The output to be sent when the Input 4 port receives a true value, but only if this is the port with the lowest number in its name. string Optional
Input 5 The output to be sent when the Input 5 port receives a true value, but only if this is the port with the lowest number in its name. string Optional
No Input The output to be sent when there is no input which has a true value. string
Type How to interpret the parameter values and set the output type.

If JSON is selected as the type, all input parameter values must be valid JSON values of the same type. This allows the Selector block to output properties which can be used, for example, with the Set Properties block to generate different sets of properties for the output blocks, depending on which input port of the Selector block is enabled.

If the Type parameter remains unselected, the type of the output value is set based on the types of all input parameter values. If all values are either true or false, the output is a boolean value. If all values are numbers, the output is a float value. In all other cases, the output is a string value.

Option - one of:

  • Float
  • Boolean
  • String
  • JSON
Optional

Input Port Details

Name Description Type
Input 1 Causes the Input 1 parameter value to be sent if true. boolean
Input 2 Causes the Input 2 parameter value to be sent if true (and no lower numbered input is true). boolean
Input 3 Causes the Input 3 parameter value to be sent if true (and no lower numbered input is true). boolean
Input 4 Causes the Input 4 parameter value to be sent if true (and no lower numbered input is true). boolean
Input 5 Causes the Input 5 parameter value to be sent if true (and no lower numbered input is true). boolean

Output Port Details

Name Description Type
Output The output value from one of the parameters. any

Switch

apama.analyticsbuilder.blocks.Switch

Outputs the values from a given input, or acts as a circuit breaker.

If the Selected Input parameter is specified, then the given input must exist and the corresponding input port must be connected.

If the Selected Input parameter is not specified, then the block acts as a circuit breaker.

You can use the initial default names for the inputs. However, you can also rename them to be more descriptive. The input names must be unique, so two inputs cannot share the same name. Connected inputs must all be of the same type.

The expected use case is that the Selected Input parameter is set to a template parameter which can then be set individually for each model instance to decide which input is used.

Parameters

Name Description Type Notes
Selected Input To specify an output, specify one of the five input names. To act as a circuit breaker, leave this parameter empty. string Optional
Name for input1 The name of the first input to the block. string Default: input1
Name for input2 The name of the second input to the block. string Default: input2
Name for input3 The name of the third input to the block. string Default: input3
Name for input4 The name of the fourth input to the block. string Default: input4
Name for input5 The name of the fifth input to the block. string Default: input5

Input Port Details

Name Description Type
input1 The first input. any
input2 The second input. any
input3 The third input. any
input4 The fourth input. any
input5 The fifth input. any

Output Port Details

Name Description Type
Switch The value from the specified input, or no value (circuit breaker) if the Selected Input parameter is empty. sameAsAll(input1, input2, input3, input4, input5)

Time Delay

apama.analyticskit.blocks.core.TimeDelay

Delays the input by the specified amount of time.

Parameters

Name Description Type Notes
Delay (secs) The amount of time (in seconds) by which the input is delayed.

This must be a finite and positive number.

float

Input Port Details

Name Description Type
Value The input value to be delayed. any

Output Port Details

Name Description Type
Delayed Value The delayed output value. input(value)

Utility

This category contains the following blocks:

Block Name Description
Constant Value Outputs a value, either when the Trigger input port receives a signal or at startup.
Cron Timer Sends a signal output based on cron-like periodic timer syntax.
Duration Measures the time elapsed from a set start time.
Extract Property Extracts the specified property from the input value and converts it to the specified type.
Geofence Compares the input value against the defined geofence value to detect whether the device is within the geofence, and whether the device entered or exited the geofence.
Missing Data Generates an output if the input has not occurred for a set amount of time.
Set Properties Outputs a pulse with properties set from values on the input ports.
Text Substitution Substitutes identifiers marked with a hash and braces (for example, #{name}) in the text template with corresponding entries from the input values.
Toggle Converts two pulse inputs to a boolean output based on the set and reset signals, with optional delays.

Constant Value

apama.analyticsbuilder.blocks.ConstantValue

Outputs a value, either when the Trigger input port receives a signal or at startup.

The Trigger input port can be used to delay the output until a trigger input is received. If the Trigger input port is not connected, then the block outputs a value when the model is activated, which may trigger further processing.

The Value parameter can be treated as a string, boolean, float or JSON value. If treated as a JSON string, number or boolean, then the output is of this type. If treated as a JSON object, the output is a pulse with the properties from the object. JSON arrays are only permitted within an object.

Parameters

Name Description Type Notes
Value The value to output. string
Type How to interpret the Value parameter and set the output type. If JSON is selected as the type, the Value parameter must be a valid JSON value.

If the Type parameter remains unselected, the type of the output value is set based on the type of the input parameter value. If the value is either true or false, the output is a boolean value. If the value is a number, the output is a float value. If the value is a valid JSON, the output is a pulse with the properties from the object. In all other cases, the output is a string value.

Option - one of:

  • Float
  • Boolean
  • String
  • JSON
Optional

Input Port Details

Name Description Type
Trigger If connected, send output on this trigger. boolean

Output Port Details

Name Description Type
Output The output value from the Value parameter. any

Cron Timer

apama.analyticskit.blocks.core.CronTimer

Sends a signal output based on cron-like periodic timer syntax.

The timer tick output is sent every time the time matches the pattern. The Time Zone parameter is a case-sensitive string that can be set to any supported time zone. The other parameters can be set to an asterisk (*) to match all times, a list of comma-separated numbers to fire at those specific times, or "* / number" to fire on every multiple of the number.

For example:

To send a signal every Wednesday at 20:30:
  • Day of Week: 4
  • Hour: 20
  • Minute: 30

To send a signal every 5 seconds:
  • Seconds: * / 5

To send a signal on Europe/Berlin time zone:
  • Time Zone: Europe/Berlin

The Days of Month and Days of Week parameters operate together such that if both are specified, then any match in either parameter triggers an output. For example, if Days of Month is set to 15 and Days of Week is set to 1, then there is an output on every Monday of the month and the 15th regardless of which day that is.

This block is not supported in simulation mode.

Parameters

Name Description Type Notes
Seconds The seconds at which to trigger the signal.

Range: 0 to 59.

string Default: 0
Minutes The minutes at which to trigger the signal.

Range: 0 to 59.

string Default: *
Hours The hours at which to trigger the signal.

Range: 0 to 23.

string Default: *
Days of Month The days of the month on which to trigger the signal.

Range: 1 to 31.

string Default: *
Months The months in which to trigger the signal.

Range: 1 to 12.

string Default: *
Days of Week The days of the week on which to trigger the signal.

Range: 0 (Sunday) to 6 (Saturday).

string Default: *
Time Zone The time zone to be used.

Example: Europe/Berlin. For a full list, see the Supported time zones.

The default value is empty which means that the platform's time zone is used.

string Default:

Output Port Details

Name Description Type
Timer Tick Sent at each trigger time based on the cron parameters. pulse

Duration

apama.analyticskit.blocks.core.Duration

Measures the time elapsed from a set start time.

The start time is set by a start signal which activates the block. If the block is already active, then a start signal is ignored and the existing measurement remains unaffected. The block is deactivated with a reset signal which also disables any periodic outputs.

The block generates a float output of the time elapsed since the start signal, measured in seconds. If the block is inactive at the time it receives a measure signal, then 0.0 is generated as the output.

If multiple signals are received at the same time, they are processed in the order of measure, reset and start. Thus, for example, if measure and reset signals are received together, the block first generates an output with the current duration and then resets its state. Processing the inputs in this order allows the current state of the block to be output and the block to be restarted within a single unit of time, if desired.

Parameters

Name Description Type Notes
Periodic Output (secs) The amount of time (in seconds) between automatically generated outputs by an active block. If not set, then an output is only generated when a measure signal is received.

This must be a finite and positive number.

float Optional

Input Port Details

Name Description Type
Measure Triggers an output of the duration (in seconds) since the block was activated. If the block is inactive, then 0.0 is output. pulse
Reset Deactivates and resets the state of the block. pulse
Start Activates the block. pulse

Output Port Details

Name Description Type
Duration The time in seconds since a start signal was received. float

Extract Property

apama.analyticskit.blocks.core.ExtractProperty

Extracts the specified property from the input value and converts it to the specified type.

The value in the Value input named by the Property Path parameter must be a string, number or boolean.

You can specify square brackets as part of the Property Path parameter to extract a specific element from a sequence.

You can also specify a period (.) as part of the Property Path parameter to extract nested values from a dictionary.

If you want to ignore the periods (.) and square brackets in the Property Path parameter and treat them as any other character, then you must select the Ignore Separators In Property Path checkbox.

For example:
  • If the input is { "users" : [ { "age" : 40.375 } ] } (in JSON form), then you can extract the value of age by specifying users[0].age as the Property Path parameter.
  • If the input is { "location" : { "city" : "Cambridge" } } (in JSON form), then you can extract the value of city by specifying location.city as the Property Path parameter.
  • If the input is { "location.city" : "Cambridge" } (in JSON form), then you can extract the value of location.city by specifying location.city as the Property Path parameter and selecting the Ignore Separators In Property Path checkbox.
  • If the input is { "a.b" : { "c.d" : "foo" } } (in JSON form) and you want to extract the value of c.d, then you must use two Extract Property blocks in a chain, both with the Ignore Separators In Property Path checkbox selected: the first block to extract the value of a.b and the second block to extract the value of c.d.

If the value is an object, then the properties of that object are output as properties on the Extracted Value output port.

In converting a string to a float, this block treats an empty string as a value of 0.0, rather than as not parseable.

Note: To extract a custom property from the Measurement Input block, you must add the prefix measurement_ to the name of the property in the Property Path parameter of the Extract Property block. For example, if the name of the custom property you want to extract is city, you must specify measurement_city as the Property Path parameter.

Parameters

Name Description Type Notes
Property Path The name or path of the property that is to be extracted from the input value. If not set, all of the properties are output. string Optional
Property Type The type to which the property value is to be converted. If set to Properties, a pulse is output with properties from the extracted value.

Option - one of:

  • String
  • Boolean
  • Float
  • Properties
Default: String
Clear On Missing If selected, the default value of the specified type is output if the Property Path parameter was not specified or if the value cannot be converted into the specified type. boolean Default: False
Ignore Separators In Property Path If selected, the value of the Property Path parameter is treated as a property name. For example, if Ignore Separators In Property Path is selected and the Property Path parameter is specified as location.city, then the property name location.city is extracted from the input value. boolean Default: False

Input Port Details

Name Description Type
Value The input value from which the property is to be extracted. any

Output Port Details

Name Description Type
Extracted Value The value that has been extracted from the input value. any

Geofence

apama.analyticsbuilder.blocks.Geofence

Compares the input value against the defined geofence value to detect whether the device is within the geofence, and whether the device entered or exited the geofence.

The boundary line itself is considered to be outside of the geofence area.

Parameters

Name Description Type Notes
Geofence A polygon describing an area on the Earth's surface.

Note that crossing the international date line, namely the longitude of +/- 180 degrees, is not supported.

sequence<apama.analyticsbuilder.LngLat>

Input Port Details

Name Description Type
Position The input value from which the properties for the longitude (lng) and latitude (lat) are to be extracted. any

Output Port Details

Name Description Type
Within Geofence Is set to true when the device is within the defined geofence. boolean
Entered Geofence Sends a signal when the device enters the defined geofence. pulse
Exited Geofence Sends a signal when the device leaves the defined geofence. pulse

Missing Data

apama.analyticskit.blocks.core.MissingData

Generates an output if the input has not occurred for a set amount of time.

The block can optionally detect an absence of changes in value if repeated same-value inputs are not counted.

Parameters

Name Description Type Notes
Ignore Repeated Inputs If selected, same-value inputs are ignored. boolean Default: False
Duration (secs) The amount of time (in seconds) the block waits for an input.

This must be a finite and positive number.

float

Input Port Details

Name Description Type
Value The data whose presence or absence is being detected. any
Reset Resets the state of the block - resets any timer and the previous value. pulse

Output Port Details

Name Description Type
Missing Data Absence of data, true if no input is received within the specified duration, else false. boolean

Set Properties

apama.analyticsbuilder.blocks.SetProperties

Outputs a pulse with properties set from values on the input ports.

The property names are taken from the parameters and the values from the input ports. New properties are only output if they have been received. An output is sent as soon as at least one of the inputs is provided.

Properties are set on the output in the following order of precedence:
  1. Any properties which have been explicitly specified by the use of a parameter. If an input is a pulse, it is treated as an object using the properties of that input. If an input has a primary value (not a pulse), then the primary value is used. To use the properties instead, use the Extract Property block with the Property Path parameter not set and the Property Type parameter set to Properties which replaces the primary value with a pulse (which is ignored) and the properties are used.
  2. The properties of any Value object on an input port which does not have the corresponding parameter set. This is a straight merge of the properties dictionary. If two dictionaries have the same property key, then the input port with the lowest identifier has precedence. Thus any shared properties on Input 1 overwrite properties from Input 2 and down.
  3. Any properties on a Value object provided to the Merge input port are kept if they are not overwritten by either of the operations above. The optional Merge input port allows chaining or supplementing a set of properties from another block.

Thus, any properties set on an input are overwritten by those with the same name on a higher precedence input, or when an input is configured for the specified property.

Parameters

Name Description Type Notes
Property 1 A property to set in the output, using the value from input port 1. string Optional
Property 2 A property to set in the output, using the value from input port 2. string Optional
Property 3 A property to set in the output, using the value from input port 3. string Optional
Property 4 A property to set in the output, using the value from input port 4. string Optional
Property 5 A property to set in the output, using the value from input port 5. string Optional

Input Port Details

Name Description Type
Input 1 Value to be added using the property name in parameter Property 1. any
Input 2 Value to be added using the property name in parameter Property 2. any
Input 3 Value to be added using the property name in parameter Property 3. any
Input 4 Value to be added using the property name in parameter Property 4. any
Input 5 Value to be added using the property name in parameter Property 5. any
Merge Source to merge with the specified properties. Properties from here not replaced by an input value are passed through to the output. any

Output Port Details

Name Description Type
Output The output value with extra properties supplied. pulse

Text Substitution

apama.analyticsbuilder.blocks.TextSubstitution

Substitutes identifiers marked with a hash and braces (for example, #{name}) in the text template with corresponding entries from the input values.

At least one of the Object or Source input ports must be connected. Identifiers that cannot be resolved are not substituted.

The identifiers prefixed with source. (for example, #{source.name}) are searched for in the value received on the Source input port. For example, if the value received on the Source input port is { "name": "sample_name" }, then the identifier #{source.name} is resolved to sample_name.

The identifiers not prefixed with source. are searched for in the value received on the Object input port.

Nested identifiers can be specified by separating them with a dot (.). For example, when the Object input port has received the value { "address": { "street": { "name": "example_street" }}}, then the identifier #{address.street.name} is resolved to example_street.

Keys with a dot (.) in them are not supported, so if the Object input port value is of the form { "address.street": { "name": "example_street" }}, then the example_street value cannot be resolved because the identifier #{address.street.name} expects street to be nested inside the address entry.

Primitive values such as integer, float, boolean and string are substituted directly, but complex values are converted to a JSON representation before substitution.

Any identifier with the text time (case-insensitive) in it and value type float is interpreted as a timestamp value and is converted into the format yyyy-MM-ddTHH:mm:ss.SSSZ before substitution. This can be modified with optional parameters using the following syntax: {time:param1="value1",param2="value2"}. Use the parameter TZ="time_zone" to specify a different time zone and/or use the parameter FORMAT="format_string" to specify a different format. For example, #{time:TZ="America/New_York",FORMAT="HH:mm:ssZ"} specifies the time zone for New York and the format to be HH:mm:ssZ. The model fails to activate if the time zone is not recognized or the format is invalid.

Note: The format string for the time must not contain quotes (") and braces ({ and }).

A hash (#) can be specified in the text template by escaping it as follows: #{#}.

For more information, see the list of time zones and the list of valid time format strings.

Parameters

Name Description Type Notes
Text Template The text that is used to generate the output by substituting the identifiers in it, such as #{name}, with the values from the input ports. string

Input Port Details

Name Description Type
Object Used to substitute identifiers that are not prefixed with source.. For example, #{name} or #{timestamp}. any
Source Used to substitute identifiers that are prefixed with source.. For example, #{source.name}. any

Output Port Details

Name Description Type
Output String containing the substitutions from the text template. string

Toggle

apama.analyticskit.blocks.core.Toggle

Converts two pulse inputs to a boolean output based on the set and reset signals, with optional delays.

Without delays, the output state is changed to true on a set signal, and changed to false on a reset signal. If both signals are received at the same time, the output state is toggled (to true if signals are received for the first time).

If delay times are specified, the output state is only changed to true or false after the delay has been applied.

The following exception applies if both signals are received at the same time: the output state is only toggled if both delay times are the same, or have not been specified at all.

Parameters

Name Description Type Notes
Set Delay (secs) The amount of time (in seconds) after which the set signal is processed.

If the parameter is not specified, then the signal is immediately processed.

This must be a finite and positive number.

float Optional
Reset Delay (secs) The amount of time (in seconds) after which the reset signal is processed.

If the parameter is not specified, then the signal is immediately processed.

This must be a finite and positive number.

float Optional

Input Port Details

Name Description Type
Set Sets the output to true. Any pending delayed set or reset signals are cancelled on the new input. pulse
Reset Sets the output to false. Any pending delayed set or reset signals are cancelled on the new input. pulse

Output Port Details

Name Description Type
Value The output value generated from the input signals. boolean