sap dynamic edge processing - sap help portal · registering and configuring a custom enterprise...

SAP Dynamic Edge Processing IoT Edge Services – Developer Guide Version 2.0 FP01

IOT EDGE SERVICES – DEVELOPER GUIDE Public

2

TABLE OF CONTENTS

PLUGIN DEVELOPMENT ............................................................................................................................ 3 Introduction to Plugins for IoT Edge Services ......................................................................................... 3 Protocol Plugins ............................................................................................................................................ 3 Enterprise Plugins ......................................................................................................................................... 3 Writing a Custom Plugin (Java) ................................................................................................................. 3 IPlugin Interface ............................................................................................................................................ 4 IProtocolPlugin Interface ............................................................................................................................... 4 IProtocolAdapter Interface ............................................................................................................................ 5 IEnterprisePlugin Interface ............................................................................................................................ 6 Configuring a Custom Plugin .................................................................................................................... 8 Location of Custom Plugin JAR .................................................................................................................... 8 Registering and Configuring a Custom Protocol Plugin ................................................................................ 8 Registering and Configuring a Custom Enterprise Plugin ............................................................................ 8

EXTERNAL CUSTOM RULE - STREAMING LITE CCL PROJECT DEVELOPMENT .............................. 9 Input Schema ............................................................................................................................................... 9 Output Schema ............................................................................................................................................ 9 Input Schema Details ................................................................................................................................ 10 Debugging.................................................................................................................................................. 10 Compiling the CCL into a CCX File ......................................................................................................... 10 Start the Custom Project .......................................................................................................................... 10 Starting the Custom Project with User Authentication ......................................................................... 10

APPENDIX .................................................................................................................................................. 11 Custom CCL Sample Template ................................................................................................................ 11


3

PLUGIN DEVELOPMENT

Introduction to Plugins for IoT Edge Services IoT edge services has been designed to be extensible. Plugins can be written in the form of Java classes conforming to a particular interface. This allows support for a multitude of IoT devices and enterprise destinations. There are two types of plugins that can be written by developers: protocol plugins and enterprise plugins.

Protocol Plugins

Protocol plugins are the entry point for data ingestion into IoT edge services. They are used to listen for and receive messages sent from smart devices, format the received data into an

Object representing the sensor’s value or state, and send it to the IoT edge services

IIoTAdapter. As such, custom protocol plugins can be written to support any type of protocol

that a smart device may make use of in order to get data into IoT edge services. Protocol plugins must also support receiving messages from the IoT edge services

IIoTAdapter. However, the plugin does not necessarily need to do anything with the message.

For example, message output is not supported via the REST portion of the provided

HttpProtocolPlugin. Messages are sent from the IIoTAdapter to the plugin if a field message is

generated as an action in response to an event. The plugin can make use of the received data as it sees fit.

Enterprise Plugins

Enterprise plugins are output end points for Dynamic Edge Processing. If a rule is configured to send to an enterprise plugin, every time an event or fidelity reading is generated by the rule, it is forwarded to the configured enterprise plugins. Enterprise plugins are a very flexible way of using Dynamic Edge Processing because the received information can be used in any way the developer wishes.

Writing a Custom Plugin (Java)

To implement a plugin, a number of interfaces must be satisfied. The IPlugin interface outlines

methods common to all types of plugins. The IProtocolPlugin interface outlines methods for protocol

plugins, while the IEnterprisePlugin interface outlines methods for enterprise plugins. Both of these

interfaces extend the IPlugin interface, so both protocol plugins and enterprise plugins must implement

these methods. Protocol plugins must implement the IProtocolPlugin interface and all of its methods

and enterprise plugins must implement the IEnterprisePlugin interface and all of its methods.

These interfaces as well as all other com.sap.dep.* classes referenced in this guide are located in the

DEPPluginClient JAR file located in /opt/dep_iot_edge/java_lib. In addition, this JAR contains the

com.sap.dep.logging.LogManager class through which you can get access to a

com.sap.dep.logging.ILogger logger instance for your plugin via the

getLogger(Class component) method. This logger will write to a file in

