SAP Edge Services, cloud edition Streaming Service - Administration Guide Version 1802

Transcription

1 SAP Edge Services, cloud edition Streaming Service - Administration Guide Version 1802

2 Table of Contents ABOUT THIS DOCUMENT... 3 Glossary... 3 CONSOLE SECTIONS AND WORKFLOWS... 5 Sensor Profiles & Rules... 5 Sensor Profiles... 5 Rules & Rule Types... 6 Understanding how readings are processed... 7 Sensor Profile Scoping... 7 Rule Types... 8 Additional Rule Configuration Actions Field Message Action Type Sensor Fidelity Change Action Type Work Order Creation Rule Data Sources Supported Rule Types & Fields per Rule Type Configuring A Rule Data Source Live Sensors Live Devices Emulator Events Logs Security Tokens Passwords Settings Import / Export Configuration Runtime Settings Whitelist Configuration Business Essential Functions Configuration HTTP & HTTPS Proxy Configuration Enterprise Plugins Protocol Plugins Engine Plugins - Advanced APPENDIX: ENTERPRISE PLUGIN CONFIGURATION VALUES Supported Date Formats ENTERPRISE_TEMPLATE FIDELITY_TEMPLATE Whitelist Formats Supported by RESTPlugin and WebSocketPlugin APPENDIX: PROTOCOL PLUGIN CONFIGURATION Sending Data to a Protocol Plugin Field Message Action to a Protocol Plugin Sending Data to the HTTP Protocol Plugin

3 ABOUT THIS DOCUMENT This administration guide provides a starting point for using the Streaming Service Edge Console. It describes the primary features of the console. This document is intended for the following audiences: Consultants Partners Customers Developers Glossary Term Definition Individual sensor profile Composite sensor profile Rule Numeric sensor value type State sensor value type Event Chainability Scoping Scope Level Scope Value Sensor Profile Device ID Device Tag Sensor ID Sensor Tag Tiering logic Live Sensor Emulation Contains a set of properties pertaining to one sensor profile A location for chained rules to be specified User-defined logic applied to the sensor readings of a specified Sensor Profile Streams numeric sensor readings Streams non-numeric sensor readings Makes the rule available for composite rules Allows rules to only apply to readings from a sensor with specific properties, controlling how often a rule is applied A set of predefined attributes that can apply to the Device or the Sensor The value for the predefined Scope Level attributes A specific sensor profile A specific device based on a unique Device ID Device(s) with a specified Device Tag. Device Tags are a flexible mechanism allowing for arbitrary device level grouping. A specific sensor based on a unique Sensor ID Sensors with a specific tag, similar to the Device Tag scope The idea behind tiering logic is that more significant events imply less significant events, so that when the conditions for more significant events are satisfied, the less significant events do not fire. Displays all sensor profiles configured to Stream Readings to Monitor 3

4 Sensor Emulation Controls Allows the administrator to emulate a stream of sensor readings for all sensor profiles 4

5 CONSOLE SECTIONS AND WORKFLOWS Sensor Profiles & Rules Users define and manage sensor profiles and their associated rules and actions in this section of the console. Sensor Profiles Sensor profiles describe the readings generated by a sensor. They also control the interpretation of readings in the context of rule evaluation. Every rule that is configured is created in the context of a sensor profile. For example, a user is interested in gathering readings from four separate sensors on a Model RF123 industrial refrigerator. There is one compressor temperature sensor, one door state sensor, and two internal temperature sensors. Both internal temperature sensors provide the readings using the same format and unit of measure. This scenario would require creating three sensor profiles. The compressor temperature sensor profile could be named RF123 Compressor Temp. The door state sensor profile could be named RF123 Door State. The internal temperature sensor profile could be named RF123 Internal Temp, and would be used for both internal temperature sensors. Note: The sensor profile name is user-defined and cannot be modified once it has been saved. Sensor profile names must be unique. Sensor profiles are also assigned a unique identifier when saved. Individual and Composite Sensor Profiles There are two types of sensor profiles, individual and composite. An Individual sensor profile contains a set of properties pertaining to one sensor profile (for example, Temperature or Refrigerator Door). Rules are defined against an individual sensor profile and are scoped to include only that sensor. Composite sensor profile is a location for chained rules to be specified looking for sensor readings coming from the same or different sensor profiles. For this reason, only individual sensors can be created. Numeric vs. State Sensor Value Type An individual sensor has two sensor reading value types, numeric and state. A numeric sensor value type streams numeric sensor readings. For example, a humidity sensor can stream relative humidity readings, or an electronic scale can stream live kilogram load. The following parameters need to be defined by the user: Testing & Production Parameters Minimum Value and Maximum Value for sensor readings. Determines the range for the Live Sensors graphs and emulated controls. Window Parameters Window parameters are required on a per-sensor profile level and are used by rules that aggregate sensor readings. For example, the value monitoring rule uses the average sensor reading based on the window parameters. o Minimum # of Readings for Evaluation is the minimum number of sensor readings needed before averaging can be performed. This is useful for noisy analog sensors, for example, where trends are more important than individual readings. o Window Size is the length of time that sensor readings are kept for aggregation. Window size is recorded in seconds. The minimum window size is one second. Typically, window sizes would be 60 seconds or more. 5

