An IoT Proof of Concept – Using HCP IoT Services and on premise SAP Transportation Management/Event management for Cold chain monitoring
Here is a PoC which uses an IoT device (Ti Sensor Tag CC2650), HANA Cloud Platform IoT Services, HANA Cloud Connector (HCC) and on premise SAP application systems(TM and EM). The PoC is built to monitor the temperature of a Freight Order (FO) which transports temperature sensitive products like medicines or meat or vegetables. For those who are not familiar with SAP TM or SAP EM: - please refer relevant SCN pages, TM and EM.
- Freight order is created in SAP TM which holds products with restricted temperature requirements
- Event Handler created in SAP EM with control parameters for temperature requirements
- A sensor (attached to the truck which carries the FO) is used to capture surrounding temperature and send this (via smart phone over cellular network) info to HCP IoT services.
- JAVA persistence API and Hana Cloud Connector used to send this info to on premise SAP EM system as event message
- EM ruleset determine the temperature limits and inform the concerned persons via e-mail
Required Software Components
- An account in HCP trial via registering at https://hanatrial.ondemand.com
- A sensor device to capture temperature, I used tiSensorTag
- An iPhone with an app called IoTSensor
- HANA Cloud connector installed on your local machine (or on premise box). Follow this blog for installation procedure (up to step 4 would be sufficient). This helps to connect applications deployed on HCP to existing on premise system. HCC need not necessarily installed within on premise firewall.
Now we start with configuring HCP for our requirements. You must create a trial user in HANA cloud trial version before proceeding with next steps described here.
1. We will start with configuring IoT Services Cockpit.
1.1 After logging into your trial version, navigate to Services menu on the left side panel. Search for service called ‘Internet of Things Services’ and enable the service. As a result, the subscriptions for the Internet of Things Services cockpit and RDMS will be automatically created for the account as described in this SAP Help portal:Internet of Things Services Cockpit.
1.2 Now you have to deploy Message Management Service(MMS) by following this sap help doc
1.3 To access the Message Management Service (MMS) cockpit and to use the sample clients that are available for the Data Services as well as for the Push Service, a user must have been assigned the role IoT-MMS-User. You can refer here to assign this role.
1.4 Next step is to create Device type and Message Type in IoT Service Cockpit. Navigate to ‘Internet of Things Services’ under Services section on the left side panel of the HCP Cockpit. Click on ‘Go to Service’ which open IoT Service Cockpit in another window.
1.5 Click on device Types tile
1.6 Create a new Device Type by clicking ( + ).
1.7 Enter a name like ‘hpiPhone’ or something like that.
1.8 Go back to the Internet of Things services Cockpit.
1.9 Choose the Message Types tile.
1.10 Create a new Message Type by clicking ( + ).
Enter a name, e.g. "tiSensorTag". Select the device Type as previously created and direction as ‘From Device’. You may choose the following as Fields.
After hit ‘Save’ it will generate an ID for this message Type.
1.12 Note the Message Type ID, Device ID and Device Registration Token.
1.13 Install IoTSensor app on your iPhone.
1.14 For registering the device on HCP, easiest way is to prepare the below url in an outlook e-mail
iot-create://&/accountName&/[Account ID]&/name&/[Connection Name]&/dataCenter&/[Data Center]&/deviceName&/[Device Name]&/deviceTypeID&/[Device Type ID]&/deviceReg&/[Device Registration Token]&/messageTypeID&/[Message Type ID]
[Account ID] => your account ID, e.g., "p1234567trail"
[Data Center] => your account data center, e.g., "hanatrial”
[Connection Name] => any name for a connection, e.g., "myConnection"
[Device Name] => any name for the device, e.g., "iPhone HP" / "Sensor Tag 1"
[Device Type ID] => the Device Type ID you noted at step 1.12
[Device Registration Token] => the Device Registration Token you noted at step 1.12.
[Message Type ID] => the Message Type ID you noted at step 1.12.
Send this URL to your e-mail which you can open from your iPhone. A sample url would look like this:
1.15 Open your e-mail and click on this URL. This will automatically launch the IoTSensor app you installed at step 1.13.
1.16 Press on Registration. The device gets registered successfully.
1.17 You can see the registered device in the IoT Service Cockpit as shown below. Click on ‘Devices’ tile
Now you are done with IoT Cockpit settings and you can start testing its configurations by sending some sample sensor signals. For this
1.18 Open the IoTSensor App on your iPhone
1.19 You can see the "Connection" is now colored red. Press on ‘Sensor’.
1.20 Make sure Bluetooth is ON in your iPhone and TI SensorTag is ON (just press the ON button on the SensorTag device).
1.21 Select a device by selecting the connected SensorTag. Press ‘Refresh’ icon if SensorTag is not yet listed.
1.22 Go back to the previous screen and then again click Go Back. Now you will see both Sensor and Connection colored red.
1.23 Now press the record button. Data will send according to the sending interval.
1.24 You can see the sensor data in MMS cockpit. Choose the Send and view messages, or perform other actions tile (The MMS Cockpit opens.) from the Internet of Things Services Cockpit. Choose the Display stored messages tile. (All tables of incoming data are listed.). Select the table that is named after the Message Type ID that you created previously ("T_IOT_<MESSAGE TYPE ID>").
2. Our next logical step is to configure HCP connection with on premise system using HANA Cloud Connector.
2.1 You might have completed the HCC installation as described in this blog during Required Software Component section above. You will see the connection state as shown below if you completed the steps successfully.
2.2 Next step is to create an access control to on premise SAP Event Management system by ‘Add’ System Mapping and providing the below details. Maintain your own system host name. You could test the connection by click on ‘Check’ button.
2.3 Now we have to give access to a resource (here in this case an RFC FM in SAP Event Management System) in the above system. You may create a wrapper function module for standard SAP BAPI FM ‘/SAPTRX/BAPI_EH_ADDEVENTMSG_02’. This RFC FM is used to post events in EM. Here in this case we have to pass the sensor temperature as event data. So create a remote function module in Z namespace which accept the temperature and sensor ID and timestamp, latitude and longitude. Code snippet below.
Once you activate the FM, switch back to HCC Administration page. Select the System mapping you created in step 2.2, and under the ‘Resource Accessible On …’ table below, click ‘Add’ and provide the below details. With this we are done with HCC set up.
2.4 You can see in HCP cockpit, under Connectivity section, you have an HCC connection up and running by now.
2.5 Now navigate to ‘Destinations’ in HCP cockpit and add a New Destination to your SAP on premise EM system.
Add the system with your own details as seen in the above screenshot. Jco.client.mshost is the message server of your backend SAP system if you are using load balancing, else use jco.client.ashost property to set application server.
3. JPA for message Reading from MMS and send to on premise system via HCC
So far, we have configured IoT Services Cockpit to receive messages from sensor device and HCC setup for passing the message to on premise SAP Event Management system. But this is not enough- we need to read the sensor message from IoT MMS data source table and call the resource (the EM BAPI) we configured via HCC. There are multiple ways to do this as described in this SAP Help portal. I use Java Persistence API(JPA) for this purpose. We have to deploy a small Java Servlet application on HCP which does this trick. Attached the sample code for this servlet.
3.1 Import the project into eclipse as dynamic web project and then make necessary changes to the SensorServlet.java file with your own destination name(as per section 2.5), function module name(as per section 2.3) and MMS table name(as per section 1.24). Deploy the project into HCP, you may refer this blog step 4.6 if you don’t know how to deploy into HCP.
After deployment, you will see the application under Java Applications section in HCP Cockpit.
3.2 Since in the servlet we want to read the data in the MMS, we have to change the default data source binding to MMS data source. For this click on the deployed project name (localproject here) and then click ‘Data Source Binding’ on the left side panel. Delete the default binding which already there by clicking ‘Delete’. Then select ‘New Binding and change the Schema ID to xxxxtrial.iotmms.web.
Make sure you have the below settings under ‘Destinations’.
3.3 The servlet we have deployed can read and send the sensor data stored under MMS. But when we should send this data to on premise will be a question. We can think of the something which trigger this ‘read and send’ – that is pushing the message to on premise system OR pulling the message from on premise system. I followed pushing the message to on premise system approach for this PoC. There is a concept of Message Processing for MMS in HCP IoT Services. By default MMS uses processing service as ‘SQL’ which means all messages are stored in a database. We can use another processing service called Message Forwarding (HTTP) – this can be used to forward an incoming message or notification of the message to web services. I have configured this to notify my servlet whenever a message comes for a specified device type and message type. This way whenever a message comes from my sensor device, my servlet is executed which read the message from MMS data source and send to on premise EM system. This can be done little more easily by just forward the message to an EM web service, but I have not tried this way. The reason is you may lose the message in case some web service failure or something as message forwarding won’t store the message in MMS, but notification will do.
The HTTP Processing Service can be configured by submitting an HTTP PUT request to:
I used a chrome browser tool called postman REST client for this purpose. Just select PUT as a service and send the below text.
Change the device type, message type, schema name, http.url, username and password which matches with your settings. In the http.url, ‘?action=’ can be any action name, we are just checking in the servlet code whether the action is null or not. You will get the URL of the servlet project from HCP cockpitàJava Applications. Click on the servlet project link and there you can see the URL under Application URLs.
By now, we have all configurations in HCP Cockpit, HCP IoT Service Cockpit, HCP IoT MMS Service and HCC. I have not gone in details with other application settings in EM or TM. I will publish another blog with this settings later. But if you have some idea on EM and TM, this would be easy as we have the message ready to be pushed to EM. We should have a ruleset in EM which check the temperature and compare the threshold control parameters and trigger and alert e-mail if it is out of range. The sensor device ID registered in HCP shall be the tracking ID of the freight order. Standard configuration in EM will push this event message to TM where we can further process this and model some business scenario like re planning FO/event based charging etc.
Your views and improvement recommendations welcome