/opt/dep_iot_edge/log/ named <YourPluginClassName>.log.


4

IPlugin Interface

/**

* Signals to the plug-in that it should clean up resources and

* shutdown

*/

public void stopPlugin();

/**

* Allows the IIoTAdapter to periodically verify that the plug-in has

* the active connections it requires.

* If {@code false} is returned, {@link #reconnectRequest} will be

* called.

*/

boolean isConnected();

/**

* Called by the IIoTAdapter after {@link #isConnected} returns {@code

* false}.

*/

void reconnectRequest();

/**

* Allows the IIoTAdapter to notify the plug-in of a change to the

* plug-ins log level.

*/

void changeLogLevel(ILogger.Level level);

The stopPlugin method, defined as part of the IPlugin interface, is called by the

IIoTAdapter before IoT edge services is shut down. This method has no parameters. An

implementation of this method should close any closeable objects the plugin is using and do any necessary cleanup.

The isConnected method is defined in order for the plugin to report its connection status in the

form of a boolean to the IIoTAdapter. This method has no parameters. An implementation of

this method should return false if the plugin requires a reconnection attempt. Otherwise, true

should be returned. If false is returned, reconnectRequest is called.

The counterpart to isConnected is reconnectRequest which is called when isConnected

returns false. This method has no parameters. The implementation of this method should

ensure that the plugin is in a valid state for interactions with smart devices and/or the

IIoTAdapter.

Lastly, a changeLogLevel method is defined. An implementation of this method should switch

the logging level to the given ILogger.Level enum argument. Following is an example of

where logger is an ILogger object that handles logging for the plugin and level is the passed

ILogger.Level.

logger.setLevel(level);

IProtocolPlugin Interface

/**

* Starts the plug-in

*


5

* @param adapter an {@link IProtocolAdapter} which can be used to

* input messages destined for {@link IEnginePlugin}s

* @param pluginConfig a {@link Properties} instance that holds the

* mapped configuration for the plug-in

*

* @throws StartupFailureException if the plugin fails to startup

* properly and cannot recover

*/

void startPlugin(IProtocolAdapter adapter, Properties pluginConfig)

throws StartupFailureException;

/**

* Handles a message being output from one of the {@link IEnginePlugin}

* plug-ins to this plug-in

*

* @param message The message being given for the plug-in to handle.

* Class type is specific to the {@link IEnginePlugin} sending the

* message

*/

void handleEngineMessage(Object message);

The IProtocolPlugin interface defines a startPlugin method with two parameters: an

IProtocolAdapter object used to route messages to the IIoTAdapter, and a Properties

object containing all configuration information stored in the database (see Registering and Configuring a Custom Protocol Plugin). This method is called from the main thread of the

IIoTAdapter so that any blocking calls should be made on a separate thread. If at any point the

plugin startup fails, a StartupFailureException should be thrown by the method.

Implementation of this method should prepare the plugin for use, which may require making use

of the Properties object. The method should also continuously listen for messages over the

desired protocol.

The IProtocolAdapter interface defines one method, sendMessageToEnginePlugins

method, which sends the given message Object to all registered engine plugins (see Plugin

Development) using the sourcePlugin argument to identify the sending plugin. To input

sensor readings to the Streaming Lite Engine Plugin, the message should be an instance of

com.sap.dep.client.InboundMessage populated with the reading data via the

InboundMessage.fromJSON(jsonMessage) method. The required JSON format can be

found in the SAP Dynamic Edge Processing IoT Edge Services - Configuration Guide, under the “Sending Data to a Protocol Plugin” section.

IProtocolAdapter Interface /**

* Passes the provided input message to the desired Engine plug-in,

* provided it exists

*

* @param message the message to forward on.

* The plug-in you are attempting to input a message into likely

* has a format or object it is expecting to receive. Ensure you

* are conforming to these expectations.

*

* @param sourcePlugin the IProtocolPlugin object that is sending to

* its registered destination IEnginePlugin(s)

* This is done using the canonical name of the Protocol plug-in

* class sending the message.

* Example:


6

* com.example.plugins.MyExampleProtocolPlugin

* @throws UnsupportedSensorException

* @throws UnsupportedMessageTypeException

*/