6 A state sensor value type streams non-numeric sensor readings. For example, a door sensor could indicate whether the door is open or closed or an intelligent robot could report various movement states as it navigates a room. The following need to be defined by the user: State Values All possible values for sensor profile readings along with an equivalent state name. For example, a traffic light could have state values 0,1,2 with the respective names, red, green, yellow. Stream Data to Monitor Toggles the streaming of sensor readings on and off to the Live Sensors page. Turning this on provides a view into the data streaming. This enables the viewing of graphs on the Live Sensors page. Tip: Monitoring this data has a negative effect on overall throughput. Turn this setting off except when conducting observation or troubleshooting. Configuring a Sensor Profile Following are the workflow steps to configure a sensor profile: [Tab: Configuration > Sensor Profiles & Rules] 1. [Required] Click + to add a new individual sensor profile. 2. [Required] Enter a name for Sensor Profile Name. 3. [Optional] Enter a description for Sensor Profile Description. 4. [Optional] Select Stream Reading to Monitor to stream sensor readings to the Live Sensors page. 5. [Required] Select Numeric or State for Sensor Value Type. 6. [Required] Complete the additional required fields. 7. [Required] Save the Sensor Profile. Rules & Rule Types A rule is user-defined logic applied to the sensor readings of a specified sensor profile. When a rule is satisfied, it triggers an event or controls the fidelity of IoT sensor data. Several built-in, configurable Rule Types are supported natively along with the option to build custom rules. To create a rule you must first define the logic used to determine that a certain event has occurred. You configure where these events are sent by specifying destinations within the rule. Destinations include the edge database and any number of available enterprise plugins. This allows you to notify services that the event has occurred. In addition, you can set one or more actions to be performed every time the event occurs. For more information on actions, refer to the Action Configuration section. You create rules within sensor profiles, but they can be applied to a variety of scopes. They are also uniquely defined for the sensor profile they belong to. Rules can also be enabled or disabled by the administrator. A rule contains the following sections: [Required] General Information o Rule Name o Rule Description o Rule Context Data o Rule Chainability (Y/N) This makes the rule available for Chained Rules [Required] Rule Definition: Rule-specific attributes to define rule logic. Currently one global parameter is required: o [When applicable] Max Event Frequency: Events trigger every time an associated sensor reading fulfils the requirements of the rule. Consider a temperature sensor that has risen to 90 6

7 degrees Celsius and remains that way. A value monitoring rule that triggers an event when the average sensor reading is over 80 degrees Celsius will fire constantly while the reading remains at 90 degrees. The Max Event Frequency controls how frequently an event occurs. For this event to be triggered hourly, for example, you would set the minimum time between events to 1 hour. [Optional] Event Actions: Associated actions applied to triggered events of the rule. [Optional] Event Destination / Sensor Readings Destination: o Enterprise plugin(s): Associate enterprise plugins. This enables events to be sent to any backend system, provided that a plugin is configured or written to move the data. Refer to the Enterprise Plugin section for information on creating plugins. o Edge Event Storage: Specify events to be stored in edge storage. Edge Keep Interval (days): Specify how long events are kept in edge storage Note: Rule names are user-defined and cannot be modified once they are saved. Rule names are uniquely defined for the sensor profile they are associated with. Rules are also assigned a unique identifier when saved. Understanding how readings are processed One or more readings can be sent at a time. All readings are sent within the context of a device. Each device has a unique device ID and readings are considered within the context of this device ID. A device can have a Device Tag, which is used to arbitrarily group devices. For example, a device tag of Outside Temperature could be applied to all devices. Note: Device tag does not affect how data is aggregated. Each reading must contain a sensor profile ID or sensor profile name and a reading value. It may also contain a sensor ID, sensor tag, context, and timestamp. Tags are used in the devices and sensor profiles to provide a flexible form of grouping. Sensor Profile Scoping Scoping allows rules to only apply to readings from a sensor with specific properties, controlling how often a rule is applied. There are two components to scoping: Scope Level and Scope Value. Scope level is a set of predefined attributes that can apply to the device or the sensor. Scope value is the value for the predefined Scope Level attributes. In any rule, the scope value chosen for a scope level must correspond to a real device or sensor for the rule to apply. The rule is applicable to readings for the following scope levels: Sensor Profile: A specific sensor profile Device ID: A specific device based on a unique Device ID Device Tag: Device(s) with a specified device tag. Device Tags are a flexible mechanism allowing for arbitrary device level grouping. For example, a rule could be scoped for the Second Floor Device Tag. This rule would only trigger for devices with that device tag. Sensor ID: A specific sensor based on a unique sensor ID. This is the most specific scoping level. Sensor tag: Sensors with a specific tag, similar to the device tag scope. For example, you can use sensor tag scoping to apply a rule to all humidity sensors tagged as Second Floor. For detailed information on Composite Sensor Profile Scoping, see Creating an Event Chaining Rule. 7

