Creating a rule

User scenario for using Rule Designer

A customer creates a rule in Rule Designer to safeguard their machinery and maintain operational efficiency. This real-world scenario demonstrates the practical application of BMC Helix Edge in monitoring and automating essential processes based on specific events, ensuring the uninterrupted performance of critical equipment.

Before you begin

• Clearly understand the metrics and data points relevant to your use case. Identify the specific metrics to monitor or trigger actions.
• Determine the threshold values for the selected metrics. Thresholds define the conditions that trigger the rule.
• Familiarize yourself with the events that can be generated based on the rule conditions. Events are outcomes triggered when the rule criteria are met.
• Consider the broader context of your IoT deployment and how the rule aligns with overall operational goals and objectives.

To create a rule

1. On the BMC Helix Edge page, select Rules and workflows > Rule Editor.
2. In the left pane of the Rule Designer page, select a node to design a rule.
3. In the Configure Nodes pane, click the Rules tab. 
4. In the Rules tab, click New.
   BMC Helix Edge displays the following page:
   

1. In the Rule ID field, provide a meaningful and descriptive name for your rule.
   This name must reflect the purpose of the rule.
2. From the Profile list, select a device profile. 

3. In the Definition tab, under SQL pane:

   1. Specify the conditions that trigger the rule.
      These conditions are based on various device metrics or events.
   2. Select the appropriate metric, event, or data source on which BMC Helix Edge must apply the rule.
   3. Set the condition parameters, such as threshold values or specific event triggers.
      Use logical operators to define complex conditions if necessary.

   The following is an example of an SQL query with various use cases covering metrics, attributes, and contextual data:

   SELECT
   meta(deviceName) AS device,
   to_json(meta(tags)) AS ctxData,
   json_path_query(ctxData, 'city') AS city,
   meta(profileName) AS profile,
   avg(GenGearOilLevelPercent) AS oilLevel,
   FROM
   enrichedStream
   WHERE
   PROFILE = "WindTurbine"
   AND city = "Pune"
   GROUP BY device, profile, ctxData, city, TUMBLINGWINDOW(ss,30)
   HAVING avg(GenGearOilLevelPercent) < 90.0

   This query monitors the gearbox oil levels in Pune's wind turbines. It identifies turbines with critically low oil levels (below 90%) within 30-second intervals. The following table breaks down the query with a description: 

   Query	Description
   SELECT	meta(deviceName: Extracts the device name (the wind turbine's ID) and labels it as the device. to_json(meta(tags)): Takes the metadata tags associated with each data point and converts them into a JSON object labeled ctxData. json_path_query(ctxData, 'city'): Extracts the 'city' value from the ctxData JSON object. meta(profileName): Retrieves the profile name ("WindTurbine" in this case) and labels it as a profile. avg(GenGearOilLevelPercent): Calculates the average gearbox oil level percentage.
   FROM	enrichedStream: Specifies that the data is being fetched from a stream named enrichedStream. This stream likely contains real-time sensor data from the wind turbines.
   WHERE	PROFILE = "WindTurbine": Filters the data to include only records related to wind turbines. city = "Pune": Further filters the data to focus on turbines located in Pune. GROUP BY device, profile, ctxData, city, TUMBLINGWINDOW(ss, 30): Groups the data by device, profile, context data (including city), and a 30-second tumbling window. This means the query analyzes each turbine's oil level data in 30-second chunks. HAVING avg(GenGearOilLevelPercent) < 90.0: Filters the results to show only those groups (turbines and time intervals) where the average oil level is below 90%.

   The query gathers and processes data for wind turbine devices in Pune from the enrichedStream data source. It groups the data into 30-second intervals and calculates each group's average gear oil level percentage. It then filters the results to include only those with an average gear oil level percentage below 90. Finally, it selects and renames specific metadata fields, converting and extracting JSON data as required. It allows for the monitoring and analyzing wind turbine performance, specifically focusing on those with potentially low gear oil levels within a specific geographic location and profile type. It provides valuable insights for maintenance and operational purposes.

4. In the Actions tab, perform the following steps:
   1. To create a new event, perform the following steps:
      1. Select New action > Event.

      2. In the Event panel, complete the following mandatory fields.
         These actions include sending notifications, generating events, or triggering workflows:

         Field name	Description
         Name	This field specifies a user-friendly name for the mapped data point.
         Message	This field defines a path name or reference to locate the event message's data. It leverages a dot notations syntax. In dashboards or alerts, furnish a concise description of the detected issue. It is crucial to include the device name associated with the event generation. Use the GoTemplate notation for dynamic value population to insert the actual device name, such as {{.device}}. BMC Helix Edge replaces the content in the brackets with the value you define in the rule.
         Device name	This field specifies the name of the device that generated the event message. The system uses the default value from {{.device}} with the actual device name by using the GoTemplate notation.
         Severity	This field assigns a severity level to the event message. The drop-down menu contains predefined options like High, Low, and Medium.
         Correlation ID	This field assigns a unique identifier to the event message to aid tracking and correlation, such as rule and device instance. The message element reference using dot notation displays this field. The correlation ID is crucial for correlating events and subsequent actions, such as closing events or creating tickets.
         Related metric	This field includes the metric's name whose threshold is used in the rule.
         Actual value	This field captures the specific value extracted from the event message. The message element reference using dot notation is displayed in this field. For example {{.oilLevel}}).
         (Optional) Threshold	This field might define a threshold value for the data point extracted from the message. If the actual value exceeds the threshold, it might trigger an alert or notification.
         (Optional) Status	This field shows the current status of the event message. The drop-down menu contains predefined options such as open and closed.
         (Optional) Unit	This field specifies the unit of measurement for the data point extracted from the message.
         Additional Data	This field provides additional information about the generated event (for example, Location). It supports name-value pairs with dynamic values.

         Information

         We recommend leaving the current configuration in the Advanced Options tab as is.

      3. Click Save.
      4. BMC Helix Edge generates a fresh event incorporating user-specified details such as a name and additional information. This event is subsequently accessible for viewing in the BMC Helix Dashboards. To automate responses to specific events, you must have the option to design a workflow activated on the reception of this particular event. For example, you can establish a dedicated workflow for creating a work order triggered by detecting a low oil level.
   2. To add a REST API, perform the following steps:
      1. Click New action > Call Rest API.

      2. In the Call Rest API panel, complete the following mandatory fields. These actions include sending notifications, generating events, or triggering workflows:

         Field name	Description
         Name	Provide a unique identifier for the HTTP sink to distinguish it from others in the configuration.
         Request Method	Select the HTTP method for the request, such as GET, POST, PUT, HEAD, or DELETE.
         URL	Enter the Uniform Resource Locator (URL) that indicates the endpoint where the HTTP request will be directed.
         Omit Empty Results	Set to true to make sure that if the SELECT result is empty, the output will not feed into the sink operator.
         Send Single Results	Use to configure how the output messages are received. If set to false, the output message will be in the format {“result”:”${the string of the received message}”}.
         Data Template	Use the Golang template (format string) to specify the output data format. The input for the template is the sink message, which is always an array of maps. The raw input will be considered the data if no data template is specified. For instance:  The JSON body structure of a REST API refers to the format in which data is organized and represented when making requests or receiving responses to and from a RESTful web service. It adheres to the JSON (JavaScript Object Notation) format, a lightweight data interchange format. The structure depends on the specific requirements of the REST API and the data it deals with. Here's a generic example of what a JSON body structure might look like: {  "field1": "value1",  "field2": "value2",  "nestedField": {    "nestedField1": "nestedValue1",    "nestedField2": "nestedValue2"   },  "arrayField": ["element1", "element2"] } In the context of BMC Helix Edge, when configuring a REST API sink, you would provide the JSON body structure of the REST API endpoint to which you want to send data. The placeholders in double curly braces (for example., {{.device}}) are used for the dynamic substitution of values from the actual data received by the rule. The structure would depend on the requirements and expected input of the specific REST API you are integrating.
         Headers	Use additional headers for the HTTP request to provide extra information about the request or the client in the key value format.

         Information

         Important

         We recommend leaving the current configuration in the Advanced Options tab as is.

   3. To add a Log, perform the following steps:
      1. Select New action > Log.

      2. In the Log panel, complete the following mandatory fields to resolve:
         

         Field name	Description
         Name	Provide a unique identifier for the HTTP sink to distinguish it from others in the configuration.
         Omit Empty Results	Set to true to make sure that if the SELECT result is empty, the output will not feed into the sink operator.
         Send Single Results	Use to configure how the output messages are received. If set to false, the output message will be in the format {“result”:”${the string of the received message}”}.
         Data Template	Use the Golang template (format string) to specify the output data format. The input for the template is the sink message, which is always an array of maps. If no data template is specified, you must consider the raw input as the data. For instance, a REST API's JSON (JavaScript Object Notation) body structure refers to the format in which data is organized and represented when requesting or receiving responses to and from a RESTful web service. It adheres to the JSON format, which is a lightweight data-interchange format. The structure depends on the specific requirements of the REST API and the data it deals with. The following is a generic example of JSON body structure: {  "field1": "value1",  "field2": "value2",  "nestedField": {    "nestedField1": "nestedValue1",    "nestedField2": "nestedValue2"   },  "arrayField": ["element1", "element2"] } In BMC Helix Edge, when configuring a REST API sink, you provide the JSON body structure of the REST API endpoint to which you want to send data. The placeholders in double curly braces (for example, {{.device}}) are used for the dynamic substitution of values from the actual data received by the rule. The structure depends on the requirements and expected input of the specific REST API you are integrating. You can copy and paste the data template from the REST API tab to see the output.

         The DevOps team can view the logs from the rule engine.

5. In the Options tab, perform the following steps:
   1. To use the event time as the time stamp for rule evaluation, click the Use Event Time as Timestamp toggle (noun) key.
   2. In the Late Tolerance (ms) field, specify the acceptable latency tolerance in milliseconds.
   3. In the Buffer Length field, set the buffer length for handling incoming events.
   4. In the Check Point Interval (ms) field, define the checkpoint interval in milliseconds.
   5. To add metadata in the actions that the rule triggers, click the Send Metadata to Actions toggle key.
   6. In the Concurrency field, configure the concurrency settings based on your requirements.
   7. In the QoS list, select the appropriate quality of service (QoS) level for rule execution.
6. To save and enable the rule:
   1. After configuring the rule conditions and actions, save the rule.
   2. Enable the rule to monitor your IoT ecosystem's specified metrics or events.
7. To test and monitor:
   1. Test the rule by generating sample data or events that match the defined conditions.
   2. Monitor the rule's performance and make sure that it responds as expected.