void sendMessageToEnginePlugins(Object message, IProtocolPlugin

sourcePlugin) throws UnsupportedMessageTypeException,

UnsupportedSensorException;

Following is an example using this method, where protocolAdapter is an

IProtocolAdapter object, message is a com.sap.dep.client.InboundMessage, and

this implements IProtocolPlugin.

protocolAdapter.sendMessageToEnginePlugins(message, this);

The IProtocolPlugin interface also defines a handleEngineMessage method. This method

takes a single argument, a generic Object that is the message. This method is called by

IIoTAdapter when the Streaming Lite Engine Plugin has generated a field message as a result

of an action associated to a triggered rule. In that case, the message object is an instance of

com.sap.dep.client.FieldMessage. Implementations that handle field messages can gain

access to a JSON string version of the field message by calling message.toString().

In order for Protocol Plugins to be loaded by Dynamic Edge Processing, the JAR file containing the plugin classes must have the appropriate service provider interface file in the META-INF directory, as outlined below. This only applies to protocol plugins.

File Path & Name File Contents

META-INF/services/com.sap.dep.interfaces.IProtocolPlugin

Canonical Name for the class implementing IProtocolPlugin Example: com.example.protocolplugin.MyPluginClass

IEnterprisePlugin Interface

/**

* Starts the plug-in

*

* @param config A {@link Properties} instance that holds mapping of

* configuration for the plugin

* @throws Exception

*/

public void startPlugin(Properties config) throws Exception;

/**

*

* @param event

* @throws Exception The plugin must throw an exception if it fails to

* handle an event and wants it to be put in a retry queue

*/

public void handleEnterpriseEvent(EnterpriseEvent event) throws

Exception;

/**


7

*

* @param event

* @throws Exception The plugin must throw an exception if it fails to

* handle an event and wants it to be put in a retry queue

*/

public void handleFidelityEvent(SensorFidelityEvent event) throws

Exception;

Enterprise plugins can be configured to allow multiple simultaneous instances of the plugin with different configuration properties.

The IEnterprisePlugin defines a startPlugin method with a Properties object

parameter containing all configuration information stored in the database (see Registering and Configuring a Custom Protocol Plugin). If at any point the plugin startup fails, a

StartupFailureException should be thrown by the implemented method. Implementation of

this method should prepare the plugin for use, which may require making use of the Properties

object.

Next, the interface defines a handleEnterpriseEvent method which takes a

com.sap.dep.client.EnterpriseEvent object as an argument. This method is called

every time an event is generated by a rule that has this plugin associated to it. Implementation of

this method should make use of the EnterpriseEvent object and perform any follow-up

actions necessary to handle the particular event. An exception can be thrown by this method in

order for the EnterpriseEvent to be put into a re-attempt queue. The get methods listed

below allow access to the event’s data. /*

* List of EnterpriseEvent object get methods

*/

String getDeviceId();

String getDeviceTag();

String getSensorProfileId();

String getSensorProfileName();

String getSensorId();

String getSensorTag();

String getSourceRuleType();

String getSourceRuleId();

String getSourceRuleName();

String getSensorInformation();

Date getDateCreated();

Finally, the interface defines a handleFidelityEvent method that takes a

com.sap.dep.client.SensorFidelityEvent object as an argument. This method is called

every time a sensor fidelity reading is sent to the enterprise plugin, as determined by the sensor’s fidelity rule settings. An exception can be thrown by this method in order for the

SensorFidelityEvent to be put into a re-attempt queue. The get methods listed below allow

access to the event’s data. /*

* List of SensorFidelityEvent object get methods

*/

String getDeviceId();

String getDeviceTag();

String getSensorProfileId();

String getSensorProfileName();


8

String getSensorId();

String getSensorTag();

String getSensorReadingValue();

String getSourceRuleId();

String getContext();

Date getDateCreated();

Configuring a Custom Plugin Once the java file(s) has/have been written for the custom plugin and a JAR file has been created, it must be placed in the designated installation subdirectory. Next, the custom plugin must be configured via the database. Location of Custom Plugin JAR