8 Tiering Logic The idea behind tiering logic is that more significant events imply less significant events, so that when the conditions for more significant events are satisfied, the less significant events do not fire. When a reading is produced by a sensor, only the most significant rule that is satisfied will be triggered and will generate an event. For example, suppose a temperature sensor has two numeric comparison rules, one for greater than 60 degrees and one for greater than 80 degrees. If the sensor produces a reading of 65 then the first rule will be triggered. However, if it produces a reading of 85 only the second rule will be triggered, because it is the most significant and it implies that the condition for the first rule is also passed. Tiering logic is only applied to rules within the same scope, and in the case of value monitoring, rules with the same threshold operator. For example, a Temperature sensor profile has two value monitoring rules, Rule 1 and Rule 2. Rule 1 is for greater than 60 degrees and Rule 2 is for greater than 80 degrees. Rule 1 is scoped by Device Tag with a value of Rig 1, and Rule 2 is scoped by Device ID with a value of MH01. If the sensor produces a reading of 85, that meets both scope criteria (i.e. the reading came from a Temperature sensor that is part of a device with Device Tag having a value of Rig 1 and Device ID having a value of MH01 ), both rules would trigger events because each of the rules have a unique scope level and scope value. Rule Types Several built-in, configurable rule types are supported natively. They allow users to easily define rules based on common event processing patterns, without the need for development work. If the provided rule types do not fit the desired logic, there is an option to create and use an external custom rule. Sensor Fidelity Rules Sensor fidelity rules are unique in that they do not generate events, but rather they control the frequency at which readings from the sensor are outputted to the edge storage or enterprise endpoints. Note: This rule type is valid for both numeric and state sensor value types. Characteristics/Attributes: Edge sensor data can be pulled to the Enterprise for analysis upon request. For example: pressure gauge readings are streamed every 500ms. The edge receives a reading every 5 seconds, and the enterprise backend receives a reading hourly. Higher fidelity data can be pulled from the edge if there is a problem. Only one sensor fidelity rule can be enabled on a sensor at any point in time. Note: Refer to the Sensor Fidelity Change Action Type section for information on the option to change the Sensor Fidelity when specific events occur. Rule-Specific Attributes: Edge Output Frequency: The frequency at which sensor readings should be outputted to the edge storage location. You can use a REST API to access the edge data. Enterprise Output Frequency: The frequency at which sensor readings should be outputted to the enterprise location. Warning: High edge output frequencies (small values, such as 1 second) result in increased data stored in the edge database, significantly increasing the required size of the edge database. Exercise caution and test/calculate edge database requirements based on the number of sensors and fidelity settings. 8

9 Creating a Sensor Fidelity Rule Following are the workflow steps to configure a sensor profile: [Tab: Configuration > Sensor Profiles & Rules] 1. [Required] Under a Sensor Profile, click + in the Rules table. 2. [Required] Complete the required fields and save. Note: Only one enabled Sensor Fidelity Rule is allowed. Value Monitoring Rule Type Uses the sensor profile s configurable time window settings to monitor a sensor s average reading value. Note: This rule type is only valid for numeric sensors. Characteristics/Attributes: Applies to numeric sensor data Average values can be monitored for: o Exceeding a threshold value > o Going below a threshold value - < Equality to a specified value with a configurable bidirectional tolerance. For example: an Average Temperature Sensor has gone over 90 C, with a minimum of five readings over a time window of 5 seconds. Note: Value monitoring rules apply tiering logic for each operator type individually (equality rules are exempt from tiering). For greater than rules, the most significant rule is the one with the greatest threshold value. For less than rules, the most significant rule is the one with the lowest threshold value. Rule-Specific Attributes: o Use Rule Data Source: If checked, enables the rule data source feature for this rule. If rule data source is enabled, then rule becomes active only after the first successful update. o Threshold Value: positive and negative values accepted o Threshold Operator: Greater Than, Less Than, Equal To (optional tolerance) Creating a Value Monitoring Rule Following are the workflow steps to create a value monitoring rule: [Tab: Configuration > Sensor Profiles & Rules] [Required] Under a Sensor Profile, click + in the Rules table. [Required] Complete the required fields and save. Timed State Rule Type Used to determine if a sensor has been in a specified state for a configured amount of time. For example, a door sensor has been in the Open state for five minutes. Note: This rule type is only valid for state sensor value types. Characteristics/Attributes: 9

