SAP Connected Goods Implementation Guide

Configuration Guide
SAP Connected Goods
Document Version: 1.0.0 – 2018-02-16
SAP Connected Goods Implementation Guide
PUBLIC
Content
1
Document History. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2
About SAP Connected Goods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Main Capabilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3
Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4
Implementation Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
5
Discovery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
5.1
Understanding Typical Connected Goods Customers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
5.2
Understanding the Company Background. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
5.3
Defining Business Use Cases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12
Example Use Case: Product Consumption and Inventory Levels. . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Example Use Case: Consistent Product Quality. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Example Use Case: Business Partner Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
Example Use Case: Device Location. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Example Use Case: Power On/Off. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Example Use Case: Regional Preferences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14
5.4
Defining Sensor Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
5.5
Defining Physical and Logical Device Types (Sensor Device). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
5.6
Defining Master Data Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
6
Defining a Thing Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17
6.1
Managing Device Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19
Creating a Device Type with a JSON File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Deleting a Device Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Defining Onboarding Fields for a Device Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
7
Using IOT Services 4.0 to Create a Connectivity Channel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
7.1
REST API for Managing IOT Services 4.0 Information in Connected Goods Secure Store. . . . . . . . . . . . . 24
7.2
Configuring IOT Services 4.0 Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
7.3
Deleting IOT Services 4.0 Information from the Connected Goods Secure Store. . . . . . . . . . . . . . . . . . 26
7.4
Mapping Connected Goods Entities to IoT Services Entities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
8
Onboarding Devices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28
8.1
Onboarding Devices in the UI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Onboarding a Single Device. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Onboarding Multiple Devices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
2
PUBLIC
SAP Connected Goods Implementation Guide
Content
8.2
Onboarding Devices Using the REST API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Single Device Onboarding API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Multiple Device Onboarding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
9
Working With Master Data Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
9.1
Creating Master Data Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
9.2
Importing Data into Master Data Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
9.3
Importing Master Data Using an Excel File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Downloading the Master Data Excel Template. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Uploading Master Data with an Excel File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Updating Master Data Records. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
9.4
Deleting Master Data Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
9.5
Extending Master Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
10
Semantic Modeling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
10.1
Setting up the Semantic Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Semantic Model Technical Notes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Example: Creating Measures for KPIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
10.2
Adding Ingestion Fields to the Semantic Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
10.3
Clearing or Resetting the Semantic Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
10.4
Including Enumerations for the Dynamic Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
11
Defining UI Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
11.1
Defining Visualization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58
Defining Visual Filters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Defining Map Overlays. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Defining Smart Search and Table Columns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Defining Grid Tiles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Defining the Visual Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
11.2
Defining the Object Detail View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Defining Header Info. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Defining Facets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .68
Defining Widgets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Defining Sections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
11.3
Defining Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Defining a Map Provider. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76
Defining an External Map Provider. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Defining Thresholds. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Defining External Interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Defining Chart Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Defining a Mail Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Defining Default Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
SAP Connected Goods Implementation Guide
Content
PUBLIC
3
12
Defining Rule Configurations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
12.1
About the Rule Engine. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
12.2
Creating an Event. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
12.3
Creating an Event from an Existing Event. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
12.4
Deleting an Event. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
12.5
Creating a Rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Example: Creating a Rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86
Using Defined Fields and Attributes in a Rule Condition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
12.6
Using Rule Actions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90
Creating an Action. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Associating an Action with a Rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Executing an Action Manually. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
12.7
Rule Engine Expert Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Creating a Rule Using a Rule Expression. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Rule Expression Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98
Finding the ID Value for the "event" Field. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Finding the ID Value for the "deviceTypeID" Field. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Finding the ID Value for "field" in a Condition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Creating an Action in Expert Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Including Defined Fields and Attributes in a Rule Expression. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
12.8
Machine Learning. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Configuring Change Point Detection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Configuring Anomaly Detection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .112
Time Series Forecasting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
13
Integrating with SAP Hybris Marketing Cloud. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116
14
Setting up Notifications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120
14.1
Setting up the Notification Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
14.2
Editing Notification Templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
14.3
Resetting Notification Templates Using SQL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
14.4
Default Notification Template Text. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
15
Setting Up Dimensional View Visualization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
15.1
Creating a Dimension. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
15.2
Deleting a Dimension. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
16
Key Performance Indicator (KPI) Modeling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
16.1
Creating a KPI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
16.2
Editing a KPI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
16.3
Deleting a KPI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137
16.4
Examples: Creating KPIs and Widgets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137
Creating a KPI Tile with a Comparison Chart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
4
PUBLIC
SAP Connected Goods Implementation Guide
Content
Creating a KPI Tile with a Column Chart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139
Creating a Device List Control Widget. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Creating a KPI Tile with a Forecast Chart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
17
Data Ingestion Expert Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .149
17.1
Transformation Background. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
17.2
Transformation Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
TRANSFORMATIONS Table Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .150
17.3
Transformations: Accessing Application Master Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Transporting Application Master Data to the Ingestion Pipeline. . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Removing Application Master Data from the Ingestion Pipeline. . . . . . . . . . . . . . . . . . . . . . . . . . . 153
CACHED_TABLES Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
17.4
Transformations: Configuring Output Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
18
CPI iFlows and Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
18.1
Predelivered CPI iFlows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
18.2
Setting up Predelivered CPI iFlows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
18.3
Predelivered Configurations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
19
Configuring an External Server and Workflow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
19.1
Configuring the Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
19.2
Viewing Device Action and Find Device. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
19.3
External Server Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
19.4
Refreshing Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
20
Application Readiness. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
SAP Connected Goods Implementation Guide
Content
PUBLIC
5
1
Document History
View the latest changes to this document.
Product Version
Document Version
Date
Comments
SAP Connected Goods 1712
1.0.0
December 14, 2017
Version release
SAP Connected Goods
10.1
February 16, 2017
Added Configuring an Exter­
1712.02
nal Server and Workflow
[page 164]
Updated Defining Smart
Search and Table Columns
[page 61]
6
PUBLIC
SAP Connected Goods Implementation Guide
Document History
2
About SAP Connected Goods
SAP Connected Goods allows companies to centrally monitor and manage a large number of customer-facing,
revenue-generating devices. It enables data-driven insights to optimize device availability, utilization, and
performance, by ensuring adequate stock levels for replenishment and proper storage conditions of goods,
helping enterprises reduce operational costs, increase revenue, and improve customer satisfaction. It is an
Internet of Things (IoT) solution running on SAP Cloud Platform Cloud Foundry using IoT reference architecture.
Main Capabilities
SAP Connected Goods enables you to do the following:
● Maximize the value of connected devices integrated with the SAP back end
● Onboard, monitor, and manage a large number of mass-market devices, including coolers, coffee makers,
vending machines, and others
● Use rules, alerts, and notifications to track and respond to device data
● Configure the system and user interface to meet your business needs and use cases
● Reduce operational costs and increase revenue by optimizing asset availability and utilization
● Improve customer satisfaction by ensuring the correct storage conditions of perishable goods
● Utilize an appliance or product container as a sales and marketing platform
● Analyze data and comparison trends to inform future business decisions
SAP Connected Goods Implementation Guide
About SAP Connected Goods
PUBLIC
7
3
Introduction
This guide will demonstrate implementation tasks primarily using the scenario of a connected coffeemaker.
Because SAP Connected Goods supports any device type, additional scenarios are occasionally included to show
other types of implementations. These scenarios are intended to help you design your own implementation.
8
PUBLIC
SAP Connected Goods Implementation Guide
Introduction
4
Implementation Prerequisites
You need the following before beginning implementation of SAP Connected Goods:
1. Access to SAP IOT Application Enablement
2. Python tool to convert AE JSON to SAP Connected Goods JSON (install Python 2.7 in your laptop)
3. Access to SAP IOT Services 4.0
4. Access to SAP Connected Goods
SAP Connected Goods Implementation Guide
Implementation Prerequisites
PUBLIC
9
5
Discovery
The discovery process enables you to determine the best practices that will guide the full implementation process.
In most cases, you can complete the discovery process without using SAP Connected Goods. Discovery enables
you to understand a company's background and business model and the business cases that are relevant to SAP
Connected Goods.
The following sections will describe the discovery process using a step-by-step example:
1. Understanding Typical Connected Goods Customers [page 10]
2. Understanding the Company Background [page 11]
3. Defining Business Use Cases [page 12]
4. Defining Sensor Data [page 14]
5. Defining Physical and Logical Device Types (Sensor Device) [page 15]
6. Defining Master Data Information [page 16]
5.1
Understanding Typical Connected Goods Customers
Before beginning implementation, you should have a high-level understanding of the typical business models for
target customers of SAP Connected Goods. SAP Connected Goods is designed particularly for customers with the
following business model:
1. The customer owns mass-market devices – from a small number to thousands or millions – distributed
remotely in public or private locations such as convenience stores and malls. These might include coolers, soft
drink machines, vending machines, and devices of any other category.
2. A business partner for the customer has a business where the device is located, or the business partner is
responsible for the location.
3. The customer has complete information about the business partner, including contact details and other
business data.
4. The customer and the business partner, or the customer and a third-party distribution partner, have a detailed
agreement to determine the operating conditions of each device, including exact location, working hours,
working conditions, financial arrangements, inventory, and maintenance rules.
The typical requirements for a typical SAP Connected Goods customer are device monitoring and alerts based on
specific rules. The following is a more detailed list of common customer requirements:
1. Live sensor data to provide visibility into the real-time working conditions of the device, including the following:
○ Location of the device
○ Inventory status of the device (if the device contains products)
○ Real-time working conditions of the device, based on the following:
○ Power On/Off, if applicable
○ KPI values (such as temperature, humidity, and so on)
○ Status of different parts (such as door Open/Closed, filter status Green/Red, and so on)
10
PUBLIC
SAP Connected Goods Implementation Guide
Discovery
2. Device metadata such as device ID, image, brand, and other characteristics of the device
3. Device historical data for usage and other measurable values
4. CRM information and other master data linked to the operation of the device (such as business partner
information, product information, and so on)
5. Alerts triggered by rules and conditions based on measurable values associated with the device (for example,
the door being open more than 5 minutes, the device being off for 10 minutes, the machine location being
located more than 10 feet from the normal location, or the operating temperature exceeding 35 F.)
Note
This guide will use the fictitious company ACME Famous Coffee to provide an end-to-end example of the SAP
Connected Goods implementation process.
5.2
Understanding the Company Background
As part of defining the business case, detailed research must be performed on the company background. It is
expected that company information will be provided by customer representatives as well as online research.
Example: ACME Famous Coffee Company Background
ACME Famous Coffee company is a global company whose primary business is producing and selling the global
top five coffee brands. ACME sells the coffee through various channels, including distributing millions of their own
branded coffeemakers to business partners such as professional business offices, bars, and restaurants. ACME
usually signs agreements directly or indirectly (via third party distributors) with those partners. In these
agreements, the financial details are clarified and the working conditions of the coffeemakers are specified (such
as location, hours of availably, maintenance schedule, brewing temperature, cleaning cycle, inventory level for milk
and coffee, coffee brand, and so on).
ACME distributes three types of machines to its business partners: ACME Delight 3000, ACME Power Coffee, and
ACME Coffee Express.
ACME distribute five brands of coffee: Manhattan Special, Mr. Brown Coffee, Coffee Delight, Turkish Coffee House,
and Costa Coffee. Each of these brands offers caffeinated and decaffeinated coffee.
The customer operates the coffeemaker as follows:
1. Select a brand. The default selection is Manhattan Special.
2. Select a drink: Cappuccino, Latte, or Coffee. The default selection is Coffee.
3. Select a coffee type: Regular or Decaffeinated. The default selection is Regular.
4. Select a cup size: Small or Large. The default selection is Small.
The machine provides visual indicators when it runs out of stock for the various brands, coffee types, or milk.
Business partners can easily refill the machine as needed with milk, decaf, or regular coffee. The machine can be
easily turned on or off as desired.
Based on current pain points, ACME Famous Coffee Company's primary issue is real-time visibility into the
following:
● Coffee inventory level in each coffeemaker device
SAP Connected Goods Implementation Guide
Discovery
PUBLIC
11
● Product quality
● Usage patterns for the device
● Maintenance status
● Supply Agreement compliance (such as whether the coffeemaker is in the correct location and other agreedupon working conditions)
ACME Famous Coffee Company's main need is for remote monitoring of its commercial coffeemakers, ensuring
optimum working conditions to produce quality coffee, thus improving customer satisfaction and increasing sales.
5.3
Defining Business Use Cases
Because the customer's business use cases will impact every step of the implementation, it is critical to define
these use cases before beginning the implementation process.
Having gathered company background information and established high-level pain points and needs, the next step
is to identify the main personas for the application and define specific user stories and exact needs for those
personas. These personas, user stories, and needs will guide the remaining implementation tasks to customize
SAP Connected Goods for this customer.
Example: ACME Famous Coffee Company User Stories
This example will focus on a single main persona. The main persona will be an ACME Famous Coffee Company
employee with the title of Operational Manager. The Operational Manager is responsible for ensuring that ACME
commercial coffeemakers are working under optimum conditions, and has the ultimate goals of improving
customer satisfaction and increasing sales. His primary need is to remotely monitor the coffeemakers.
There are six main use cases for the Operational Manager:
● Use Case 1: Product Consumption and inventory levels
● Use Case 2: Consistent Product Quality
● Use Case 3: Business Partner Information
● Use Case 4: Device Location
● Use Case 5: Power On/Off
● Use Case 6: Regional Preferences
To understand a use case, it is helpful to define one or more user stories associated with the use case. A user story
is written with a persona in mind and should be verified with the persona. User stories are usually written in the
following format:
As a <Persona>, I need to <Action> so that <reason>.
Following user story format, this guide will define a single user story for each use case.
12
PUBLIC
SAP Connected Goods Implementation Guide
Discovery
5.3.1 Example Use Case: Product Consumption and Inventory
Levels
This use case is designed to allow the Operational Manager to understand coffee consumption patterns and
monitor inventory level in the coffeemakers. This will ensure that an appropriate level of inventory is available at all
times, thus avoiding lost sales and negative customer experiences.
The user story for this use case is:
As an Operational Manager, I need to remotely monitor stock levels and coffee consumption from ACME
commercial coffeemakers so that I can initiate product shipments on time.
5.3.2 Example Use Case: Consistent Product Quality
This use case is designed to allow the Operational Manager to monitor coffee quality in the coffeemakers to ensure
consistent high quality. This will improve customer experience and increase sales from repeat visits.
The user story for this use case is:
As an Operational Manager, I need to remotely monitor brew temperatures and cleaning cycles of ACME
commercial coffeemakers so that I can send a field technician to service the machine if the product quality is low.
5.3.3 Example Use Case: Business Partner Information
This use case is designed to provide the Operational Manager with information about the business partners
mapped to each device. This allows the Operational Manager to communicate with the business partners when
necessary.
The user story for this use case is:
As an Operational Manager, I need to know business partner information, including business name, address,
phone number and contact information, for each distributed ACME commercial coffeemaker, so that I can contact
business partners as needed.
5.3.4 Example Use Case: Device Location
This use case is designed to provide the Operational Manager with the exact coordinates of each device, to ensure
that the business partners follow the agreement regarding the device location.
The user story for this use case is:
As an Operational Manager, I need to know the exact location coordinates for each distributed ACME commercial
coffeemaker, so that I can ensure that it is located in the best location for sales and that it is not missing or stolen.
SAP Connected Goods Implementation Guide
Discovery
PUBLIC
13
5.3.5 Example Use Case: Power On/Off
This use case is designed to provide the Operational Manager with information about the availability of each device
by determining whether each device is powered on or off. The Operational Manager can use this information to act
to prevent lost sales.
The user story for this use case is:
As an Operational Manager, I need to monitor the availability to consumers of each ACME commercial coffeemaker
by checking whether the machine is on or off, so I can avoid lost sales.
5.3.6 Example Use Case: Regional Preferences
This use case is designed to provide the Operational Manager with information about the regional preferences of
consumers as they relate to coffee brand, cup size, and drink type, and use this information to plan shipments and
compare trends.
The user story for this use case is:
As an Operational Manager, I need to know the coffee consumption preferences (coffee brand, cup size, and drink
type) for each region in the country so that I can understand regional preferences, compare trends, and plan
shipments accordingly.
5.4
Defining Sensor Data
This section defines the sensor data that will support the use cases defined for this customer. This step will help to
identify the technical requirements for sensors and thus identify sensor vendors who can provide and install the
sensors for each device.
Based on the use cases for ACME Famous Coffee Company, the following sensor data is required:
Type of Data
Data Item
Description/ Sample Value
Device Metadata
Device Type
Example: ACME Delight 3000, ACME
Power Coffee, ACME Coffee Express
Device Image
One for each coffeemaker type
Device ID
Example: CF1-XXXXX, CF23-XXXXX,
CF3-XXXXX
Transaction Date
Date for each instance of brewing coffee
Transaction Time
Time for each instance of brewing coffee
Power
On/Off
Connectivity
On/Off
Sensor Data
14
PUBLIC
SAP Connected Goods Implementation Guide
Discovery
Type of Data
Data Item
Description/ Sample Value
Brew Temperature
Degrees Fahrenheit
Cup Size
1 for Large Cup, 2 for Small Cup
Coffee Brand
(1/2/3/4/5)
1: Manhattan Special
2: Mr. Brown Coffee
3: Coffee Delight
4: Turkish Coffee House
5: Costa Coffee
Drink
(1/2/3)
1: Cappuccino
2: Latte
3: Coffee
5.5
Coffee Type
(Regular/ Decaf)
Cleaning Date
Date of the cleaning cycle performed on
this machine
Milk Inventory Level
% Full
Caffeinated Coffee Inventory Level
% Full
Decaffeinated Coffee Inventory Level
% Full
Defining Physical and Logical Device Types (Sensor
Device)
The first step in the physical device design and installation process is searching for and selecting a third-party IoT
partner. This partner will understand the required sensor data to support the business use cases, define the
technical specification, manufacture the required sensors, and install or work with other vendors to install the
sensors for each coffeemaker.
For information about defining the logical device, see Defining a Thing Model [page 17].
SAP Connected Goods Implementation Guide
Discovery
PUBLIC
15
5.6
Defining Master Data Information
This section defines the master data that will support the use cases defined for this customer. This step will help to
identify the integration requirements with back-end systems (such as CRM) and with uploading new types of data
as required by the use cases.
Based on the use cases for ACME Famous Coffee Company, the following master data is required:
Table
Data Item
Business Partners
BP Name
BP Type
Description/Sample Value
Office Building, Restaurant
BP Address
BP Geo-Coordinates
Longitude/Latitude
BP Contact Info
Name, E-mail, Phone
Distribution Partner
Distribution Partners
DP Name
DP Address
DP Contact Info
Region
Region ID
Region
Coffee Type
16
PUBLIC
Cappuccino, Latte, Coffee
Brand ID
Brand
Coffee Quality Standards
Regular, Decaf
Drink ID
Drink
Coffee Brand
West, East, Midwest, South
Type ID
Type
Coffee Drink
Name, E-mail, Phone
Manhattan Special, Mr. Brown Coffee,
Coffee Delight, Turkish Coffee House,
Costa Coffee
Standard ID
Cleaning Cycle Frequency
Days
Best Brew Temperature
Degrees Fahrenheit
Cleaning Cycle Frequency
Days
SAP Connected Goods Implementation Guide
Discovery
6
Defining a Thing Model
You can model a device type either by creating a Thing Model in SAP IoT Application Enablement (AE) and
exporting it as a JSON file, or by creating your own JSON file. You then upload it to SAP Connected Goods.
Procedure
Option 1: Creating a Thing Model in AE
1. Create a Thing Package: In SAP IoT Application Enablement (AE), create an AE package (example:
coffeemakers).
2. Create Thing Types: In SAP IoT Application Enablement (AE), define thing types for the package.
a. Define Basic Properties: For each property, provide a name, type, and length.
AE basic properties for the coffeemakers package:
Sensor Data
AE Property
AE Type
AE Length
Device ID
deviceid
String
127
Device Type
deviceType
String
127
b. Define Measure Properties for the sensor device: For each property, provide a name, type, and length.
AE measure properties for the coffeemakers package:
Sensor Data
AE Property
AE Type
Transaction Date
transactionDate
Timestamp
Transaction Time
transactionTime
Timestamp
Power
power
Integer
Connectivity
connectivity
Integer
Brew Temperature
brewTemperature
Decimal
10,2
Cup Size
cupSize
String
127
Coffee Brand
coffeeBrand
String
127
Drink
drink
String
127
Coffee Type
coffeeType
String
127
Cleaning Date
cleaningDate
Timestamp
Milk Inventory Level
milkInventoryLevel
Decimal
10,2
Caffeinated Coffee Inven­
tory Level
caffeinatedCoffeeInvLevel
Decimal
10,2
SAP Connected Goods Implementation Guide
Defining a Thing Model
AE Length
PUBLIC
17
Sensor Data
AE Property
Decaffeinated Coffee Inven­ decaffeinatedCoffeeInvLe­
tory Level
vel
AE Type
AE Length
Decimal
10,2
Note
For inventory calculations in the Vending scenario, define measures as follows.
Define the following measures for the vending product replenishment event, in addition to other standard
fields:
Field
Type
Length
SLOT_CODE
String
127
STOCK_AFTER
Integer
CAPACITY
Integer
PRICE
Decimal
10,2
CURRENCY
String
127
VEND_QUANTITY
Integer
Define the following measure for the vending transaction event, in addition to other standard fields:
○ VEND_QUANTITY
3. Create a Thing Model: In SAP IoT Application Enabler (AE), create at least one thing model for an existing AE
package. You can create an unlimited number of thing models. A thing model can contain all or a subset of the
basic or measured thing types in the package.
Create a thing model named coffee_maker in the coffeemakers package. The coffee_maker model will
contain the following properties:
18
Sensor Data
AE Property
Device ID
deviceId
Device Type
deviceType
Transaction Date
transactionDate
Transaction Time
transactionTime
Power
power
Connectivity
connectivity
Brew Temperature
brewTemperature
Cup Size
cupSize
Coffee Brand
coffeeBrand
Drink
drink
Coffee Type
coffeeType
PUBLIC
SAP Connected Goods Implementation Guide
Defining a Thing Model
Sensor Data
AE Property
Cleaning Date
cleaningDate
Milk Inventory Level
milkInventoryLevel
Caffeinated Coffee Inventory Level
caffeinatedCoffeeInventoryLevel
Decaffeinated Coffee Inventory Level
decaffeinatedCoffeeInventoryLevel
4. Download an AE File as JSON File: SAP IoT AE provides a utility to extract a package, as defined in the
previous steps, as a JSON file. The JSON file will include all metadata for the package, including thing types
and thing models. To extract a package, do the following:
a. In a browser, enter the following URL: https://<system>/appcore-conf/
Configuration('<packagename>')
Example: https://iot-dev.sb-iot-sap.cfapps.sap.hana.ondemand.com/appcore-conf/
Configuration('iot.dev.knu.sync.coffeemakers)
b. Copy and paste the content of the browser to a text file and save the file (example: ae_model.json).
c. Upload the JSON file as described below.
Note
Use the fully qualified package name.
Option 2: Using Your Own JSON File
5. Create your own device type as a JSON as described in Creating a Device Type with a JSON File [page 20] and
upload it as indicated below.
Uploading the JSON File
6. Do the following to upload a JSON file to SAP Connected Goods. You can upload a file in either AE JSON or
CnG JSON format.
a. Log into SAP Connected Goods as a user with the Administrator role.
b. In the launchpad, choose the Device Types tile.
c. Choose Upload Device Types.
d. Browse to and choose the <packagename>.json (if using Option 1) or the JSON file you created (if using
Option 2).
e. Choose OK.
In the device types list, you see all the types defined.
6.1
Managing Device Types
You can add and delete device types that specify a group of devices that share similar properties.
Note
The property definition in a message type must be unique throughout the application. You cannot reuse the
property name (fieldName) with a different dataType or UoM.
SAP Connected Goods Implementation Guide
Defining a Thing Model
PUBLIC
19
6.1.1 Creating a Device Type with a JSON File
You can register device types in SAP Connected Goods by uploading a JSON file from the Device Types page. This
upload feature accepts two types of JSON format:
● IOT AE Thing Modeler JSON
● Connected Goods Device Types JSON
To create device types using IOT AE JSON format, you must first create thing types in the IOT AE Thing Modeler,
and then download them as a JSON. You can then upload this file from theDevice Types page. Alternatively, the you
can upload a JSON file containing the SAP Connected Goods data model as described in the example below.
The JSON file can only contain device types belonging to one device category (or package). If the device category
does not exist, it will be created before creating the device types. After the device types have been created, you can
use the Device Type Details page to determine which custom attributes should be visible and which should be
mandatory for the new device types.
The device types (and message types) will also be registered in IOT Services 4.0 if the configuration is set up
correctly and the register_device_type flag is set to true. If not, these artifacts will only be saved in the
Connected Goods database. If IOT Services 4.0 have been switched on, message forwarding will also be set up for
each device type/message type combination. Two additional fields, cng_deviceId and timestamp, will be
created for each message type. The cng_deviceId field will be used by the ingestion layer to uniquely identify a
device when sensor data is received.
For more information on configuring IOT Services 4.0, see Using IOT Services 4.0 to Create a Connectivity Channel
[page 24].
Note
Modifying device types and message types is not supported. To modify these types, delete them and re-create
them.
The following table describes some key attributes of the JSON file.
Property
Description
deviceCategoryId
The device category (or package) to which the device types
belong.
deviceTypesReqList
The list of device types to be created for the specified device
category. No action will be performed on already existing de­
vice types.
If any existing device types are omitted from this list, they will
be deleted.
imageId
The image URL for the device type. If specified, this will be dis­
played on the Device Type Details page.
deviceTypeId
The name (or ID) of the device type.
deviceMessageTypes
The list of message types or attributes for a device type.
20
PUBLIC
SAP Connected Goods Implementation Guide
Defining a Thing Model
Property
Description
basicData
If set to true, the properties will be recorded as device type
attributes. If set to false, the properties will be recorded as
message types (sensor data or time series data).
id
The unique name for the message type. The maximum length
is 255 characters.
properties
The list of properties for a message type or attribute. The max­
imum number of properties per message type is 100.
fieldName
The unique name (or ID) of the message type property. Valid
characters are a-z, A-Z, 0-9. No spaces are allowed. The maxi­
mum length is 30 characters.
dataType
The data type of a message type or attribute. Currently sup­
ported data types are STRING, INTEGER, DECIMAL,
BOOLEAN, DATETIME, TIMESTAMP, DATE, JSON.
fieldLength
The field length of a message type or attribute. This field is op­
tional. The value should be an integer value of 1 or greater.
uom
The unit of measure for message type properties
The following is a sample JSON containing the SAP Connected Goods data model for creating a device type.
{
"deviceCategoryId": "coffeemakers",
"deviceCategoryDescription": "Coffee Makers",
"deviceTypesReqList": [{
"imageId": "http://www.cdn.coffeemakers.com/images/img001.jpg",
"deviceTypeId": "Coffee_Maker",
"description": "Coffee Maker",
"deviceMessageTypes": [{
"basicData": false,
"id": "Coffeemaker_Measures",
"description": "",
"properties": [{
"dataType": "STRING",
"displayName": "coffeeType",
"fieldLength": 20,
"fieldName": "Coffee Type"
}, {
"dataType": "INTEGER",
"displayName": "Brew Temperature",
"fieldName": "brewTemperature",
"uom": "F"
}, {
"dataType": "DECIMAL",
"displayName": "connectivity",
"fieldName": "Connectivity"
}
]
},
{
"basicData": true,
"id": "Coffeemaker_Attributes>",
"description": "",
"properties": [{
"dataType": "STRING",
"displayName": "Serial Number",
"fieldName": "serialNumber"
}, {
"dataType": "INTEGER",
SAP Connected Goods Implementation Guide
Defining a Thing Model
PUBLIC
21
}
]
}
]
}
]
}
"displayName": "Model Number",
"fieldName": "modelNumber"
6.1.2 Deleting a Device Type
You delete a device type by omitting it from the device types list in the same PUT request described in the previous
topic. The JSON file should contain the package name and the list of device types that should remain. Any device
type not specified here may be deleted.
Note
The device type can be deleted only if no devices have been onboarded for that device type.
The following is a sample JSON for deleting all device types for a device category.
{
}
"deviceCategoryId": "coffeemakers",
"deviceCategoryDescription": "",
"deviceTypesReqList": []
6.1.3 Defining Onboarding Fields for a Device Type
Define optional and required custom attributes for a device type.
Prerequisites
You have created device types by uploading a JSON file.
Context
The custom attributes you define will be displayed for selection when you onboard devices of this type. For
example, you might add attributes such as deviceMaterialId and deviceSerialNumber and select them as required
fields.
22
PUBLIC
SAP Connected Goods Implementation Guide
Defining a Thing Model
Procedure
1. In the launchpad, choose the Device Types tile.
2. On the Device Types page, choose Edit.
3. The Basic Data for Onboarding displays all the fields for this device type, as determined by the JSON file you
uploaded. Do the following:
a. Choose Visible for all attributes that should be displayed as optional when onboarding a device of this
type.
b. Choose Mandatory for all attributes that should be displayed as required when onboarding a device of this
type. (Visible will be automatically selected.)
4. Save your changes.
When onboarding a device in the UI, you will have the option to display the selected fields for devices of this
type. For more information, see Onboarding Devices [page 28].
SAP Connected Goods Implementation Guide
Defining a Thing Model
PUBLIC
23
7
Using IOT Services 4.0 to Create a
Connectivity Channel
7.1
REST API for Managing IOT Services 4.0 Information in
Connected Goods Secure Store
This section has the following prerequisites:
● An IOT Services 4.0 account has been created in HCP and a technical user has access to this account.
● The user is familiar with the steps required to obtain the CSRF Token.
● A capability and sensor type exist in IoT Services. These IoT Services entities correspond to an SAP
Connected Goods device message type and device type. The entities are created manually via services offered
by IoT Services, independent of the SAP Connected Goods application.
● All device types in SAP Connected Goods must be mapped to existing capabilities and sensor types in IoT
Services. For information about mapping, see Mapping Connected Goods Entities to IoT Services Entities
[page 26] .
SAP Connected Goods provides a REST API which enables an Admin user to configure the information required
for the IOT Services 4.0 integration. This includes a flag which can be used to enable or disable the use of IOT
Services 4.0 in SAP Connected Goods.
The information is stored in the HANA Secure Store used by SAP Connected Goods. For details about storing this
information, see Configuring IOT Services 4.0 Information [page 25].
For information about deleting a value, see Deleting IOT Services 4.0 Information from the Connected Goods
Secure Store [page 26]. Postman (or any other REST client) can be used to make the HTTP requests.
The following table provides the list of items that are currently required for the configuration of IOT Services 4.0 in
Connected Goods.
Property
Description
dms_hostname
The hostname for the HCP IOT Services 4.0 server instance
client_id
The user name of the technical user used for IOT Services 4.0
client_secret
The password of the technical user used for IOT Services 4.0
register_device
The flag that is used to enable and disable the integration with IOT Services 4.0.
Devices will be registered in IOT Services 4.0 only if the register_device flag is set to
true. If not, the devices will only be created in the CnG database.
24
PUBLIC
SAP Connected Goods Implementation Guide
Using IOT Services 4.0 to Create a Connectivity Channel
Note
After devices have been created, changing the register_device flag is not recommended, since this can
cause inconsistencies between IOT Services 4.0 and CnG.
7.2
Configuring IOT Services 4.0 Information
Procedure
Configure the settings required for IOT Services 4.0 by making a POST request containing a JSON array. The array
can contain one or more settings, as shown in the example below. The response body will show the status for each
element in the array.
Request:
POST https://<sample.cng.sap.hana.ondemand.com>/devicemetadata/securestore
Content-Type: application/json
X-CSRF-Token: <abcd0123456789>
[
{
"key": "dms_hostname",
"value": "<dms.iotservices.us1.hana.ondemand.com>"
},
{
"key": "client_id",
"value": "<P123467890>"
},
{
"key": "client_secret",
"value": "<Welcome1>"
},
{
"key": "register_device",
"value": "<true>"
}
]
Response:
HTTP Status: 201
{
"0": "OK",
"1": "OK",
"2": "OK",
"3": "OK"
}
SAP Connected Goods Implementation Guide
Using IOT Services 4.0 to Create a Connectivity Channel
PUBLIC
25
7.3
Deleting IOT Services 4.0 Information from the
Connected Goods Secure Store
Procedure
Delete IOT Services 4.0 settings by making the following DELETE request with the name (key) of the setting as a
path parameter.
Request:
DELETE https://<sample.cng.cfapps.sap.hana.ondemand.com>/devicemetadata/securestore/
<key>
X-CSRF-Token: <abcd0123456789>
Response:
HTTP Status: 204
7.4
Mapping Connected Goods Entities to IoT Services
Entities
Prerequisites
A capability and a sensor type have been created in the IoT Services system. This system must be defined using
the value dms_hostname, as described in Configuring IOT Services 4.0 Information [page 25].
Context
This procedure maps an SAP Connected Goods device type to an existing IoT Services sensor type and maps a
message type of the device type to the existing IoT Services capability of the sensor type.
26
PUBLIC
SAP Connected Goods Implementation Guide
Using IOT Services 4.0 to Create a Connectivity Channel
Procedure
1. In the launchpad, choose the Device Types tile.
2. Choose the ID link for a device type to open its Details page.
3. Choose the Map to IoT Service link.
Note
This link is not displayed if IoT Service integration is disabled.
4. In the Map to IoT Service window, do the following
a. From the first drop-down list, select the IoT Services entity you want to map to a device type.
b. From the second drop-down list, select the capability to which to map to a message type.
c. Choose Mapping.
SAP Connected Goods Implementation Guide
Using IOT Services 4.0 to Create a Connectivity Channel
PUBLIC
27
8
Onboarding Devices
8.1
Onboarding Devices in the UI
8.1.1 Onboarding a Single Device
Context
Note
Once onboarded, devices cannot be modified or deleted.
Procedure
1. In the launchpad, under Administration, choose the Device Onboarding tile.
2. Choose Onboard a Device.
3. In the Onboard a Device window, under Select Device Type, choose the Category and the Device Type to
onboard and choose Next.
4. In the Onboard a Device window, under Enter Device Details, do the following:
a. In the ID field, enter a string value which can be used to uniquely identify the device.
b. You see the custom attributes that were defined for this device type during device type setup. Enter values
for all required fields (marked with a red asterisk) and for any optional fields you want to display for this
device.
c. If IoT Services 4.0 integration has been enabled, the Gateway field is displayed. Select an IoT Services
Gateway from the list.
d. Choose Onboard.
Note
If IoT Services 4.0 Integration has been enabled, when a device is onboarded in SAP Connected Goods, a
new IoT Services 4.0 device is also created in the system specified in the value of the key dms_host in the
SAP Connected Goods Secure Store. This IoT Services 4.0 device is created with a gatewayId attribute
that corresponds to the Gateway field selected in the Onboard a Device window under Enter Device Details.
28
PUBLIC
SAP Connected Goods Implementation Guide
Onboarding Devices
You see the new device in the devices list. The system automatically attempts to geomatch the device and
assign its location. If the automatic geomatching is unsuccessful, you can manually assign the device to a
location on its Details page.
8.1.2 Onboarding Multiple Devices
Procedure
1. In the launchpad, under Administration, choose the Device Onboarding tile.
2. Choose Mass Onboard Devices.
3. In the Mass Onboard Devices window, under Select Device Type, choose a category and a device type and
choose Next.
4. In the Mass Onboard Devices window, under Download Template, choose Download Template.
5. Open the template and enter the following information:
Column
Description
ID
Enter a unique identifier for the device.
Device Category
Optionally, enter the device category.
Device Type
Optionally, enter the device type.
Device Type GUID
Enter the device type GUID.
The template also displays columns for the custom attributes that were defined for this device type during
device type setup. Enter values for all required fields (marked with an asterisk) and for any optional fields you
want to display for this device.
Note
If IoT Services 4.0 integration has been enabled, the IoT Services Device Gateway ID column is displayed in
the template and is mandatory.
6. Save the template file locally.
7. In the Mass Onboard Devices window, under Upload Data, browse to and select the template you saved.
8. Choose Onboard.
You see the new devices in the devices list.
SAP Connected Goods Implementation Guide
Onboarding Devices
PUBLIC
29
8.2
Onboarding Devices Using the REST API
As an alternative to the Device Onboarding feature, you can onboard devices in SAP Connected Goods by making a
POST request to the REST API directly. The API supports single device onboarding, and multiple device onboarding
using an Excel sheet.
The devices will also be registered in IOT Services 4.0, if the configuration has been set up correctly, and if the
register_device_type and register_device flags are both set to true. If not, the devices will only be saved
in the SAP Connected Goods database. For more information on how to configure IOT Services 4.0, see
Configuring IOT Services 4.0 Information [page 25].
Note
The API uses Basic Authentication, and the user should have the DeviceOnboard scope assigned.
8.2.1 Single Device Onboarding API
You can onboard a device in SAP Connected Goods by making a POST request as specified in the example below.
Device Id and Device Type GUID are mandatory and cannot be null. In addition to these, any custom attributes for
the given Device Type that are marked as mandatory must be provided. All custom attributes should be specified
in the data section of the JSON.
The following table describes some key attributes of the JSON payload.
Property
Description
deviceId
The unique identifier for the device. This should be a string
value which can have a maximum length of 255 characters.
deviceTypeGuid
The GUID for the device type of the device.
data
Should contain the key, value pairs for any visible or manda­
tory custom attributes.
The following table describes some key attributes of the response JSON.
Property
Description
status
The onboarding status, which will be either success or
error.
deviceGUID
The GUID for the device, if successfully onboarded.
errorCode
The error code indicating the cause of failure.
errors
A list containing error messages.
30
PUBLIC
SAP Connected Goods Implementation Guide
Onboarding Devices
Sample Request
Posting Instructions
POST https://<sample.cng.sap.hana.ondemand.com>/ConnectedGoods/v1/OnboardDevice/
createdevice
Content-Type: application/json
Authorization: Basic Abcd1234=
{
"deviceId": "COFFEEMAKER-001",
"deviceTypeGuid": "fda57c02cec77f09b",
"data": {
"modelNumber": 1001,
"serialNumber": "CFM0001"
}
}
Sample Responses
Sample success message:
HTTP Status: 201
{
"status": "success",
"deviceGUID": "00a240a1-ce8d-48ea-9593-1a4a98efb2ee",
"errorCode": null,
"errors": []
}
Sample error messages:
HTTP Status: 400
{
"status": "error",
"deviceGUID": null,
"errorCode": "1002",
"errors": [
"Device Id already exists"
]
}
HTTP Status: 400
{
"status": "error",
"deviceGUID": null,
"errorCode": "1007",
"errors": [
"Mandatory attribute not found - serialNumber",
"serialNumber"
]
}
SAP Connected Goods Implementation Guide
Onboarding Devices
PUBLIC
31
8.2.2 Multiple Device Onboarding
8.2.2.1
Multiple Device Onboarding API
Multiple devices can be onboarded by uploading an Excel sheet from the Device Onboarding page. Alternatively, a
POST request can be made to the REST API as specified below. The Excel sheet should be specified in a form
element called file. The URL should contain the device type GUID as a path parameter.
The response JSON file will contain an overall status for the batch of devices, and information on how many
devices were successfully onboarded and how many failed. The following table describes some key attributes of
the response JSON.
Property
Description
status
The overall status for the upload, which can be one of four val­
ues:
●
none – Indicates no devices onboarded, no failures
●
failed – Onboarding failed for all devices
●
partial success – Onboarding failed for at least 1
●
success – Onboarding successful for all devices
device
onboarded
The number of devices (rows) successfully onboarded.
notOnboarded
The number of devices (rows) that failed to onboard.
unsuccessfulRows
The list of unsuccessful rows, if any.
errorCode
The error code indicating the overall cause of failure.
errors
A list containing error messages for each row that was unsuc­
cessful.
Sample Excel upload request using POSTMAN:
32
PUBLIC
SAP Connected Goods Implementation Guide
Onboarding Devices
Sample Request
POST https://sample.cng.sap.hana.ondemand.com/ConnectedGoods/v1/MassOnboard/
<deviceTypeGUID>
Authorization: Basic Abcd1234=
file=devices.xlsx
Sample Responses
Sample success message:
HTTP Status: 201
{
"status": "success",
"onboarded": 50,
"notOnboarded": 0,
"unsuccessfulRows": [],
"errorCode": null,
"errors": []
}
Sample error messages:
HTTP Status: 400
{
"status": "error",
"onboarded": 0,
"notOnboarded": 0,
"unsuccessfulRows": [],
"errorCode": "1012",
"errors": [
"Error during Mass Device Onboarding - Invalid header name for column #5",
"Invalid header name for column #5"
]
}
HTTP Status: 201
{
"status": " partial success",
"onboarded": 45,
"notOnboarded": 5,
"unsuccessfulRows": [4, 5, 6, 8, 11],
"errorCode": null,
"errors": [
"4: Device Id already exists",
"5: Mandatory attribute cannot be null - serialNumber",
"6: No Device Id specified",
"8: DeviceTypeGUID is null",
"11: Error while calling IOT Services - 409 Conflict"
]
}
HTTP Status: 200
{
"status": "none",
"onboarded": 0,
"notOnboarded": 0,
SAP Connected Goods Implementation Guide
Onboarding Devices
PUBLIC
33
}
34
"unsuccessfulRows": [],
"errorCode": null,
"errors": []
PUBLIC
SAP Connected Goods Implementation Guide
Onboarding Devices
9
Working With Master Data Tables
9.1
Creating Master Data Tables
Create the master data tables you identified during the Discovery process.
Prerequisites
Perform the following initial steps before creating master data tables:
1. Install the Postman Interceptor plugin in the browser and enable it.
2. Log into SAP Connected Goods.
3. In Postman, write and execute (send) the following method:
Method: GET
https://iot-dev.sb-iot-sap.cfapps.sap.hana.ondemand.com
Header: X-CSRF-Token: Fetch
4. The execution of the method in Step 3 will return a value for the token X-CSRF-Token for this Postman
session. Make a note of this value. You will use it for this Postman session to create tables and insert metadata.
Context
This procedure will use the coffeemaker scenario to demonstrate how to create master data tables. This scenario
requires the following custom master data tables:
Master Data Table
Database Table Name
Region
REGION
Coffee Type
COFFEE_TYPE
Coffee Drink
COFFEE_DRINK
Coffee Brand
COFFEE_BRAND
Coffee Quality Standards
COFFEE_STANDARDS
SAP Connected Goods Implementation Guide
Working With Master Data Tables
PUBLIC
35
Note
In the following procedure, < X-CSRF-Token> will represent the token value that was returned from executing
the Fetch command above. It should be replaced with the actual value.
Procedure
1. Create the Region table by executing the following script in Postman:
https://<sample.cng.sap.hana.ondemand.com>/masterdata/type/
Header: X-CSRF-Token: <Value of X-CSRF-Token>
Body:
{
"name":"REGION", "fields":
[{"fieldName":"regionid","isKey":"true", "dataType":"STRING","length":
30,"displayName":"Region ID"},
{"fieldName":"region", "dataType":"STRING","length":
20,"displayName":"Region"}
]
}
The Region table contains the following columns:
Field Name
Is Key
Data Type
Length
Display Name
regionid
True
INTEGER
30
Region ID
region
False
STRING
20
Region
2. Create the Coffee Type table by executing the following script in Postman:
https://<sample.cng.sap.hana.ondemand.com>/masterdata/type/
Header: X-CSRF-Token: <Value of X-CSRF-Token>
Body:
{
"name":"COFFEE_TYPE", "fields":
[{"fieldName":"coffetypeid","isKey":"true", "dataType":"INTEGER","length":
30,"displayName":"Type ID"},
{"fieldName":" coffetype", "dataType":"STRING","length":
20,"displayName":"Coffee Type"}
]
}
The Coffee Type table contains the following columns:
36
Field Name
Is Key
Data Type
Length
Display Name
coffeetypeId
True
INTEGER
30
Coffee Type ID
coffeetype
False
STRING
20
Coffee Type
PUBLIC
SAP Connected Goods Implementation Guide
Working With Master Data Tables
3. Create the Coffee Drink table by executing the following script in Postman:
https://<sample.cng.sap.hana.ondemand.com>/masterdata/type/
Header: X-CSRF-Token: <Value of X-CSRF-Token>
Body:
{
"name":"COFFEE_DRINK", "fields":
[{"fieldName":" coffeedrinkeId","isKey":"true", "dataType":"INTEGER","length":
30,"displayName":"Drink ID"},
{"fieldName":" coffeedrinkeId", "dataType":"STRING","length":
20,"displayName":"Coffee Drink"}
]
}
The Coffee Drink table contains the following columns:
Field Name
Is Key
Data Type
Length
Display Name
coffeedrinkId
True
INTEGER
30
Coffee Drink ID
coffeedrink
False
STRING
20
Coffee Drink
4. Create the Coffee Brand table by executing the following script in Postman:
https://<sample.cng.sap.hana.ondemand.com>/masterdata/type/
Header: X-CSRF-Token: <Value of X-CSRF-Token>
Body:
{
"name":"COFFEE_BRAND", "fields":
[{"fieldName":" coffeebrandid ","isKey":"true", "dataType":"INTEGER","length":
30,"displayName":"Brand ID"},
{"fieldName":" coffeebrand ", "dataType":"STRING","length":
20,"displayName":"Coffee Brand "}
]
}
The Coffee Brand table contains the following columns:
Field Name
Is Key
Data Type
Length
Display Name
coffeebrandId
True
INTEGER
30
Coffee Brand ID
coffeebrand
False
STRING
20
Coffee Brand
5. Create the Coffee Quality Standards table by executing the following script in Postman:
https://iot-dev.sb-iot-sap.hana.ondemand.com/masterdata/masterdata/
create_masterdata_type
Header: X-CSRF-Token: <Value of X-CSRF-Token>
Body:
{
"name":"COFFEE_STANDARDS", "fields":
[{"fieldName":" coffeebrandid ","isKey":"true", "dataType":"INTEGER","length":
30,"displayName":"Standard ID"},
{"fieldName":" brewtemperature ", "dataType":" INTEGER","length":
20,"displayName":"Brew Temperature"},
{"fieldName":" frequency ", "dataType":" INTEGER","length":
20,"displayName":" Cleaning Frequency"}
SAP Connected Goods Implementation Guide
Working With Master Data Tables
PUBLIC
37
}
]
The Coffee Quality Standards table contains the following columns:
Field Name
Is Key
Data Type
Length
Display Name
standardid
True
INTEGER
30
Quality Standard ID
brewtemperature
False
STRING
20
Brew Temperature
frequency
False
STRING
20
Cleaning Frequency
9.2
Importing Data into Master Data Tables
Import master data into the tables you created.
Prerequisites
As with the previous procedure, perform the following initial steps before importing master data:
1. Log into SAP Connected Goods.
2. In Postman, write and execute (send) the following method:
Method: GET
https://iot-dev.sb-iot-sap.cfapps.sap.hana.ondemand.com
Header: X-CSRF-Token: Fetch
3. The execution of the method in Step 2 will return a value for the token X-CSRF-Token for this Postman
session. Make a note of this value. You will use it for this Postman session to create tables and insert metadata.
Context
In the previous procedure, you created the following custom master data tables for the coffeemaker scenario:
Master Data Table
Database Table Name
Region
REGION
Coffee Type
COFFEE_TYPE
Coffee Drink
COFFEE_DRINK
Coffee Brand
COFFEE_BRAND
Coffee Quality Standards
COFFEE_STANDARDS
38
PUBLIC
SAP Connected Goods Implementation Guide
Working With Master Data Tables
Note
In the following procedure, < X-CSRF-Token> will represent the token value that was returned from executing
the Fetch command above. It should be replaced with the actual value.
Procedure
1. Add master data to the Region table by executing the following script in Postman. (The table name is included
at the end of the URL.)
http://<sample.cng.sap.hana.ondemand.com>/masterdata/data/REGION
Header: X-CSRF-Token: <Value of X-CSRF-Token>
Body:
[
{ "regionid":"1001", "region":"West”},
{ "regionid":"1002", "region":”East”},
{ "regionid":"1003", "region":"Midwest”},
{ "regionid":"1004", "region":"South”}
]
2. Add master data to the Coffee Type table by executing the following script in Postman. (The table name is
included at the end of the URL.)
https://<sample.cng.sap.hana.ondemand.com>/masterdata/data/COFFEE_TYPE
Header: X-CSRF-Token: <Value of X-CSRF-Token>
Body:
[
{ "coffeetypeid":"1101", "coffeetype":"Regular”},
{ "coffeetypeid":"1102", "coffeetype":"Decaf”},
]
3. Add master data to the Coffee Drink table by executing the following script in Postman. (The table name is
included at the end of the URL.)
https://<sample.cng.sap.hana.ondemand.com>/masterdata/data/COFFEE_DRINK
Header: X-CSRF-Token: <Value of X-CSRF-Token>
Body:
[
{ "coffeedrinkid":"1301", "coffeedrink":"Cappuccino”},
{ "coffeedrinkid ":"1302", "coffeedrink":"Latte”},
{ "coffeedrinkid ":"1303", "coffeedrink":"Coffee”}
]
4. Add master data to the Coffee Brand table by executing the following script in Postman. (The table name is
included at the end of the URL.)
https://<sample.cng.sap.hana.ondemand.com>/masterdata/data/COFFEE_BRAND
Header: X-CSRF-Token: <Value of X-CSRF-Token>
Body:
[
{ "coffeebrandid":"1501", "coffeebrand":"Manhattan Special”},
{ "coffeebrandid":"1502", "coffeebrand":"Mr Brown Coffee”},
{ "coffeebrandid":"1503", "coffeebrand":"Coffee Delight”},
{ "coffeebrandid":"1504", "coffeebrand":"Turkish Coffee House”},
SAP Connected Goods Implementation Guide
Working With Master Data Tables
PUBLIC
39
{ "coffeebrandid":"1505", "coffeebrand":"Costa Cofee”}
]
5. Add master data to the Coffee Quality Standards table by executing the following script in Postman. (The table
name is included at the end of the URL.)
https://<sample.cng.sap.hana.ondemand.com>/masterdata/data/COFFEE_STANDARDS
Header: X-CSRF-Token: <Value of X-CSRF-Token>
Body:
[
{ "standardid":"1701", "brewtemperature":80, “frequency”:10},
{ "standardid":"1702", "brewtemperature":85, “frequency”:12},
{ "standardid":"1703", "brewtemperature":90, “frequency”:15}
]
9.3
Importing Master Data Using an Excel File
9.3.1 Downloading the Master Data Excel Template
Context
You can also upload master data using an Excel file. A template for BULK Excel creation of master data records can
be downloaded by making a GET request as follows. Key fields are marked with a star appended to the column
header.
Procedure
Make the following GET request:
Request:
GET https://<sample.cng.sap.hana.ondemand.com>/masterdata/data/excel/
{masterDataTypeName}/
Accept: application/ms-excel
X-CSRF-Token: <abcd0123456789>
Response:
HTTP Status: 200 – Body: Excel template file
40
PUBLIC
SAP Connected Goods Implementation Guide
Working With Master Data Tables
9.3.2 Uploading Master Data with an Excel File
Context
An Excel file can be uploaded via a POST request. If a record for a given key is already present, the record will be
updated.
Procedure
Make the following POST request:
Request:
POST https://<sample.cng.sap.hana.ondemand.com>/masterdata/data/excel/
{masterDataTypeName}/
Content-Type: application/ms-excel
X-CSRF-Token: <abcd0123456789>
Request-Body(form-data):
file="<excelFile>”
Response:
HTTP Status: 200 – Body: Excel template file
9.3.3 Updating Master Data Records
Context
Updating master data types is not supported, but you can update master data records by making a PUT request as
follows. The master data type as URL parameter and the key column value for every JSON Object of the master
data type are mandatory. All non-key columns present in the call will be updated. Note that this call is made in
BULK, so an array must be at the root of the request body.
Procedure
Make the following PUT request:
Request:
PUT https://<sample.cng.sap.hana.ondemand.com>/masterdata/data/{masterDataTypeName}/
Content-Type: application/json
X-CSRF-Token: <abcd0123456789>
SAP Connected Goods Implementation Guide
Working With Master Data Tables
PUBLIC
41
Request-Body:
[
{
"<vendorName>":"<vendorNameValue>",
"<vendorID>":"<vendorIDValue>",
[other structure properties]
},
[other instances of your structure]
]
Response:
HTTP Status: 201 – Message: Success
9.4
Deleting Master Data Tables
Delete a custom master data table and data.
Procedure
1. Delete a custom master data table making a DELETE request as Follows. The master data type name must be
given present when making the call.
Request:
DELETE https://<sample.cng.sap.hana.ondemand.com>/masterdata/type/
{masterDataTypeName}/
X-CSRF-Token: <abcd0123456789>
Response:
HTTP Status: 201 -Body: Success
2. Delete custom master data by making a DELETE request as follows. The master data type and the key column
value for every JSON Object of the master data type are mandatory when making this call. This call is made in
BULK, so an array must be at the root of the request body.
Request:
DELETE https://<sample.cng.sap.hana.ondemand.com>/masterdata/data/
{masterDataTypeName}/
Content-Type: application/json
X-CSRF-Token: <abcd0123456789>
Request-Body:
[
{
"<vendorID>":"<vendorIDValue>",
{
},
}
…
[other JSON Objects with associated structure keys]
]
Response:
HTTP Status: 201 – Message: Success
42
PUBLIC
SAP Connected Goods Implementation Guide
Working With Master Data Tables
9.5
Extending Master Data
Context
You can extend existing master data tables and create new tables for master data objects that are not provided
with the tenant.
All master data fields can be accessed by all run-time components and can be presented in the UI or used as visual
filters. You can use the same master data object (for example, Business Partner) for multiple device categories and
device types.
You extend master data as follows:
● Invoke the master data API to enhance the existing master data.
● Generate the Semantic Model to consider the extended attributes.
● Create visualizations to use the attributes for modeling in the UI.
The following steps use the example of extending BUSINESS_PARTNER master data with the master data API.
Procedure
Update the Master Data Type
1. Add columns: Add new columns to the existing master data using the following method.
URL:
PUT /masterdata/type/BUSINESS_PARTNER
Request:
Body:
{
"action":"ADD_COLUMNS",
"fields":
[
{"fieldName":"regionId","dataType":"STRING","length":
30,"displayName":"Region Id"},
{"fieldName":"regionName", "dataType":"STRING","length":
20,"displayName":"Region Name"}
]
}
Response:
HTTP status code: 200 OK
Success!!
Exceptions - Internal Server Error/500
1. Masterdatype does not exist
2. Invalid Request
2. Update columns: Modify the newly added columns' data type, length, and so on, using the following method.
SAP Connected Goods Implementation Guide
Working With Master Data Tables
PUBLIC
43
URL:
PUT /masterdata/type/BUSINESS_PARTNER
Request:
Body:
{
"action":"UPDATE_COLUMNS",
"fields":
[
{"fieldName":"regionId","dataType":"STRING","length":
30,"displayName":"Region Id"},
{"fieldName":"regionName", "dataType":"STRING","length":
20,"displayName":"Region Name"}
]
}
Response:
HTTP status code: 200 OK
Success!!
Exceptions - Internal Server Error/500
1. Masterdatype does not exist
2. Mapped table is not empty
3. Invalid Request
3. Delete columns: Delete the newly added columns, if they are not relevant, using the following method.
URL:
PUT /masterdata/type/BUSINESS_PARTNER
Request:
Request:
Body:
{
"action":"DELETE_COLUMNS",
"fields":
[
{"fieldName":"regionId","dataType":"STRING","length":
30,"displayName":"Region Id"},
{"fieldName":"regionName", "dataType":"STRING","length":
20,"displayName":"Region Name"}
]
}
Response:
HTTP status code: 200 OK
Success!!
Exceptions - Internal Server Error/500
1. Masterdatype does not exist
2. Mapped table is not empty
3. Invalid Request
Generate the Semantic Model
4. In the launchpad, choose the Semantics Model tile.
5. On the Semantics Model page, choose Generate.
The newly added attributes are not displayed in the list, but the generation will add the attributes to the views.
Configure the Visualization
44
PUBLIC
SAP Connected Goods Implementation Guide
Working With Master Data Tables
6. The newly added attribute is available for visualization, where you can configure it as part of a visual filter to
table_columns as needed. For details, see Defining Visual Filters [page 58]
SAP Connected Goods Implementation Guide
Working With Master Data Tables
PUBLIC
45
10 Semantic Modeling
Semantic model data includes the following. Use this information as a guide for your semantic model.
Semantic Types
Five semantic types are defined as part of the SAP Connected Goods application. These values define the property
type.
Type
Description
Generic Latitude
Use this semantic type if you have any latitude properties in
the message or device.
Generic Longitude
Use this semantic type if you have any longitude properties in
the message or device.
Generic Temperature
Use this semantic type if you have any temperature properties
in the message or device.
Generic Measure
Use this type if any device or message properties are number
fields, including integer, decimal and float fields.
Generic Attribute
Use this type if any device or message properties are string
fields.
Aggregations
By default, the aggregation is provided based on the data type of the property:
● Most device properties will be mapped to the Generic Attribute semantic type.
● Most device data properties will be mapped to the Generic Measure semantic type.
You can also change this mapping based on the data type of the property.
Aggregations include:
● SUM
● MAX
● MIN
● COUNT
● AVG
● LATEST
For a device data property of a semantic type other than Generic Measure, you must choose LATEST for the
aggregation, since this will create the Group by field. If you choose a different type, you will see an error.
For a measure, you must choose at least one aggregation.
You can define multiple aggregations for a property.
UI Label
46
PUBLIC
SAP Connected Goods Implementation Guide
Semantic Modeling
This is the display label for the user interface. Any text you enter here is displayed in the user interface at run time.
For example, for a TEMPERATURE field whose UI label is Temperature, you might change the label to MyTemp.
Based on the aggregations you select, at run time it will be displayed as Avg MyTemp, Sum MyTemp, etc.
Field Length
This is the display field length for the UI, in characters. For example, if Avg Temperature is the value that is
populated in a table, this field specifies the length to be displayed based on the data. A Field Length value of 8
indicates that 8 characters will be displayed on the UI.
Table Name
This is the table reference that is internally mapped for the property. Options include:
● DEVICE
● DEVICE_DATA
● MDT_TABLE1 through MDT_TABLE5 (these tables refer to the new master data being added)
10.1 Setting up the Semantic Model
Prerequisites
Before setting up your semantic model, do the following:
● Set up an AE model to generate a JSON file.
● Upload this JSON file to the SAP Connected Goods system. You will use the uploaded device properties and
message properties (KPIs, etc.) for reference.
For more information, see Defining a Thing Model [page 17].
Context
This semantic model example will follow the scenario of a cooler.
Procedure
Sync and Verify Mappings
1. In the launchpad, choose the Semantics Model tile.
2. On the Semantics Model page, choose Sync.
All uploaded properties are displayed in the semantic model table. All device properties are displayed in the
Device table. All message properties are displayed in the Device Data table.
SAP Connected Goods Implementation Guide
Semantic Modeling
PUBLIC
47
An asterisk indicates a new property that requires some action on your part.
3. Choose Edit.
4. Verify that every entry in the table is mapped to the appropriate semantic type, changing the default mapping
if needed. By default, the aggregations provided are AVG and LATEST.
5. Save your changes.
Include Master Data
6. To include master data in the semantic model, choose Master Data.
A new table is created below the External Fields mapping table. All master data tables that have been uploaded
are displayed.
7. Map each master data record to either the DEVICE or DEVICE_DATA table and choose an appropriate column
mapping, as follows:
a. Choose Edit in the Master Data table.
b. In the Attribute Value field, select the attribute of the master data record.
c. Select Assign to Device or Assign to Device Data.
d. Select the column in the list to map to.
Note
You can only map an attribute to a device or device data type that is compatible with it. For example, an
integer attribute such as Material ID can only be mapped to an integer field such as D_INT_ or
DD_INT_. A string attribute can be mapped only to string fields such as D_STR or DD_STR.
e. For Join Type, choose rightouter.
f. For Cardinality, choose 1:1.
g. Choose the Delete icon for any empty rows in the Master Data table.
h. Save your changes to the table.
For example, for an onboarded device with the property vendorID, this property will be included in the
Device columns. When the Vendor master data is brought into the system, if the primary key of the Vendor
table is vID, map the Vendor table - vID column to the Device table - vendorID column. Since the join is
always on the master data, it will be a rightouter join with cardinality 1:1.
All the master data attributes are added to the semantic model table. (For this example, you would see
data such as vID, vendor_description, and vendor_name added to the table.) Most of this data will be
assigned to the Generic Attribute semantic type. You can change these mappings as needed.
8. Choose Save again to complete the master data changes.
Check the mappings carefully if you expect the data to be visible. Data must be uploaded to the Master Data
table and the corresponding column in the Device/Device Data must contain a value in order for the join to
occur.
Additionally, it is recommended that you map to a column that is the primary key of the master data, in order
to avoid repeated records, and to produce properly aggregated values in the UI.
Add a Calculation
9. Optionally, model a new calculation in the system as follows:
a. Choose Add Calculation.
b. Enter the Field Name.
c. Select either Generic Attribute or Generic Measure for the Semantic Type.
d. Select the Aggregation.
48
PUBLIC
SAP Connected Goods Implementation Guide
Semantic Modeling
e. Select the Data Type.
f. Specify the Formula to be applied and choose Add. Change the description if required and save your
changes in the table.
The formula must be in HANA SQL­specific format. If you are adding a column, do so with any of the
aggregation names.
For example, you might want to find a whole number on a decimal column such as Pressure. The formula
will be based on the aggregation, so if you have selected AVG as an aggregation for the dynamic field
Pressure, the formula will be: “AVG_PRESSURE” * 100
You can also create your own formulas, but this may introduce errors that cause the generation to fail. It is
recommended to generate the semantic model for the first time without any formulas in place. After
generation is successful, add a formula and try again.
Note that the calculation does not support attribute-based calculations. Add only measure-based
calculations and ensure that the Data Type is not nvarchar.
Examples of calculations are as follows.
The values in quotes are the fields to be generated. For example, if TEMPERATURE is the field and the
aggregation is AVG, AVG_TEMPERATURE will be included in the formula in quotes. Give each formula a
unique name.
○ For DOOR_OPEN_CLOSE_RATIO, the aggregation is AVG and the formula is:
"AVG_DOOR_OPEN_COUNT"/case when "AVG_DOOR_CLOSE_COUNT" = 0 then null else
"AVG_DOOR_CLOSE_COUNT" end
○ For DOOR_OPEN_TIME_RATIO, the aggregation is AVG and the formula is:
"AVG_DOOR_OPEN_TIME"/case when "AVG_DOOR_OPEN_COUNT" = 0 then null else
"AVG_DOOR_OPEN_COUNT" end
○ For TEMPERATURE_CELSIUS, the aggregation is AVG and the formula is:
("AVG_TEMPERATURE_FAHRENHEIT" - 32) * 5 / 9
○ For TEMP_CELSIUS, the aggregation is LATEST and the formula is:
("LATEST_TEMPERATURE_FAHRENHEIT" - 32) * 5 / 9
○ For INSIDE_TEMPERATURE_CELSIUS, the aggregation is AVG and the formula is:
("AVG_INSIDE_TEMPERATURE_FAHRENHEIT" - 32) * 5 / 9
○ For INSIDE_TEMP_CELSIUS, the aggregation is LATEST and the formula is:
("LATEST_INSIDE_TEMPERATURE_FAHRENHEIT" - 32) * 5 / 9
○ For POWERSTATEON, the aggregation is LATEST and the formula is:
case when "LATEST_POWER_STATE" = 1 then 1 else 0 end
○ For POWERSTATEOFF, the aggregation is LATEST and the formula is:
case when "LATEST_POWER_STATE" = 0 then 1 else 0 end
○ Select Add.
The calculation is added to the semantic model table.
10. To edit a formula, choose the farthest left box in the table to open the dialog box. Delete the formula or edit it
and add it again.
11. Save your changes.
Your changes are saved and a Generate button is displayed.
Generate the Semantic Model
12. Choose Generate.
SAP Connected Goods Implementation Guide
Semantic Modeling
PUBLIC
49
This button triggers generation of the run-time artifacts. The entire scenario of the run-time artifact creation is
performed at this time.
During generation, the system reads all the external field mappings you provided, as well as the aggregation
for each of the fields, and builds a view around them. This view will be consumed later in the run-time UI. If the
generation fails, the run-time UI will not load any of the data.
Note the following to ensure successful generation:
○ There should not be any repeated column names in the semantic modeling table. For example,
TEMPERATURE should not be included twice.
○ It is recommended that you prefix with some variable so that all values are unique.
○ For a Generic Measure, some aggregation must be defined.
○ For a Generic Attribute in the Device Data table, LATEST must be selected as the aggregation.
○ Avoid formulas for first­time modeling. Once you are familiar with the generation process, try creating
formulas.
○ Do not include ADDRESS, BUSINESS_PARTNER and PRODUCT in the master data. These fields are
already included in the static template for processing. However, you can bring in your own master data for
processing.
The specified artifacts are created in the back end to be consumed by the UI. Generation may be immediate,
or may take a minute or two. If the process completes within two minutes, you will see a message indicating
whether generation was successful.
Note
If the response exceeds two minutes, a 502 timeout error will be displayed. However, the process will
continue to run in the background. To view the progress, check the logs of the connected-goodsgeneration application. You can view this either in the console with the Cloud Foundry plugin or in the
HANA Cloud Platform cockpit.
You must map fields correctly to their semantic type to ensure successful generation.
10.1.1 Semantic Model Technical Notes
Inventory View for Vending Scenario
To deploy the Inventory view for the Vending scenario, do the following:
1. Log into SAP Connected Goods.
2. Use Postman with the following URL to fetch the X-CSRF-Token:
Method: GET
https://sample.cng.sap.hana.ondemand.com
Header: X-CSRF-Token: Fetch
3. Use Postman with the X-CSRF-Token and the following URL to generate the Inventory view:
Method: PUT
50
PUBLIC
SAP Connected Goods Implementation Guide
Semantic Modeling
https://sample.cng.sap.hana.ondemand.com/templateview/updatecalcview
Header: X-CSRF-Token: <ABCD12345ABCD>
General Notes
These tables must have templates stored in the GEN_ARTIFACTS table. A copy of this is also located in
generation/mock/templateinserts.sql. This is all handled as part of the CSV deliverable from SAP.
GEN_ARTIFACT_ENTITIES should have the definition of the relationship between the entities and the calculation
views.
If a field is enumerated, the flag must be maintained in the semantic mapping aggregation table and also have
entries in enumeration table.
If any master data is deleted, the GEN_ARTIFACTS_JOIN table must be deleted with the appropriate entries. The
corresponding fields must also be removed from the Semantic Mapping and Semantic Mapping Aggregations
tables. Alternatively, perform a clear/reset with the API.
10.1.2 Example: Creating Measures for KPIs
Context
You can use the semantic model to create measures to be used as the basis for KPIs in a dimension view. For more
information about KPIs, see Key Performance Indicator (KPI) Modeling [page 135]. You can use calculated
measures to nest other calculated measures for use in these KPIs.
The following example demonstrates how to create measures to indicate the percentage of all coolers that are
currently working.
Procedure
1. In the launchpad, choose the Semantics Model tile.
2. Choose Edit.
3. Create a WORKING_COOLERS measure by choosing Add Calculation and entering information as follows:
SAP Connected Goods Implementation Guide
Semantic Modeling
PUBLIC
51
Field
Description
Field Name
WORKING_COOLERS
Semantic Type
Generic Attribute
Aggregation
Choose LATEST to enable this measure to be used in any
other formula or measure.
Data Type
INTEGER
Formula
See example for details. For more information about formu­
las, see Setting up the Semantic Model [page 47].
Aggregation Level
Calculate per Device
4. Create a WORKING_COOLERS_INTERIM measure, to sum up the devices, by choosing Add Calculation and
entering information as follows:
52
PUBLIC
SAP Connected Goods Implementation Guide
Semantic Modeling
Field
Description
Field Name
WORKING_COOLERS_INTERIM
Semantic Type
Generic Attribute
Aggregation
SUM
Data Type
INTEGER
Formula
See example for details. For more information about formu­
las, see Setting up the Semantic Model [page 47].
Aggregation Level
After
5. Create a PERCENT_WORKING_COOLERS measure, to determine the percentage of total coolers that are
working, by choosing Add Calculation and entering information as follows:
SAP Connected Goods Implementation Guide
Semantic Modeling
PUBLIC
53
Field
Description
Field Name
PERCENT_WORKING_COOLERS
Semantic Type
Generic Measure
Aggregation
SUM
Data Type
DOUBLE
Precision
2
Formula
Add a formula that nests the previous measure. See exam­
ple for details. For more information about formulas, see
Setting up the Semantic Model [page 47].
Aggregation Level
After
6. Select Add.
7. Save your changes.
54
PUBLIC
SAP Connected Goods Implementation Guide
Semantic Modeling
10.2 Adding Ingestion Fields to the Semantic Model
Context
For ingestion-related fields, perform a direct entry into the semantic mapping table as follows.
Procedure
1. Run the following SQL in the database to create the entry in semantic model table.
Insert values as follows into sap.iot.scb.cng.md::semantics_model.SEMANTIC_MAPPING:
('SE_10', 'DD_GEN_DEC_1','SM1902', 'INGMEASURE', 'INGESTION',
'sap.iot.scb.cng.md::device_data.DEVICE_DATA','Ingestion Measure', '10');
Value
Description
SE_10
For use with a measure
SE_26
For use with an attribute
DD_GEN_DEC_1
Appropriate field name mappings
SM1902
Any primary key that does not already exist
INGMEASURE
Name of the property that will be used
INGESTION
The type, which must be INGESTION
TableName
For device data, use the above table name. For a device, this
must be changed.
Description and Field Length
Enter a value
2. In the SAP Connected Goods launchpad, choose the Semantics Model tile.
3. Choose Sync.
4. Choose the aggregations for these fields and choose Save.
5. Generate the semantic model.
The fields required for ingestion are generated.
SAP Connected Goods Implementation Guide
Semantic Modeling
PUBLIC
55
10.3 Clearing or Resetting the Semantic Model
You can clear/reset a semantic model that you have created.
Context
You reset the semantic model using an API.
Procedure
1. Load the SAP Connected Goods application in a Google Chrome browser.
2. Choose the Console tab and clear it.
3. Choose the Network and clear it.
4. Return to the Console tab and execute the following command. Copy the entire code snippet for CSRF.
var csrf = function() {
var xmlhttp = new XMLHttpRequest();
xmlhttp.open("GET","/");
xmlhttp.setRequestHeader("Content-type", "application/json");
xmlhttp.setRequestHeader("X-CSRF-Token", "Fetch");
xmlhttp.send();
}
csrf();
5. Go to Network.
6. Choose <tenantname>*.sap.hana.ondemand.com.
7. Choose Headers.
8. In Request Headers, find and copy the CSRF token.
9. Make the following call in the Console tab again, substituting the copied value for X-CSRF-Token.
var clearSemanticModel = function() {
var xmlhttp = new XMLHttpRequest();
xmlhttp.open("POST","/ConnectedGoods/v1/internal/annotations/
deleteSemanticModel");
xmlhttp.setRequestHeader("Content-type", "application/json");
xmlhttp.setRequestHeader("X-CSRF-Token", "");
xmlhttp.send();
}
clearSemanticModel()
10.4 Including Enumerations for the Dynamic Fields
Data from customers may be enumerated; that is, numeric representation of the data can have corresponding
textual names (for example, 1 – On, 0 – Off). This kind of data can apply to many cases. For example, a
56
PUBLIC
SAP Connected Goods Implementation Guide
Semantic Modeling
connectivity type might have a numeric representation from 1-4, with a specification provided for each: 1 –
Analog, 2 – Bluetooth, 3 – Wi-Fi and 4 – Manual. When the device sends data, the value for the connectivity
type is in the integer format, so this entry must be maintained in an enumeration table. This can only be done with
insert statements; it cannot be done in the UI.
For example, if an integer field is enumerated, the field name must have _NV suffixed at the end. If
connectivitytype is the dynamic integer field, the corresponding field name should be
CONNECTIVITYTYPE_NV (all capital letters and suffixed with _NV).
If the enumeration is on an aggregated field such as LATEST, the aggregation should be prefixed as well and stored
in the enumeration table. Typically, if it is from the DEVICE_DATA table, an aggregation will be defined by default.
This aggregation must be added to the field name before doing the insert statement. The is_dynamic column
must contain the value YES.
The following is the syntax for enumeration tables.
insert into "sap.iot.scb.cng.md::enumeration_model.ENUMERATE"
(value, field_name, table_name, language, short_txt, is_dynamic)
values
(1, 'CONNECTIVITYTYPE_NV', 'sap.iot.scb.cng.md::devicedata.DEVICE', 'EN',
'Connected', 'YES');
insert into "sap.iot.scb.cng.md::enumeration_model.ENUMERATE"
(value, field_name, table_name, language, short_txt, is_dynamic)
values
(2, 'CONNECTIVITYTYPE_NV', 'sap.iot.scb.cng.md::devicedata.DEVICE', 'EN',
'Bluetooth', 'YES');
insert into "sap.iot.scb.cng.md::enumeration_model.ENUMERATE"
(value, field_name, table_name, language, short_txt, is_dynamic)
values
(3, 'CONNECTIVITYTYPE_NV', 'sap.iot.scb.cng.md::devicedata.DEVICE', 'EN', 'Baecon',
'YES');
insert into "sap.iot.scb.cng.md::enumeration_model.ENUMERATE"
(value, field_name, table_name, language, short_txt, is_dynamic)
values
(4, 'CONNECTIVITYTYPE_NV', 'sap.iot.scb.cng.md::devicedata.DEVICE', 'EN', 'Analog',
'YES');
insert into "sap.iot.scb.cng.md::enumeration_model.ENUMERATE"
(value, field_name, table_name, language, short_txt, is_dynamic)
values
(1, 'LATEST_POWERSTATE_NV',
'sap.iot.scb.cng.md::devicedata.DEVICE_DATA_LATEST_VALUES', 'EN', 'On', 'YES');
insert into "sap.iot.scb.cng.md::enumeration_model.ENUMERATE"
(value, field_name, table_name, language, short_txt, is_dynamic)
values
(0, 'LATEST_POWERSTATE_NV',
'sap.iot.scb.cng.md::devicedata.DEVICE_DATA_LATEST_VALUES', 'EN', 'Off', 'YES');
Note
Take particular care when calling the clear API. You must delete the enumeration entries manually or the
generation will fail. Run this statement when you clear/reset the API:
delete from "sap.iot.scb.cng.md::enumeration_model.ENUMERATE" where
is_dynamic='YES';
SAP Connected Goods Implementation Guide
Semantic Modeling
PUBLIC
57
11
Defining UI Configurations
You use the Visualization tile to design the UI pages in your SAP Connected Goods implementation.
11.1
Defining Visualization
11.1.1 Defining Visual Filters
Use the Visual Filters tab to define the dimensions you can use to display the filters used on the device pages.
Context
Filters allow users to filter the display of device information. There are three types of visual filters: Donut, Bar and
Line charts.
Procedure
1. In the launchpad, choose the Visualization tile.
58
PUBLIC
SAP Connected Goods Implementation Guide
Defining UI Configurations
2. On the Visual Filters tab, choose a perspective: Device or Location.
3. Choose the device category for which you want to define visual filters from the Device Category drop-down list.
By default, Common is selected.
4. Choose Edit.
5. Choose New Visual Filter.
A new line appears in the Visual Filters table.
6. Enter information as follows:
Column
Description
Dimension
Choose an attribute from the drop-down list. This is the list
of columns created from the semantic model and the mas­
ter data (for example, City, Alert Type, Power State,
Connectivity Type, BP Status, BP Type).
The filter will display the top three values for this attribute. If
there are more than three values, the top two are displayed
and the others are grouped together as Other. (The Other
category cannot be clicked.)
Measure
A read-only field that displays the Count measure of the di­
mension.
Type
Choose a type from the drop-down list: Donut, Bar or Line
chart.
For example, if the chosen dimension is City and the chart
type is Donut, a donut chart will be displayed in the Filter bar
that will contain the top three cities and their respective per­
centages.
Be sure to choose a chart type that is compatible with the
selected dimension.
For a cooler scenario, configure filters as follows:
○ BP Type Text - Donut
○ Latest Power State Text - Donut
○ BP Status Text - Donut
○ Connectivity Type Text - Donut
○ Has Alert Text - Bar
○ Alert Type – Bar
7. Save your changes.
SAP Connected Goods Implementation Guide
Defining UI Configurations
PUBLIC
59
11.1.2 Defining Map Overlays
Use the Map Overlays tab to configure map overlays for the Map view.
Context
Map overlays customize the content displayed on a device map. Users can choose map overlays from an icon on
the Map & Table view.
Procedure
1. In the launchpad, choose the Visualization tile.
2. Choose the Map Overlays tab.
3. Choose the device category for which you want to define map overlays from the Device Category drop-down
list. By default, Common is selected.
4. Choose Edit.
5. Choose New Map Overlay.
A new line appears in the Map Overlays table.
6. Enter information as follows:
Column
Description
Key
Select a measure to be displayed on the icons on the map.
Based on the icon's size, it can display up to 6-8 characters.
For a cooler scenario, select the following: Latest
Temperature Celsius, Avg Door Open Count, Avg Door Open
Time.
60
PUBLIC
SAP Connected Goods Implementation Guide
Defining UI Configurations
Column
Description
Threshold
Enter a value to act as a threshold for the selected key
measure. Values less than or greater than this threshold
(depending on what is chosen as the Threshold
Comparison) are displayed in red on the icons in the map.
Unit
Enter a unit to be appended after the measure in the text
(for example, min or °F).
Precision
Enter the number of decimal points to be displayed in the
value for the selected key.
Threshold Comparison
Choose LT (Less Than) if you want values less than the
value of the measure key to be displayed in red.
Choose GT (Greater Than) if you want values greater than
the value of the measure key to be displayed in red.
Label
Enter the label that will be displayed when this key is se­
lected in the map overlay.
Image URL
Enter the path to the icon image to display in the map over­
lay. The image path is: ../sap/iot/scb/cng/goods/
images/<image_name>.png
Replace <image_name> with the image you want to use.
Image options are: temp, emergencies, month,
opentime, opebvsclose, crm, and weather.
If any other URL value is used, the default icon is displayed.
Do not choose an attribute, since attribute values are too
large to be displayed on the map icons. Additionally, it is typ­
ically not useful to display an attribute value on map icons.
7. Save your changes.
11.1.3 Defining Smart Search and Table Columns
Use the Smart Search and Table Columns tab to specify the fields used for Search and the table columns displayed
for devices.
Context
Smart Search is the search bar displayed above the Filter bar in the Device Overview page. You can specify the
fields that are searched when this feature is used.
You can also specify the columns included in the Devices table in the Table and Map & Table views.
SAP Connected Goods Implementation Guide
Defining UI Configurations
PUBLIC
61
Procedure
1. In the launchpad, choose the Visualization tile.
2. Choose the Smart Search and Table Columns tab.
3. Choose the device category for which you want to define search fields and table columns from the Device
Category drop-down list. By default, Common is selected.
4. Choose Edit.
5. For Smart Search, use the drop-down to select the attributes you want to include in the search feature. These
attributes are derived from the semantic model and master data. Measures cannot be searched and are not
displayed in the list.
If you choose City, Address, Device ID, and Device Serial Number, the search text will be matched to all values
in the selected columns and the search results will display the device ID, device type, and address of the
device.
For a cooler scenario, select the following: Address, Device Type Description, Device ID, City, Country, Product
ID Description.
6. For Table Columns, use the drop-down to select the columns you want to include in the Devices table. The
width of the table is configured by the Length column in the semantic model.
For a cooler scenario, select the following: Device ID, Device Type Description, Store Name, Address, Alerts,
Latest Temperature Celsius, Latest Power State Text, Latest Battery Level, Connectivity Type Text, Ext Device
Type ID.
Note
Because the table row indicates the individual device, selecting a column property that has one-to-many
associations with the device (for example, DEVICE_ID and Alert Type) will duplicate the device rows in the
Table view. Select only properties that have a one-to-one association with the device.
7. Save your changes.
62
PUBLIC
SAP Connected Goods Implementation Guide
Defining UI Configurations
11.1.4 Defining Grid Tiles
Use the Grid Tiles tab to specify the information displayed on the device tiles in the Grid view.
Context
Grid tiles are configurable for each device category.
Procedure
1. In the launchpad, choose the Visualization tile.
2. Choose the Grid Tiles tab.
3. Choose a perspective: Device or Location.
4. Choose the device category for which you want to define grid tile information from the Device Category dropdown list. By default, Common is selected.
5. Choose Edit.
SAP Connected Goods Implementation Guide
Defining UI Configurations
PUBLIC
63
6. In the Grid View panel, make data selections for each area of the grid tile. For your reference, the sample tile in
the left navigator indicates the location of each data field. Be sure to select attributes and measures exactly
as indicted below or the tile will not display correctly.
Field
Description
Header
Select an attribute to be displayed as the header at the top of the grid tile (for ex­
ample, Device ID, Serial Number, Device Description, or Material Description).
For a cooler scenario, select Device Material ID.
Sub Header1
Select an attribute to be displayed below the header (for example, Device ID).
For a cooler scenario, select Device Type Description.
Sub Header 2
Select any attribute to be displayed in the second line below the header.
For a cooler scenario, select Address.
Status Label
Select an attribute to be displayed as the device status indicator (for example,
Power State, BP Status, or BP Text). This label displays text and an image deter­
mined by the selected value.
For a cooler scenario, select BP Status Text. This displays the Assigned/Nearby sta­
tus with an associated image.
Alert Count
Select the Alerts attribute if you want the alerts count (the number of current notifi­
cations for the device) to be displayed in red on the grid tile.
For a vending machine scenario, select Out of Stock to display the number of prod­
ucts that are out of stock for the vending machine.
KPI-1
Select a measure for the first KPI you want to display (for example, for a cooler, you
might select Average Temperature).
For a cooler scenario, select Latest Temperature.
Unit
If relevant, select a unit for the selected KPI (such as °C). This is appended to the
KPI value.
For a cooler scenario, select °C.
Micro Chart
Choose to include a micro chart that will display the last three values of the KPI.
These values are derived from device data.
For a cooler scenario, select Avg Temperature.
KPI-2
Select a measure for the second KPI you want to display. This value is made up of
text and an image.
For a cooler scenario, choose Power State to display text and an image indicating
whether the device is On or Off.
For a cooler scenario, select Latest Power State Text.
Show History Links
Select this checkbox to display the History link in the grid tile. The user can choose
this link to see the location of the device over the last few days.
For a cooler scenario, select this option.
Grid Sorters
Configure the properties by which devices in the grid view can be sorted.
Choose New Sorter to add a property and configure each property as follows:
64
PUBLIC
SAP Connected Goods Implementation Guide
Defining UI Configurations
Field
Description
○
Sorter: Choose a column from the semantic model or the master data. This can
be either an attribute or a measure. For example: Device ID, Device Serial
Number, Device Type, Temperature.
○
Label: Enter the string to be displayed instead of the technical name in the Sort
by drop-down list.
By default, the list can be sorted by Pinned Devices, but this does not require config­
uration.
For a cooler scenario, choose the following sorters: Device ID, Device Type, Device
Name, Alerts, Temperature (°C), Power.
7. Save your changes.
11.1.5 Defining the Visual Table
Use the Visual Table tab to configure elements in the visual table: the attributes by which to group the table and the
measures that display data.
Context
This task allows any user to configure the Visual Table View to select, display, and compare just the pertinent data.
You must configure the Visual Table View here for it to display meaninful results.
Procedure
1. In the launchpad, choose the Visualization tile.
2. On the Visual Table tab, choose a device type.
3. Choose Edit.
4. Choose the Time Dimension to use by default in the visual table: Hourly, Daily, Weekly, Monthly, Yearly.
5. To add an attribute, choose New Group By Attribute.
The attibute appears in the Group By list.
6. Repeat Step 5 until you have added all desired attributes to the list. You may add as many attributes to the list
as you like.
7. To add measure, choose New Measure.
The attibute appears in the Measures list.
8. Repeat Step 5 until you have added all desired measures to the list. You may add as many measures to the list
as you like.
SAP Connected Goods Implementation Guide
Defining UI Configurations
PUBLIC
65
9. Save your changes.
The selections appear in the Visual Table View as options for viewing this data in table form. For more
information, see Visual Table View in the SAP Connected Goods User Guide.
11.2
Defining the Object Detail View
Use the Object Detail Configuration tile to define the information displayed on the Object Details pages.
Context
You configure the Object Details pages with the following procedures:
Procedure
1. Defining Header Info [page 66]
2. Defining Facets [page 68]
3. Defining Widgets [page 71]
4. Defining Sections [page 74]
11.2.1 Defining Header Info
Use the Header Info tab to define the header of the Object Details page.
Context
The Header Info tab controls the device image, title, and description displayed at the top of the page.
66
PUBLIC
SAP Connected Goods Implementation Guide
Defining UI Configurations
Procedure
1. In the launchpad, choose the Object Detail Configuration tile.
2. On the Header Info tab, choose a perspective: Device or Location.
3. Choose the device category for which you are defining object details from the Device Category drop-down list.
4. Choose Edit.
5. Enter header information as follows:
Property
Attribute
Value
Description
<../objectpage/sap/iot/
template/general/
ObjectPage/local/assets/
<device_name>.png>
The URL for the device
image that will appear on
device tiles of this type.
(This field is set by de­
fault by SAP Connected
Goods.)
Note
For attributes, choose
String to enter a value
manually. Choose Path to
choose a column from
master data or the se­
mantic model.
ImageURL
String
Replace
<device_name> with
the name of the device.
This must be present in
the UI package.
Description
Path
Device Type Description
Determines the descrip­
tion that is displayed be­
low the title on the Object
Details page.
Title
Path
Device ID
Determines the title that
appears at the top of the
Object Details page.
6. Save your changes.
SAP Connected Goods Implementation Guide
Defining UI Configurations
PUBLIC
67
11.2.2 Defining Facets
Use the Facets tab to define facets of the Object Details page.
Context
The Facets tab controls the information displayed below the title on the page.
Note
This set of procedures provides sample values. Implementation values may vary depending on the device type
and scenario.
Procedure
1. In the launchpad, choose the Object Detail Configuration tile.
2. Choose the Facets tab.
3. Choose a perspective: Device or Location.
4. Choose the device category for which you are defining object details from the Device Category drop-down list.
5. Choose Edit.
6. Enter facet information as follows:
68
PUBLIC
SAP Connected Goods Implementation Guide
Defining UI Configurations
The Header Facet table displays the qualifiers, or UI elements, that are configured on this tab. This table is
provided for reference and is read only.
Header Facet
Qualifier
Label
Target
Description
SubHeader1
DeviceSubHeader1
UI.Badge
Determines the Assigned/
Unassigned text and associ­
ated image.
SubHeader2
DeviceSubHeader2
UI.Badge
Determines the Connected/
Disconnected text and asso­
ciated image.
SubHeader3
DeviceSubHeader3
UI.Badge
Determines the On/Off text
and associated image.
SubHeaderPerson
DeviceSubHeaderPerson
UI.Badge
Determines the contact per­
son's name and associated
image.
GeoMatch (provided for all
cooler device types)
iceActions
UI.Identification
Determines the label text
and image for the geomatch­
ing Assign button.
The Header Facet Details table allows you to set the properties that configure the details of the listed qualifiers.
Note that some qualifiers have more than one property to set. Choose Add to add a row for each property and
make selections as follows:
Header Facet Details
Qualifier
Attribute
Property
Value
HeadLine
BP Status Text
Note
For attributes, choose
String to enter a value
manually. Choose Path to
choose a column from
master data or the se­
mantic model.
SubHeader1
Path
This property sets the text
for this qualifier (Assigned/
Unassigned).
SubHeader1
Path
ImageURL
BP Status Text
This property sets the image
for this qualifier (the green
dot icon).
SubHeader2
Path
HeadLine
Power Status
This property sets the text
for this qualifier (On/Off).
SAP Connected Goods Implementation Guide
Defining UI Configurations
PUBLIC
69
Qualifier
Attribute
Property
Value
SubHeader2
Path
ImageURL
Power Status
This property sets the image
for this qualifier.
SubHeader3
Path
HeadLine
Choose any attribute you
want to be displayed as a
subheader.
This property sets the text
for this qualifier.
For example, for a cooler
scenario, you might choose
Connectivity Status, for
which the display values are
Bluetooth/Connected.
SubHeader3
Path
ImageURL
This property sets the image
for this qualifier.
SubHeaderPerson
Path
Choose the same attribute
you chose for the HeadLine
property.
Employee Responsible Name
1
HeadLine
This property sets the text
for the first line of this quali­
fier (the last name of the
contact, if you want it to ap­
pear first).
SubHeaderPerson
Path
Employee Responsible Name
2
Title
This property sets the text
for the second line of this
qualifier (the first name of
the contact).
SubHeaderPerson
String
ImageURL
This property sets the image
sap-icon://personplaceholder
for this qualifier (the person
graphic).
Geomatch
String
HeadLine
Assign
This property sets the text
for this qualifier (the Assign
text).
7. Save your changes.
70
PUBLIC
SAP Connected Goods Implementation Guide
Defining UI Configurations
11.2.3 Defining Widgets
Use the Widgets tab to define widgets on the Object Details page.
Context
The Widgets tab controls the store name and address, map, and list of nearby devices in the left navigator.
Note
This set of procedures provides sample values for a smart cooler. Implementation values may vary depending
on the device type and scenario.
Procedure
1. In the launchpad, choose the Object Detail Configuration tile.
2. Choose the Widgets tab.
3. Choose a perspective: Device or Location.
4. Choose the device category for which you are defining object details from the Device Category drop-down list.
SAP Connected Goods Implementation Guide
Defining UI Configurations
PUBLIC
71
5. Choose Edit.
6. Enter widget information as follows:
The Widget Definition table displays the qualifiers, or UI elements, that are configured on this tab. This table is
provided for reference and is read only.
Widget Definition
Qualifier
Navigation Property
CoolerMap
NearbyCoolerList
DeviceDataCharts
StoreInfo
Target
Description
UI.Map
Determines the map used for
the page.
UI.Lineitem
Determines the Nearby
Coolers list for the page.
UI.Fieldgroup
Determines the store infor­
mation displayed on the
page.
The Field Group & Line Item table allows you to set the properties that configure the store address and Nearby
Coolers list. Note that some qualifiers have more than one property to set. Choose Add to add a row for each
property and make selections as follows:
Field Group & Line Item
Qualifier
Label
Value
Is Image
Store Name
Store Name
Unselected
Enter the store name (any
This property sets the store
value). This value is required
name.
Note
For attributes, choose
String to enter a value
manually. Choose Path to
choose a column from
master data or the se­
mantic model.
StoreInfo
but is not displayed in the UI.
StoreInfo
Street
Address
Unselected
Enter the street address (any This property sets the store
value). This value is required
address.
but is not displayed in the UI.
Note
Order the following prop­
erties based on the se­
quence in which you want
them to be displayed.
72
PUBLIC
SAP Connected Goods Implementation Guide
Defining UI Configurations
Qualifier
Label
Value
Is Image
NearByCoolerList
Title
Device GUID
Unselected
Enter this value exactly as
Choose the column name for
shown.
the device ID.
Address
Address Formatted
Enter this value exactly as
Choose the column name for
shown.
the device address.
ImageUrl
Device GUID
Enter this value exactly as
Choose the column name for
shown.
the device type.
This property is optional.
This property displays a de­
NearByCoolerList
NearByCoolerList
Unselected
Selected
vice­type­specific image.
NearByCoolerList
Distance
Distance_m
Unselected
Enter this value exactly as
This property displays the
shown.
distance in meters.
The Map table allows you to configure the map displayed in the left navigator. Choose Add to add a row for
each property and make selections as follows:
Map
Qualifier
Property
Path
CoolerMap
Latitude
Latitude
Sets the latitude for the device on the
Choose a column that corresponds
map.
with the latitude property (for example,
Latitude, Latest Latitude).
CoolerMap
Longitude
Longitude
Sets the longitude for the device on the
Choose a column that corresponds
map.
with the longitude property (for exam­
ple, Longitude, Latest Longitude).
CoolerMap
Image
BP Type Text
Displays the device image that indi­
Determines whether the device is as­
cates whether it is assigned, unas­
signed, unassigned, or nearby.
signed, or nearby.
7. Save your changes.
SAP Connected Goods Implementation Guide
Defining UI Configurations
PUBLIC
73
11.2.4 Defining Sections
Use the Sections tab to define sections on the Object Details page.
Context
The Sections tab controls the information sections in the main body of the page.
Note
This set of procedures provides sample values. Implementation values may vary depending on the device type
and scenario.
Procedure
1. In the launchpad, choose the Object Detail Configuration tile.
2. Choose the Sections tab.
3. Choose a perspective: Device or Location.
4. Choose the device category for which you are defining object details from the Device Category list.
5. Choose Edit.
6. Enter section information as follows:
The Section Definition table displays the qualifiers, or UI elements, that are configured on this tab. This table is
provided for reference and is read only.
Section Definition
Qualifier
Navigation Property
Target
Label
SectionChart1 - 4
DeviceDataCharts
UI.Chart
Enter the labels to be dis­
played for each of the four
charts (for example, On/Off
Status, Average Temperature,
and so on).
Notifications
UI.Lineitem
Enter the label to be dis­
played for notifications, such
as Alerts.
UI.Datapoint
Enter the label to be dis­
played for the primary KPI in
the UI.
These qualifiers configure
the four charts on the page.
Notifications
This qualifier determines
whether notifications are dis­
played on the page.
DetailKpi
This qualifier determines the
primary KPI that is displayed
on the page.
74
PUBLIC
SAP Connected Goods Implementation Guide
Defining UI Configurations
Qualifier
Navigation Property
Target
Label
KpiMicroQualifier
MicroChartData
UI.Chart
Leave this field blank.
This qualifier determines the
mini chart that is displayed
to the right of the primary
KPI.
The Section Chart Configuration table allows you to set the properties that configure charts on the page.
Choose Add to add a row for each property and make selections as follows:
Section Chart Configuration
Qualifier
Chart Type
Measure
Dimension
KpiMicroQualifier
Select Line.
Select a measure to deter­
mine the three values used in
the chart. For example, if you
select Average Pressure, the
last three average pressure
values are displayed.
The default dimension for all
charts is Hour. The chart di­
mension can be changed as
needed by the user.
For this qualifier, the chart
type is always Line.
Options include Minute,
Hour, Day, Week, Month, and
Year.
SectionChart1 - 4
Select a chart type: Line,
Bar, Column, or Column
Stacked.
Select a measure to deter­
mine the values in the chart.
For ColumnStacked, you can
select multiple values to be
displayed.
The Section Fieldgroup Configuration table allows you to configure data on the page. Choose Add to add a row
for each property and make selections as follows:
Section Fieldgroup Configuration
Qualifier
Value1
Unit
Value2
DetailKpi
Choose any measure or KPI
visualization for the detail
KPI.
Enter a unit of measure for
the KPI. For example, for a
temperature KPI, you might
enter °C.
Select the value to display
for the KPI, such as Latest
Temperature.
Field
Description
Time dimension for Detail KPI - Show for Last
Enter the time period for which to calculate the Detail KPI.
Notifications
Select this checkbox to display notifications on the page.
Inventory Data
Select this checkbox to display inventory data on the page.
7. Save your changes.
11.3
Defining Settings
SAP Connected Goods Implementation Guide
Defining UI Configurations
PUBLIC
75
11.3.1 Defining a Map Provider
Set the map provider for the SAP Connected Goods map features.
Procedure
1. In the launchpad, choose the Settings tile and then choose the Map Settings tab.
2. Choose Edit and edit the following settings as needed.
Map Provider Details
Field
Description
Map Provider
Enter the name of the service to use as the map provider:
Google, Bing, or Custom
Map Style
Enter the style of map to display:
Tile URL 1 - 4
○
Roadmap
○
Satellite
○
Terrain
○
Hybrid
Enter one or more URLs for the provider, in the preferred or­
der of usage. Default URLs are provided for Google and Bing.
Map View Behavior
Field
Description
Enable clustering/grouping of device
Enables you to group devices on the map.
Sync map and table view content while zooming in/out
Dynamically updates the table view so that only the devices
displayed on the map are included in the table.
3. Save your changes.
11.3.2 Defining an External Map Provider
Set the external map provider for the SAP Connected Goods map features.
Context
This section determines the map provider that is used when you display the location of a device from the Device
Details page.
76
PUBLIC
SAP Connected Goods Implementation Guide
Defining UI Configurations
Procedure
1. In the launchpad, choose the Settings tile and then choose the External Map Provider tab.
2. Choose Edit and edit the following settings as needed.
External Map Provider Details
Field
Description
Map Provider
Choose the service to use as the map provider: Google,
Bing, or Custom
Map Style
Choose the style of map to display:
External Map URL
○
Roadmap
○
Satellite
○
Terrain
○
Hybrid
Enter the external map URL to use. A default UR is provided
for Google and Bing.
3. Save your changes.
11.3.3 Defining Thresholds
Set key factors for device data.
Procedure
1. In the launchpad, choose the Settings tile and then choose the Thresholds tab.
2. Choose Edit and edit the following settings as needed.
Settings
Field
Description
Distance for Geo-matching Assignment
Enter the distance around a mapped device for which to dis­
play other devices on a map.
Distance for Geo-matching Nearby Status
Enter the distance around a mapped device for which to dis­
play other devices in the Nearby Devices list.
Temperature
Enter the target temperature for a device. A variation from
this temperature will generate an alert.
Door Openings Threshold
Enter the maximum number of times a device door can
open without generating a notification.
Door Open Time Threshold
Enter the maximum length of time a device door can be
open without generating a notification.
SAP Connected Goods Implementation Guide
Defining UI Configurations
PUBLIC
77
Field
Description
Temperature Unit
Choose to display temperature in Centigrade or Fahrenheit.
3. Save your changes.
11.3.4 Defining External Interfaces
Set APIs for accessing application data from an external device.
Context
Entering external interface data also enables the Device Action option on the Object Details page.
Procedure
1. In the launchpad, choose the Settings tile and then choose the External Interfaces tab.
2. Choose Edit and edit the following settings as needed.
APIs
Field
Description
API to get Device Data
Enter the URL for the API to use to get device data.
User Name/Password
Enter the user name and password for this API.
API to get Device Location
Enter the URL for the API to use to get a device location.
User Name/Password
Enter the user name and password for this API.
3. Save your changes.
11.3.5 Defining Chart Settings
Enter Time Dimension Settings data.
Procedure
1. In the launchpad, choose the Settings tile and then choose the Chart Settings tab.
78
PUBLIC
SAP Connected Goods Implementation Guide
Defining UI Configurations
2. Choose Edit and edit the following settings as needed.
Time Dimension Settings
Field
Description
Default Aggregation
Select a default time increment to display in the device
views.
No. of Periods
Enter the number of past time periods to display.
3. Save your changes.
11.3.6 Defining a Mail Server
Set mail server configuration data.
Procedure
1. In the launchpad, choose the Settings tile and then choose the Mail Server tab.
2. Choose Edit and edit the following settings as needed.
Server Configurations
Field
Description
YAAS Email Send URL
Enter a URL for this configuration.
YAAS Client ID
Enter the client ID.
YAAS Client Secret
Enter the client secret used for authentication.
Notification Service URL
Enter a URL for the notification service.
YAAS Template Owner
Enter the template owner.
3. Save your changes.
11.3.7 Defining Default Settings
Set the default view settings for the user.
Procedure
1. In the launchpad, choose the Settings tile and then choose the Default Settings tab.
2. Choose Edit and edit the following settings as needed.
SAP Connected Goods Implementation Guide
Defining UI Configurations
PUBLIC
79
Field
Description
View
Choose to display device data by default in Grid, Table, or
Map form.
Preview
Displays a preview of your data in the selected default view.
3. Save your changes.
80
PUBLIC
SAP Connected Goods Implementation Guide
Defining UI Configurations
12
Defining Rule Configurations
12.1
About the Rule Engine
The Rule Engine enables you to set up rules, based on device events, that will trigger notification events under
conditions you specify.
Rules allow you to respond to complex situations that occur with your connected devices. For example, you might
create rules to prepare for the following situations:
● A business operations manager might set up a rule to create a “Close Door” alert if the system detects that a
cooler door has been left open for more than an hour.
● A business operations manager might create a rule to send out an email alerting the field service technician to
visit a cooler if the inside temperature goes above 55 F and the door has been closed for the past 30 minutes.
You create rules based on events. Events are composed of criteria based on the information that is available in the
event’s selected message type. When an event occurs, it triggers any rules that are associated with it.
Rules are made up of conditions that further refine the event criteria. Rule conditions can be based on message
data, business data, and aggregators (mathematical functions). When an event is detected and a rule’s conditions
are met, the rule triggers a response action. Possible responses include in-application notifications and email
notifications.
To follow an example above, you might create an event with criteria that specify the temperature of a device rising
above 55 degrees Fahrenheit. A rule might then trigger a notification for this event if certain additional conditions
are met: for example, the device contains ice cream and the device door has been closed for 30 minutes.
Notification templates are provided with the application.
You can also base rules on scheduled events at a frequency that you determine. You can specify when to check that
a rule condition is met and when not to check that it is met.
To create a rule that is too complex to set up in the Custom Rule interface, you can use Expert mode to create the
rule using a rule expression.
SAP Connected Goods Implementation Guide
Defining Rule Configurations
PUBLIC
81
12.2 Creating an Event
Create a device event that will trigger one or more rules and their associated actions.
Procedure
1. On the launchpad, choose Event Management.
2. On the Event Management page, choose Create New Event.
3. In the Create New Event dialog box, enter details as follows.
82
Field
Description
Event Name
Enter a name for the event using a maximum of 50 charac­
ters.
Device Type
From the list, choose the device type for this event.
Description
Enter a description for the event using a maximum of 150
characters.
Message Type
Choose a message type from the list. List options will vary
based on the selected device type. This field is required.
Event Type
For most events, choose General. If you are creating a geo­
fencing event, choose Geofencing.
PUBLIC
SAP Connected Goods Implementation Guide
Defining Rule Configurations
Field
Description
Criteria
Optionally, enter criteria for the event. Event criteria must
do the following:
○
Reference only fields (case sensitive) of the message
type for which it is defined.
○
Compile to a valid Spark SQL where clause. For infor­
mation about syntax, see the Spark SQL documenta­
tion.
Expressions are not validated on the front end. If you input
an invalid expression, an error will be created when the
event is triggered (errors can be checked using the Ingestion
Logs tile). The error will indicate a syntax error during the
execution of the SQL statement in Spark.
As an example, for a message type with the fields
pressure and temperature, the following are valid ex­
pressions:
○
temperature > 10
○
(temperature > 10 AND pressure < 0.5)
OR (temperature > 0.5 AND pressure <
10)
○
1 = 1
The event criteria are used to evaluate streaming data and
to raise the event (and trigger an associated rule) if the cri­
teria are met. An event can also be raised from an external
system (for example, Edge Gateway or another IoT applica­
tion) to trigger the rule inside SAP Connected Goods. In this
situation, event criteria are not required, as the external sys­
tem's logic, based on its own data, will raise the event into
SAP Connected Goods via Rest API.
If you create an event with no criteria that is not raised by an
external system, it will save without error, but will never trig­
ger a rule.
4. Choose Create.
The event is added to the events list.
SAP Connected Goods Implementation Guide
Defining Rule Configurations
PUBLIC
83
12.3 Creating an Event from an Existing Event
You can base a new event on an existing event.
Procedure
1. On the launchpad, choose Event Management.
2. On the Event Management page, choose the Event ID of the event to use as the basis for your new event.
3. In the Edit Event dialog box, make the desired changes. See Creating an Event [page 82] for more information.
4. Choose Save As....
The event is added to the events list.
12.4 Deleting an Event
Context
Note
You can only delete events that are not linked to any existing rules.
Procedure
1. On the launchpad, choose Event Management.
2. Choose the Select link and select one or more events to delete.
3. Choose Delete.
The events are deleted.
84
PUBLIC
SAP Connected Goods Implementation Guide
Defining Rule Configurations
12.5 Creating a Rule
You can use the Rule Engine to create a rule. When a specified event occurs and the rule's conditions are met, the
rule will trigger an action such as a notification.
Procedure
Create and Name the Rule
1. On the launchpad, select the Rule Engine tile.
2. On the Rule Engine page, choose Create New.
3. Select a Device Type (for example, Smart Cooler).
4. Enter a Rule Name and, optionally, a Description for the rule.
Add an Event
5. Under If, use the Add Event control to select the event on which to base the rule. Only the events linked to the
selected device type are displayed. Do one of the following:
○ Select an event created in Event Management that specifies the criteria that will trigger the rule. For more
information, see Creating an Event [page 82].
○ Select Scheduled Event to set up an event to check for the rule conditions at a specified time interval. You
can also choose when not to check for the rule conditions (for example, on evenings or weekends).
Set up Rule Conditions
6. Under If, use the Add Condition control to choose values to represent the conditions that will trigger a
notification.
7. Choose Add Condition and optionally choose one or more Measures for the rule (for example, Temperature,
Power State, or Battery Level) and specify any thresholds. For example, you might choose the Temperature
measure and set it to Higher than 55.
8. Choose Add Condition and optionally choose one or more Dimensions for the rule and specify its details. For
example, to apply the rule only to device IDs with the prefix AA, you might choose Device ID and set it to
Contains AA.
9. To create a more complex condition using an Aggregator (a mathematical calculation such as Average, Sum,
etc., that is performed on a measure), do the following:
a. Choose Add Condition and choose Create New under Aggregators.
b. Choose Aggregate Function and choose a measure (such as Temperature) from the list.
c. Enter a name in the Aggregator Name field. Do not include any spaces in the aggregator name.
d. Choose a function for the aggregator: Count, Sum, Max, Min, Average, or Previous.
e. Enter a time period and select a unit of measure (Seconds, Minutes, Hours, or Days).
f. Save your changes.
Note
The aggregator is saved for this rule only. If you create another rule, you will not see this aggregator in
its custom aggregator list.
g. Choose Add Condition again and choose your new aggregator from the list.
SAP Connected Goods Implementation Guide
Defining Rule Configurations
PUBLIC
85
The aggregator is displayed in the list of conditions.
h. Add additional values as needed to complete the aggregation.
10. Add as many measures, dimensions, and aggregations as necessary, modifying the operators (AND, OR)
between them as needed to define the rule.
Add an Action
11. Under Then, use the Add Action button to choose the notification action for the rule. Select the action and add
contact information as needed.
To send email to the responsible employee, choose
Add Action
Send Email
EMP_RES_EMAIL
button.
Add a Notification Frequency
12. Under Additional Information, choose the Notification Frequency with which the action should occur: Every
time the condition is detected, or just the First time it is detected.
Note
In Expert mode, you can also set the frequency to a number that you specify, to trigger a notification after
the rule conditions have been met a certain number of times (consecutive or nonconsecutive). See the
Continuous Violation section under Rule Expression Reference for more information.
Add Rule Status and Priority
13. Select the Status button to activate or deactivate the rule.
14. Choose a priority for the rule using the Priority slider.
15. Choose Save.
The rule is added to the rules list.
12.5.1 Example: Creating a Rule
Context
The following example creates a rule for a cooler that will check once a minute every day (excluding weekends) to
determine whether the cooler's average temperature has been higher than or equal to 55 degrees for 15 minutes
and its door has been open for 20 minutes. If this condition is detected, it will send a notification email to the
contact person for the cooler.
Procedure
Create and Name the Rule
86
PUBLIC
SAP Connected Goods Implementation Guide
Defining Rule Configurations
1. On the launchpad, select the Rule Engine tile.
2. On the Rule Engine page, choose Create New.
3. Select Smart Cooler as the Device Type.
4. Enter High Temp/Door Open as the rule name.
Add an Event
5. Under If, use the Add Event control to select Scheduled Event.
6. For Execute on, choose minute and 1.
7. For Don't execute on, choose Saturday and Sunday.
Set up Rule Conditions
8. Under If, use the Add Condition control.
9. Under If, choose Add Condition and add the Door Open measure as follows:
a. Under Measures, choose Door Open Count.
b. In the condition row, choose Higher than or equal to and enter 20.
10. Under If, choose Add Condition and add the Temperature-related aggregator as follows:
a. Choose Add Condition and choose Create New under Aggregators.
b. Choose Aggregate Function and choose Temperature from the list.
c. Enter HighTemp in the Aggregator Name field. Do not include any spaces in the aggregator name.
d. Choose the Average function for the aggregator.
e. Enter 15 and select Minutes as the unit of measure.
f. Save your changes.
g. Choose Add Condition again and choose your new aggregator from the list.
The HighTemp aggregator is displayed in the list of conditions.
h. In the condition row, choose Higher than or equal to and 55 to complete the aggregation..
Add an Action
11. Under Then, use the Add Action button to choose the notification action for the rule. Select Send Email and
add contact information as needed.
Add a Notification Frequency
SAP Connected Goods Implementation Guide
Defining Rule Configurations
PUBLIC
87
12. Under Additional Information, choose Every time as the Notification Frequency.
Add Rule Status and Priority
13. Select On (green) for the Status to activate the rule.
14. Choose High as the rule Priority.
15. Choose Save.
The rule is added to the rules list.
12.5.2 Using Defined Fields and Attributes in a Rule Condition
You can include fields in a rule condition in the Rules interface or in expert mode. For information about performing
these tasks in expert mode, see Including Defined Fields and Attributes in a Rule Expression [page 109].
Comparing Two Fields or Attributes in a Rule
You can use defined (semantic or other) fields as part of the rule condition.
The basic format used to define a field is ${TableorView.field}. Use the following guidelines to format fields
and attributes.
Field or Attribute Type
Format
Field from the semantic view
${SemanticView.field}
Predefined aggregate field
The TableorView assumes the same name as the defined aggregate field. Use
the following format:
${aggregate field.aggregate field}
For example, if you have defined a field as max_temperature, the format for us­
ing this aggregate field in the rule condition is:
${max_temperature.max_temperature}
88
PUBLIC
SAP Connected Goods Implementation Guide
Defining Rule Configurations
Field or Attribute Type
Format
Start time and end time from the
DEVICE_RELOCATION.field
DEVICE_RELOCATION table for
checking planned relocation times
For example:
●
To include the start time from the DEVICE_RELOCATION table in the rule
condition, use this format:
DEVICE_RELOCATION.START_TIME
●
To include the end time from the DEVICE_RELOCATION table in the rule con­
dition, use this format:
DEVICE_RELOCATION.END_TIME
Device field or attribute
Enter the field name in the rule condition.
Rule Example: Defined Field for Semantic Model
This rule example checks to determine if the current temperature is higher than the average temperature. The field
added on the right-hand side (RHS) of the equation is ${SemanticView.Average_Temperature}.
Note
In a custom rule, the semantic field or fields from other tables can only be an RHS field.
Using SQL Expressions in a Rule
You can use calculated expressions as part of the rule condition.
The expression definition follows regular BODMAS rules and the format used to define a field is ${}.
Rule Example
This rule example checks to determine if the inside temperature is higher than or equal to the calculated value of
(Average Temperature – 10).
Use the following alias for this expression: (${SemanticView.Average_temperature} – 10) as
min_of_avg_temperature.
SAP Connected Goods Implementation Guide
Defining Rule Configurations
PUBLIC
89
The field on the RHS is ${SemanticView.Average_temperature} – 10.
12.6 Using Rule Actions
12.6.1 Creating an Action
Context
You can use Action Management to automatically create or update a business object in an SAP business system.
For example, you might create add an action to create a sales order or service ticket when certain rule conditions
are met.
You specify the REST service details to be executed by defining an action, which can then be associated with a rule.
After the rule runs, the associated action or actions can be executed, either triggered automatically or manually.
Procedure
1. On the launchpad, select the Action Management tile.
2. On the Action Management page, choose Create New Action.
3. Define the HTTP service parameters as follows:
90
Field
Description
Action Name
Enter the name of the action service. This field is required.
Description
Enter a description of the action.
Action Type
Select HTTP. This is currently the only supported action type. This field is required.
PUBLIC
SAP Connected Goods Implementation Guide
Defining Rule Configurations
Field
Description
Action URL
Select the HTTP method: GET, POST, or PUT. This field is required.
Enter the URL endpoint to invoke when the action is triggered. This URL is typically provided
by the partner or application you are integrating with. For example:
https://cd4iot-iflmap.hcisb.int.sap.hana.ondemand.com/http/c4c/
post_srvc_rqst
Optionally, choose Test to check the availability of the URL endpoint.
Authentication Type
Choose the authentication type: BASIC or SAML. This field is required.
User ID
Enter the user ID for authentication. This field is required.
Password
Enter the password for authentication. This field is required.
Invocation Type
Choose one of the following:
○
Manual: When the action is invoked, it remains in Pending status until it is executed man­
○
Automatic: When the action is invoked, it is executed immediately
ually. For more information, see Executing an Action Manually [page 94].
This field is required.
Parameters
Choose +Add Parameter to add an action parameter. Enter information as follows:
○
ID: Start typing to see a list of parameters to choose from. Select a parameter from the
list.
○
Name: Enter a name to identify the parameter. For example, My Quantity
○
Unit: If applicable, enter a unit of measure. For example, C, ft
○
Read Only: Check this box to create a fixed parameter that can't be edited by the user.
Leave it unchecked to create an editable parameter.
○
Clipboard: You can copy the parameter to the payload or one of the action templates con­
figured below. Choose the Clipboard icon and select the text box in which to paste the pa­
rameter:
Note
Do not edit the format (${}) of this parameter in the payload. The system uses this
format to read the parameter.
Payload
Enter the service payload, if any.
A sample payload is as follows:
{
SAP Connected Goods Implementation Guide
Defining Rule Configurations
PUBLIC
91
Field
Description
"ServicePriorityCode": "2",
"Name": {
"content": "Check Cooler ${device.t_device_id} for High
Temperature Alert "
},
"ProcessingTypeCode": "SRRQ",
"CustomerID" : "10005",
"InstallationPointID" :
"0000000000000000000000000000000000000021",
"SerialID" : "CSR-19-005-1",
"ServiceRequestDescription": [
{
"Text": "Temperature is high : $
{device.inside_temperature} ",
"TypeCode": "10022"
}
]
}
Using Defined Expressions in an Action Payload
To use predefined calculated expressions as part of the action payload, define the following ex­
pression in the rule condition:
(${SemanticView.Average_temperature} – 10) as
min_of_avg_temperature
Include this expression in the action payload using the format $
{min_of_avg_temperature}.
Action Path Feature
You can use the following fields to specify the path (XPath or JsonPath) for any parameter of
interest in the response received as a result of the action execution.
Path Name
Enter the name of the parameter (for example, Service Ticket Number).
Path
Enter the XPath or JsonPath for the parameter of interest in the response.
For example:
○
JsonPath: $.d.results.ID is the JsonPath to access the Service Ticket confirmation
number. For more information about defining the JsonPath, see the Json source docu­
mentation
○
.
XPath: RETURN/item[1]/MESSAGE_V2 is the XPath to access the Purchase Order
number.
Type
Choose one of the following:
○ JsonPath: JSON
○
XPath: XML
This extracted value can also be used in the alert texts using the template parameter
{T_RESULTS}.
Action Notification Tem­
plates Feature
You can use the following fields to configure custom alert templates for each action.
You can use the following standard template parameters in any of these texts:
○
{T_ACTION_NAME}: The Action Name value specified above.
○
{T_RESULTS}: The XPath/JsonPath result extracted from the action response (from
the Action Pathvalue specified above).
92
PUBLIC
SAP Connected Goods Implementation Guide
Defining Rule Configurations
Field
Description
You can also use any field specified in the Parameters values specified above when configuring
these texts. You can choose the Clipboard icon to paste the parameter to any of the following
templates.
Note
After you create the action with the configured templates, you can also access the tem­
plates using the Notification Templates tile.
In-App Text
Enter the text for an alert to be displayed on the Device Details page in the application.
Email Header
Enter the subject of an email alert.
Email Text
Enter the body of the email alert.
4. Choose Save.
12.6.2 Associating an Action with a Rule
Context
To trigger an action created in Action Management, you associate it with a rule.
Procedure
1. On the launchpad, select the Rule Engine tile.
2. Create a rule or edit an existing rule that specifies the desired rule conditions. For more information, see
Creating a Rule [page 85].
3. Under Then, use the Add Action button and choose the action from the list.
To notify the responsible employee when the action is executed successfully, choose
Email
EMP_RES_EMAIL
Add Action
Send
button.
4. Enter information into other rule fields as needed.
5. Choose Save.
SAP Connected Goods Implementation Guide
Defining Rule Configurations
PUBLIC
93
12.6.3 Executing an Action Manually
Context
When the Invocation Type for an action is specified as Automatic, the action is executed automatically when the
rule associated with the action is invoked.
When the Invocation Type for an action is specified as Manual, the the action execution must be completed
manually.
Procedure
1. When the rule is invoked, the pending action appears in the Details page of the device that meets this rule
condition. For example:
2. In the menu, choose Review Pending Actions.
3. Choose See More for the action to execute.
4. In the window that appears, edit fields to include the desired values when the action is executed.
Note
You can only edit fields that are not designated as Read Only parameters in the action. For more
information, see Creating an Action [page 90].
5. Choose Create.
94
PUBLIC
SAP Connected Goods Implementation Guide
Defining Rule Configurations
12.7 Rule Engine Expert Mode
12.7.1 Creating a Rule Using a Rule Expression
For complex rules, you can create a rule using a rule expression.
Prerequisites
You are a developer who is familiar with the technical structure of JSON format and can formulate its structure as
needed by following the CNG predefined format.
Context
Use a rule expression to create a rule that is too complex to create using the Custom Rule feature.
Procedure
1. In the launchpad, choose the Rule Engine tile.
2. On the Rules page, choose Create New and then choose Create Rule Expression.
3. In the Rule Name field, enter a name for the rule.
4. In the Rule Expression field, enter a rule expression in JSON format.
For more information, see Rule Expression Reference [page 98].
12.7.1.1 Creating a Stock on Hand Rule
You can create a Stock on Hand rule to check conditions for the current stock and the percentage of stock on hand
for one or more Product IDs and generate notifications as necessary.
Note the following when creating this rule:
● Do not create any other rule conditions with this rule.
● Do not create any other rule aggregations with this rule.
● The defined fields must be of type NORMAL and cannot have aggregates, since these are pre-calculated figures.
● This rule must be associated with an existing event.
● Do not check for or include the Device ID/GUID in the rule condition.
SAP Connected Goods Implementation Guide
Defining Rule Configurations
PUBLIC
95
The following is a sample of pre­defined JSON format:
{
"name":"StockOnHandRule",
"description": "Sample Rule using Expression",
"priority": "high",
"isActive": "true",
"event": "12",
"deviceTypes": [
{
"deviceTypeID": "2000"
}
],
"aggregations": [
],
"if": [
"AND",
{
"field": "PRODUCT_ID",
"type": "NORMAL",
"operator": "LIKE",
"value": "SD"
},
{
"field": "STOCK_ON_HAND",
"type": "NORMAL",
"operator": "<",
"value": "20"
},
{
"field": "PERCENTAGE_STOCK_ON_HAND",
"type": "NORMAL",
"operator": "<",
"value": "80"
}
],
"then": {
"actions": [
{
"actionType": "EMAIL",
"recipients": [
{
"id": "xxxxxxx",
"email": "abc@cdf"
}
]
}
],
"frequency": "EVERYTIME"
}
}
Use the following table for allowable definitions in the JSON payload:
Object
Description
Allowed Field Defini­
tion
Allowed Type
Allowed Operators
PRODUCT_ID
Product ID
PRODUCT_ID
NORMAL
=, <>, LIKE
STOCK_ON_HAND
Stock on hand
STOCK_ON_HAND
NORMAL
=, <>,>=,<=
PERCENTAGE_STOCK NORMAL
_ON_HAND
=, <>,>=,<=
PERCENTAGE_STOCK Percentage of stock
_ON_HAND
96
PUBLIC
SAP Connected Goods Implementation Guide
Defining Rule Configurations
12.7.1.2 Creating a Time Period Check Rule
You can create a Time Period Check rule to compare the current time with a pre­defined time value. This is useful
for determining whether the current time falls within a certain period.
The following is a sample of pre­defined JSON format. This rule condition will check whether the current UTC time
falls outside the start and end times of the relocation period defined in the DEVICE_RELOCATION table for a
particular device.
{
}
"name": "TimePeriodCheck",
"description": "check if current time within period",
"priority": "high",
"isActive": "true",
"event": "5",
"deviceTypes": [
{
"deviceTypeID": "abcdef1234"
}
],
"aggregations": [],
"if": [
[
"OR",
{
"field": "CURRENT_TIME",
"type": "NORMAL",
"operator": "<",
"value": "START_TIME;DEVICE_RELOCATION;DEVICE_ID"
},
{
"field": "CURRENT_TIME",
"type": "NORMAL",
"operator": ">",
"value": "END_TIME;DEVICE_RELOCATION;DEVICE_ID"
}
]
],
"then": {
"actions": [{
"actionType": "EMAIL",
"recipients": [
{
"id": "xxxxxxx",
"email": "xxx.xxx@xxx.xxx"
}
]
}
],
"frequency": "EVERYTIME"
}
Use the following table for allowable definitions in the JSON payload of RuleStep (defining if):
Object
Description
Allowed Field Defi­ Allowed Type
nition
Allowed Operators Allowed Values
CURRENT_TIME
Current UTC time
CURRENT_TIME
=, <>,>=,<=
NORMAL
See Allowed Value
Format below.
Allowed Value Format
SAP Connected Goods Implementation Guide
Defining Rule Configurations
PUBLIC
97
The allowed value format is as follows:
Time_Column_name;Table_name;Key_Field_Column_Name
Where:
● Time_Column_Name = The column name containing the time value within the table
● Table_Name = The name of the table containing the time period information
● Key_Field_Column_Name = The column name of the search by field (for example, Device ID)
For example, from the sample payload:
value: START_TIME;DEVICE_RELOCATION;DEVICE_ID
12.7.2 Rule Expression Reference
This topic provides reference information for a rule expression in JSON format.
JSON Sample Code
You create a rule expression in JSON format. The following are examples of predefined JSON.
JSON Sample for Coffeemaker Scenario
This rule specifies the following: If (MINIMUM COFEEINVENTORY within 60 second period is less than 0.10 AND
(MILK_INVENTORY_LEVEL is less than 0.2 or DECAFFEINATED_COFFEE_INVENTORY_LEVEL is less than 0.1))
then send email to recipients.
{
"description": "Coffee Maker Scenario Rule using Expression",
"priority": "high",
"isActive": "true",
"event": "1000",
"deviceTypes": [
{
"deviceTypeID": "1000"
}
],
"aggregations": [
{
"name": "MINCOFEEINVENTORY",
"field": "CAFFEINATED_COFFEE_INVENTORY_LEVEL",
"function": "MIN",
"timeDuration": "60",
"timeUnit": "SECONDS"
}
],
"if": [
[
"AND",
{
"field": " MINCOFEEINVENTORY",
"type": "AGG",
"operator": "<",
"value": "0.10"
},
98
PUBLIC
SAP Connected Goods Implementation Guide
Defining Rule Configurations
[
]
}
]
"OR",
{
"field": "MILK_INVENTORY_LEVEL",
"type": "NORMAL",
"operator": "<",
"value": "0.2"
},
{
"field": "DECAFFEINATED_COFFEE_INVENTORY_LEVEL ",
"type": "NORMAL",
"operator": "<",
"value": "0.1"
}
],
"then": {
"actions": [
{
"actionType": "EMAIL",
"recipients": [
{
"id": "i808440",
"email": "joe.smith@yourcompany.com"
},
{
"id": "i802886",
"email": "cheryl.chung@yourcompany.com"
}
]
}
],
"frequency": "EVERYTIME"
}
JSON Sample for Cooler Scenario
This rule specifies the following: If (MAXIMUM TEMP > 25 within 10 second period AND (DOOR_OPEN_COUNT
greater than 5 OR VEND_QUANTITY Less than 1)) then send emails to recipients.
{
"description": "Cooler Scenario Rule using Expression",
"priority": "high",
"isActive": "true",
"event": "1000",
"deviceTypes": [
{
"deviceTypeID": "1000"
}
],
"aggregations": [
{
"name": "MAXTEMP",
"field": "INSIDE_TEMPERATURE",
"function": "MAX",
"timeDuration": "10",
"timeUnit": "SECONDS"
}
],
"if": [
[
"AND",
{
"field": "MAXTEMP",
"type": "AGG",
SAP Connected Goods Implementation Guide
Defining Rule Configurations
PUBLIC
99
"operator": ">",
"value": "25"
},
[
"OR",
{
"field": "DOOR_OPEN_COUNT",
"type": "NORMAL",
"operator": ">",
"value": "5"
},
{
"field": "VEND_QUANTITY",
"type": "NORMAL",
"operator": "<",
"value": "1"
}
]
}
]
],
"then": {
"actions": [
{
"actionType": "EMAIL",
"recipients": [
{
"id": "i808440",
"email": "joe.smith@yourcompany.com"
},
{
"id": "i802886",
"email": "cheryl.chung@yourcompany.com"
}
]
}
],
"frequency": "EVERYTIME"
}
Rule Main Body: RULE
This table provides reference information for creating the main body of the rule.
Object
Required?
Description
Allowed Values
description
Yes
Rule description
No restrictions
priority
Yes
Rule priority
low, medium, high
isActive
Yes
Rule status
true, false
Rule will be ignored if set
to false.
100
PUBLIC
SAP Connected Goods Implementation Guide
Defining Rule Configurations
Object
Required?
Description
Allowed Values
event
Yes
Rule event [page 108]
Existing event ID
(EVENT_ID) or
schedule for schedule
event type
Note
This field is required
and cannot be left
empty.
run_Schedule
Yes, for schedule
Rule Execute on
Only relevant for
schedule event type.
event type only
Note
Follows Cron format.
For more information,
see: http://
www.nncron.ru/
help/EN/
working/cronformat.htm
notRun_Schedule
Yes, for schedule
Rule Don’t Execute on
Only relevant for
schedule event type.
event type only
Note
Follows Cron format.
For more information,
see: http://
www.nncron.ru/
help/EN/
working/cronformat.htm
deviceTypes
aggregations
if
then
Yes
No
No
No
SAP Connected Goods Implementation Guide
Defining Rule Configurations
Array with 1 or more elements of type
Elements of type
RULE_DEVICE_TYPES
RULE_DEVICE_TYPES
Array with 1 or more elements of type
Elements of type
RULE_AGGREGATION
RULE_AGGREGATION
Array with 1 or more elements of type
Elements of type
RULE_STEP or RULE_GROUP
RULE_STEP|
RULE_GROUP
Array with 1 or more elements of type
Elements of type
RULE_ACTION
RULE_ACTION
PUBLIC
101
RULE_DEVICE TYPES
This section provides reference information for creating a rule expression that applies to a device type.
Object
Description
Allowed Values
deviceTypeID
Device Type ID [page 108] that this rule applies to
Existing Device Type IDs only
Note
This field is required and
cannot be left empty.
RULE_AGGREGATION
The following table provides reference information for using rule aggregators in a rule expression.
Note
When using aggregations in a rule, all objects listed are required.
Object
Description
Allowed Values
name
Aggregation name
No restrictions
field
Rule condition field [page 108]
Existing rule field ID (FIELD_ID)
function
Aggregation function
MAX, SUM, AVG, MIN, PREVIOUS,
COUNT
timeDuration
Time duration
Any numeric value
timeUnit
Time unit
SECONDS, MINUTES, HOURS, DAYS
RULE_STEP
The following table provides reference information for a rule expression using the if operator.
Note
When using rule steps in a rule, all objects listed are required.
Object
Description
Allowed Values
field
Rule condition field [page 108]
Existing rule field ID (FIELD_ID)
102
PUBLIC
SAP Connected Goods Implementation Guide
Defining Rule Configurations
Object
Description
Allowed Values
type
Rule condition type
NORMAL for non-aggregate condition
AGG for aggregate condition
operator
Rule operator
If the field is a type of STRING, only the
following operators can be used:>, <, >=,
<=, <>, LIKE, IS
If the field is a type of INTEGER or
DECIMAL, only the following operators
can be used:>, <, >=, <=, <>
value
Rule condition value
If using the IS operator, the value must
be NULL. For other operators, no restric­
tions.
RULE_GROUP
An array with 3 or more elements. It allows you to check for multiple conditions (door is open AND temperature is
below 10°). The first element of the array must have the value "AND" or "OR" and defines how your conditions are
connected. The rest of the elements can be either of type RULE_STEP or another RULE_GROUP, which allows you
to nest conditions.
RULE_ACTION
The following table provides reference information for a rule expression using an action.
Note
When using actions in a rule, include one or more of the following objects.
ActionType
Description
EMAIL
Send email to specified recipients
Sample
{
"actionType":"EMAIL",
"recipients":[
{
"id":"<userid>",
"email":"<email
address>"
}
SAP Connected Goods Implementation Guide
Defining Rule Configurations
]
}
PUBLIC
103
ActionType
Description
EMAIL
Send email to responsible employee
Sample
"then": {
"actions": [
{
"actionType":"EMAIL",
"recipients":[
{
"id":"EMP_RESPONSIBLE",
"email":"EMP_RES_EMAIL"
}
]
}
],
"frequency": "EVERYTIME"
}
GEO_MATCH
Execute geo-matching
{
"actionType":
"GEO_MATCH"
},
GEO_UNASSIGN
GEO_REVERSECODE
MOVE_ALERT
EMAIL_STOREEMPL
Object
action
104
PUBLIC
Unassign a device from a previously
matched location
Update the address of a device based
on latitude and longitude
Send an alert if the device moves
away from its assigned location
Send an email to the relevant store
employee
Description
{
"actionType":
"GEO_UNASSIGN"
},
{
"actionType":
"GEO_REVERSECODE"
},
{
"actionType":
"MOVE_ALERT"
},
{
"actionType":
"EMAIL_STOREEMPL"
},
Allowed Values
Array with 1 or more elements of type
See the table above for allowed
actionType
actionType
SAP Connected Goods Implementation Guide
Defining Rule Configurations
Object
Description
Allowed Values
frequency
Action frequency
EVERYTIME, FIRSTTIME,
NTIMECONS, NTIMENON
If NTIMECONS or NTIMENON are
used for frequency, the object
frequencyNumber must be speci­
fied.
frequencyNumber
Number of condition checks expected
An integer value. See Continuous
Violation below for details.
Continuous Violation
The continuous violation feature allows you to check for a condition that has occurred a certain number of times.
This condition can be checked for both consecutive occurrence and non-consecutive occurrence. For example,
you might use this feature to determine whether the temperature has stayed consistently high for the last three
record readings.
To use this feature, specify the following rule conditions:
"frequency": "NTIMECONS" or "NTIMENON"
"frequencyNumber": "n"
where n = number of condition checks
"NTIMECONS" = check if condition is satisfied consecutively n times
"NTIMENON" = check if condition is satisfied non-consecutively n times
The following is a sample payload for the consecutive condition check:
{
"name":"ConsecutiveRule",
"description": " Consecutive condition check",
"priority": "high",
"isActive": "true",
"event": "11",
"deviceTypes": [
{
"deviceTypeID": "2000"
}
],
"aggregations": [
],
"if": [
{
"field": "SERIAL_ID",
"type": "NORMAL",
"operator": "LIKE",
"value": "VM"
}
],
"then": {
"actions": [
{
"actionType":"EMAIL",
"recipients":[
{
"id":"ixxxxxx",
SAP Connected Goods Implementation Guide
Defining Rule Configurations
PUBLIC
105
}
]
}
"email":"xxx.xxx@xxx.com"
],
"frequency": "NTIMECONS",
"frequencyNumber": "3"
}
}
The following is a sample payload for the non-consecutive condition check:
{
}
"name":"NonConsecutiveRule",
"description": "Non Consecutive condition check",
"priority": "high",
"isActive": "true",
"event": "11",
"deviceTypes": [
{
"deviceTypeID": "2000"
}
],
"aggregations": [
],
"if": [
{
"field": "SERIAL_ID",
"type": "NORMAL",
"operator": "LIKE",
"value": "VM"
}
],
"then": {
"actions": [
{
"actionType":"EMAIL",
"recipients":[
{
"id":"ixxxxxx",
"email":"xxx.xxx@xxx.com"
}
]
}
],
"frequency": "NTIMENON",
"frequencyNumber": "3"
}
Additional Sample JSON Code
The following example of a schedule event shows JSON format without a nested logical operation.
Sample Code
{
106
"description": "Sample Format",
"priority": "high",
PUBLIC
SAP Connected Goods Implementation Guide
Defining Rule Configurations
"isActive": "true",
"event": "SCHEDULE",
"run_Schedule": "0 0 0 1 4 ? *",
"notRun_Schedule": "* * * * *",
"deviceTypes": [
{
"deviceTypeID": "2000"
}
],
"aggregations": [
{
"name": "MAXTEMP",
"field": "INSIDE_TEMPERATURE",
"function": "MAX",
"timeDuration": "10",
"timeUnit": "S"
}
],
"if": [
"AND",
{
"field": "Temperature",
"type": "NORMAL",
"operator": ">",
"value": "10"
},
{
"field": "doorOpenCount",
"type": "NORMAL",
"operator": ">",
"value": "5"
}
],
"then": {
"actions": [
{
"actionType": "EMAIL",
"recipients": [
{
"id": "i808440",
"email": "abc@cdf"
}
]
}
],
"frequency": "EVERYTIME"
}
}
SAP Connected Goods Implementation Guide
Defining Rule Configurations
PUBLIC
107
12.7.3 Finding the ID Value for the "event" Field
Procedure
1. In the launchpad, choose the Event Management tile.
You see a table of events and their associated data.
2. Locate the event you want to use and note the value in the Event ID column for that event.
12.7.4 Finding the ID Value for the "deviceTypeID" Field
Procedure
1. In the launchpad, choose the Device Type tile.
You see a table of device types and their associated data.
2. Locate the device type you want to use and note the value in the ID column for that event.
12.7.5 Finding the ID Value for "field" in a Condition
Procedure
1. In the launchpad, choose the Device Type tile.
You see a table of device types and their associated data.
2. Locate the device type you want to use and select the value in the ID column for that event.
You see the Message Types page.
3. In the Field Name column, locate and make a note of the fields you want to use.
108
PUBLIC
SAP Connected Goods Implementation Guide
Defining Rule Configurations
12.7.6 Creating an Action in Expert Mode
You can use expert mode to create very complex actions that cannot be created in Action Management. For more
information about creating actions, see Creating an Action [page 90].
To create an action in expert mode, specify the following:
actionType
“REST”
actionId
To obtain the value, choose the Action Management tile on the launchpad, choose the action, and
copy the Action ID.
12.7.7 Including Defined Fields and Attributes in a Rule
Expression
You can include fields in a rule condition in the Rules interface or in expert mode. For information about performing
these tasks in the Rules interface, see Using Defined Fields and Attributes in a Rule Condition [page 88].
Comparing Two Fields or Attributes in a Rule
You can compare two fields or attributes in a rule condition. This rule example checks to determine whether the
current temperature is higher than the average temperature.
Rule Expression Example
"IF": [
{
"field": " INSIDE_TEMPERATURE ",
"type": "NORMAL",
"operator": ">",
"value": "${SemanticView.Average_Temperature}"
}
],
Using SQL Expressions in a Rule
You can use calculated expressions as part of the rule condition. This rule example checks to determine whether
the temperature is less than (Average Temperature – 10).
Rule Expression Example 1
"IF": [
{
"field": " temperature ",
"type": "NORMAL",
SAP Connected Goods Implementation Guide
Defining Rule Configurations
PUBLIC
109
]
}
"operator": "<",
"value": "${SemanticView.Average_temperature} – 10
Rule Expression Example 2
This rule example checks to determine whether the current stock is less than 30 percent of the stock capacity.
Since STOCK_ON_HAND, which is a calculated field, is not available on LHS of rule condition in the Rules interface
for a custom rule, this rule can only be defined in expert mode.
"IF": [
{
"field": " ${SemanticView.STOCK_ON_HAND} ",
"type": "NORMAL",
"operator": "<",
"value": "30/100*${Device.Capacity}"
}
]
12.8 Machine Learning
SAP Connected Goods supports two machine learning algorithms: Change Point Detection and Anomaly
Detection.
12.8.1 Configuring Change Point Detection
Prerequisites
You must have a valid API key and password for the SAP Leonardo Machine Learning service.
Context
SAP Connected Goods provides integration with SAP Leonardo Machine Learning Services to detect change
points on SAP Connected Goods data. When the change point is detected in the data, the event is raised. The
event can be subscribed in the rule definition to trigger the appropriate actions based on the rule condition. For
example, you might create a rule to trigger a notification or service request when a change point is detected in the
last hour.
Configure change point detection as follows.
110
PUBLIC
SAP Connected Goods Implementation Guide
Defining Rule Configurations
Procedure
1. In the launchpad, choose the Machine Learning tile.
2. On the Dataset tab, choose Create to create a new dataset.
3. In the Create New Dataset window, choose the field or fields for which to detect change points, as follows:
Field
Description
Name
Enter a name for the dataset. This field is required.
Description
Enter a description for the dataset.
Source Type
Choose Fields from the drop-down list.
Device Type
Choose a device type from the drop-down list. This field is
required.
Source
Choose the source from the drop-down list. The source pro­
vides numeric fields from the device message that should
be included in the datasets.
Parameters
Optionally, enter parameters.
Filter
Optionally, enter filters.
4. Choose Save.
5. Choose the Service tab.
6. Choose Create to create a new service.
7. Enter service information as follows:
Field
Description
ID
This field is read only.
Name
Enter a name for the service. This field is required.
Field Name
Enter the name of the field to store the output of the change
point detection. This field can also be used in the Semantic
view and in charts to visualize change points.
Description
Enter a description for the service.
Type
Choose ChangePoint Detection from the drop-down list.
This field is required.
Dataset
Choose the dataset you created from the drop-down list.
This field is required.
Execute on Event
Choose the event that will trigger execution of this Machine
Learning service.
Post Execute Raise Event
Choose the event to be raised when the change point is de­
tected.
Under Parameters, choose + Add Parameter to enter each of the following properties:
Property
Description
API_KEY
Key for the SAP Leonardo Machine
Language service
SAP Connected Goods Implementation Guide
Defining Rule Configurations
Default Value
PUBLIC
111
Property
Description
Default Value
API_URL
URL for the SAP Leonardo Change
Point service
MAX_REQUESTS_PER_DAY
Maximum requests per day per device
to the SAP Leonardo Machine Lan­
guage service
3
WINDOW_SIZE
Total number of recent records to pass
to the SAP Leonardo service
1000
8. Choose Save.
12.8.2 Configuring Anomaly Detection
Context
The anomaly detection service can detect anomalies on any numeric data stored in SAP Connected Goods. This
service can accept one or more fields that can be used together to detect anomalies. When the anomaly is
detected, it is persisted in the model field that is available in the Semantic view for charts and rules/actions.
Additionally, the event is raised. The event can be subscribed in the rule definition to trigger the appropriate
actions based on the rule condition. For example, you might create a rule to trigger a notification or service request
when an anomaly point is detected in the last hour.
Configure anomaly detection as follows.
Procedure
1. In the launchpad, choose the Machine Learning tile.
2. On the Dataset tab, choose Create to create a new dataset.
3. In the Create New Dataset window, choose the field or fields for which to add detect anomalies, as follows:
112
Field
Description
Name
Enter a name for the dataset. This field is required.
Description
Enter a description for the dataset.
Source Type
Choose Fields from the drop-down list.
Device Type
Choose a device type from the drop-down list. This field is
required.
Source
Choose the source from the drop-down list. The source pro­
vides numeric fields from the device message that should
be included in the datasets.
PUBLIC
SAP Connected Goods Implementation Guide
Defining Rule Configurations
Field
Description
Parameters
Enter parameters as needed.
Filter
Enter filters as needed.
4. Choose Save.
5. Choose the Service tab.
6. Choose Create to create a new service.
7. Enter service information as follows:
Field
Description
ID
This field is read only.
Name
Enter a name for the service. This field is required.
Field Name
Enter the name of the field to store the output of the anom­
aly detection. This field can also be used in the Semantic
view and in charts to visualize anomalies.
Description
Enter a description for the service.
Type
Choose Anomaly Detection from the drop-down list. This
field is required.
Dataset
Choose the dataset you created from the drop-down list.
This field is required.
Execute on Event
Choose the event that will trigger execution of this Machine
Learning service.
Post Execute Raise Event
Choose the event to be raised when the anomaly is de­
tected.
Under Parameters, choose + Add Parameter to enter each of the following properties:
Property
Description
AUTO_PARAM
Use auto parameters
THREAD_NUMBER
Number of threads to use
MIN_PTS
Minimum points to detect a cluster.
Use this only if AUTO_PARAM is set to
Default Value
3
false.
RADIUS
Radius from center to detect a cluster.
Use this only if AUTO_PARAM is set to
1000
false.
8. Choose Save.
9. Navigate to the launchpad and choose the Semantic Model tile to open the Semantic Model.
10. Apply the appropriate aggregate function (for example, Max) to the Anomaly/ChangePoint field.
SAP Connected Goods Implementation Guide
Defining Rule Configurations
PUBLIC
113
12.8.3 Time Series Forecasting
Context
The time series forecast service can forecast numeric data stored in SAP Connected Goods. When the forecast is
calculated, it is persisted in the model field that is available in the Semantic view for charts and rules/actions, and
it raises the event. You can use rule definitions to trigger appropriate actions based on the condition of the rule. For
example, you might create a rule that can trigger a notification or service request when a forecasted temperature
is above a specified temperature.
For more information about rules, see Creating a Rule [page 85].
Note
The forecast feature requires the script server to be enabled when HANA is first provisioned.
Configure a time series forecast as follows.
Procedure
1. In the launchpad, choose the Machine Learning tile.
2. On the Dataset tab, choose Create.
3. In the Create New Dataset dialog box, choose one or more fields on which to forecast.
4. Choose the Service tab.
5. Choose Create.
6. In the Create New Service dialog box, enter information as follows:
Field
Description
Name
Enter a name for the service
Field Name
Enter a field name. This field can also be used in the Semantic view and in
charts to visualize the forecast.
Description
Enter a description for the service.
Type
Select Timeseries Forecast.
Dataset
Select the dataset you created.
Execute on Event
Choose the event to trigger execution of this Machine Learning service.
Post Execute Raise Event
Choose the event to be raised.
Under Parameters, choose + Add Parameter to enter each of the following properties:
114
PUBLIC
SAP Connected Goods Implementation Guide
Defining Rule Configurations
Property
FORECAST_INTERVAL
Description
Default Value
The forecast interval to persist (for example,
DAILY
MINUTE, DAILY, HOURLY, WEEKLY)
FORECAST_INTERVAL
The number of cycles present in the data
FORECAST_NUM
The number of days to forecast
THREAD_NUMBER
The number of threads
10
DATA_SINCE_EVENT
The data to be used for the forecast after the event
occurs
For example, Refill Event
WINDOW_SIZE
The number of data points to send for the forecast
1000
1
7. Choose Save.
8. Navigate to the launchpad and choose the Semantics Model tile.
9. Apply the appropriate aggregate function (for example, Max to the Forecast field).
10. Choose Generate to regenerate the semantic model.
SAP Connected Goods Implementation Guide
Defining Rule Configurations
PUBLIC
115
13
Integrating with SAP Hybris Marketing
Cloud
Prerequisites
The following prerequisites are needed to integrate SAP Connected Goods with SAP Hybris Marketing Cloud:
● SAP Hybris Marketing Cloud system
● Communication Arrangement (Create User/Communication Arrangement/Assign Roles)
○ Create the following Communication Roles: SAP_CORE_BC_COM, SAP_COM_0135, SAP_COM_CSR_0207,
SAP_COM_0205, SAP_COM_0019
○ To create the Communication Arrangement, you must have Admin authorization for the relevant SAP
Hybris Marketing Cloud system.
● Download the following iFlow (HYBRIS) content from the Connected_Goods package to configure for your
system:
○ GET_HYBRIS_CAMPAIGNS: This iFlow is responsible for pulling all campaigns, target groups, and Business
Partner (Interaction Contact) details from the Hybris_Marketing_Cloud system. This iFlow, which is
called in the iFlow described below, makes an Odata service call to the SAP Hybris Marketing Cloud
system to retrieve this information.
○ GET_HYBRIS_CAMPAIGN_MAPPING: This iFlow uses the above iFlow to get the entity set for multiple
requests at the same time. It handles the request in the payload for multiple Business Partners at the
same time. This iFlow service is called from the action, which is configured in SAP Connected Goods.
Context
To integrate these systems, you create an action, event, and rule for SAP Hybris Marketing Cloud in SAP
Connected Goods.
Procedure
1. In the launchpad, choose the Events tile.
2. Create an event, as described in Creating an Event [page 82]. See the following example for guidance.
116
PUBLIC
SAP Connected Goods Implementation Guide
Integrating with SAP Hybris Marketing Cloud
3. In the launchpad, choose the Actions tile.
4. Create an action, as described in Creating an Action [page 90].
SAP Connected Goods Implementation Guide
Integrating with SAP Hybris Marketing Cloud
PUBLIC
117
This example creates an action and provides a sample payload to retrieve campaigns based on the
CampaignStartDate and the BP_GUID in SAP Connected Goods.
Note
In this example, the CampaignStartDate must be specified a day before the desired campaigns, in order
to retrieve all campaigns in the next request. For example, to retrieve all campaigns starting on October 9,
specify the CampaignStartDate as October 8.
118
Field
Description
Action URL
(Method)
POST
PUBLIC
SAP Connected Goods Implementation Guide
Integrating with SAP Hybris Marketing Cloud
Field
Description
Action URL
https://<cpi-tenant>-iflmap.xxxxx.sap.hana.ondemand.com/http/hybris/
get_hybris_campaign_mapping
User ID
Technical User
Password
Password for CPI Tenant
Invocation Type
Choose either Manual or Automatic.
Payload
Use the following payload structure:
}
{
"CampaignStartDate": "2017-10-08",
"BPINFORMATION": [
{
"BPGUID": "00163e35-da9f-1ed7-a29a-cfa164db48d1"
},
{
"BPGUID": "00163e35-da9f-1ed7-a29a-cfa164dbe8d1"
},
{
"BPGUID": "00163e35-da9f-1ed7-a29a-cfa164db68d1"
},
{
"BPGUID": "00163e35-da9f-1ed7-a29a-cfa164dce8d1"
}
]
5. Create a rule for the action, as described in Creating a Rule [page 85]. In this example, you would create a rule
to pull up campaigns (on a daily or hourly basis) in SAP Connected Goods from the Hybris system that
includes the event created in step 2. The rule can be either scheduled or triggered by an event.
Note the following:
○ The iFlow is tuned with a test system. As it is generic, system URLs can be changed and updated to
configure the iFlow for a user­specific Hybris system after the prerequisites are fulfilled.
○ Some service end-points are filtered on specific value parameters, as they are based on the use case to
pull in only active campaigns, such as Lifecycle Status = 2, for released and active running
campaigns.
○ Hybris limits the service calls to top = 100,1000,5000 while pulling the campaign details.
SAP Connected Goods Implementation Guide
Integrating with SAP Hybris Marketing Cloud
PUBLIC
119
14
Setting up Notifications
14.1 Setting up the Notification Service
Context
The notification service is used in SAP Connected Goods to push notifications to end users. It provides two
delivery channels for pushing notifications: they can be displayed in the Notifications panel of the UI and/or sent
via email. Notifications are generated at runtime from notification templates that are configured in the notification
service.
SAP Connected Goods delivers several predefined notification templates. These templates specify the delivery
channel for pushing notifications and are used to generate notifications at runtime. For more information about
the templates, see Editing Notification Templates [page 122].
You set up the notification service in a new SAP Connected Goods customer tenant on the SAP Cloud Platform by
doing the following:
1. Set up a YaaS account and client at yaas.io.
2. Set up YaaS email with the notification service for email notifications from SAP Connected Goods.
3. Set up the notification origin for SAP Connected Goods with the notification service.
4. Save SAP Connected Goods notification templates with the notification service.
You must perform these steps only once, in the specified order, as follows.
Procedure
Set up a YaaS Account and Client
1. Go to yaas.io.
2. In Yaas, create a new organization (for example, Rule Engine Email).
3. Create a new project (for example, Rule Engine Notifier).
4. In the Administration area, add a subscription to the Email service.
5. In the Development area, create a client (for example, CNG Mail).
6. Add the following scopes to the new client and generate the client credentials:
○ hybris.email_send
○ hybris.email_admin
○ hybris.email_view
○ hybris.email_manage
120
PUBLIC
SAP Connected Goods Implementation Guide
Setting up Notifications
Set up the YaaS Email Service with the Notification Service
7. In the SAP Connected Goods launchpad, choose the Settings tile and choose the Mail Server tab.
8. Enter the following information under Server Configuration:
Field
Description/Value
YaaS Email Service URL
https://api.yaas.io/hybris/email/v1/
{YaaSProject}/send-async
YaaS Client ID and YaaS Client Secret
Authorization credentials to use the YaaS email service
YaaS Template Owner
{YaaSProject}.{YaaSProjectClient}
Notification Service URL
https://connected-goods-ns-java{TenantId}.cfapps.sap.hana.ondemand.com
9. Save your changes.
Set up the Notification Origin for SAP Connected Goods
Note
You must have the Administrator role to perform this step.
10. Use Postman to create the notification origin for SAP Connected Goods as follows:
a. Log into SAP Connected Goods.
b. In Postman, write and execute (send) the following method:
Method: GET
https://<sample.cng.sap.hana.ondemand.com>
Header: X-CSRF-Token: Fetch
The execution of the method returns a value for the token X-CSRF-Token for this Postman session.
c. Make a note of the value returned in the previous step. You will use it to create the Notification Origin in
this Postman session.
d. Create the Notification Origin for SAP Connected Goods by executing the following script in Postman:
Method: POST https://<sample.cng.sap.hana.ondemand.com>/rules/
notificationtemplate/origin
Header: X-CSRF-Token: <value of x-csrf-token>
Save SAP Connected Goods Notification Templates with the Notification Service
11. Save the SAP Connected Goods predefined notification templates with the Notification Service by executing
the following script in Postman:
Method: POST https://<sample.cng.sap.hana.ondemand.com>/rules/
notificationtemplate/loadtemplates
Header: X-CSRF-Token: <value of x-csrf-token>
SAP Connected Goods Implementation Guide
Setting up Notifications
PUBLIC
121
14.2 Editing Notification Templates
Context
You can edit the templates of predefined services but not introduce new services. Two types of templates are
supported: Email and In-App.
Procedure
1. On the launchpad, choose the Notification Templates tile.
2. In the Notification Templates table, you see the following predefined templates provided by SAP Connected
Goods:
122
Service
Type
Name
Last Updated by
Last Updated at
Action
Rules
Email
Rules Email Tem­
plate
SAP
<date>
Edit
Rules
In-App
Rules In-App Tem­
plate
SAP
<date>
Edit
Geofencing
Email
Geofencing Email
Template
SAP
<date>
Edit
Geofencing
In-App
Geofencing In-App SAP
Template
<date>
Edit
Geomatching
Email
Geomatching
Email Template
SAP
<date>
Edit
Geomatching
In-App
Geomatching InApp Template
SAP
<date>
Edit
Onboarding
Email
Onboarding Email
Template
SAP
<date>
Edit
Onboarding
In-App
Onboarding InApp Template
SAP
<date>
Edit
CRM Update
Email
CRM Update
Email Template
SAP
<date>
Edit
CRM Update
In-App
CRM Update InApp Template
SAP
<date>
Edit
CRM Service Re­
quest Initiation
Email
CSR Initiation
Email Template
SAP
<date>
Edit
PUBLIC
SAP Connected Goods Implementation Guide
Setting up Notifications
Service
Type
Name
Last Updated by
Last Updated at
Action
CRM Service Re­
quest Initiation
In-App
CSR Initiation InApp Template
SAP
<date>
Edit
CRM Service Re­
quest Update
Email
CSR Update Email
Template
SAP
<date>
Edit
CRM Service Re­
quest Update
In-App
CSR Update InApp Template
SAP
<date>
Edit
Object Details
Page Notification
Email
Object Details
Page Notification
Email Template
SAP
<date>
Edit
3. Choose Edit for the template you want to edit.
4. For an Email template, edit the subject and body of the template as needed. For an In-App template, edit the
text area as needed.
Note
Use only the variables provided in the sample template. Do not add new variables.
5. Choose Save. Your changes are saved and overwrite the default template. The Notification Templates table
indicates when the template was last updated and by whom.
This guide provides the text of the predefined templates to allow you to revert to the original content if needed.
See Default Notification Template Text [page 126] for more information.
You can also reset the default templates using SQL. See Resetting Notification Templates Using SQL [page
123].
14.3 Resetting Notification Templates Using SQL
Context
You can use SQL statements to reset the notification templates to their predefined text.
Procedure
1. Connect to the HANA DB instance of the customer’s SAP Connected Goods tenant using the following URL:
https://dbutil-vmmt.cfapps.sap.hana.ondemand.com/
2. Run the following SQL statements:
DELETE from "sap.iot.scb.rules::mdl.RULE_NOTIFICATION_TEMPLATE";
SAP Connected Goods Implementation Guide
Setting up Notifications
PUBLIC
123
INSERT INTO
"sap.iot.scb.rules::mdl.RULE_NOTIFICATION_TEMPLATE"(GUID,TEMPLATE_OWNER,TEMPLATE_
VERSION,TEMPLATE_NAME,TEMPLATE_CONSUMPTION_CHANNEL,TEMPLATE_HEADER_TEXT,TEMPLATE_
BODY_TEXT,CREATED_BY,CREATED_TIME,MODIFIED_BY,MODIFIED_TIME) VALUES (100,'RULES',
100,'Rules Email Notification Template','EMAIL','{T_EVENT_NAME}, {T_RULE_NAME} :
{T_DEVICE_TYPE}, {T_DEVICE_ID}','Dear User
This message is to inform you about a {T_PRIORITY} priority event.
The rule {T_RULE_NAME} has occurred with these conditions: {T_RULE_CONDITION}.
This occurred at {T_TIME} for the device {T_DEVICE_ID}.
The current values for the device {T_DEVICE_ID} are as follows {T_DEVICE_DATA}.
The device is located at {T_LOCATION}.
Click here to see the device details: {T_DEVICE_URL}.
Please take the necessary steps to resolve this issue.
Kind regards
SAP Connected
Goods','SAP','2017-01-03T12:11:13.000Z','SAP','2017-01-03T12:11:13.000Z');
INSERT INTO
"sap.iot.scb.rules::mdl.RULE_NOTIFICATION_TEMPLATE"(GUID,TEMPLATE_OWNER,TEMPLATE_
VERSION,TEMPLATE_NAME,TEMPLATE_CONSUMPTION_CHANNEL,TEMPLATE_HEADER_TEXT,TEMPLATE_
BODY_TEXT,CREATED_BY,CREATED_TIME,MODIFIED_BY,MODIFIED_TIME) VALUES (101,'RULES',
100,'Rules InApp Notification Template','INAPP',NULL,'{T_EVENT_NAME},
{T_RULE_NAME} has been detected for the device
{T_DEVICE_ID}','SAP','2017-01-03T12:11:13.000Z','SAP','2017-01-03T12:11:13.000Z')
;
INSERT INTO
"sap.iot.scb.rules::mdl.RULE_NOTIFICATION_TEMPLATE"(GUID,TEMPLATE_OWNER,TEMPLATE_
VERSION,TEMPLATE_NAME,TEMPLATE_CONSUMPTION_CHANNEL,TEMPLATE_HEADER_TEXT,TEMPLATE_
BODY_TEXT,CREATED_BY,CREATED_TIME,MODIFIED_BY,MODIFIED_TIME) VALUES
(102,'GEOMATCH',100,'GeoMatch Email Notification Template','EMAIL','Device
{T_DEVICE_ID} successfully auto-mapped to location/store {T_LOCATION} :
{T_STORE_NAME}','Dear User
The following device has been successfully auto-mapped to a location/store by
the geo-matching service in the SAP Connected Goods system:
Device {T_DEVICE_ID}
Device category: {T_DEVICE_CATEGORY_DESCRIPTION}
Device type: {T_DEVICE_TYPE}
Mapped to {T_LOCATION} : {T_STORE_NAME} at {T_TIME}.
Click here to see device details: {T_DEVICE_URL}.
Please take any necessary next steps.
Kind regards
SAP Connected
Goods','SAP','2017-01-03T12:11:13.000Z','SAP','2017-01-03T12:11:13.000Z');
INSERT INTO
"sap.iot.scb.rules::mdl.RULE_NOTIFICATION_TEMPLATE"(GUID,TEMPLATE_OWNER,TEMPLATE_
VERSION,TEMPLATE_NAME,TEMPLATE_CONSUMPTION_CHANNEL,TEMPLATE_HEADER_TEXT,TEMPLATE_
BODY_TEXT,CREATED_BY,CREATED_TIME,MODIFIED_BY,MODIFIED_TIME) VALUES
(103,'GEOMATCH',100,'GeoMatch InApp Notification Template','INAPP',NULL,'Device
{T_DEVICE_ID} successfully auto-mapped to location/store {T_LOCATION} :
{T_STORE_NAME}','SAP','2017-01-03T12:11:13.000Z','SAP','2017-01-03T12:11:13.000Z'
);
INSERT INTO
"sap.iot.scb.rules::mdl.RULE_NOTIFICATION_TEMPLATE"(GUID,TEMPLATE_OWNER,TEMPLATE_
VERSION,TEMPLATE_NAME,TEMPLATE_CONSUMPTION_CHANNEL,TEMPLATE_HEADER_TEXT,TEMPLATE_
BODY_TEXT,CREATED_BY,CREATED_TIME,MODIFIED_BY,MODIFIED_TIME) VALUES
(104,'GEOFENCE',100,'GeoFence Email Notification
Template','EMAIL','{T_DEVICE_CATEGORY_DESCRIPTION} {T_DEVICE_ID} exited geofence
{T_GEOFENCE_ID}','Dear User {T_DEVICE_CATEGORY_DESCRIPTION} {T_DEVICE_ID} exited
geofence {T_GEOFENCE_ID}.
Please take the necessary steps to resolve this issue.
Kind regards
SAP Connected
Goods','SAP','2017-01-03T12:11:13.000Z','SAP','2017-01-03T12:11:13.000Z');
INSERT INTO
"sap.iot.scb.rules::mdl.RULE_NOTIFICATION_TEMPLATE"(GUID,TEMPLATE_OWNER,TEMPLATE_
VERSION,TEMPLATE_NAME,TEMPLATE_CONSUMPTION_CHANNEL,TEMPLATE_HEADER_TEXT,TEMPLATE_
BODY_TEXT,CREATED_BY,CREATED_TIME,MODIFIED_BY,MODIFIED_TIME) VALUES
(105,'GEOFENCE',100,'GeoFence InApp Notification
Template','INAPP',NULL,'{T_DEVICE_CATEGORY_DESCRIPTION} {T_DEVICE_ID} exited
124
PUBLIC
SAP Connected Goods Implementation Guide
Setting up Notifications
geofence
{T_GEOFENCE_ID}','SAP','2017-01-03T12:11:13.000Z','SAP','2017-01-03T12:11:13.000Z
');
INSERT INTO
"sap.iot.scb.rules::mdl.RULE_NOTIFICATION_TEMPLATE"(GUID,TEMPLATE_OWNER,TEMPLATE_
VERSION,TEMPLATE_NAME,TEMPLATE_CONSUMPTION_CHANNEL,TEMPLATE_HEADER_TEXT,TEMPLATE_
BODY_TEXT,CREATED_BY,CREATED_TIME,MODIFIED_BY,MODIFIED_TIME) VALUES
(106,'ONBOARD',100,'Onboard Email Notification Template','EMAIL','Device
{T_DEVICE_ID} onboarded successfully at {T_TIME}','Dear User
The following device has been onboarded successfully into the SAP Connected
Goods system:
Device: {T_DEVICE_ID}
Device category: {T_DEVICE_CATEGORY_DESCRIPTION}
Device type: {T_DEVICE_TYPE}
Onboarding mechanism: via {T_ONBOARD_TYPE} mechanism at {T_TIME}
Custom Device attributes/identifiers: {T_DEVICE_DATA}
Click here to see device details: {T_DEVICE_URL}
Please take any necessary next steps.
Kind regards
SAP Connected
Goods','SAP','2017-01-03T12:11:13.000Z','SAP','2017-01-03T12:11:13.000Z');
INSERT INTO
"sap.iot.scb.rules::mdl.RULE_NOTIFICATION_TEMPLATE"(GUID,TEMPLATE_OWNER,TEMPLATE_
VERSION,TEMPLATE_NAME,TEMPLATE_CONSUMPTION_CHANNEL,TEMPLATE_HEADER_TEXT,TEMPLATE_
BODY_TEXT,CREATED_BY,CREATED_TIME,MODIFIED_BY,MODIFIED_TIME) VALUES
(107,'ONBOARD',100,'Onboard InApp Notification Template','INAPP',NULL,'The
{T_DEVICE_TYPE} with the ID {T_DEVICE_ID} has been onboarded
successfully','SAP','2017-01-03T12:11:13.000Z','SAP','2017-01-03T12:11:13.000Z');
INSERT INTO
"sap.iot.scb.rules::mdl.RULE_NOTIFICATION_TEMPLATE"(GUID,TEMPLATE_OWNER,TEMPLATE_
VERSION,TEMPLATE_NAME,TEMPLATE_CONSUMPTION_CHANNEL,TEMPLATE_HEADER_TEXT,TEMPLATE_
BODY_TEXT,CREATED_BY,CREATED_TIME,MODIFIED_BY,MODIFIED_TIME) VALUES
(108,'RUNTIME_USER_MESSAGE',100,'RuntimeUserMessage Email Notification
Template','EMAIL','DeviceAlert: Notification for
{T_DEVICE_ID}','{T_USERMESSAGE}','SAP','2017-01-03T12:11:13.000Z','SAP','2017-0103T12:11:13.000Z');
SAP Connected Goods Implementation Guide
Setting up Notifications
PUBLIC
125
14.4 Default Notification Template Text
Use this default notification template text if you need to revert a notification template to its original content.
Rules
Email Notification
Subject: <event name>, <rule name>: <device type>, <device ID/name>
Body:
Dear User,
This message is to inform you about a <priority level> priority event.
The rule <rule name> has occurred with these conditions: <rule condition >. This
occurred at <detection time> for the device <device ID/name>.
The current values for the device <device ID/name> are as follows:
<value 1>
<value 2, etc.>
The device is located at <location>.
Click here to see the device details: <hyper link to device detail page>.
Please take the necessary steps to resolve this issue.
Kind regards,
SAP Connected Goods
In-App Notification
<event name>, <rule name> has been detected for the device <device ID/name>
Geofencing
Email Notification
Subject: <Device_Category> <Device_ID> exited geofence <Geofence_ID>
Body:
Dear User,
<Device_Category> <Device_ID> exited geofence <Geofence_ID>.
Please take the necessary steps to resolve this issue.
Kind regards,
SAP Connected Goods
In-App Notification
<Device_Category> <Device_ID> exited geofence <Geofence_ID>
126
PUBLIC
SAP Connected Goods Implementation Guide
Setting up Notifications
Geomatching
No rules are needed for alert notifications with geomatching. The alert is generated when the geo-matching
service completes the auto-mapping process.
Email Notification
Subject: Device <Device_ID> successfully auto-mapped to location/store <location/
store name>
Body:
Dear User,
The following device has been successfully auto-mapped to a location/store by the
geo-matching service in the SAP Connected Goods system:
Device <Device_ID>
Device category: <device_category>
Device type: <device_type>
Mapped to <Location_type> : <Store name> & <store address>
at <timestamp>
Click here to see device details: <hyperlink to device detail page>
Please take any necessary next steps.
Kind regards,
SAP Connected Goods
In-App Notification
The <Device Type> with the ID <Device_ID> has been successfully auto-mapped to
location/store <location/store name>.
Onboarding
No rules are needed for alert notifications with onboarding. The alert is generated when the onboarding of the
device takes place.
Email Notification
Subject: Device <Device_ID> onboarded successfully at <timestamp>
Body:
Dear User,
The following device has been onboarded successfully into the SAP Connected Goods
system:
Device <Device_ID>
Device category: <device_category>
Device type: <device_type>
Onboarding mechanism: via <manual/mobile/upload> mechanism
at <timestamp>
Custom Device attributes/identifiers:
<attribute 1 e.g. serial no>
<attribute 1 e.g. module no>
<on-boarded by / quality check done by>
Click here to see device details: <hyperlink to device detail page>
Please take any necessary next steps.
Kind regards,
SAP Connected Goods
SAP Connected Goods Implementation Guide
Setting up Notifications
PUBLIC
127
In-App Notification
The <Device Type> with the ID <Device_ID> has been onboarded successfully
CRM Update
The alert notification is generated when the SAP Connected Goods system updates the back-end business
system.
For example, after geomatching of a cooler to a store in the SAP Connected Goods system, the mapped store/
cooler data is updated in the CRM (creation of installed base with attributes and store information).
Email Notification
Subject: SAP Connected Goods updated a <field> in the back-end CRM system
Body:
Dear User,
SAP Connected Goods updated the following <field> in the back-end CRM system:
Field <field/attribute>
Updated with <information>
Kind regards,
SAP Connected Goods
In-App Notification
<field/attribute> was updated in the CRM back-end system with <information>
CRM Service Request Initiation
The notification is generated when SAP Connected Goods creates a service request in the CRM back-end business
system.
128
PUBLIC
SAP Connected Goods Implementation Guide
Setting up Notifications
Email Notification
Subject: Service Request Creation in back-end CRM system for device <Device_Id>
successful - <Service request ID>
Body:
Dear User,
SAP Connected Goods initiated the creation of the following service request in the
back-end CRM system:
Device <Device_ID>
Device category: <device_category>
Device type: <device_type>
Service Request ID: <service_request_id>
Service Request Description: <service_request_desc>
Priority: <High/Medium/Low>
Current Status: <Created/Initiated/Open>
Further Device attributes/identifiers:
<attribute 1 e.g. serial no>
<attribute 1 e.g. module no>
Click here to see device details: <hyperlink to device detail page>
Kind regards,
SAP Connected Goods
In-App Notification
Service Request creation in back-end CRM system for device <Device_Id> successful <Service request ID>
CRM Service Request Update
The notification is generated when there is an update in the service ticket status in the back-end CRM system.
Email Notification
Subject: Service Request - <service_request_id> in CRM : Status update
<current_status>
Body:
Dear User,
The status related to the service request <service_request_id> was updated:
Device <Device_ID>
Device category: <device_category> & Device type <device_type>
Service Request ID: <service_request_id>
Service Request Description: <service_request_desc>
Priority: <High/Medium/Low>
Previous status: <old status>
Updated status: <Modified/Closed>
Further Device attributes/identifiers:
<attribute 1 e.g. serial no>
<attribute 1 e.g. module no>
Click here to see device details: <hyperlink to device detail page>
Kind regards,
SAP Connected Goods
SAP Connected Goods Implementation Guide
Setting up Notifications
PUBLIC
129
In-App Notification
Status for Service Request <Service request ID> for the device <Device_Id> changed to
<new status> in back-end CRM system
Object Details Page Notification
This template enables you to notify a contact person directly by choosing Notify on the Object Details Page.
Email Notification
Subject: DeviceAlert: Notification for {T_DEVICE_ID}
Body:
{T_USERMESSAGE}
130
PUBLIC
SAP Connected Goods Implementation Guide
Setting up Notifications
15
Setting Up Dimensional View Visualization
You use the Dimensional View Visualization tile to render the dimensional view by configuring KPI tiles and widgets
for a specified dimension and device category.
Dimension View Setup
The process of setting up a dimension view is as follows:
1. Use the Semantic Model to define generic and calculated measures (which can include nested calculated
measures) to use as a basis for the KPIs. See Example: Creating Measures for KPIs [page 51] for more
information.
2. Define KPIs to include a measure, apply boundary conditions, and define a target and a criticality range. See
Creating a KPI [page 135] for more information.
3. Configure dimension visualizations by creating KPI tiles and widgets. See Creating a Dimension [page 131] for
more information.
At run time, annotations are generated based on these configurations. The annotations are consumed to render
the Fiori smart template-based interface.
15.1
Creating a Dimension
Procedure
1. In the launchpad, choose the Dimensional View Visualization tile.
2. On the Dimensional View Visualization page, choose the + icon in the left navigator.
3. In the Select Dimension dialog box, choose the dimension for the view: Region, Business Partner, or Device
Type.
Note
Each of these dimensions can be configured only once.
4. In the Dimensions list, select the dimension you created and choose Add Device Category.
You can add multiple device categories to a dimension, but each one must be unique.
5. Choose OK.
You see a configuration page where you can configure KPI tiles and widgets for the device category.
SAP Connected Goods Implementation Guide
Setting Up Dimensional View Visualization
PUBLIC
131
6. On the KPI tab, choose Add New KPI.
7. In the Configure KPI dialog box, enter information as follows:
Field
Description
Select KPI Name
Select a KPI from the drop-down list. This field is required.
The list reflects KPIs that have been added for this device
category using Key Performance Indicator (KPI) Modeling
[page 135].
Select one of the following types:
○ Choose Aggregation to show only an aggregated value
in the KPI.
○ Choose Time Series to show KPI data over a time pe­
riod, in chart form.
○ Choose Actual vs. Target to show the current KPI value
compared to the target value, in chart form.
Select Visualization Type
Each type renders a different visualization for the KPI tile in
the dimensional view. This field is required.
Select Time Period
Select the duration of time for which to visualize the KPI de­
tails (for example, Last 3 Hours or Last 4 Weeks).
Unit
Enter a unit of measure to add as a suffix to the KPI value in
the KPI tile.
8. Choose Save.
A KPI tile is added to the KPI tab.
Note
You can use the Edit and Delete icons to edit or delete this tile.
9. Add additional KPI tiles as needed. You can add an unlimited number of KPI tiles.
Note
Each KPI in a device category must have a unique name.
10. Choose the Widgets tab.
11. Choose Add New Widget.
12. In the Configure Widget dialog box, enter information as follows:
132
Field
Description
Widget Title
Enter a title for the widget. This field is required.
Widget Description
Enter a description for the widget. This field is required.
Widget Type
Select one of the following types:
○ TABLE
○ Select Table Dimensions: Select one or more fields (for example, Avg
Temperature or Capacity) to display in the Table widget. This field is re­
quired for this widget.
○ Show Insights: Select this box to display the Insights section in the di­
mensional view. This field is required for this widget.
PUBLIC
SAP Connected Goods Implementation Guide
Setting Up Dimensional View Visualization
Field
Description
○
○
HEATMAP:
○ Latitude: Select a latitude field for the heatmap (for example, Latest
Latitude). This field is required for this widget.
○ Longitude: Select a longitude field for the heatmap (for example, Latest
Longitude). This field is required for this widget.
CHART:
○ Select Chart Dimension: Select a time dimension to use for the widget
(for example, Hour, Day , Week, Month, Year). This field is required for
this widget.
○ Select Maximum Chart Range: Select a field (such as Avg Temperature or
FillLevel) to define the maximum chart range value.
○ Select Minimum Chart Range: Select a field (such as Avg Temperature or
FillLevel) to define the minimum chart range value.
The chart will plot a line, based on the KPI, between these maximum and
minimum range values.
KPI
From the drop-down list, select a valid KPI for the widget.
13. Choose Save.
A widget tile is added to the Widgets area.
Note
For a Table widget, choose the ellipsis button to see any additional dimensions that are not displayed in the
tile.
Note
You can use the Edit and Delete icons to edit or delete this tile.
14. Add additional widgets as needed. You can add an unlimited number of widgets.
Note
Each widget in a device category must have a unique name.
15. Review your changes and do one of the following:
○ To save the device category, choose Save.
○ To delete the device category, choose Delete Category.
SAP Connected Goods Implementation Guide
Setting Up Dimensional View Visualization
PUBLIC
133
15.2 Deleting a Dimension
Procedure
1. In the launchpad, choose the Dimensional View Visualization tile.
2. On the Dimensional View Visualization page, select the dimension to delete in the Dimensions list.
3. Choose Delete Dimension.
You see a message indicating that the message was deleted successfully.
Deleting a dimension deletes KPI tiles and widgets on all configured device category perspectives in the
dimension.
134
PUBLIC
SAP Connected Goods Implementation Guide
Setting Up Dimensional View Visualization
16
Key Performance Indicator (KPI) Modeling
You use the Key Performance Indicator Model tile to define and manage KPI definitions. A KPI definition contains
metadata such as attributes and filters. You can define KPI attributes including Name, Description, Goal Type,
associated Device Category, Measure, Criticality Values, and Target Value.
16.1
Creating a KPI
Procedure
1. In the launchpad, choose the Key Performance Indicator Model tile.
2. On the Key Performance Indicator Configuration page, choose the + icon in the left navigator.
3. In the Add KPI Name dialog box, enter the name of the KPI and choose OK.
4. On the Key Performance Indicator Details page under KPI Definition, enter the following information:
Field
Description
Name
Displays the KPI name you entered.
Description
Enter a description for the KPI.
Device Category
Choose a device category for the KPI. This field is required.
Measure
Choose a measure for the KPI. This field is required.
For more details, see Example: Creating Measures for KPIs
[page 51].
Type
Choose Increasing Trend if an increase in the measure value
indicates an improved KPI (for example, assigned coolers).
Choose Decreasing Trend if a decrease in the measure value
indicates an improved KPI (for example, unassigned cool­
ers).
Lower Limit
For an Increasing Trend KPI, enter the lowest value that is
acceptable. Values below this limit indicate a critical KPI.
For a Decreasing Trend KPI, enter the lowest standard value.
Values below this limit indicate a high KPI.
Values between these limits are neutral.
SAP Connected Goods Implementation Guide
Key Performance Indicator (KPI) Modeling
PUBLIC
135
Field
Description
Upper Limit
For an Increasing Trend KPI, enter the highest standard
value. Values above this limit indicate a high KPI.
For a Decreasing Trend KPI, enter the highest value that is
acceptable. Values above this limit indicate a critical KPI.
Values between these limits are neutral.
Values between these limits are neutral.
Target Value
The current or expected value.
5. Under KPI Filters, add boundary conditions as follows:
a. Choose + Add.
b. Choose the field on which to filter from the Field drop-down list.
c. Choose an operator from the Operator drop-down list.
d. Enter a value in the Value field.
6. Save your changes.
You see a confirmation message that you have successfully created the KPI. The KPI is added to the list in the
left navigator.
16.2 Editing a KPI
Procedure
1. In the launchpad, choose the Key Performance Indicator Model tile.
2. On the Key Performance Indicator Configuration page, select the KPI to edit in the KPIs list.
3. On the Key Performance Indicator Details page, choose Edit.
4. Edit KPI information as needed. For more information, see Creating a KPI [page 135].
5. Save your changes.
136
PUBLIC
SAP Connected Goods Implementation Guide
Key Performance Indicator (KPI) Modeling
16.3 Deleting a KPI
Procedure
1. In the launchpad, choose the Key Performance Indicator Model tile.
2. On the Key Performance Indicator Configuration page, select the KPI to delete in the KPIs list.
3. On the Key Performance Indicator Details page, choose Delete.
4. In the confirmation window, choose OK.
The KPI is deleted and you see a success message.
Note
You cannot delete the KPI if it is used in a dimensional view. A message is displayed to indicate that the KPI
is being used in a visualization.
16.4 Examples: Creating KPIs and Widgets
The following examples demonstrate how to create specific types of KPI tiles and widgets.
16.4.1 Creating a KPI Tile with a Comparison Chart
Context
In this type of KPI tile, the chart displays a comparison of the top three dimension values, measured against a
common KPI for a selected time period. The sorting type can be increasing or decreasing, depending on whether
the KPI shows an increasing or decreasing trend.
SAP Connected Goods Implementation Guide
Key Performance Indicator (KPI) Modeling
PUBLIC
137
In this example:
● The KPI used is Working Coolers, where the measure is Average Door Open Count and Device is the selected
dimension against which to compare the values for this KPI.
● Cooler-12 has the highest Door Open Count (112), followed by Cooler-21 (132) and Cooler-37 (82).
● 63.4 is the average Door Open Count for all devices categorized as working coolers.
Procedure
KPI Modeling
1. In the launchpad, choose the Key Performance Indicator Model tile.
2. On the Key Performance Indicator Configuration page, choose the + icon in the left navigator.
3. In the Add KPI Name dialog box, enter the name of the KPI and choose OK.
4. On the Key Performance Indicator Details page under KPI Definition, enter the following information. See
Creating a KPI [page 135] for details.
Field
Description
Name
Display the KPI name you entered.
Description
Enter a description for the KPI. This value is displayed as the
title of the KPI (Working Cooler Analysis in the example).
Device Category
Choose a device category for the KPI. This field is required.
Measure
Choose a measure for the KPI. This field is required.
For more details, see Example: Creating Measures for KPIs
[page 51].
Select Increasing Trend to show the top three dimension val­
ues with the maximum measure value.
Type
Select Decreasing Trend to display the bottom three dimen­
sion values with the lowest measure value.
Enter a suffix to append to the measure value (63.4
Numbers in the example).
Unit of Measure/Suffix
5. Under KPI Filters, add boundary conditions as needed.
6. Save your changes.
Dimension View Visualization
7. In the launchpad, choose the Dimensional View Visualization tile.
8. On the Dimensional View Visualization page, choose the dimension detail page you want to edit. For details, see
Creating a Dimension [page 131].
9. On the KPI tab, choose Add New KPI.
10. In the Configure KPI dialog box, do the following:
138
Field
Description
Select KPI Name
Select the KPI to configure.
PUBLIC
SAP Connected Goods Implementation Guide
Key Performance Indicator (KPI) Modeling
Field
Description
Select Visualization Type
Select Comparison.
Select Dimension
Select the dimension. In the example, Device ID (Cooler-12 and so on) is
selected.
Select Time Period
Select the time period for which to calculate the KPI. In the example,
Last 10 Days is selected.
Select Unit
Select the suffix. In the example, Numbers is selected. This value is ap­
pended to the KPI aggregate value.
11. Choose Save.
12. On the KPI tab, save your changes.
16.4.2 Creating a KPI Tile with a Column Chart
Context
In this type of KPI tile, the chart visualizes KPI aggregate values over a selected time period.
This example visualizes Average Fill Level over the last 10 weeks.
Procedure
KPI Modeling
1. In the launchpad, choose the Key Performance Indicator Model tile.
2. On the Key Performance Indicator Configuration page, choose the + icon in the left navigator.
3. In the Add KPI Name dialog box, enter the name of the KPI and choose OK.
SAP Connected Goods Implementation Guide
Key Performance Indicator (KPI) Modeling
PUBLIC
139
4. On the Key Performance Indicator Details page under KPI Definition, enter the following information. See
Creating a KPI [page 135] for details.
Field
Description
Name
Display the KPI name you entered.
Description
Enter a description for the KPI. This value is displayed as the
title of KPI (FILLLEVEL ANALYSIS in the example).
Device Category
Choose a device category for the KPI. This field is required.
Measure
Choose a measure for the KPI. This field is required.
For more details, see Example: Creating Measures for KPIs
[page 51].
Choose Increasing Trend if an increase in the measure value
indicates an improved KPI.
Type
Choose Decreasing Trend if a decrease in the measure value
indicates an improved KPI.
For example, with a lower limit of 5 and an upper limit of 7, a
measure value of 10 indicates a success state for an in­
creasing trend, but a critical state for a decreasing trend.
Unit of Measure/Suffix
Enter a suffix to append to the average value displayed (3.9
Litres in the example).
Semantic coloring is enabled for the chart as follows:
○ If the KPI value is less than the lower limit, the column is displayed in red to indicate a critical state.
○ If the KPI value is between the upper and lower limits, the column is displayed in orange to indicate a
warning state.
○ If the KPI value is equal to or greater than upper limit, the column is displayed in green to indicating a
success state.
Note
This coloration applies to KPI with an increasing trend. For a decreasing trend, the color scheme is reversed.
5. Under KPI Filters, add boundary conditions as needed.
6. Save your changes.
Dimension View Visualization
7. In the launchpad, choose the Dimensional View Visualization tile.
8. On the Dimensional View Visualization page, choose the dimension detail page you want to edit. For details, see
Creating a Dimension [page 131].
9. On the KPI tab, choose Add New KPI.
10. In the Configure KPI dialog box, do the following:
140
Field
Description
Select KPI Name
Select the KPI to configure.
Select Visualization Type
Select Column.
PUBLIC
SAP Connected Goods Implementation Guide
Key Performance Indicator (KPI) Modeling
Field
Description
Select Time Period
Select the time period for which to calculate the KPI. In the example,
Last 10 Days is selected.
Select Unit
Select the suffix. In the example, Litres is selected. This value is ap­
pended to the KPI aggregate value.
11. Choose Save.
12. On the KPI tab, save your changes.
16.4.3 Creating a Device List Control Widget
Context
In this type of widget, the chart visualizes KPI performance by individual device for the top five devices. The KPI
value is displayed in a radial chart next to each image.
Procedure
KPI Modeling
1. In the launchpad, choose the Key Performance Indicator Model tile.
2. On the Key Performance Indicator Configuration page, choose the + icon in the left navigator.
3. In the Add KPI Name dialog box, enter the name of the KPI and choose OK.
4. On the Key Performance Indicator Details page under KPI Definition, enter the following information. See
Creating a KPI [page 135] for details.
Field
Description
Name
Display the KPI name you entered.
Description
Enter a description for the KPI. This value is displayed as the
title of KPI (FILLLEVEL ANALYSIS in the example).
Device Category
Choose a device category for the KPI. This field is required.
SAP Connected Goods Implementation Guide
Key Performance Indicator (KPI) Modeling
PUBLIC
141
Field
Description
Measure
Choose a measure for the KPI. The percentage measure in
the radial chart = <Measure Value>/Target *100
This field is required.
For more information, see Example: Creating Measures for
KPIs [page 51].
Choose Increasing Trend if an increase in the measure value
indicates an improved KPI.
Type
Choose Decreasing Trend if a decrease in the measure value
indicates an improved KPI.
Semantic coloring is enabled for the chart as follows:
○ If the KPI value is less than the lower limit, the column is displayed in red to indicate a critical state.
○ If the KPI value is between the upper and lower limits, the column is displayed in orange to indicate a
warning state.
○ If the KPI value is equal to or greater than upper limit, the column is displayed in green to indicating a
success state.
Note
This coloration applies to KPI with an increasing trend. For a decreasing trend, the color scheme is reversed.
5. Under KPI Filters, add boundary conditions as needed.
6. Save your changes.
Dimension View Visualization
7. In the launchpad, choose the Dimensional View Visualization tile.
8. On the Dimensional View Visualization page, choose the dimension detail page you want to edit. For details, see
Creating a Dimension [page 131].
9. On the Widget tab, choose Add New Widget.
10. In the Configure Widget dialog box, enter information as follows. All fields are required.
Field
Description
Widget Title
Enter a title for the widget.
Widget Description
Enter a description for the widget.
Widget Type
Select Device List Chart.
KPI
From the list, select the KPI that defines the measure.
Device Title Field
Select an attribute for the KPI label. (In the example, this value is displayed as
bin-3839.)
Alert Measure
Select a field to be displayed in the red alert bubble. (In the example, the selected
field is alerts.)
Sorting Order
Select Ascending Trend or Descending Trend.
Time Range
Select a time range for the widget.
11. Choose Save.
142
PUBLIC
SAP Connected Goods Implementation Guide
Key Performance Indicator (KPI) Modeling
12. On the KPI tab, save your changes.
16.4.4 Creating a KPI Tile with a Forecast Chart
Context
A forecast chart helps to visualize how much time it will take for a specific KPI value to reach a critical state. This
chart uses forecasted information powered by the machine learning algorithm.
Procedure
1. In the launchpad, choose the Machine Learning tile.
2. Choose the Dataset tab.
3. Enter information as indicated in the following examples.
SAP Connected Goods Implementation Guide
Key Performance Indicator (KPI) Modeling
PUBLIC
143
4. Choose the Service tab.
5. Enter information as indicated in the following examples.
6. In the launchpad, choose the Semantic Model tile.
7. On the Semantics Model page, save the new attributes and measures related to forecasting.
8. Choose Generate.
144
PUBLIC
SAP Connected Goods Implementation Guide
Key Performance Indicator (KPI) Modeling
9. In the launchpad, choose the Key Performance Indicator Model tile.
10. On the Key Performance Indicator Configuration page, choose the + icon in the left navigator.
11. Enter information as indicated in the following examples.
Note
The Lower Limit value set is used for plotting critical values in the forecast chart.
SAP Connected Goods Implementation Guide
Key Performance Indicator (KPI) Modeling
PUBLIC
145
16.4.4.1 Configuring a Forecast Chart
Context
This chart is used to compare two forecasted KPIs.
This chart can be configured using either Object Detail Configuration or Dimension View Visualization.
146
PUBLIC
SAP Connected Goods Implementation Guide
Key Performance Indicator (KPI) Modeling
Procedure
Configuring a Combination Chart Using Object Detail Configuration
1. In the launchpad, choose the Object Detail Configuration tile.
2. Choose the Sections tab.
3. In the Chart Configuration area, choose + Add to add a new chart configuration.
4. In the Qualifier column, select Forecast Chart.
5. Select KPIs with forecasted measures.
6. Select an appropriate Dimension parameter and the number of data points you want to display before the
forecasted points.
7. Save your changes.
Configuring a Combination Chart Using Dimension View Visualization
8. In the launchpad, choose the Dimensional View Visualization tile.
9. Choose the Widgets tab.
10. Choose Add New Widget.
11. For Widget Type, select Forecast Chart.
12. From the drop-down list, select an appropriate Dimension parameter.
13. Save your changes.
16.4.4.2 Configuring a Combination Chart
Context
A combination chart displays two KPI values in a chart, along with forecasted information powered by the machine
learning algorithm.
This chart can be configured using either Object Detail Configuration or Dimension View Visualization.
SAP Connected Goods Implementation Guide
Key Performance Indicator (KPI) Modeling
PUBLIC
147
Procedure
Configuring a Combination Chart Using Object Detail Configuration
1. In the launchpad, choose the Object Detail Configuration tile.
2. Choose the Sections tab.
3. In the Chart Configuration area, choose + Add to add a new chart configuration.
4. In the Qualifier column, select Combination.
5. Select KPIs with forecasted measures.
6. Select an appropriate Dimension parameter and the number of data points you want to display before the
forecasted points.
7. Save your changes.
Configuring a Combination Chart Using Dimension View Visualization
8. In the launchpad, choose the Dimensional View Visualization tile.
9. Choose the Widgets tab.
10. Choose Add New Widget.
11. For Widget Type, select Combination Chart.
12. Select two KPIs with forecasted measures.
13. From the drop-down list, select an appropriate Dimension parameter.
14. Save your changes.
148
PUBLIC
SAP Connected Goods Implementation Guide
Key Performance Indicator (KPI) Modeling
17
Data Ingestion Expert Mode
This section describes how to perform data ingestion in Expert mode.
17.1
Transformation Background
By default, SAP Connected Goods creates an entry in the
sap.iot.scb.cng.dataManagement::dataManagement.TRANSFORMATIONS (TRANSFORMATIONS) database
table for every device type and message type combination that exists. The naming convention for these default
transformations is <DEVICE TYPE NAME>__<MESSAGE TYPE NAME>_BASE. The purpose of these entries is to
define the mapping of the message type fields of the ingested data to the generic SAP Connected Goods KPI
database table columns. This is done primarily through an SQL statement that will be executed using Apache
Spark SQL.
During data ingestion, raw message data is grouped by device type and message type and stored in temporary
tables (Apache Spark SQL). The naming convention for these tables is <DEVICE TYPE NAME>__<MESSAGE TYPE
NAME>_CORE. Following this, the default SAP Connected Goods transformations are executed to produce another
set of temporary tables in Spark (_BASE tables). By default, _BASE tables are written to the SAP Connected Goods
KPI database tables.
Depending on the requirements of your business case, you can configure additional transformations to produce
and store calculated values (data enrichment) in addition to the fields of a message type. This can be done using
data in the _CORE tables, _BASE tables, and optionally using SAP Connected Goods application master data. The
coffeemaker scenario example does not require the configuration of additional transformations. If your business
case requires this, consult the topics in this section for more information.
17.2
Transformation Configuration
Context
You can configure new transformations by adding records to the TRANSFORMATIONS database table.
SAP Connected Goods Implementation Guide
Data Ingestion Expert Mode
PUBLIC
149
By default, the table will contain a default transformation for each SAP Connected Goods device type/message
type combination. In this example, SAP Connected Goods has mapped the field of message type MESSAGE from
device type SMART_DEVICE to the SAP Connected Goods KPI tables:
TID
DEVICE_TYPE
SMART_DEVICE SMART_DEVICE
__
MESSAGE_BASE
DEVICE_MESSAGE TRANS_ TYPE
_ TYPE
ORDINAL
MESSAGE
1
SQL
QUERY
SELECT
DEVICE_GUI
D ,
timestamp
as
TIMESTAMP
,
COL1 as
DD_INT_1 ,
COL2 as
DD_INT_2
FROM
`SMART_DEV
ICE__MESSA
GE_CORE`
Configure a new transformation that calculates the value of the expression COL1 + COL2 for the above device and
store it in the SAP Connected Goods KPI tables. COL1 and COL2 are fields in the message type MESSAGE.
Procedure
Using SQL, add the following entry to the TRANSFORMATIONS table:
insert into "sap.iot.scb.cng.dataManagement::dataManagement.TRANSFORMATIONS"
(tid,device_type_guid,device_message_type,trans_type,ordinal,query,created_by,create
d_time)
values
(SMART_COOLER_MESSAGE_NEW,SMART_COOLER,MESSAGE,SQL,2,'SELECT DEVICE_GUID ,
TIMESTAMP , (COL1+COL2) as DD_GEN_INT_3 FROM `SMART_DEVICE__MESSAGE_CORE`','<User
Id>',CURRENT_UTCTIMESTAMP)
17.2.1 TRANSFORMATIONS Table Reference
This table provides reference information on the columns that must be populated when adding an entry to the
TRANSFORMATIONS table.
150
PUBLIC
SAP Connected Goods Implementation Guide
Data Ingestion Expert Mode
Table Column
Description
Allowed Values
TID
The unique identifier for this transforma­ String
tion. A transformations result can be ref­
erenced by subsequent transformations
using this value as the table name (Spark
SQL).
DEVICE_TYPE_GUID
The device type name
String
DEVICE_MESSAGE_TYPE
The message type name
String
TRANS_TYPE
The type of transformation
The string SQL is the only allowed value
ORDINAL
Integer
The order of execution of the transfor­
mation. It is important to correctly order
transformations. Dependent result sets
are available when a transformation is in­
voked.
QUERY
The Apache Spark SQL statement that
defines a transformation
A string that must compile to a valid
Apache Spark SQL SELECT query.
Note
If the transformation will have an out­
put operation:
1.
Only SAP Connected Goods KPI
table column alias names con­
taining “GEN” (for example,
DD_GEN_INT_3,
DD_GEN_STR_1) can be used
when configuring custom trans­
formations.
2. The DEVICE_GUID columns
and TIMESTAMP columns must
be part of the result structure of
the transformation.
CREATED_BY
User ID of the creator
String
CREATED_TIME
Time of creation
UTC Timestamp
17.3
Transformations: Accessing Application Master Data
The database table sap.iot.scb.cng.dataManagement::dataManagement.INGESTION_CACHED_TABLES
(CACHED_TABLES) allows you to transport application master data entities to the ingestion pipeline for use in
transformations.
SAP Connected Goods Implementation Guide
Data Ingestion Expert Mode
PUBLIC
151
By default, the table contains a list of all available SAP Connected Goods master data tables. For example:
INT_NAME
EXT_NAME
COLUMN
S
FILTER CHECK_INTERVAL_ STATUS
SECS
ADDRESS
sap.iot.scb.cng.md::masterdat
a.ADDRESS
60
NONE
MDT_TABLE1
sap.iot.scb.cng.md::masterdat
a.MDT_TABLE1
60
NONE
17.3.1 Transporting Application Master Data to the Ingestion
Pipeline
Procedure
1. Using the following SQL, flag the table or tables to be transported:
update
"sap.iot.scb.cng.dataManagement::dataManagement.INGESTION_CACHED_TABLES"set
(columns,filter,check_interval_secs,status) = ('','','60','CACHED') where
int_name = '<Masterdata Table Name>';
2. Optionally, supply a comma-separated list of column names and a filter within the SQL to isolate specific data:
update
"sap.iot.scb.cng.dataManagement::dataManagement.INGESTION_CACHED_TABLES"set
(columns,filter,check_interval_secs,status) =
('COLUMN1,COLUMN2,COLUMN3',’COLUMN1=12345','60','CACHED') where int_name =
'<Masterdata Table Name>';
3. The table will be transported to the ingestion pipeline. You can view transport progress by choosing the
Ingestion Logs tile on the SAP Connected Goods launchpad. Once the load is complete, the table will be
available for use in transformations. It can be referenced using the value from the INT_NAME column of
CACHED_TABLES.
152
PUBLIC
SAP Connected Goods Implementation Guide
Data Ingestion Expert Mode
17.3.2 Removing Application Master Data from the Ingestion
Pipeline
Procedure
Using the following SQL, flag the table or tables to be removed from the ingestion pipeline:
update "sap.iot.scb.cng.dataManagement::dataManagement.INGESTION_CACHED_TABLES"set
(columns,filter,check_interval_secs,status) = ('','','60','NONE') where int_name =
'<Masterdata Table Name>';
17.3.3 CACHED_TABLES Reference
The following table provides reference information for the columns that can be updated in CACHED_TABLES.
Table Column
Description
COLUMNS
A list of column names used to restrict
A comma-separated list of column
the amount of data transported to the in­ names from the database table
gestion pipeline
FILTER
A filter used to restrict the amount of
data transported to the ingestion pipe­
line
The filter must be a valid SQL predicate
for accessing the database table
CHECK_INTERVAL_SECS
The interval (in seconds) at which the
validity of the records cached in the in­
gestion pipeline is checked against the
values in the database
An integer value
STATUS
Flags the database table for transport to
the ingestion pipeline
A string: CACHED or NONE
17.4
Allowed Values
Transformations: Configuring Output Operations
Context
Output operations enable the results of a transformation to be written to the SAP Connected Goods KPI tables.
Output operations are configured in the
SAP Connected Goods Implementation Guide
Data Ingestion Expert Mode
PUBLIC
153
sap.iot.scb.cng.dataManagement::dataManagement.TRANSFORMATION_OUTPUTS (OUTPUTS) database
table.
You must configure the output of a transformation to the SAP Connected Goods KPI tables. The following
procedure configures the outputs for the transformation SMART_DEVICE__MESSAGE_NEW that was created in the
previous section.
Procedure
Using SQL, create the following two entries in the OUTPUTS database table:
insert into "sap.iot.scb.cng.dataManagement::dataManagement.TRANSFORMATION_OUTPUTS"
(tid,view_name,destination,category,write_type,key) values
('SMART_DEVICE__MESSAGE_NEW','sap.iot.scb.cng.md::devicedata.DEVICE_DATA','HANA','CO
RE','INSERT','');
insert into "sap.iot.scb.cng.dataManagement::dataManagement.TRANSFORMATION_OUTPUTS"
(tid,view_name,destination,category,write_type,key) values
('SMART_DEVICE__MESSAGE_NEW','sap.iot.scb.cng.md::devicedata.DEVICE_DATA_LATEST_VALU
ES','HANA','CORE','UPSERT-NOT-NULL','DEVICE_GUID');
Note
When inserting rows into the OUTPUTS table, the only variable column value is the value inserted to the TID
column. All other column values must be populated as indicated in the procedure above.
154
PUBLIC
SAP Connected Goods Implementation Guide
Data Ingestion Expert Mode
18
CPI iFlows and Setup
18.1
Predelivered CPI iFlows
The following Cloud Platform Integration (CPI) iFlows are delivered as part of SAP Connected Goods.
1. Post Service Notifications to C4C
This iFlow makes an OData service call to SAP Cloud for Customer (C4C) to create a service request.
The iFlow is triggered from the action of a rules framework. This service accepts a payload from the action of a
rules framework and calls an OData service in C4C. The payload should be in a valid Service Notification Creation
format (for example, the ServiceRequestCollection, ServiceRequestDescriptionCollection, or
ServiceRequestItemCollection entity sets). This is a passthrough iFlow and the response from C4C is
passed directly back to SAP Connected Goods. SAP Connected Goods consumes this to handle the downstream
logging and processes. This iFlow service is called from an action configured in SAP Connected Goods.
Config Parameters Used
PID
Parameter
CNG
ServicePost (Value should be
ServiceNotificationPost)
ServiceNotificationPost
URL (C4C URL including entity set)
ServiceNotificationPost
Credentials
Where Used
In Action configuration
Source Systems
Cloud for Customer (C4C)
Adapters
http sender/receiver
2. Post Salesorder to ECC
This iFlow makes an OData service call to the ECC gateway system to create a sales order in an ECC back-end
system.
The iFlow is triggered from the action of a rules framework. This iFlow service accepts a payload from the action of
a rules framework and calls an OData service in the ECC gateway system. The gateway OData service uses
BAPI_SALESORDER_CREATEFROMDAT2.
SAP Connected Goods Implementation Guide
CPI iFlows and Setup
PUBLIC
155
This iFlow has the following prerequisite:
● The gateway service must be configured in a gateway system connected to the back-end ECC system
where sales orders are created. This gateway service must map the inbound fields to the ECC BAPI input
structures and should map the outbound structures and return table.
This iFlow service is called from an action configured in SAP Connected Goods.
Config Parameters Used
PID
Parameter
CNG
SalesOrderPost
SalesOrderPost
URL (Gateway service URL)
SalesOrderPost
Query
SalesOrderPost
Credentials
Where Used
In Action configuration
Calls
None
Source Systems
ECC (through a gateway service)
Adapters
http sender/receiver
Prerequisite
An OData service using
BAPI_SALESORDER_CREATEFROMDAT2 must exist in the
gateway server connected to ECC
3. Post Consignment SO to ECC
This iFlow makes an RFC call using the CPI RFC sender adapter to create a sales order in an ECC back-end system.
This iFlow is triggered from the action of a rules framework. The service accepts a payload from the action of a
rules framework and calls BAPI_SALESORDER_CREATEFROMDAT2 / ZRFC_SALESORDER_CREATEFROMDAT2 in the
back-end ECC gateway system.
This is not strictly a consignment order creation iFlow. Depending on the value in the Document Type (DocType)
field in the payload, different types of orders can be created, such as TA for a standard sales order or KB for
consignment orders. This mapping step in the iFlow maps the inbound fields in the payload to the ECC BAPI input
structures. Depending on the business scenario, applicable fields from the payload can be mapped to the relevant
ECC BAPI input structures to ensure that the back-end order has all the required attributes.
The BAPIRETURN table is returned from the back end to the sender. This iFlow service is called from an action
configured in SAP Connected Goods.
Config Parameters Used
Externalized Parameter
Parameter
RFC Destination
{{Receiver_destination_0}}
Where Used
In Action configuration
156
PUBLIC
SAP Connected Goods Implementation Guide
CPI iFlows and Setup
Calls
None
Source Systems
ECC
Adapters
http sender/RFC receiver
4. Post Purchase Requisition to ECC
This iFlow makes an RFC call using the CPI RFC sender adapter to create a purchase requisition in an ECC backend system. This iFlow is triggered from the action of a rules framework. The service accepts a payload from the
action of a rules framework and calls BAPI_REQUISITION_CREATE in the back-end ECC gateway system.
This mapping step in the iFlow maps the inbound fields in the payload to the ECC BAPI input structures.
Depending on the business scenario, applicable fields from the payload can be mapped to the relevant ECC BAPI
input structures to ensure that the back-end order has all the required attributes.
The BAPIRETURN table is returned from the back end to the sender. This iFlow service is called from an action
configured in SAP Connected Goods.
Where Used
In Action configuration
Calls
None
Source Systems
ECC
Adapters
http sender/RFC receiver
5. Post Waste Order to ECC
This iFlow makes an RFC call using the CPI RFC sender adapter to create a waste order in an ECC back-end
system. This iFlow is triggered from the action of a rules framework. This service accepts a payload from the
action of a rules framework and calls BAPI_WASTEORDER_CREATEFROMDATA in the back-end ECC gateway
system.
This mapping step in the iFlow maps the inbound fields in the payload to the ECC BAPI input structures.
Depending on the business scenario, applicable fields from the payload can be mapped to the relevant ECC BAPI
input structures to ensure that the back-end order has all the required attributes.
The BAPIRETURN table is returned from the back end to the sender. This iFlow service is called from an action
configured in SAP Connected Goods.
Where Used
In Action configuration
Calls
None
Source Systems
ECC
Adapters
http sender/RFC receiver
SAP Connected Goods Implementation Guide
CPI iFlows and Setup
PUBLIC
157
6. Post Purchase Order to ECC
This iFlow makes an RFC call using the CPI RFC sender adapter to create a purchase order in an ECC back-end
system. This iFlow is triggered from the action of a rules framework. The service accepts a payload from the action
of a rules framework and calls BAPI_PO_CREATE1/ ZBAPI_PO_CREATE1 in the back-end ECC gateway system.
This mapping step in the iFlow maps the inbound fields in the payload to the ECC BAPI input structures.
Depending on the business scenario, applicable fields from the payload can be mapped to the relevant ECC BAPI
input structures to ensure that the back-end order has all the required attributes.
The BAPIRETURN table is returned from the back end to the sender. This iFlow service is called from an action
configured in SAP Connected Goods.
Where Used
In Action configuration
Calls
None
Source Systems
ECC
Adapters
http sender/RFC receiver
7. Post Inventory Levels
This iFlow makes an IDOC call using the IDOC adapter to create inventory levels in an ECC back-end system. This
iFlow is triggered from the action of a rules framework. The service accepts a payload from the action of a rules
framework and calls AOPOST IDOC in the back-end ECC gateway system.
This mapping step in the iFlow maps the inbound fields in the payload to the ECC BAPI input structures.
Depending on the business scenario, applicable fields from the payload can be mapped to the relevant ECC BAPI
input structures to ensure that the back-end order has all the required attributes.
The IDOC created in the back-end ECC system is returned from the back end to the sender. This iFlow service is
called from an action configured in SAP Connected Goods.
Config Parameters Used
PID
Parameter
CNG
StockLevelPost (Value should be CnG_StockLevelPost)
CnG_StockLevelPost
URL
CnG_StockLevelPost
Credentials
Where Used
In Action configuration
Calls
None
Source Systems
ECC
Adapters
IDOC Adapter
158
PUBLIC
SAP Connected Goods Implementation Guide
CPI iFlows and Setup
8. GET_HYBRIS_CAMPAIGNS
This iFlow is responsible for pulling all the campaigns, target groups, and Business Partner (Interaction Contact)
details from the Hybris_Marketing_Cloud system. This iFlow (which is called by
GET_HYBRIS_CAMPAIGN_MAPPING) makes an OData service call to the SAP Hybris Marketing Cloud system and
retrieves the campaign, target group, and associated Business Partner details.
This iFlow is internally called by GET_HYBRIS_CAMPAIGN_MAPPING, which is called from an action configured in
SAP Connected Goods.
Config Parameters Used
PID
CNG
Parameter
CampaignsRead (Value should be
CNG_Hybris_Campaigns_read)
CNG_Hybris_Campaigns_read
URL1
CNG_Hybris_Campaigns_read
URL2
CNG_Hybris_Campaigns_read
URL3
CNG_Hybris_Campaigns_read
Credentials
Where Used
In GET_HYBRIS_CAMPAIGN_MAPPING iFlow
Calls
None
Source Systems
SCI
Adapters
http
Prerequisite
SCI credentials maintained for the host
9. GET_HYBRIS_CAMPAIGN_MAPPING
This iFlow uses GET_HYBRIS_CAMPAIGNS to get the entity set for multiple requests at the same time. This iFlow
handles requests in the payload for multiple Business Partners at the same time. The service is called from an
action configured in SAP Connected Goods.
Config Parameters Used
PID
Parameter
hciself
Host
hciself
Credentials
Where Used
In Action configuration
Calls
None
Source Systems
SAP Hybris Marketing Cloud
SAP Connected Goods Implementation Guide
CPI iFlows and Setup
PUBLIC
159
Adapters
http Adapter
Prerequisite
Credentials are maintained for the SAP Hybris Marketing
Cloud system in SCI. Communication arrangements are main­
tained in the configuration for SAP Hybris Marketing Cloud, as
described in Integrating with SAP Hybris Marketing Cloud
[page 116].
18.2 Setting up Predelivered CPI iFlows
Context
The Partner Directory functionality of CPI is used to store configurations.
The Partner ID is used to group parameters and values. The source systems and business documents are
designated as Partner IDs and the parameters used in the iFlows are configured as Parameter IDs along with
values. The predelivered Partner ID (PID) and Parameter ID (ID) names must not be changed, as they are
referenced within each iFlow. Only values can be changed. The Partner Directory values can be deleted or set by a
predelivered iFlow such as the following:.
https://{cpi-tenant}-iflmap.hcisb.int.sap.hana.ondemand.com/http/pd/
delete_and_set_config_params
To delete a PID, use the following request-body as an example:
{"Pid":"HCISELF2"}
To delete a PID and ID, use the following request-body as an example:
{"Pid":"HCISELF3", "Id":"hosturl" }
{"Pid":"HCISELF2", "Id":"hosturl" }
To set a PID and ID, use the following request-body as an example:
{"Pid":"HCISELF2",
{"Pid":"HCISELF2",
{"Pid":"HCISELF3",
{"Pid":"HCISELF4",
}
"Id":"hosturl1", "Value":"https://abc.uvw.com" }
"Id":"hosturl2", "Value":"https://pqr.xyz.com" }
"Id":"hosturl", "Value":"https://abc.uvw.com" }
"Id":"hosturl", "Value":"https://cat.xyz.com" }
The predelivered configuration file is as follows:
{"Pid":"hciself", "Id":"host","Value":"https://{cpi}iflmap.hcisb.int.sap.hana.ondemand.com:443/"}
{"Pid":"hciself", "Id":"credentials","Value":"xxxxx"}
{"Pid":"CNG", "Id":"Service", Value":"ServiceNotif"}
{"Pid":"CNG", "Id":"SalesOrderPost", "Value":"SalesOrderPost"}
{"Pid":"SalesOrderPost", "Id":"url", "Value":"{ECC gateway Odata service URL to
create sales order}"}
{"Pid":"SalesOrderPost", "Id":"query", "Value":"sap-client=xxx&sap-language=EN"}
160
PUBLIC
SAP Connected Goods Implementation Guide
CPI iFlows and Setup
{"Pid":"SalesOrderPost", "Id":"credentials", "Value":"xxx"}
{"Pid":"CNG", "Id":"ServicePost", "Value":"ServiceNotificationPost"}
{"Pid":"ServiceNotificationPost", "Id":"url", "Value":"{C4C host name}/sap/c4c/
odata/v1/c4codata/ServiceRequestCollection}"
{"Pid":"ServiceNotificationPost", "Id":"credentials", "Value":"C4CUSER"}
{"Pid":" CNG ", "Id":" StockLevelPost ", "Value":"CnG_StockLevelPost"}
{"Pid":" CnG_StockLevelPost ", "Id":"url ", "Value":"Ecc IDOC Post URL to create
Inventory "}
{"Pid":" CnG_StockLevelPost ", "Id":" Credentials ", "Value":"xxxx"}
{"Pid":"CNG","Id":"CampaignsRead","Value":"CNG_Hybris_Campaigns_read"}
{"Pid":"CNG_Hybris_Campaigns_read","Id":"URL1","Value":"{Hybris System URL}/sap/opu/
odata/sap/API_MKT_INTERACTION_CONTACT_SRV/InteractionContacts"}
{"Pid":"CNG_Hybris_Campaigns_read","Id":"URL2","Value":"{Hybris System URL}/sap/opu/
odata/SAP/API_MKT_TARGET_GROUP_SRV/TargetGroupInteractionContacts"}
{"Pid":"CNG_Hybris_Campaigns_read","Id":"URL3","Value":"{Hybris System URL}/sap/opu/
odata/sap/API_MKT_CAMPAIGN_SRV/Campaigns"}
{"Pid":"CNG_Hybris_Campaigns_read","Id":"credentials","Value":" xxxx "}
The source systems accessed by the iFlows are:
● SAP Cloud for Customer (C4C)
● SAP ECC
● SAP HYBRIS Marketing Cloud
Procedure
Copy and Deploy the Integration Content
1. Launch the SAP Cloud Platform Integration (CPI) web-based application.
2. On the Discover page, locate your package and select it to navigate to the details page:
○ Package name: Connected Goods 1709 iFlow Templates
3. Select Copy and then navigate to the Design page.
Post-Deployment Steps
4. Verify that system.jks is set up in the CPI tenant.
5. For on-premise ECC, configure the Cloud Connector settings.
6. Create the necessary user credentials in CPI for the following:
○ CPI tenant own credentials: Technical user
○ IBP: Technical user to access C4C to run the OData service and read key figures
○ ECC: OData service credentials, if necessary
○ Hybris Marketing Cloud: Hybris system OData service credentials
7. Set the partner directory for credentials for the own CPI tenant using any RESTAPI client, such as POSTMAN.
a. POST the PID, parameter, and values for the following parameters using the following URL, for the first
time:
○ https://{CPI tenant}-tmn.xxxxx.hana.ondemand.com/api/v1/StringParameters
○ {"Pid":"hciself", "Id":"tmnurl","Value":"https://{CPI tenant}tmn.xxxxx.hana.ondemand.com"}
○ {"Pid":"hciself", "Id":"credentials","Value":"xxxxxx"}
8. Set other Partner ID, Parameters, and values in the partner directory using a configuration file as per the
landscape. Use the following iFlow to set PD:
SAP Connected Goods Implementation Guide
CPI iFlows and Setup
PUBLIC
161
○ https://{cpi-tenant}-iflmap.xxxxx.sap.hana.ondemand.com/http/pd/
delete_and_set_config_params.
18.3 Predelivered Configurations
Partner ID
Parameter ID
HCISELF
Remarks
Where Used
Refers to the own CPI tenant
host
Refers to the own CPI tenant URL Set using PID API.
credentials
Refers to the own CPI tenant cre­
dentials
Create the credentials
for own tenant as part
of initial setup. Set us­
ing PID API.
Tmnurl
Refers to Tenant management
node URL
Set using PID API.
CNG
CNG-related IDs
ServiceNotific
ationPost
Refers to the ID of Service Notifi­
cation­related parameters
SalesOrderPost
Refers to the ID of Sales Order-re­ Represents another
lated parameters
Partner ID where re­
lated parameters are
grouped
CampaignsRead
Refers to the ID of Hybris Cam­
paign-related parameters for
Business Partners in SAP Con­
nected Goods
url
C4C OData service host URL to
create service request
credentials
User credential for C4C access
Represents another
Partner ID where re­
lated parameters are
grouped
As a prerequisite, must
be created in CPI
Sales Order-related IDs
SalesOrder
Post
PUBLIC
Represents another
Partner ID where re­
lated parameters are
grouped.
Service Notification­related IDs
ServiceNot
ificationP
ost
162
Description
url
ECC gateway URL to create sales
order
query
Any query parameters
credentials
ECC system credentials
As a prerequisite, must
be created in CPI
.
SAP Connected Goods Implementation Guide
CPI iFlows and Setup
Partner ID
Parameter ID
Description
URL1
Hybris OData service URL to get
Interaction Contact (Business
Partner) details
URL2
HyHybris OData service URL to
get Target Groups for the fetched
Interaction Contact
URL3
Hybris OData service URL to get
Campaign Details for the fetched
Interaction Contact and Target
Groups
credentials
Hybris Marketing Cloud system
credentials
Remarks
Where Used
CNG_Hybris
_Campaigns
_read
SAP Connected Goods Implementation Guide
CPI iFlows and Setup
Must already be cre­
ated in CPI
PUBLIC
163
19
Configuring an External Server and
Workflow
Configuring the external server enables you to obtain the following data:
● Current sensor and location-related data for a device (using the Refresh option)
● Device details (using the Device Action option)
● Location data (using the Find Device option)
19.1
Configuring the Server
Context
To configure the external server, provide the server URL and credentials as follows:
Procedure
1. Launch SAP Connected Goods.
2. In the launchpad, choose the Settings tile.
3. Choose External Interfaces.
4. Choose Edit.
164
PUBLIC
SAP Connected Goods Implementation Guide
Configuring an External Server and Workflow
5. Under DeviceData, configure device data APIs and credentials as follows:
Field
Value
API to Get Device Data
In the text box, enter the external API URL.
Sample API format to get device data:
{DEVICE_DATA_API}/{deviceId}
Note
{deviceId} is mandatory in the URL.
Username
In the text box, enter the user name. This field is required.
Password
In the text box, enter the password. This field is required.
6. Under DeviceLocation, configure device location APIs and credentials as follows:
Field
Value
API to Get Device Location
In the text box, enter the external API URL.
Sample API format to get the device location:
{{DEVICE_LOCATION API}/{deviceId}/
location
Note
{deviceId} is mandatory in the URL.
Username
In the text box, enter the user name. This field is required.
Password
In the text box, enter the password. This field is required.
7. Save your changes.
19.2 Viewing Device Action and Find Device
Prerequisites
The external server API and its credentials must be configured as described in Configuring the Server [page 164].
If the external server is not configured, you will see an error message when you perform the following steps.
SAP Connected Goods Implementation Guide
Configuring an External Server and Workflow
PUBLIC
165
Procedure
1. Launch SAP Connected Goods.
2. In the launchpad, choose the Connected Goods tile.
3. Go to
Overview Page
Object Detail Page .
4. Do one of the following:
○ To see device data, choose the ellipsis icon and then choose the Device Action link in the Actions menu.
○ To see the device location, choose Find Device in the mini map.
19.3 External Server Response
Response Code
Description
200
Success
Response Body
{
transactionId:
"99a1912b8c1b581cb3b720b279397429"
}
Note
If the client receives response code 200, the success message
Device message has been triggered is displayed.
400
Bad request
500
Internal server error
No Content
{
}
403
Forbidden
"message": "An error has occurred"
{
"message": "You're not authorized to
perform this request"
}
166
PUBLIC
SAP Connected Goods Implementation Guide
Configuring an External Server and Workflow
19.4 Refreshing Data
Context
Refresh the device data and device location as follows.
Procedure
1. In the launchpad, choose the Connected Goods tile.
2. Go to the Object Detail page by choosing a grid tile in the Grid View or a Device ID in the Table View.
3. Do one of the following:
○ To refresh device data, choose the ellipsis icon and then choose the Device Action link in the Actions menu.
○ To refresh the device location, choose Find Device in the mini map.
4. In the Object Detail page, choose Refresh.
5. Verify that the Object Detail page displays the refreshed data.
SAP Connected Goods Implementation Guide
Configuring an External Server and Workflow
PUBLIC
167
20 Application Readiness
After you have completed all the procedures in this guide, SAP Connected Goods is ready to support your business
use cases. See the SAP Connected Goods 3.0 User Guide for information about using the application.
168
PUBLIC
SAP Connected Goods Implementation Guide
Application Readiness
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.
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.
Internet Hyperlinks
The SAP documentation may contain hyperlinks to the Internet. 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:
https://help.sap.com/viewer/disclaimer).
SAP Connected Goods Implementation Guide
Important Disclaimers and Legal Information
PUBLIC
169
go.sap.com/registration/
contact.html
© 2018 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 construed 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 https://www.sap.com/corporate/en/legal/copyright.html
for additional trademark information and notices.
Download PDF
Similar pages