The custom JAR file needs to be placed in the /opt/dep_iot_edge/java_lib directory. This

is the directory where Dynamic Edge Processing will look for plugins to start.

Registering and Configuring a Custom Protocol Plugin The protocol plugin must be configured for integration with IoT edge services. Please refer to the SAP Dynamic Edge Processing IoT edge services - Configuration Guide.

Registering and Configuring a Custom Enterprise Plugin

The enterprise plugin must be configured for integration with IoT edge services. Please refer to the SAP Dynamic Edge Processing IoT edge services - Configuration Guide.


9

EXTERNAL CUSTOM RULE - STREAMING LITE CCL PROJECT DEVELOPMENT

NOTE: This document assumes you are familiar with CCL development. If this is not the case, please refer to the Smart Data Streaming developer information found at http://help.sap.com/hana_options_sds/ for further information. Streaming Lite does not support the full functionality offered by Smart Data Streaming.

The external custom rule provides the ability define custom processing logic to be used as a rule. The custom CCL project must satisfy these two requirements to integrate into IoT edge services.

1. The custom CCL project has an Input Stream named isCustomSL with a schema matching the

Input Schema outlined below.

2. The custom CCL project has an Output Stream named osCustomSL with a schema matching the

Output Schema outlined below.

The RuleId being output needs to match either the Rule ID or Rule Name of the

External Custom Rule configured to use the custom CCL project. It is recommended to

use the Rule Name as it isn’t system generated and can be consistent across

deployments.

Between these streams, the custom CCL can consume the data from isCustomSL and define the logic

required for the custom rule. Once the conditions for the rule have been met, an output to osCustomSL

must be made with all of the input stream data, except Context, and the Rule ID or Rule Name of the

triggered event. The output is consumed by IoT edge services, and IoT edge services performs scoping and enforces the Max Event Frequency for the rule. If scoping is met and the event hasn’t occurred too recently, the actions configured for the rule will fire, the event will be sent to the configured enterprise endpoints, and the event will be saved to the edge database if the rule has been configured to do so. A basic sample template for a custom CCL project can be found in the appendix. Input Schema SCHEMA (

DeviceId string,

DeviceTag string,

SensorId string,

SensorTag string,

SensorProfileId string,

SensorReadingValue string,

Context string,

DateCreated msdate

)

Output Schema SCHEMA (

DeviceId string,

DeviceTag string,

SensorId string,

SensorTag string,



DateCreated msdate,

RuleId string

)

http://help.sap.com/hana_options_sds/

IOT EDGE SERVICES - DEVELOPER

10

Input Schema Details

The only required and guaranteed non-null fields are DeviceId, SensorProfileId, SensorReadingValue,

and DateCreated. SensorReadingValue can be cast to an integer or a float using the to_integer() or

to_float() CCL functions.

Debugging

To debug using Streaming Lite, make use of the print(string) function and direct the output to a file or

watch the terminal hosting the streamingproject. If the value of the print statement is null or any of the

values being concatenated are null, an empty line will be output. An easy way to get prevent this is to use

firstnonnull(thePossibleNullValue, 'null').

Compiling the CCL into a CCX File

Use the streamingcompiler executable in $STREAMING_HOME/bin to compile the CCL file. Replace the

placeholders in the following example with your path and files. $STREAMING_HOME/bin/streamingcompiler –i <path-to-ccl>/<ccl-file-name>.ccl –o

<output-path>/<compiled-file-name>.ccx

The -i flag is used to specify the input file and the -o flag is used to specify the output file.

Start the Custom Project

Start the project using the streamingproject executable in $STREAMING_HOME/bin to start the compiled

ccx as a process. Replace the placeholder paths and file with those for your CCX file. NOTE: Port 9230 is used by the primary IoT Edge Services streaming project and should not be used for custom projects.

$STREAMING_HOME/bin/streamingproject --ccx <path-to-ccx>/<compiled-file-name>.ccx -

-command-port 9231 --host localhost

The --ccx flag is used to specify the CCX file to run, the --command-port flag is used to specify the port that