10 Timed state rules apply tiering logic, where the rule with the longest time in state is considered the most significant. o Rules with a time in state of 0 are exempt from tiering. These rules will fire every time the state is read. Note: Timed state operates on an on-demand basis: computations are only done (and events are triggered) only when a new reading comes in. Consider a door sensor with open and closed states. If an open reading comes in and then a closed reading comes in 15 seconds later, it is assumed that the sensor was in the open position for those 15 seconds (up until the time the closed reading arrives) and events are fired accordingly. No events will be triggered in the time between readings (assuming there were no other readings for the corresponding sensor). Rule-Specific Attributes: Target State: This is the state the rule is looking for. Time in State: The minimum length of time the sensor is in the target state. One reading from another state will reset the timer. Creating a Timed State Rule Following are the workflow steps to create a value monitoring rule: [Tab: Configuration > Sensor Profiles & Rules] 1. [Required] Under a Sensor Profile, click + in the Rules table. 2. [Required] Complete the required fields and save. Sensor Watchdog Rule Type Used to determine if a sensor has gone silent for a configurable time period. For example, when a motion detector has not streamed data for 15 minutes. Note: This rule type is valid for both numeric and state sensor value types. Characteristics/Attributes: Sensor watchdog rules apply tiering logic, where the rule with the longest time since last reading is considered the most significant. Sensor watchdog automatically runs every second once a sensor has sent its first reading and continues to run for the lifetime of the current session. Rule-Specific Attributes: Max Interval Without Reading: Length of time passed without a sensor reading Creating a Timed State Rule Following are the workflow steps to create a timed state rule: [Tab: Configuration > Sensor Profiles & Rules] 1. [Required] Under a Sensor Profile, click + in the Rules table. 2. [Required] Complete the required fields and save. Event Chaining Rules 10

11 A composite sensor profile is used to chain two events together. Note: This rule type is valid for both numeric and state sensor value types. Characteristics/Attributes: Two rules are chained at a time. Rules created by individual sensor profiles must have the Event Chainability field enabled. Event chaining rules themselves can also be chained. Looks for two events to occur within a configurable period of time of each other, for example a worker s motion sensor has reported the Fallen state within 60 seconds of a High Gas Levels event. Scoping is as follows: o Device Wide The Chained Rule s Events must occur on the same device ID. For example: Rule 1, Temperature High, and Rule 2, Door Open, have been chained and scoped to Device Wide. Conditions for Rule 1 are met on device ID Fridge 105 and Rule 2 on device ID Fridge 106. As the events have not occurred on the same device ID, the chained rule is not triggered. However, when conditions for both rules are met on the same device ID, the chained rule is triggered. o Device ID The chained rule s events must occur on the specified device ID, which is the only device ID that can trigger the event. For example: Rule 1, Temperature High, and Rule 2, Door Open, have been chained and scoped to Device ID of Fridge123. Conditions for Rule 1 and Rule 2 are met on device ID Fridge 789. As the events have not occurred on the specified device ID, the chained rule is not triggered. However, when conditions for both rules are met on the service ID Fridge123, the chained rule is triggered. Rule-Specific Attributes: Rule Name 1: First unique chainable rule selected. The selection list includes only chainable rules. Rule Name 2: Second unique chainable rule selected. The selection list includes only chainable rules. Time Gap: The maximum time allowance between the two chained events. Event Ordered: Specify whether events need to occur in the specified order of rule selection, i.e.: Rule 1 before Rule 2. When not selected, the rule looks for the two events to occur within the time gap, regardless of order. Creating an Event Chaining Rule Following are the workflow steps to create an event chaining rule: [Tab: Configuration > Sensor Profiles & Rules] [Required] Under a Sensor Profile, click + in the Rules table heading to create Rule 1. [Required] Complete the required fields, make sure the Event Chainability option is selected, and save this Rule. [Required] Follow steps 1 and 2 to create Rule 2. [Required] Under Composite, click + in the Chained Rules table heading to create an Event Chaining Rule. [Required] Complete the required fields to save the Event Chaining Rule. 11

12 Note: Event Chaining Rules themselves can also be chained. External Custom Rule Allows developers to define their own rule logic and events. Note: This rule type is valid for both numeric and state sensor value types. Characteristics/Attributes: Custom rules can be written in a separate Streaming Lite project Template project and examples are provided Integrates back into the framework o Events can be sent to the edge and enterprise endpoints o o Events can have actions associated to them Scoping and Max Event Frequency are handled by the IoT Adapter, not the external custom rule logic Creating an External Custom Rule Refer to the Streaming Service Developer Guide for creating CCL projects. Additional Rule Configuration Event Actions Actions are automated, user-configured responses to events generated by rules. One or more actions can be associated to a rule. For detailed information on Actions, refer to the Actions section. Event Destination & Sensor Readings Destination Enterprise Plugins Define the enterprise destination(s) for the events generated by a rule. For detailed information on Enterprise Plugins, refer to the Enterprise Plugins section. Edge Event Storage Controls whether events are stored locally in the edge database. Edge Keep Interval Specify the length of time to store events in the edge database. Enabling and Disabling Rules Rules can be enabled and disabled as required (rather than being deleted and added). Actions Use this section of the console to configure and manage actions. Actions are automated responses to events generated by rules. These actions are executed whenever their associated event(s) occur. One or more configurable actions can be associated to a rule. Supported action types include: Field Message Sensor Fidelity Change Work Order Creation Field Message Action Type Sends a Message to a specified Protocol Plugin 12

