User Guide Document Version: 1.25.0 2017-01-19 PUBLIC SAP IoT Application Enablement Reuse Components and Templates
Content 1 Reuse Components and Templates....3 1.1 IoT Application Enablement Reuse Components.... 3 Map.... 3 Thing Card....4 Thing Card - Details View.... 4 Thing Card - List View....5 Thing List.... 6 Measured s....6 Event List....7 Timeline.... 7 Sensor chart.... 7 1.2 Project Templates....8 IoT Project Template Components....9 2 IoT Application Projects in Web IDE....10 2.1 Enabling the IoT Plugin....10 2.2 Configuring Your Account....11 2.3 Configuration Details for Services and Reuse Components....11 2.4 Creating IoT Application Projects in Web IDE.... 19 2.5 Deploying the Application....19 2 P U B L I C Content
1 Reuse Components and Templates A generic of Things (IoT) application for all use cases or for a specific domain is difficult to define because requirements can vary across use cases. However, there is a set of user interface components and functionality that is required in most IoT applications. For example, maps are useful to visualize the overall status. Graphs are useful to analyze the data and determine where action must be taken. The IoT Application Enablement plugin enables you to create IoT applications from scratch using a wizard-based approach. The wizard also includes the IoT Application Enablement user interface reuse components. IoT Application Enablement Reuse Components [page 3] IoT Project Template Components [page 9] 1.1 IoT Application Enablement Reuse Components Reuse components are already linked to the backend services of SAP IoT Application Enablement. SAP maintains the code of the reuse components and you benefit from continuous improvements made to these components over time. Thing cards and sensor charts are examples of reuse components that you can include in your applications. The various reuse components are: Map [page 3]: Helps you visualize things and their current status in different locations Thing Card [page 4]: Displays additional details about a thing or a list of things Thing List [page 6]: Displays the list of things that you configured for monitoring and basic information about them Measured s [page 6]: Displays the time series data and latest values for the chosen measurement criteria Event List [page 7]: Displays information about events Timeline [page 7]: Displays events along a timeline Sensor chart [page 7]: Displays detailed information about the measured values defined for a thing 1.1.1 Map The map component shows the things clustered by location. A map shows pins to denote things and clusters. The number on a pin indicates the number of things in that location. The pins can have semantic colors to show where action is needed. Reuse Components and Templates P U BL IC 3
From a map, you can: View the number of things by location. The things that are shown in a map are based on standard events with severities Urgent, Important, or Information. If a thing has at least one event of severity Urgent, the overall thing status is Urgent. The color of the pin is red. If the thing has no events of severity Urgent, but at least one event of severity Important, the overall thing status is Important. The color of the pin is orange. If the thing has no events of severity Urgent or Important, but at least one event of severity Information, the overall thing status is Information. The color of the pin is green. If a thing has no open events, the color of the pin is gray. View the breakup of a cluster by zooming in. Obtain additional information about a thing through other reuse components such as thing cards based on your defined workflow. For example, clicking a pin could open the relevant thing card. Thing Card - Details View [page 4] Thing Card - List View [page 5] 1.1.2 Thing Card A thing card shows additional information about a thing. Thing cards can be used in maps. There are two types of views available in thing cards. The details view is used to display details about a single thing. The list view is used to display a list of things in a thing cluster. Thing Card - Details View [page 4] Thing Card - List View [page 5] Map [page 3] 1.1.2.1 Thing Card - Details View In the details view, the thing card displays specific details about a specific thing. The card header displays the thing image, thing external ID, and customer name. The header of the thing card is clickable. You can configure a navigation target from the header, for example, to the thing page. 4 P U B L I C Reuse Components and Templates
The card body shows contact information and the number of open events by severity. Semantic bars serve as a quick indicator of the severity level of open events. The card footer can contain a button to initiate the next course of action. For example, if a thing has open events of severity Error, you may want to view the measured values information in detail to troubleshoot. In such a scenario, the action button can be configured to open the analysis page of the thing. From the thing card in details view, you can: View basic details and status of a thing. Initiate the next course of action, such as inspection, further analysis, and so on. Thing Card - List View [page 5] Map [page 3] IoT Project Template Components [page 9] 1.1.2.2 Thing Card - List View In the list view, the thing card displays a list of things and some basic information about each thing in the list. By default, things shown in the list view are ordered by severity and then by name. In each row, the thing card typically shows the following: The thing image, thing external ID, and one measured value (optional). If measured value is shown, the first value from the database is shown by default. The highest severity level of open events for the thing is indicated by the color of the semantic bar next to the thing image. From the thing card in list view, you can: View the severity levels of open events and key measured values of things in a cluster. View detailed information about the thing. Clicking a row in the card would open the thing page, from where you can view more information and determine the next course of action. Map [page 3] Thing Card - Details View [page 4] IoT Project Template Components [page 9] Reuse Components and Templates P U BL IC 5
1.1.3 Thing List A thing list displays the list of things that you configured for monitoring, some basic information about the things, and their status. Basic information includes the number of configured things, thing image, thing external ID, thing name, thing type, thing address, and customer details. Status information includes the number of high severity alerts and a chart showing the ratio of critical events to total events. Visual indication includes the highest severity level of open events for a thing indicated by the color of the semantic bar next to the thing image. From a thing list you can: Search for specific data based on filtering criteria. Sort the data based on given criteria. Configure navigation targets for clicking a line in the thing list. Sensor chart [page 7] IoT Project Template Components [page 9] 1.1.4 Measured s The measured values component displays the time series data and latest values for the defined measuring criteria. The color of the semantic bar next to a measured value is based on the severity of events for this value. The measured value component enables you to: Navigate to the chart by clicking a measured value row in the table view Search for a specific measured value in the table view A typical use of the measured value is in the thing page of the IoT project template. IoT Project Template Components [page 9] 6 P U B L I C Reuse Components and Templates
1.1.5 Event List The event list component displays information about events. The color of the semantic bar next to an event indicates the severity level of the event. From the event list you can: Toggle between table view and chart view of the event information Sort the events by date, severity, and so on Search for a specific event in the table view A typical use of event list is in the thing page of the IoT project template. IoT Project Template Components [page 9] 1.1.6 Timeline The timeline component displays events along a timeline. For example, you can see details such as date of the last service, last major breakdown, and so on. Timeline helps you plan or initiate a further course of action. A typical use of timeline is in the thing page of the IoT project template. IoT Project Template Components [page 9] 1.1.7 Sensor chart A sensor chart displays detailed information about the measured values defined for a thing. The information shown includes: Measured values data. You can choose to show the time series data for up to 10 measured values in the chart. Each measured value is represented by a colored dot. Note If you select more than one measured value, the Y axis does not show any labels because the measured values selected can have different scales. The Y axis labels become visible when you select one of the shown measured values by clicking on the line directly or by clicking on the measured value name in the legend.. Reuse Components and Templates P U BL IC 7
Threshold values defined for each measured value. These values are shown as colored lines when you select the measured value from the legend. For example, there could be threshold lines for upper error level, upper warning level, lower warning level, and lower error level. Thick red lines indicate error thresholds. Dotted orange lines indicate warning thresholds. A time slider and several time tabs to view the data in multiple ways. From the chart, you can: Add or remove measured values. Zoom in to examine the data. You can zoom in by selecting an area of the chart or by adjusting the time slider. By default, measured value data for 7 days is shown. You can manually select other time ranges from the tabs. Dynamically alter the scale when the data for a selected measured value occupies a small area of the chart. Dynamic Scaling normalizes the data to fill the chart area. Thing Card - Details View [page 4] Thing Card - List View [page 5] Thing List [page 6] 1.2 Project Templates Project templates help you create new IoT applications by a wizard-based approach. For example, to view your assets, monitor their health, and assign service tickets to technicians, you can build a new IoT application. In the template, you can select the reuse components that you want to use in your own application. The default landing page for an IoT application is the map, which gives a high-level view of the status of your assets. The template offers some standard configuration in a form-based screen for customization and for defining the workflow among components. Once you generate the code out of the project template, you own the code and its maintenance. IoT Project Template Components [page 9] Creating IoT Application Projects in Web IDE [page 19] 8 P U B L I C Reuse Components and Templates
1.2.1 IoT Project Template Components The IoT project template provides four basic pages to build your applications. Landing Page (Main page): This page reuses the map component. It displays a map and optionally a thing list, which can be sorted based on defined criteria. Clicking a row in the thing list zooms the map view on the relevant thing or cluster. For individual things, a navigation is to thing card details view can be configured. For thing clusters, a navigation to thing card list view can be configured. The proposed navigation targets for thing card detail view are thing page and analysis page. The proposed navigation targets for the thing card list view are thing card detail view, thing page, and analysis page. Map [page 3] Thing List: The proposed navigation targets are thing page and analysis page. Thing List [page 6] Thing Page: The thing page reuses the measured values, event list, and timeline components. The proposed navigation target by clicking a measured value row is the analysis page. Measured s [page 6] Event List [page 7] Timeline [page 7] Analysis Page: This page displays the sensor chart that enables analysis of the sensor data. Sensor chart [page 7] Creating IoT Application Projects in Web IDE [page 19] Reuse Components and Templates P U BL IC 9
2 IoT Application Projects in Web IDE You can leverage the project templates to create IoT applications from scratch. The templates make use of the reuse components and allow some easy and form based initial configuration of those components and possible navigation targets. Creating IoT Application Projects in Web IDE [page 19] 2.1 Enabling the IoT Plugin Before you can create an IoT application project, ensure that the IoT plugin is enabled. To enable it, complete the following steps: Procedure 1. In SAP Web IDE, from the Tools menu, choose Preferences. 2. Choose Plugins. 3. Choose SAP Plugins from the Repository dropdown list. 4. Choose IoT Application Enablement plugin, enable it, and save your changes. 5. Refresh the browser window. Configuring Your Account [page 11] Creating IoT Application Projects in Web IDE [page 19] 10 P U B L I C IoT Application Projects in Web IDE
2.2 Configuring Your Account Context Before you can create an IoT Application project in Web IDE, configure the destinations for the reuse components and the services used by them. Periodically verify that your destination data is up to date. Procedure 1. In Web IDE, from the Tools menu, choose SAP HANA Cloud Platform Cockpit. 2. Open the Destinations editor. 3. Choose New Destination. 4. Under Destination Configuration, configure each destination. If additional properties are required, choose New under Additional Properties and configure them. Configuration Details for Services and Reuse Components [page 11] 5. Save the destination and configure other destinations as required. Creating IoT Application Projects in Web IDE [page 19] 2.3 Configuration Details for Services and Reuse Components The number of properties to be configured is different for reuse components and services. Observe the following tables carefully and configure the services and components. Table 1: IOTAS IOTAS IoT Application Projects in Web IDE P U B L I C 11
Proxy Audience Client Key Token Service Token Service User Token Service Password Thing Service https://appiotmds.cfapps.sap.hana.ondemand.com OAuth2SAMLBearerAssertion Same as Token Service in the following format: https://<tenantid>.authentication.eu10.hana.ondemand.com/ oauth/token Same as Client Key Table 2: IOTAS-COMPOSITE Proxy Audience Client Key IOTAS-COMPOSITE Composite Thing Service https://appiot-compositethings.cfapps.sap.hana.ondemand.com/ OAuth2SAMLBearerAssertion Same as Token Service 12 P U B L I C IoT Application Projects in Web IDE
Token Service Token Service User Token Service Password in the following format: https://<tenantid>.authentication.eu10.hana.ondemand.com/ oauth/token Same as Client Key Table 3: IOTAS-COMPOSITE-EVENTS-ODATA Proxy Audience Client Key Token Service Token Service User Token Service Password IOTAS-COMPOSITE-EVENTS-ODATA Composite Events OData Service https://composite-eventsodata.cfapps.sap.hana.ondemand.com/ OAuth2SAMLBearerAssertion Same as Token Service in the following format: https://<tenantid>.authentication.eu10.hana.ondemand.com/ oauth/token Same as Client Key IoT Application Projects in Web IDE P U B L I C 13
Table 4: IOTAS-COMPOSITE-THINGS-ODATA Proxy Audience Client Key Token Service Token Service User Token Service Password WebIDEUsage IOTAS-COMPOSITE-THINGS-ODATA Composite Things OData Service https://composite-thingsodata.cfapps.sap.hana.ondemand.com/ OAuth2SAMLBearerAssertion Same as Token Service in the following format: https://<tenantid>.authentication.eu10.hana.ondemand.com/ oauth/token Same as Client Key odata_gen Table 5: IOTAS-CONF Proxy IOTAS-CONF Configuration Service https://appcoreconf.cfapps.sap.hana.ondemand.com/ OAuth2SAMLBearerAssertion 14 P U B L I C IoT Application Projects in Web IDE
Audience Client Key Token Service Token Service User Token Service Password Same as Token Service in the following format: https://<tenantid>.authentication.eu10.hana.ondemand.com/ oauth/token Same as Client Key Table 6: IOTAS-FILEIMAGE Proxy Audience Client Key Token Service Token Service User IOTAS-FILEIMAGE File Service https://thingmodelerfileservice.cfapps.sap.hana.ondemand.com/ OAuth2SAMLBearerAssertion Same as Token Service in the following format: https://<tenantid>.authentication.eu10.hana.ondemand.com/ oauth/token Same as Client Key IoT Application Projects in Web IDE P U B L I C 15
Token Service Password Table 7: IOTAS-EVENTLIST Proxy IOTAS-EVENTLIST Event list reuse component https:// eventlist.cfapps.sap.hana.ondemand.com/ No Table 8: IOTAS-CHART Proxy IOTAS-CHART Sensor chart reuse component https:// chart.cfapps.sap.hana.ondemand.com/ No Table 9: IOTAS-MAP IOTAS-MAP 16 P U B L I C IoT Application Projects in Web IDE
Map reuse component https://map.cfapps.sap.hana.ondemand.com/ Proxy No Table 10: IOTAS-MEASUREDVALUES Proxy IOTAS-MEASUREDVALUES Measured values reuse component https:// measuredvalues.cfapps.sap.hana.ondemand.co m/ No Table 11: IOTAS-THINGCARD Proxy IOTAS-THINGCARD Thing card reuse component https:// thingcard.cfapps.sap.hana.ondemand.com/ No IoT Application Projects in Web IDE P U B L I C 17
Table 12: IOTAS-THINGLIST Proxy IOTAS-THINGLIST Thing list reuse component https:// thinglist.cfapps.sap.hana.ondemand.com/ No Table 13: IOTAS-TIMELINE Proxy IOTAS-TIMELINE Timeline reuse component https:// timeline.cfapps.sap.hana.ondemand.com/ No Configuring Your Account [page 11] Creating IoT Application Projects in Web IDE [page 19] 18 P U B L I C IoT Application Projects in Web IDE
2.4 Creating IoT Application Projects in Web IDE Before you create an application, ensure that IoT Application plugin is enabled and that the required account is configured correctly to use the IoT services and reuse components. Procedure 1. In SAP Web IDE, from the File menu, choose New Project from Template. 2. On the Template Selection page, select of Things, choose IoT Application, and choose Next. 3. On the Basic Information page, enter the project information such as project name, namespace, and title. 4. On the Data Connection page, select the data source (OData service) on which you want to base your project, as follows: a. Under Sources, choose Service. b. Select IoTAS odata Service as the system from the dropdown list. c. In the Service field, enter /CompositeThings/v1. d. Choose Test to verify connectivity to the service. 5. On the Select Pages page, choose the Set (PST) and ID (d PST) for your application. Then, deselect the pages that you do not want in your IoT application. By default, all component pages are preselected. The default home page for your application is the map. You can include additional components such as thing card, thing list, thing page, and analysis page. 6. On the wizard pages that follow, configure the home page and additional pages. 7. Choose Finish. The project wizard creates the project structure in the workspace under a new folder with the project name that you specified. Deploying the Application [page 19] 2.5 Deploying the Application Procedure 1. In SAP Web IDE, choose your project file and choose Deploy Deploy to SAP Hana Cloud Platform. IoT Application Projects in Web IDE P U B L I C 19
2. If required, provide the user details, and choose Deploy. 3. In the Successfully Deployed dialog box, choose Open the active version of the application. Your generated application opens in a browser. Note If you want to change the default property set or the tenant, you can modify the code. Search your project for entries of the <tenant>.<package>.<propertyset> format and update the code to reflect the new tenant or property set values. Reuse Components and Templates [page 3] IoT Application Projects in Web IDE [page 10] 20 P U B L I C IoT Application Projects in Web IDE
Important Disclaimers and Legal Information Coding Samples Any software coding and/or code lines / strings ("Code") included in this documentation are only examples and are not intended to be used in a productive system environment. The Code is only intended to better explain and visualize the syntax and phrasing rules of certain coding. SAP does not warrant the correctness and completeness of the Code given herein, and SAP shall not be liable for errors or damages caused by the usage of the Code, unless damages were caused by SAP intentionally or by SAP's gross negligence. Accessibility The information contained in the SAP documentation represents SAP's current view of accessibility criteria as of the date of publication; it is in no way intended to be a binding guideline on how to ensure accessibility of software products. SAP in particular disclaims any liability in relation to this document. This disclaimer, however, does not apply in cases of willful misconduct or gross negligence of SAP. Furthermore, this document does not result in any direct or indirect contractual obligations of SAP. Gender-Neutral Language As far as possible, SAP documentation is gender neutral. Depending on the context, the reader is addressed directly with "you", or a gender-neutral noun (such as "sales person" or "working days") is used. If when referring to members of both sexes, however, the third-person singular cannot be avoided or a gender-neutral noun does not exist, SAP reserves the right to use the masculine form of the noun and pronoun. This is to ensure that the documentation remains comprehensible. Hyperlinks The SAP documentation may contain hyperlinks to the. These hyperlinks are intended to serve as a hint about where to find related information. SAP does not warrant the availability and correctness of this related information or the ability of this information to serve a particular purpose. SAP shall not be liable for any damages caused by the use of related information unless damages have been caused by SAP's gross negligence or willful misconduct. All links are categorized for transparency (see: http://help.sap.com/disclaimer). Important Disclaimers and Legal Information P U BL IC 21
go.sap.com/registration/ contact.html 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. The information contained herein may be changed without prior notice. 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 or its affiliated companies shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP 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 consd as constituting an additional warranty. 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. All other product and service names mentioned are the trademarks of their respective companies. Please see http://www.sap.com/corporate-en/legal/copyright/ index.epx for additional trademark information and notices.