the custom project listens to, and the --host flag specifies the host address the custom project listens on.

To redirect the terminal output to a file, add the following to the end of the previous command. Customize the path and file name, as necessary. >> ~/customProjectOutput.log 2>&1

Starting the Custom Project with User Authentication

Starting the project using the streamingproject executable in with the -V flag will enable user authentication.

Custom projects are authenticated using the same user credentials as the main IoT edge services streaming lite project. See the SAP Dynamic Edge Processing: Edge Business Services - Configuration Guide for instructions to configure the Streaming Lite authentication mechanism


11

APPENDIX

Custom CCL Sample Template /* Copyright (c) 2016 SAP SE or an affiliate company. All rights reserved. */

/** This is a sample template that may be used to create custom CCL project that

integrates with SAP Dynamic Edge Processing */

/* You MUST have an input stream with this name and this schema */

CREATE INPUT STREAM isCustomSL SCHEMA (

DeviceId string,

DeviceTag string,

SensorId string,

SensorTag string,



Context string,

DateCreated msdate

);

/* You may call this flex operator or any window operation and its output stream

whatever you wish */

CREATE FLEX ThisCanBeRenamed

IN isCustomSL

OUT OUTPUT STREAM ThisCanBeRenamed

SCHEMA (

DeviceId string,

DeviceTag string,

SensorId string,

SensorTag string,



DateCreated msdate,

RuleId string

)

BEGIN

ON isCustomSL {

OUTPUT [

DeviceId=isCustomSL.DeviceId;

DeviceTag=isCustomSL.DeviceTag;

SensorId=isCustomSL.SensorId;

SensorTag=isCustomSL.SensorTag;

SensorProfileId=isCustomSL.SensorProfileId;

SensorReadingValue=isCustomSL.SensorReadingValue;

DateCreated=isCustomSL.DateCreated;

RuleId='This will be the Id or Name of the Rule your custom logic

triggers';

];

};

END;

/* You MUST have an output stream with this name and this schema */

CREATE OUTPUT STREAM osCustomSL


12

AS

SELECT

ThisCanBeRenamed.DeviceId DeviceId,

ThisCanBeRenamed.DeviceTag DeviceTag,

ThisCanBeRenamed.SensorId SensorId,

ThisCanBeRenamed.SensorTag SensorTag,

ThisCanBeRenamed.SensorProfileId SensorProfileId,

ThisCanBeRenamed.SensorReadingValue SensorReadingValue,

ThisCanBeRenamed.DateCreated DateCreated,

ThisCanBeRenamed.RuleId RuleId

FROM ThisCanBeRenamed;

www.sap.com

© 2016 SAP SE or an SAP affiliate company. All rights reserved. No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP SE or an SAP affiliate company. SAP and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP SE (or an SAP affiliate company) in Germany and other countries. Please see http://www.sap.com/corporate-en/legal/copyright/index.epx#trademark for additional trademark information and notices. Some software products marketed by SAP SE and its distributors contain proprietary software components of other software vendors. National product specifications may vary. These materials are provided by SAP SE or an SAP affiliate company for informational purposes only, without representation or warranty of any kind, and SAP SE or its affiliated companies shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP SE or SAP affiliate company products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty. In particular, SAP SE or its affiliated companies have no obligation to pursue any course of business outlined in this document or any related presentation, or to develop or release any functionality mentioned therein. This document, or any related presentation, and SAP SE’s or its affiliated companies’ strategy and possible future developments, products, and/or platform directions and functionality are all subject to change and may be changed by SAP SE or its affiliated companies at any time for any reason without notice. The information in this document is not a commitment, promise, or legal obligation to deliver any material, code, or functionality. All forward-looking statements are subject to various risks and uncertainties that could cause actual results to differ materially from expectations. Readers are cautioned not to place undue reliance on these forward-looking statements, which speak only as of their dates, and they should not be relied upon in making purchasing decisions.

http://www.sap.com/corporate-en/legal/copyright/index.epx#trademark

sap dynamic edge processing - sap help portal · registering and configuring a custom enterprise...

Documents