13 Can be used for sending messages and actuation instructions to devices The target protocol plugin is responsible for transmitting message to devices o The protocol plugin must support outbound messages The Protocol Plugin is responsible for formatting the outbound message. For example, when a High Gas event occurs, use an MQTT Protocol plugin to broadcast the message Evacuate Area 4 Immediately to all workers. Action-Specific Attributes: Plugin ID The protocol plugin that receives the message. Message Free-form text sent to the protocol plugin. Usage is specific to the protocol plugin. Recipient Parameters Free-form text sent to the protocol plugin. Usage is specific to the protocol plugin. The protocol plugins that are included handle field messages in the following manner: MQTT: Sends a message to the configured topic. The message body is a JSON formatted object including all available properties: o Device ID o Device Tag o Sensor Profile ID o Sensor Profile Name o Sensor ID o Sensor Tag o Timestamp (The timestamp of the sensor reading that triggered the event) o Source Rule ID (The ID of the rule that triggered the event for the field message) o Source Rule Name (The name of the rule that triggered the event for the field message) o Instruction o Parameters Refer to the Appendix: Protocol Plugin Configuration for the specific JSON format. HTTP: (Only supported for clients connected via the Websocket protocol not supported for clients connected via REST). Sends a message to all connected clients. The message body is a JSON formatted object including all available properties: o Device ID o Device Tag o Sensor Profile ID o Sensor Profile Name o Sensor ID o Sensor Tag o Timestamp (The timestamp of the sensor reading that triggered the event) o Source Rule ID (The ID of the rule that triggered the event for the field message) o Source Rule Name (The name of the rule that triggered the event for the field message) o Instruction o Parameters Refer to the Appendix: Protocol Plugin Configuration for the specific JSON format. 13

14 Tip: Field message actions are a quick and effective way to test rules and validate the endto-end flow. You can test specific rules in a controlled emulation environment, as opposed to monitoring the Event History screen, which logs all events fired by any rule. The Emulator is implemented as a Websocket client to the HTTP protocol plugin. In order to see field messages in the emulator, create a field message action that specifies the plugin ID as HttpProtocolPlugin. Sensor Fidelity Change Action Type Changes the edge and enterprise output frequencies for a sensor profile. Only applicable to sensor profiles with an enabled sensor fidelity rule. Changes are optionally rolled back to original frequencies after a configurable period of time. For example: When the Average Temperature goes above 90 C, increase the enterprise sensor fidelity frequency to every 5 seconds for the next hour (rollback in effect). When the average temperature goes above 90 C, increase the enterprise sensor fidelity frequency to every 5 seconds. (rollback not in effect). Restarting the server resets all sensor fidelity rules to their original frequencies, regardless of the sensor fidelity change action that was previously applied. If two sensor fidelity change actions are created and applied to the same target sensor profile, the one that occurred most recently will be in effect. Tip: Multiple sensor fidelity change actions can be applied to the same sensor profile. This allows the user to configure a sensor fidelity increase on a certain event and configure a sensor fidelity decrease on a separate event. For example, assume the enterprise sensor fidelity Frequency is configured to 60 seconds. When the average temperature goes above 90 C, increase the enterprise sensor fidelity frequency to every 5 seconds (rollback not in effect). When the average temperature goes below 90 C, decrease the enterprise sensor fidelity frequency to every 60 seconds (rollback not in effect). Action-Specific Attributes: Target Sensor Profile This list only pulls the sensor profiles that have a sensor fidelity rule enabled. Edge Fidelity Change Specify the new frequency (s) and the rollback time period (s) (if desired) for the edge storage destination. A value of 0 prevents a rollback. Any frequency changes due to an edge fidelity change are reset to original values when the server is restarted. Enterprise Fidelity Change Specify the new frequency (s) and the rollback time period (s) (if desired) for the enterprise destination. A value of 0 prevents a rollback. Any frequency changes due to an enterprise fidelity change are reset to original values when the server is restarted. Work Order Creation This feature must be configured. Refer to the Business Essential Functions Configuration section below. This Action uses an external Business Essential Functions server to automatically create a plant maintenance (PM) work order. 14

15 Rule Data Sources The required fields for the work order are configured based on the Business Essential Functions implementation. This ensures the required fields are valid for the local environment. When a work order is initially created, it creates a new work order in Business Essential Functions Service. If the work order is being created again, Business Essential Functions Service checks to see if the work order already exists, and if it does, it adds a note to the work order, rather than creating a new one. For example, when a piece of equipment has not streamed a water level sensor reading for four hours, create a maintenance work order to have it repaired. Refer to the Business Essential Functions - API Guide for specific field requirements. Use this section of the console to configure and manage rule data sources. Rule data sources provide dynamic configuration to one or more rules. The feature allows the configuration of a Rule to be updated automatically from a HTTP backend capable of returning a JSON response. Supported Rule Types & Fields per Rule Type Rule: Value Monitoring o Field: Thresholding Value Validated against the same rules as the UI A minimum of one digit is required If a decimal point (.) is present, at least one decimal digit must be too Up to 10 digits with 10 decimals are allowed No grouping separators are allowed Configuring A Rule Data Source Supported Template Placeholders For the HTTP(s) Endpoint URL and Request Body Template fields, the following dynamic placeholders are supported: Rule Name o ${rulename} Rule Id o ${ruleid} Rule Type o ${ruletype} Possible Values: o THRSH This is Value Monitoring Rule Context o ${rulecontext} Rule Scope Value o ${rulescopevalue} Sensor Profile Name o ${sensorprofilename} Sensor Profile Id o ${sensorprofileid} Last Updated Timestamp o ${lastupdatedtimestamp} 15

16 Node Id o ${nodeid} HTTP(s) Endpoint URL The full URL for the endpoint, including scheme, port, path, and any query variables. Supports all the Template Placeholders. All template replacement values will be URL encoded. Request Method This controls the HTTP method that will be used to make the request. Values are GET and POST. If POST is chosen, the Content Type Header Value and Request Body Template options must be configured. Content Type Header Value This should match the type of the content defined in Request Body Template. For example, if the request body template is JSON, this should be set to application/json. Request Body Template The body of the request being sent. It supports the template placeholders identified previously under Supported Template Placeholders. Authentication Type Controls authentication against the configured endpoint. None o No authentication will be performed oauth o The configured oauth token will be passed in the Authorization header prefix with Bearer ( Bearer plus one space) Basic o The configured username and password will be used for pre-emptive basic authentication against the configured endpoint Business Essential Functions o Before sending the configured request, authenticate against the configured Business Essential Functions system configured in Runtime Settings Update Frequency This controls the period between update requests. Custom Headers Allows custom headers to be added to the request. The value is a JSON object where the keys are the header names and the values are the header values. E.g. { X-Custom-Header : somevalue } Date Format The format string to be used to format the Last Updated Timestamp placeholder. If not configured, ISO8601 will be used. The full details on format options can be found under the Supported Date Formats heading of the APPENDIX ENTERPRISE PLUGIN CONFIGURATION VALUES section in the Administration Guide. Response Configuration The supported response content type is JSON. Response Type Currently two formats are supported. All fields on the response are optional. If they are not present, an update to the configuration will not occur, but the last updated timestamp is updated. Built-in Schema o o A static response JSON schema per Rule type Value Monitoring { thresholdingvalue : <A string or number value> } OData V2 o Value Monitoring Configuration 16

17 o Thresholding Value Member The name of the field on the response Entity that is mapped to the corresponding Rule configuration option. For example, to map equipmentmaximumsafevalue from the following simplified OData Entity sample to Threshold Value, specify the value equipmentmaximumsafevalue { d : { equipmentmaximumsafevalue : 100 } } Live Sensors Use this section of the console to monitor sensor readings from live devices and other sources and test rules in an emulated environment. Live Devices Sensor profiles configured to Stream Readings to Monitor appear under the device ID in the Live Devices. Graphs will not appear if sensor readings are not currently streaming data. Emulator You can test end-to-end rule logic using the built-in emulated device and emulated sensor controls. The Live Sensors Emulation view displays all sensor profiles configured to Stream Readings to Monitor. The Sensor Emulation Controls Panel allows you to emulate a stream of sensor readings for all sensor profiles. The Sensor Emulator only sends readings when it has been started. Each sensor profile control allows you to modify the sensor values sent in real time. In addition, you can configure device ID, device Tag, sensor ID, and sensor tag for testing rule scoping. You can only edit these when the sensor emulator is stopped. You can enable or disable sensor profiles using the Settings button on the panel. Disabled sensor profiles do not show up as a control and therefore do not stream any readings. Use the slider to control numeric sensor profile values. The standing value is always streamed first, even if it has not been modified. For example, a temperature sensor with a range of -40 to 100 will initially stream a value of -40. The range of the slider is determined by the range specified in the sensor profile. State sensor profile values are controlled by a collection of buttons. The selected state is streamed until it is unselected or the selection is changed. If no selection is made, no value is streamed. Note: The Emulator streams the current sensor readings at a default rate of once every second. The rate can be configured in the Emulator Controls Panel Settings. Note: A new Device ID is generated every time the Emulator page is loaded. Note: If Device Whitelisting is enabled, change the Emulator s Device ID to match a whitelisted Device ID to avoid readings being blocked. Note: While using the Emulator, if any of the scoping values are changed or removed, any effective Sensor Watchdog Rule will generate events against the previously active scoping values. Make sure any effective Sensor Watchdog Rules are disabled to prevent any undesired events. 17

18 Triggered Field Messages The instructions for the field message action are displayed along with the name of the triggering sensor profile. Tip: Field message actions are a quick and effective way to test rules and validate the end-to-end flow. You can test specific rules in a controlled emulation environment, as opposed to monitoring the Event History screen, which logs all events fired by any rule. The emulator is implemented as a Websocket client to the HTTP Protocol Plugin. In order to see field messages in the emulator, create a field message action that specifies the Plugin ID as HttpProtocolPlugin. Readings are always considered within the context of a device ID, even if they are not scoped by a device ID. For this reason, the emulator initially generates an emulated device ID. For example, if there are two users using the emulator at the same time, two distinct emulated device IDs are generated to prevent overlap. There is no differentiation between emulated devices and live devices. Other users emulated devices show up under Live Devices, the exception being the current user s emulated device, which shows up under Emulated Device. Note: SSL configuration If a self-signed certificate is used for the emulator that differs from the self-signed certificate used by the web server, the certificate used by HTTPProtocolPlugin needs to be trusted by the browser for the emulator to successfully stream readings Refresh the page from the Devices list to see latest changes made to sensor profiles. Events Use this section to view a log of all triggered edge events that have been configured to be saved on the edge. When creating a rule, Edge Event Storage must be selected under the Event Destination section. Logs Logs are written to both the file system and database. The logging threshold for each is configured in Settings->Runtime Settings. Within Runtime Settings, Log Level controls what is written to the file system and Database Appender Log Threshold controls what is written to the database. This section is used to view error logs written to the database only, based on the Database Appender Log Threshold configured in Runtime Settings. Security Use the Security section of the console to configure authentication Tokens and update technical account passwords. Tokens Tokens are used to securely authenticate requests. Tokens can be authorized for the following actions: Sending Sensor Readings via HTTP Protocol Plugin Read access to the OData interface Tokens have several properties: 18

19 Token This is the Token value. Name Name is used to describe who or what the token is for. Description Description is used to further describe who or what the token is for. Enabled This controls the current state of the token, whether the token is currently valid or not. Tokens can be temporarily disabled, and then re-enabled. Expiry Date This is when the token expires. After this point, the token is not valid. A blank expiry date means a token will not expire. Permissions This controls the authorizations for the token. Configuring a Token Following are the workflow steps to configure a token: [Tab: Security > Token] 1. [Required] Click + to add a new token. 2. [Required] Enter a Name. 3. [Optional] Enter a Description. 4. [Optional] Select Enabled to enable the token (or uncheck to disable the token). 5. [Optional] Select Expiry Date (or leave blank to allow for no expiry date). 6. [Required] Select the allowed Permissions. 7. [Required] Save the token. The token value is generated on save and displayed in the Token field. Using a Token The configured token must be sent in a special HTTP header ( Authorization ) and will be validated by the server. For example, for token 71AA540962F382D7E5EFD6DA84142F2D the HTTP header will look like this: Authorization: Bearer 71AA540962F382D7E5EFD6DA84142F2D Note: Tokens should always be sent over HTTPS. Note: The EmulatorSystemToken is required for the Live Sensors screen to function. Live Sensors streams data using this special Token. If EmulatorSystemToken is deleted, a new EmulatorSystemToken is automatically generated. If EmulatorSystemToken is disabled, then Live Sensors will not function correctly. Passwords Use this section of the console to change the passwords for the two technical accounts. Use the Admin Password Settings section for the technical admin user s account password and the OData Password Settings section for the technical OData user password. There are only two technical users with no multiuser support. Settings (Advanced feature) Changes to Settings should be undertaken with caution on production systems. Important Note: Changes to configuration are live after 10 seconds, with the exception of changes to Engine Plugin configuration (which requires an explicit process restart). 19

20 Import / Export Configuration The configuration of the Streaming Service can be imported and exported as a JSON file. For more details on the JSON format, please refer to the Streaming Service JSON Reference Guide. WARNING: Both the export and import are all or nothing. Only a complete configuration can be exported. When imported, all existing configuration is deleted and replaced with the configuration in the import file. Exporting Streaming Service Configuration To export the current configuration of Streaming Service: 1. Navigate to the Settings > Import/Export Configuration tab 2. In the Export Configuration section, click Export This downloads a file entitled export.json containing both the system and rule configuration of the local Streaming Service instance. This is an excellent way to build up a template.json file for custom configurations defined outside of the UI. Security Note: Authentication configuration for external connections (Enterprise Plugins, Rule Data Sources, and Business Essential Functions, for example) is exported, therefore, the contents of an exported file will require secure handling if authentication configuration exists. Note: If the export fails, then detailed information can be found in the EdgeConsole.log file in the log folder of the Streaming Service. Note: Only one Fidelity rule per Sensor Profile is supported in the export (by design). Therefore, export only exports enabled Fidelity rules. Importing Streaming Service Configuration To import a configuration into Streaming Service: 1. Navigate to the Settings > Import/Export Configuration tab 2. In the Import Configuration section, click Browse, select the desired.json configuration file from your local machine 3. Click Import Importing will either return a 200 status indicating a successful import, or a 406 status providing reasons and context for a failed validation. Validating Streaming Service Configuration Validation ensures the structural correctness and data integrity of the configuration but does not apply configuration to the gateway. This is useful for configurations that have either been authored or edited outside of the console. To validate a configuration: 1. Navigate to the Settings > Import/Export Configuration tab 2. In the Validate Configuration section, click Browse, select the desired.json configuration file from your local machine 3. Click Validate Validation will either return a 200 status indicating a valid configuration, or a 406 status providing reasons and context for a failed validation. 20

21 Runtime Settings Runtime settings can be viewed and updated on this screen. The following chart describes each configuration value. Take special care when modifying values. Setting Name (UI) Setting Name (DB) Description Log Level log.level Controls the default verbosity of logging. This setting also controls the verbosity of IoTAdapter. Each plugin may opt to allow individual overriding of this, if desired. Sample Value INFO Database Appender Log Threshold Remote Error Log Size (rows) Reconnect Check Interval (minutes) Password History Count Service Log History (days) Enable Inbound Whitelisting log.dbappender.t hreshold db.size.remoteer rorlogmaxrows reconnect.interva l.minutes security.passwor d.maxhistorycou nt service.log.keep. days whitelist.enablein boundwhitelistin g Available log levels, from most to least logging: - TRACE - DEBUG - INFO - WARN - ERROR - FATAL - OFF Controls the verbosity of logs written to the database and visible in the Edge Console. The maximum number of error log rows maintained in the database. Default is Frequency, in minutes, at which plugin connection status and reconnection attempts will are made. Attempts to reconnect are initiated only if a plugin reports itself as being disconnected. The maximum number of hashed old passwords that are maintained and used for validation of password history when changing passwords. Default is 1. Number of days to keep Windows service files. Set to true to enable filtering of inbound readings based on the sum of all Enterprise whitelists. Default is false. WARN false Whitelist Configuration Streaming Service supports the configuration of whitelist support for filtering both inbound and outbound data via the deviceid value. The deviceid values in a whitelist are always maintained at the Enterprise Plugin level. There is no interface in Streaming Service to maintain individual values in a whitelist. Streaming Service always polls an Enterprise Plugin for the whitelist values and maintains an internal cache of allowed deviceids. Whitelist filtering of deviceid can be applied at two combinable levels. 21

22 1. Individually for each Enterprise Plugin This ensures that an Enterprise Plugin only receives events and fidelity readings that match a deviceid in the whitelist for that specific Enterprise Plugin instance. 2. Globally at the inbound message level to all incoming readings. This prevents the processing of readings from non-whitelisted devices. When Global whitelist is enabled, the deviceid on each inbound message must match the whitelist of at least one Enterprise Plugin. If the deviceid does not match any whitelist, then the message is dropped. The global inbound whitelist filtering is configured by the whitelist.enableinboundwhitelisting setting in the Runtime Settings section. The enterprise plugin-specific filtering is configured individually for each enterprise plugin. See configuration of RESTPlugin and WebSocketPlugin for whitelisting. NOTE: Changes to Whitelist configuration of Enterprise plugins requires a Streaming Service restart to take effect. Business Essential Functions Configuration To support the Create Work Order action, the configuration of the Business Essential Functions host is required. Take special care when modifying values. Host Name: the name of the Business Essential Functions server (fully-qualified domain name). Must specify or (ie Port: the port of the Business Essential Functions server. Authentication (Base64): the Business Essential Functions user and password in the following format (converted to Base64): username:password HTTP & HTTPS Proxy Configuration This section is used to optionally configure a global proxy for the Streaming Service to use. URL: The URL should be the fully-qualified URL for the HTTP(s) proxy host, including protocol and port. If port is omitted, 443 will be used for https and 80 will be used for anything else. Exclusions: By default, the only requests excluded from going through the proxy are those with the same hostname and port as the proxy. Exclusions are comma separated values of either host or host:port. Handling is plugin dependent, but generally an omitted port will exclude all requests to the host while an explicit port will exclude only requests to the combination. Enterprise Plugins Enterprise Plugin configuration can be viewed and updated on this screen. Take special care when modifying values. Initially, there are no configured enterprise plugins for a deployed edge instance. The following Enterprise plugin types are supported: RESTEnterprisePlugin: outbound WebsocketEnterprisePlugin (Client): outbound to WebSocket server IoTServicesEnterprisePlugin (SAP Edge Services, cloud edition only): outbound to IoT Services cloud 22

23 There is no limit on the number of Enterprise plugins of a certain type. For example, multiple REST Enterprise plugins can be configured to send data to different REST endpoints. The configuration required for every Enterprise Plugin is as follows: Setting Name (UI) Name Class Setting Name (DB) ENTERPRISE_ PLUGIN_ID (required) PLUGIN_CLAS S (required) Description Unique name of plugin, used in the Admin UI. The plugin type to use, either for REST communication or for WebSocket communication. Sample Value RESTPluginToHana1 com.sap.dep.enterprisepl ugin.rest.restenterprise Plugin OR Description Process In Order DESCRIPTION (required) PROCESS_IN_ ORDER (required) Description of the plugin. This field ensures that the Enterprise Events are processed in order. The options for this value are: - 0 (false) events are processed by the number of threads that have been set. - 1 (true) only 1 thread is used, regardless of the value specified in the THREADS setting. com.sap.dep.enterprisepl ugin.websocket.websoc ketenterpriseplugin REST plugin configured to send to Hana1 server 0 Threads Retry Count Retry Delay (Seconds) Log message on Failure THREADS (required) RETRY_COUN T (required) RETRY_DELAY (required) LOG_MESSAG E_ON_FAIL (required) The number of threads to use when processing enterprise events for this plugin. The maximum number of attempts to handle each enterprise event. When the maximum number has been reached, no more attempts are made. This retry count is unique to each event that occurs. The delay, in seconds, between each attempt to handle an enterprise event. Whether an error message is logged when a message failure occurs. - 0 (false) no message logged. - 1 (true) error messages are logged Additionally, there are both required and optional configuration settings based on the type of plugin. 23