configuration of sap predictive maintenance and service ... · sap predictive maintenance and...

Configuration Information PUBLIC

SAP Predictive Maintenance and Service, on-premise edition 1.0 FP03Document Version: 1.00 – 2017-08-18

Configuration of SAP Predictive Maintenance and Service, on-premise edition 1.0

Content

1 Document History. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2 Configuring SAP Predictive Maintenance and Service, on-premise edition 1.0. . . . . . . . . . . . . . . . 62.1 Configuring Thing Model Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Configuration Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Create a Package. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Read a Package. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Update a Package. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22Delete a Package. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Value Data Types for Property Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Naming Conventions for IoT Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27HTTP Status Codes for Configuration Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Thing Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Create a Thing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Read a Thing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31Read All Things. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32Update a Thing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34ISO Language Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34Delete a Thing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36HTTP Status Codes for Thing Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

2.2 Managing Machine Learning Engine Using Configuration UIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Custom Algorithms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Entries to Create a Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Model-Specific Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Normalization of Scores. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

2.3 Managing Machine Learning Engine Using REST APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Custom Algorithms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55Create a Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Train a Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Score a Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Check the Status of a Training Job or Scoring Job. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Delete a Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Read Information About All Algorithms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

2.4 Scheduling Regular Scoring of a Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 782.5 Creating Custom Algorithms Using the Launchpad. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Entries to Create a Custom Algorithm. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 822.6 Creating Custom Algorithms Using REST APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

2 P U B L I CConfiguration of SAP Predictive Maintenance and Service, on-premise edition 1.0

Content

Create a Custom Algorithm. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Delete a Custom Algorithm. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

2.7 Configuring the Insight Provider Catalog Using REST APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93Create Insight Provider Entries in the Catalog. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93Read an Insight Provider Entry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Read All Insight Provider Entries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Read an Insight Provider Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Read All Insight Provider Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Delete an Insight Provider Entry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103Delete an Insight Provider Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

2.8 Configuring Insight Providers Using Configuration UIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104Creating Key Figures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106Creating Key Figure Sets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Entries to Configure the Asset Explorer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Entries to Configure Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119Entries to Configure Work Activities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Entries to Configure Derived Signals. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Entries to Configure the Map. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124Entries to Configure the 2D Chart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132Entries to Configure the 3D Chart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134Entries to Configure the Asset and Component Scores. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

2.9 Configuring Insight Providers Using REST APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140Retrieve a CSRF Token. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .141Configuring Key Figures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141Manage Configurations of Insight Providers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .163Manage Configurations of Insight Providers Variants. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225Insight Provider Values for Base URI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .242

2.10 Checking Configurations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2432.11 Configuring Thing Hierarchy Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .244

Create Thing Hierarchy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245Update (PATCH) Hierarchy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248Delete Hierarchy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .250Read Thing Hierarchy/Hierarchies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

Configuration of SAP Predictive Maintenance and Service, on-premise edition 1.0Content P U B L I C 3

1 Document History

CautionBefore you start the configuration, make sure you have the latest version of this document. You can find the latest version at the following location: https://help.sap.com/viewer/136b5b20c3bf4896ab373e3b757b30c5/1.0.3/en-US

TipYou might need to refresh your browser to see the latest version of this document.

The following table provides an overview of the most important document changes:

Table 1:

Version Date Description

1.0.4 2017-08-17 Updated chapters:

● Entries to Configure the 2D Chart [page 132]

● Configuration Parameters per Insight Provider [page 167]

● Document History [page 4]

1.03 2017-07-06 Updated chapters:

● Document History [page 4]● Delete a Model [page 76]


● Scheduling Regular Scoring of a Model [page 78]


Document History

https://help.sap.com/viewer/136b5b20c3bf4896ab373e3b757b30c5/1.0.3/en-US

https://help.sap.com/viewer/136b5b20c3bf4896ab373e3b757b30c5/1.0.3/en-US

Version Date Description


● All chapters referring to role collections: Updated role collection names

Removed chapters:

● REST API endpoints:

○ DELETE: /variants/<variantId>/config

○ DELETE: /variants/<variantId>/i18n

○ DELETE, GET, PUT: /variants/<variantId>/i18n/<language>/<key>

Uop

1.00

2017-03-15 Initial Version

Configuration of SAP Predictive Maintenance and Service, on-premise edition 1.0Document History P U B L I C 5

2 Configuring SAP Predictive Maintenance and Service, on-premise edition 1.0

Context

To configure SAP Predictive Maintenance and Service, on-premise edition 1.0, it is recommended to follow the configuration order described in this chapter.

Procedure

1. Create packages as described in the chapter Create a Package [page 9].2. Configure the machine learning engine either using the UI configuration tools or the configuration REST APIs.

○ Configuration using UI configuration tools [page 38]○ Configuration using REST APIs [page 54]

3. Configure the Insight Provider Catalog using configuration REST APIs as described in the chapter Configuring the Insight Provider Catalog Using REST APIs [page 93].

4. Configure insight providers either using the UI configuration tools or the configuration REST APIs.

○ Configuration using UI configuration tools [page 104]○ Configuration using REST APIs [page 140]

5. Check the effects of your configurations on business users as described in the chapter Checking Configurations [page 243].

6. Create things, which can be assets or components as described in the chapter Create a Thing [page 29].

2.1 Configuring Thing Model Services

Before you can start configuring all other software components of SAP Predictive Maintenance and Service, on-premise edition, you need to configure IoT application services first.

Prerequisites

The following role collection is assigned to your user:


Configuring SAP Predictive Maintenance and Service, on-premise edition 1.0

● <pdms_config_user>

For more information about role collections, see the chapters Maintaining Roles and Users in SAP HANA and Role Templates for SAP Predictive Maintenance and Service, on-premise edition in the guide Installation of SAP Predictive Maintenance and Service, on-premise edition 1.0.

Context

You configure the thing model services using REST APIs. To work with SAP Predictive Maintenance and Service, on-premise edition, you need to configure the Configuration services and the Thing services.

For more information about the services, see:

● Configuration Services [page 8]● Thing Services [page 29]

Procedure

1. Configure the Configuration services. The following steps provide you with instructions on certain actions.a. Create a Package [page 9]b. Read a Package [page 17]c. Update a Package [page 22]d. Delete a Package [page 24]

More information:○ Value Data Types for Property Types [page 25]○ Naming Conventions for IoT Objects [page 27]○ HTTP Status Codes for Configuration Services [page 29]

2. Configure the Thing services. The following steps provide you with instructions on certain actions.a. Create a Thing [page 29]b. Read a Thing [page 31]c. Read All Things [page 32]d. Update a Thing [page 34]e. Delete a Thing [page 36]

More information:○ ISO Language Codes [page 34]○ HTTP Status Codes for Thing Services [page 37]

Configuration of SAP Predictive Maintenance and Service, on-premise edition 1.0Configuring SAP Predictive Maintenance and Service, on-premise edition 1.0 P U B L I C 7

2.1.1 Configuration Services

The configuration services are used to manage the configuration of the Thing model in the form of packages. A package is a logical group of meta-data objects like thingTypes, propertySetTypes, properties and so on.

ExampleIndustrial Robot

Consider an example of an industrial robot as a thing. Industrial robots can be used in a production line of a car manufacturing plant. It can have different components such as a motor drive, hydraulic piston, and so on. These components carry sensors that provide relevant data about the robot at specific time intervals.

The configuration service is used to model things. These are the types of data that can be stored and read using the Thing service. Consider the motor drive component of the robot. The motor drive can have different signals from the sensors such as temperature, power consumption, motor status or rotations per minute. The data that comes from these sensory devices can have different properties (such as temperature, power consumption) and units of measure (K, KWHr). This forms the basic atom of a thing known as propertySetType.

There can be many types of such industrial robots. A thing type contains an array of property set types. A robot of Type A can contain both property set types (example, motor drive and piston) while another robot of Type B may contain only one of the property set types (example, motor drive).

Car Manufacturer

Consider an example of a car manufacturer where the task is to monitor the performance of all manufactured cars out of the assigned production line. Cars of different models (example, ABC2Series, ABCXSeries) produced by this manufacturer can have some attributes that are similar. In such case, each car model can be modelled as a thingType containing many propertySetTypes that in turn contain properties.

Few of the properties such as body style, class, wheel base can be master data that corresponds to non-timeseries data. Few of the properties such as pressure and temperature of a wheel can correspond to timeseries data (data that changes with time very frequently while the car is in operation).

The graphic below shows a model of a package that contains two thingTypes. One for each model - ABC2Series and ABCXSeries. Both the models re-use propertySetTypes defined once called "Car" and "Engine" that contain master data Properties. Both models re-use propertySetTypes defined once called "Wheel" and "DriveUnit" that contain timeseries Properties like Rotation Speed, Power Consumption, Pressure and Temperature. Having defined the model in a package, one can create instances of a thingType. An instance of a thingType in the example can be a car with a registration number: RA KL 8136, color: Black

Packages

The following diagram illustrates a package as an example. This package contains two thingTypes; one for each car model. Both these car models reuse propertySetTypes Car and Engine that contain master data properties. They also reuse propertySetTypes Wheel and DriveUnit that contain timeseries properties such as rotation speed, power consumption, pressure and temperature. Since all these objects are defined in one package, you can create instance of a thingType. An instance of a thingType in the example can be a car with a registration number <abc> and color as black.



2.1.2 Create a Package

This configuration service is used to create a package. It is used to call the Thing services to create the thing types, property set types and so on. The default scope for a package is always set to private.

The scope is used to determine if the package is public or private.

NoteThe Thing model allows to reuse property set types across different packages. This means, a package can contain the definition of a property set type. This package is the base package. Other packages can now declare a dependency on this base package and reuse its property set type in their own thing types.


Note● A package can depend on another package. This is possible only if the scope of the latter package defines it

as public.● If you create a package that depends on another package, this service verifies that the property set types

referred to are defined in the package on which your package depends.● When you create a package that depends on another package, you can use only the latest version of the

latter package.

Request

URI:http://<hostname>:<port>/platform/thing-model/api/v1/config/Configuration

HTTP Method:POST

Request Example

{ "schema": { "type": "ConfigurationPackage" }, "version": "1.0.0", "id": "core.automobiles", "dependencies": [], "description": { "en": "Automobiles package" }, "scope": "public", "services": { "dataService": { "thingTypes": [{ "name": "core.automobiles:ABC2Series", "description": { "en": "ABC 2 Series car" }, "propertyTypes": [{ "id": "engine", "description": { "en": "Engine Usage", "de": "Motornutzung" }, "propertySetType": "core.automobiles:Engine" }, { "id": "drive_fr", "description": { "en": "Drive Unit Front Right" }, "propertySetType": "core.automobiles:DriveUnit" }, { "id": "drive_fl", "description": { "en": "Drive Unit Front Left" }, "propertySetType": "core.automobiles:DriveUnit" }, { "id": "car", "description": { "en": "Car Usage" },



"propertySetType": "core.automobiles:Car" }, { "id": "wheel_fr", "description": { "en": "Wheel front right", "de": "vorderes rechtes Rad" }, "propertySetType": "core.automobiles:Wheel" }, { "id": "wheel_fl", "description": { "en": "Wheel front left", "de": "vorderes linkes Rad", "ru": " переднее левое колесо" }, "propertySetType": "core.automobiles:Wheel" }, { "id": "wheel_rr", "description": { "en": "Wheel rear right" }, "propertySetType": "core.automobiles:Wheel" }, { "id": "wheel_rl", "description": { "en": "Wheel rear left" }, "propertySetType": "core.automobiles:Wheel" }] }, { "name": "core.automobiles:ABCXSeries", "description": { "en": "ABC X Series Car" }, "propertyTypes": [{ "id": "engine", "description": { "en": "Engine Usage" }, "propertySetType": "core.automobiles:Engine" }, { "id": "drive_fr", "description": { "en": "Drive Unit Front Right" }, "propertySetType": "core.automobiles:DriveUnit" }, { "id": "drive_fl", "description": { "en": "Drive Unit Front Left" }, "propertySetType": "core.automobiles:DriveUnit" }, { "id": "car", "description": { "en": "Car Usage" }, "propertySetType": "core.automobiles:Car" }, { "id": "wheel_fr", "description": { "en": "Wheel front right" }, "propertySetType": "core.automobiles:Wheel" }, { "id": "wheel_fl", "description": { "en": "Wheel front left"


}, "propertySetType": "core.automobiles:Wheel" }, { "id": "wheel_rr", "description": { "en": "Wheel rear right" }, "propertySetType": "core.automobiles:Wheel" }, { "id": "wheel_rl", "description": { "en": "Wheel rear left" }, "propertySetType": "core.automobiles:Wheel" }] }], "propertySetTypes": [{ "name": "core.automobiles:Car", "description": { "en": "Sensory parameters for car" }, "dataCategory": "MasterData", "propertyTypes": [{ "value": { "id": "BodyStyle", "description": { "en": "Car body style" }, "type": "String", "length": "127" } }, { "value": { "id": "Class", "description": { "en": "Car Class" }, "type": "String", "length": "127" } }, { "value": { "id": "WheelBase", "description": { "en": "Car Wheel Base" }, "type": "Numeric", "length": "2" } }, { "value": { "id": "RegistrationNumber", "description": { "en": "Car Registration number", "de": "Registriernummer", "zh": "注册号码" }, "type": "String", "length": "127" } }, { "value": { "id": "Colour", "description": { "en": "Car Colour" }, "type": "String", "length": "127"



} }] }, { "name": "core.automobiles:Wheel", "description": { "en": "Sensory parameters for wheel" }, "dataCategory": "TimeSeriesData", "propertyTypes": [{ "value": { "id": "Pressure", "description": { "en": "Wheel pressure", "zh": "轮压", "de": "Raddruckes" }, "type": "Numeric", "length": "2", "annotations" : ["com.sap.pdms:Flow"], "unitOfMeasure": "PA" } }, { "value": { "id": "Temperature", "description": { "en": "Wheel temperature" }, "type": "Numeric", "length": "2", "annotations" : ["com.sap.pdms:Flow"] } }] }, { "name": "core.automobiles:DriveUnit", "description": { "en": "Sensory parameters for drive unit" }, "dataCategory": "TimeSeriesData", "propertyTypes": [{ "value": { "id": "RotationSpeed", "description": { "en": "Drive unit rotation speed" }, "type": "Numeric", "length": "2", "annotations" : ["com.sap.pdms:Flow"] } }, { "value": { "id": "PowerConsumption", "description": { "en": "Drive unit power consumption" }, "type": "Numeric", "length": "2", "annotations" : ["com.sap.pdms:Flow"] } }] }, { "name": "core.automobiles:Engine", "description": { "en": "Sensory parameters for engine" }, "dataCategory": "MasterData", "propertyTypes": [{ "value": { "id": "Type",


"description": { "en": "Engine type" }, "type": "String", "length": "127" } }, { "value": { "id": "Capacity", "description": { "en": "Engine capacity" }, "type": "Numeric", "length": "2", "unitOfMeasure": "MM" } }, { "value": { "id": "Torque", "description": { "en": "Engine torque" }, "type": "Numeric", "length": "2", "unitOfMeasure": "NM" } }, { "value": { "id": "Transmission", "description": { "en": "Engine transmission" }, "type": "String", "length": "254", "unitOfMeasure": "" } }] }] } } }

Request Properties

Package Object Properties

Table 2:

Property Type Mandatory Maximum Length Description

id string Yes 50 Configuration package identifier

dependencies Array of package name and version

No - List of dependent packages relevant to this configuration package




description string No 60 Description of the configuration package for each language with the corresponding ISO language code

scope string No Fixed Indicates the scope of the configuration package. Permissible values are public, tenant, or private

version string Yes 9999.9999.9999 Indicates the version of the configuration package. For example, 1.0.0, 1.0, or 1

Property Set Type Object Properties

Table 3:


name string Yes 81 Name of the property set type

description string No 60 Description of the property set type for each language with the corresponding ISO language code

dataCategory enum Yes - Data category of the property set type

propertyTypes Array of property types

No - Array of property types

Data Category Enumeration Values

Table 4:

Value Description

MasterData Indicates the property set type for storing master data

TimeSeriesData Indicates the property set type for storing time series data

Property Type Object Properties

Table 5:


id string Yes 30 Name of the property

type enum Yes 30 Type used by the property



length string Yes (For more information on supported data types, refer to Value Data Types for Property Types [page 25])

30 Storage length for the property specified as an integer value

description string No 60 Description of the property for each language with the corresponding ISO language code

unitOfMeasure string No 12 Indicates the unit of measure in which the property is measured

Annotations Array of strings No 81 Can have one of the following values: com.sap.pdms;Flow; com.sap.pdms:Level; com.sap.com:Discrete

NoteOnly one annotation is supported

Thing Type Object Properties

Table 6:


name string Yes 81 Name of the thing type

description string No 60

propertyTypes Array of named property set type objects

No - Array of named property set types that belong to the thing type

Named Property Set Type Object Properties

Table 7:


id string Yes 30 Name of the property set

propertySetType string Yes 81 Name of the property set type referred

description string No 60 Description of the property for each language with the corresponding ISO language codeDescription of the thing type for each language with the corresponding ISO language code



Note● Description of the thing type for each language with the corresponding ISO languageIf the descriptions are

maintained in the requested language they are shown on the UIs of insight providers in the Asset Health Control Center or Asset Health Fact Sheet, and on the configuration UIs of insight providers.

Response

Format: JSON

Response Status and Error Codes

Table 8:

Code Description

201 Package created successfully

2.1.3 Read a Package

This configuration service is used to read the details contained within the specified package. The response returns the latest version of the package.

Request

URI:http://<hostname>:<port>/platform/thing-model/api/v1/config/Configuration('<id>')

HTTP Method:GET

Request Example

GET http://<hostname>:<port>/platform/thing-model/api/v1/config/Configuration('core.automobiles')

Response

Format: JSON



Table 9:

Code Description

200 Package retrieved successfully

Response Example

{ "schema": { "type": "ConfigurationPackage" }, "version": "1.0.0", "id": "core.automobiles", "dependencies": [], "description": { "en": "Automobiles package" }, "scope": "public", "services": { "dataService": { "thingTypes": [{ "name": "core.automobiles:ABC2Series", "description": { "en": "ABC 2 Series car" }, "propertyTypes": [{ "id": "engine", "description": { "en": "Engine Usage", "de": "Motornutzung" }, "propertySetType": "core.automobiles:Engine" }, { "id": "drive_fr", "description": { "en": "Drive Unit Front Right" }, "propertySetType": "core.automobiles:DriveUnit" }, { "id": "drive_fl", "description": { "en": "Drive Unit Front Left" }, "propertySetType": "core.automobiles:DriveUnit" }, { "id": "car", "description": { "en": "Car Usage" }, "propertySetType": "core.automobiles:Car" }, { "id": "wheel_fr", "description": { "en": "Wheel front right", "de": "vorderes rechtes Rad" }, "propertySetType": "core.automobiles:Wheel" }, { "id": "wheel_fl", "description": { "en": "Wheel front left", "de": "vorderes linkes Rad", "ru": " переднее левое колесо" }, "propertySetType": "core.automobiles:Wheel" }, {



"id": "wheel_rr", "description": { "en": "Wheel rear right" }, "propertySetType": "core.automobiles:Wheel" }, { "id": "wheel_rl", "description": { "en": "Wheel rear left" }, "propertySetType": "core.automobiles:Wheel" }] }, { "name": "core.automobiles:ABCXSeries", "description": { "en": "ABC X Series Car" }, "propertyTypes": [{ "id": "engine", "description": { "en": "Engine Usage" }, "propertySetType": "core.automobiles:Engine" }, { "id": "drive_fr", "description": { "en": "Drive Unit Front Right" }, "propertySetType": "core.automobiles:DriveUnit" }, { "id": "drive_fl", "description": { "en": "Drive Unit Front Left" }, "propertySetType": "core.automobiles:DriveUnit" }, { "id": "car", "description": { "en": "Car Usage" }, "propertySetType": "core.automobiles:Car" }, { "id": "wheel_fr", "description": { "en": "Wheel front right" }, "propertySetType": "core.automobiles:Wheel" }, { "id": "wheel_fl", "description": { "en": "Wheel front left" }, "propertySetType": "core.automobiles:Wheel" }, { "id": "wheel_rr", "description": { "en": "Wheel rear right" }, "propertySetType": "core.automobiles:Wheel" }, { "id": "wheel_rl", "description": { "en": "Wheel rear left" }, "propertySetType": "core.automobiles:Wheel" }] }], "propertySetTypes": [{


"name": "core.automobiles:Car", "description": { "en": "Sensory parameters for car" }, "dataCategory": "MasterData", "propertyTypes": [{ "value": { "id": "BodyStyle", "description": { "en": "Car body style" }, "type": "String", "length": "127", "annotations" : [] } }, { "value": { "id": "Class", "description": { "en": "Car Class" }, "type": "String", "length": "127", "annotations" : [] } }, { "value": { "id": "WheelBase", "description": { "en": "Car Wheel Base" }, "type": "Numeric", "length": "2", "annotations" : [] } }, { "value": { "id": "RegistrationNumber", "description": { "en": "Car Registration number", "de": "Registrationsnummer", "zh": "注册号码" }, "type": "String", "length": "127", "annotations" : [] } }, { "value": { "id": "Colour", "description": { "en": "Car Colour" }, "type": "String", "length": "127", "annotations" : [] } }] }, { "name": "core.automobiles:Wheel", "description": { "en": "Sensory parameters for wheel" }, "dataCategory": "TimeSeriesData", "propertyTypes": [{ "value": { "id": "Pressure", "description": {



"en": "Wheel pressure", "zh": "轮压", "de": "Raddruckes" }, "type": "Numeric", "length": "2", "unitOfMeasure": "PA", "annotations" : ["com.sap.pdms:Flow"] } }, { "value": { "id": "Temperature", "description": { "en": "Wheel temperature" }, "type": "Numeric", "length": "2", "annotations" : ["com.sap.pdms:Flow"] } }] }, { "name": "core.automobiles:DriveUnit", "description": { "en": "Sensory parameters for drive unit" }, "dataCategory": "TimeSeriesData", "propertyTypes": [{ "value": { "id": "RotationSpeed", "description": { "en": "Drive unit rotation speed" }, "type": "Numeric", "length": "2", "annotations" : [] } }, { "value": { "id": "PowerConsumption", "description": { "en": "Drive unit power consumption" }, "type": "Numeric", "length": "2", "annotations" : [] } }] }, { "name": "core.automobiles:Engine", "description": { "en": "Sensory parameters for engine" }, "dataCategory": "MasterData", "propertyTypes": [{ "value": { "id": "Type", "description": { "en": "Engine type" }, "type": "String", "length": "127", "annotations" : [] } }, { "value": { "id": "Capacity", "description": { "en": "Engine capacity"


}, "type": "Numeric", "length": "2", "unitOfMeasure": "MM", "annotations" : [] } }, { "value": { "id": "Torque", "description": { "en": "Engine torque" }, "type": "Numeric", "length": "2", "unitOfMeasure": "NM", "annotations" : [] } }, { "value": { "id": "Transmission", "description": { "en": "Engine transmission" }, "type": "String", "length": "254", "unitOfMeasure": "", "annotations" : [] } }] }] } } }

2.1.4 Update a Package

This configuration service is used to update an existing package. When you update a package, you must incrementally change the version number.

NoteYou must provide the complete payload even if you do not have any changes to the existing thing type or property set type definitions.

You can update a package in the following scenarios:

Table 10:

Object Thing Type Property Set Type

Scenario

Add Yes Yes



Object Thing Type Property Set Type

Scenario

Update Yes

NoteYou can update a thing type by:

● Adding new property sets.● Deleting property sets● Modifying property sets

You can update a thing type only if it is not used by any thing.

Yes

NoteYou can update a property set type by:

● Adding new properties.

● Deleting properties● Modifying properties

You can update a property set type only if it is not used by any thing.

Delete Yes

NoteYou can delete a thing type only if it is not used by any thing.

Yes

NoteYou can delete a property set type only if it is not used by any thing.

You can update a package by changing the scope of the package as follows:

Table 11:

Old Scope New Scope Restrictions

Public Private Possible only if there are no dependent packages

Private Public No restrictions

Request


HTTP Method:POST

Response

Format: JSON



Table 12:

Code Description

201 Package updated successfully

2.1.5 Delete a Package

This configuration service is used to delete a package.

NoteYou cannot delete a package under the following conditions:

● Other packages depend on this package.● Existing things that reference thing types belonging to the package being deleted.

Request


HTTP Method:DELETE

Request Example

DELETE http://<hostname>:<port>/platform/thing-model/api/v1/config/Configuration(‘core.automobiles’)

Response

Format: JSON


Table 13:

Code Description

204 Package deleted successfully



2.1.6 Value Data Types for Property Types

The following tabulation shows the value data types available for the property types.

Table 14:

Value Data Type Data Type Length Mandatory Value

(Valid for data stored in DATA.MASTERDATA)

String

String

NoteMaximum permissible length is 254 characters.

You can increase the length for a property type even if the data already exists for this property. However, you cannot decrease the length for a property regardless of whether the data exists or not.

No Default length is 127 characters.

(Valid for data stored in DATA.READINGS)

Numeric, NumericFlexible

Double

NoteThis is used to store 64-bit floating point values.

No Value range is -1.7976931348623157E308 to 1.7976931348623157E308

(Valid for data stored in DATA.READINGS)

Boolean

Double No Values supported are 1 and 0.

NoteYou cannot change a Boolean data type to another data type and vice versa.

(Valid for data stored in DATA.LOCATIONS)

GeoLocation

hana.ST_GEOMETRY(4326) No For more information, see SAP HANA Spatial Reference.


http://help.sap.com/hana/SAP_HANA_Spatial_Reference_en.pdf

http://help.sap.com/hana/SAP_HANA_Spatial_Reference_en.pdf

Examples for Property Definition

Table 15:

Value Data Type Payload Type Example

NumericFlexible Configuration "value": { "id": "MachineReading","type": "NumericFlexible" }

Boolean Configuration "value": { "id": "MachineRunningStatus","type": "Boolean" }

String (without a specified length)

Configuration "value": { "id": "Name","type": "String" }

String (with a specified length)

Configuration "value": { "id": "Name","type": "String","length": "60" }



2.1.7 Naming Conventions for IoT Objects

You must adhere to the following naming conventions and conditions while creating objects for the SAP IoT Application Services.

Table 16:

Object Maximum Length Naming Conditions

Package Char 50 ● Must be a combination of alphanumeric characters and dots (dots to be used only to separate segments).

● Dots have to be followed by an alphanumeric character.

● Prefix the package name with the tenant name separated by a dot.

● Do not start the name with a dot or digit.

● Any segment length has to be at least 2 characters.Second segment length has to be at least 3 characters.The name must contain a minimum of two segments.

● The name should be in lowercase.


Object Maximum Length Naming Conditions

Thing Type

Property Set Type

Property Set Type Name

Char 30 ● Can be a combination of alphanumeric characters and underscore.

● Do not start the name with a digit or an underscore.

● Length should be at least 3 characters.

● Camel case is generally allowed, however there is a uniqueness check carried out against textual case conflicts:Two names with same characters of different textual case is not allowed. For example: A value "AbcDef" is not accepted when there is another value "abcDEF" that exists.Check on uniqueness ignoring case like SELECT toLower( name) WHERE NAME = toLower(new_name)

● Names have to be unique for a given set of property set types, thing types.

● The property set type and thing type names names must be fully qualified.

● Verify that a colon is used to separate a namespace and name. The syntax is: <namespace>:<name>. For example: com.sap.iotas:FlyWheel

● Each fully qualified name needs a namespace, colon as a separator and name.

Property Char 30 ● Property names must be unique within a thing type and property set type.

● No spaces can be used in the property name.



2.1.8 HTTP Status Codes for Configuration Services

List of status codes for configuration services

In the following table, you find the list of HTTP status codes that are used by the configuration services:

Table 17:

POST GET (Single value) GET (Collection) DELETE Description

201 200 200 204 Success

400 400 400 400 Bad request (for example: header field missing, wrong filter, validation failed)

403 403 403 403 Forbidden (scope(s) not assigned for the user)

n/a 404 n/a 404 Not found

500 500 500 500 Internal server error

2.1.9 Thing Services

The thing services allow you to create, update, and delete things that are instances of the thing types modeled using the configuration services.

A thing constitutes a single tangible object.

2.1.10 Create a Thing

This thing service is used to create a thing that is an instance of a thing type.

Note● A thing has exactly one thing type.● The thing type has to be a fully qualified name that is prefixed with the package name. For example,

core.automobiles:ABCXSeries001.

Request

URI:http://<hostname>:<port>/platform/thing-model/api/v1/thing/Things


HTTP Method:POST

Request Example

POST http://<hostname>:<port>/platform/thing-model/api/v1/thing/Things

{ "_externalId": "ABCXSeries001", "_name": "ABCXSeries001", "_description": { "en": "English" }, "_thingType": [ "core.automobiles:ABCXSeries" ] }

Request Properties

Thing Object Properties

Table 18:

Property Type Mandatory Description

_id string No Internal identifier for a Thing.

_externalId string Yes Thing identifier from an external system. This is a unique identifier within a tenant.

_name string Yes Name of the thing.

_description string Yes Description of a Thing in the specified language as defined in ISO Language Codes [page 34]. The ISO code for the language is used here.

_thingType Array of thing types

Yes Array of thing types for a thing. It must correspond to one of the thing types found in a package. Currently, only one element is supported

Response

Format: JSON


Table 19:

Code Description

201 Thing created successfully

NoteThe URL of the thing created is returned in the Location Header of the response.



2.1.11 Read a Thing

This Thing service is used to read the generic fields and the thing type associated with the specified Thing.

Request

URI:http://<hostname>:<port>/platform/thing-model/api/v1/thing/Things('<id>')

HTTP Method:GET

Request Header Parameters

Table 20:

Parameter Required Description

Accept-Language No Language of the Thing description. The default language is en.

Request Example

GET http://<hostname>:<port>/platform/thing-model/api/v1/thing/Things('<id>')

Response

Format: JSON

Response Properties

Table 21:

Property Type Description

_id string Internal identifier for a thing.

_externalId string Thing identifier from an external system.

_name string Name of the thing.

_description string Description of a thing in a specified language.

_thingType Array of thing types Array of thing types for the thing.


Table 22:

Code Description

200 Thing retrieved successfully

Response Example

{ "_id": "<thingID>",


"_externalId": "ABCXSeries001", "_name": "ABCXSeries001", "_description": { "en": "English" }, "_thingType": [ "core.automobiles:ABCXSeries" ] }

2.1.12 Read All Things

This Thing service is used to read all the available things.

Request

URI:http://<hostname>:<port>/platform/thing-model/api/v1/thing/Things

HTTP Method:GET

Request Header Parameters

Table 23:


Accept-Language No Language of the Thing description. The default language is en.

Query String Request Parameters

Table 24:

Parameter Required Type Description

$top No Integer Corresponds to the number of records to include in the result set.

$skip No Integer Corresponds to the number of records to exclude from the result set.

$count No Boolean Corresponds to the total number of thing objects available based on the current user's authorizations; permissible values are true and false.

The following results apply, if this parameter is used in conjunction with the other query parameters:

● If you use this with the $top and $skip parameters, the result contains the total count of thing objects available.

● If you use this with $filter parameter, the result contains the total count of thing objects based on the defined filter condition.



Parameter Required Type Description

$orderby No String Corresponds to the field name to be used for sorting the result set in ascending order; valid fields are _id, _name and _externalId.

To sort the result set, use asc for the ascending order and desc for the descending order.

$filter No String Corresponds to the filter condition to be applied; valid fields are _id, _name, _externalId, _thingType. The filter operators supported are eq and ne.

Request Example

GET http://<hostname>:<port>/platform/thing-model/api/v1/thing/Things?$filter=_thingType eq 'core.automobiles:ABCXSeries'&$count=true

Retrieves all things where the thing type is "core.automobiles:ABCXSeries".

Response

Format: JSON

Response Properties

Table 25:

Property Type Description

value Array of thing objects Array of things returned upon application of the filter conditions.


Table 26:

Code Description

200 Things retrieved successfully

Response Example

{ "count": 1, "value": [ { "_id": "<thingID>", "_externalId": "ABCXSeries001", "_name": "ABCXSeries001", "_description": { "en": "English" }, "_thingType": [ "core.automobiles:ABCXSeries" ] } ] }


2.1.13 Update a Thing

This Thing service is used to update the Thing with new attributes such as external ID or name.

Request


HTTP Method:POST

Request Example

POST http://<hostname>:<port>/platform/thing-model/api/v1/thing/Things('<id>') { "_externalId": "ABCXSeries001", "_name": "ABCXSeries001", "_description": { "en": "English" }, "_thingType": [ "core.automobiles:ABCXSeries" ] }

Response

Format: JSON


Table 27:

Code Description

201 Thing updated successfully

2.1.14 ISO Language Codes

List of supported language codes for IoT Application Services

In the following table, you find the list of supported languages for IoT Application Services and the corresponding ISO codes that you need to tell the system which language shall be used in a particular service request.



Table 28: ISO Language Codes

Description ISO Code

Afrikaans af

Arabic ar

Bulgarian bg

Catalan ca

Chinese zh

Croatian hr

Czech cs

Danish da

Dutch nl

English en

Estonian et

Finnish fi

French fr

German de

Greek el

Hebrew he

Hindi hi

Hungarian hu

Icelandic is

Indonesian id

Italian it

Japanese ja

Korean ko

Latvian lv

Lithuanian lt

Malaysian ms


Description ISO Code

Norwegian no

Polish pl

Portuguese pt

Romanian ro

Russian ru

Serbian sr

Slovakian sk

Slovenian sl

Spanish es

Swedish sv

Thai th

Turkish tr

Ukrainian uk

Vietnamese vi

2.1.15 Delete a Thing

This Thing service is used to delete the specified thing.

Request


HTTP Method:DELETE

Request Example

DELETE http://<hostname>:<port>/platform/thing-model/api/v1/thing/Things('<id>')



Response

Format: JSON


Table 29:

Code Description

204 Thing deleted successfully

2.1.16 HTTP Status Codes for Thing Services

List of status codes for thing services

In the following table, you find the list of HTTP status codes that are used by the thing services:

Table 30:

Post (Create) Post (Update) Delete Get (single value) Get (collection) Description

201 201 204 200 200 Success

n/a 404 n/a 404 200 Capabilities not assigned to read a specific thing.

201 404 404 404 200 Read capability not assigned to read a specific thing. However, the user is assigned with the capabilities to perform operations such as create, update, and delete.

403 403 403 200 200 Read capability assigned to read a specific thing. However, the user is not assigned with capabilities to perform operations such as create, update, and delete.


Post (Create) Post (Update) Delete Get (single value) Get (collection) Description

n/a 404 404 404 n/a Not found

The requested thing is not found.

403 403 403 403 403 Forbidden (scope(s) not assigned for the user)

400 400 400 400 400 Bad request (for example: header field missing, wrong filter, validation failed)

500 500 500 500 500 Internal server error

2.2 Managing Machine Learning Engine Using Configuration UIs

As an alternative to REST APIs, you can also decide to manage models for machine learning using the configuration UIs.

Prerequisites


● <pdms_datascience_role>


● Maintaining Roles and Users in SAP HANA● Role Templates for SAP Predictive Maintenance and Service, on-premise edition

Context

NoteThe configuration UIs to manage models support the following languages:



● English

TipWe recommend that you avoid using the Refresh functionality of your browser while creating, scoring, or training models. If you experience issues with the Refresh functionality, please try one of the following options:

● Click the Back button of your browser.● Close the browser window and open the launchpad again.

Procedure

1. Open the URL https://<hostname>:<port>/app/launchpad/index.html and log on with your user.

2. In the group Manage Machine Learning Engine, open the app Model Management.

3. To create a model, choose Create Model.4. Fill in all required fields in the Model section.

For more information see, Entries to Create a Model [page 40].5. Save your model

NoteWhen you save your model, you cannot change it anymore.

NoteYou can delete a model also after it has already been successfully trained and scored. To ensure the traceability of already created score,s models are not removed from the system but set to inactive, meaning they do not show up any more. You can inspect a deleted model by directly accessing the database.

6. After you have created a model, you can train it in the training section.a. Choose the model you want to train from the model search pane.b. Choose Train to get to the training section.c. Define the time frame of the training.d. Choose Train Model.

You can check the training log and see the training job ID in the Job Log URL column.

NoteTrained model versions are listed with chronologically numbered version.

Models for which training has started, but has not finished yet or failed, are listed with negative version numbers.

7. After you have trained a model, you can score it in the scoring section.


NoteThe latest version of a model can be scored and scores must be numerical.

a. Choose the model you want to score from the model search pane.b. Choose Score Model.

You can check the scoring status in the Scoring Data section of the scored model. To see the scoring job ID, click the job log URL in the Job Log URL column.

Custom Algorithms

You can also extend the predelivered machine learning engine by creating your own algorithms. For more information about extending the machine learning engine, see the guide SAP Predictive Maintenance and Service, Test Tool for Data Science.

2.2.1 Entries to Create a Model

Table 31: Entries to Create a Model

Entry Field Mandatory Description

Name x Model name

Description - Model description

Training Table x Name of the data fusion view in SAP HANA used for training. This view is executed whenever a model is trained, and is additionally filtered by a time frame defined in the model training call. For more information about the time frame, see the chapters Managing Machine Learning Engine Using Configuration UIs [page 38] and Train a Model [page 71].

For more information about creating data fusion views, see the chapter Creating Data Fusion Views Machine Learning Engine in the guide Installation of SAP Predictive Maintenance and Service, on-premise edition 1.0.



https://uacp2.hana.ondemand.com/viewer/9b3e0f5964ed4f37829349c7c1146de9/1.0.3/en-US



Scoring Table x Name of the data fusion view in SAP HANA used for scoring. This view is executed whenever a model is scored, and all rows returned are processed by the algorithm.


Property Set Type ID x ID of the property set type for which you want to create the model.

To get the property set type ID, use the REST API described in the chapter Read a Package [page 17].

Algorithm x The namespace in which the model is created, and the algorithm on which the model is based

The namespace com.sap.pdms.datascience is preconfigured and cannot be changed.

You can choose from the following algorithms:

● EMDDistance-based failure analysis using Earth Mover’s Distance

● MARAnomaly detection using Multivariate Autoregression

● PCAAnomaly detection with Principal Component Analysis

● RULRemaining Useful Life prediction using Weibull

● TECFailure prediction using Tree Ensemble Classifier

For more information about the algorithm, see the chapter Algorithms for Machine Learning in the guide Getting Started with SAP Predictive Maintenance and Service, on-premise edition 1.0.



Learner Type x Machine learning style that serves as metadata to provide information on what the data service is being used for

Depending on the algorithm you use, you are provided with the following algorithms:

● CLASSIFICATIONChoose this learner type if data is being used to predict a category, for example, to classify between good and defective.Prediction target: Mandatory

● REGRESSIONChoose this learner type to predict a value, for example, a health score.Prediction target: Mandatory

● SURVIVALChoose this learner type to predict the expected length of time until a certain event, such as the breakdown of an asset, will happen.Prediction target: Mandatory

● RULESChoose this learner type to include rules in the machine learning process.Prediction target: Not allowed

● UNSUPERVISEDChoose this learner type if data needs to be organized or its structure needs to be described.Prediction target: Not allowed

● OTHERPrediction target: Optional

Prediction Target - The variable or attribute that you want to train and score on

NoteThe prediction target must differ from the independent variables.




Input Variables x Independent variables

NoteIndependent variables must differ from the prediction target.

These variables are the names of the columns that you want to be used as input for the model.

Model-Specific Parameters - Model-specific parameters

NoteThese parameters differ according to the algorithm you want to use for the model. For more information, see Model-Specific Parameters [page 44].

How to Deal With Property Set Type IDs

If two models that score the same Thing have the same PropertySetTypeId, this results in ambiguous entries in the READINGS table. This is because the READINGS table does not work with keys. Insight providers might therefore not be able to resolve scores in the Asset Health Control Center.

For more information about the READINGS table, see the chapter Data Model in the guide Installation of SAP Predictive Maintenance and Service, on-premise edition 1.0.

Please make sure that you either use one property set type ID per model, or you only use the same property set type ID for different models if the models score different Things related to this ID or Things of different Thing types related to this ID.

ExampleThe following sample scenarios illustrate a correct usage of the same property set type ID (PST ID) used for different models:

Things of Different Thing Types

Model A PST ID temperature Thing Type Battery Possibly all Things having the given Thing Type

Model B PST ID temperature Thing Type AirCondition Possibly all Things having the given Thing Type

Different Things of the Same Thing Type

Model A PST ID temperature Thing Type Battery Things 1-5


Model B PST ID temperature Thing Type Battery Things 6-9

Related Information

Managing Machine Learning Engine Using Configuration UIs [page 38]

2.2.2 Model-Specific Parameters

EMD

Table 32:

Parameter Description

nCores Number of cores to use during scoring

The default value is 1.

bins The number of bins to use in each dimension to generate the histogram. By default, bins are created such that the minimum and maximum reading of each sensor come to lie at the center of the lowest or highest bin respectively, and linearly equi-spaced bins are created in each dimension.

Positive integer for discretization that is not zero. The default value is 20.

group.by Column name of data to be excluded in contingency table computation. It contains the name(s) of the column(s) used for grouping data. This parameter is mandatory.

The default is NULL/empty.




normaliser.type The type of normaliser that should be applied to the scores calculated by the algorithm. Allowed values are:

● Quantile (default)Internally calculates an effective threshold value based on the training data. Raw scores and normalized scores are generated.

● ThresholdUses the given value. Raw scores and normalized scores are generated.

● NoneDoes not do any normalization of the values. Only raw scores are generated.

NoteFor more information about the normalization of scores, see the chapter Normalization of Scores [page 52].

normaliser.value The value used for the normalization (default: 0.99). For quantile, a value between 0 and 1 is valid; for threshold, a value larger than 0.

PCA

Table 33:


group.by Name(s) of the column(s) used for grouping data rows. This parameter is mandatory.

The default is Thing.

sort.by Name(s) of the column(s) used for sorting data rows. This parameter is mandatory

The default is Timestamp.



smoothing.window Integer specifying the width of the running median window.

NoteThis value must be an odd number.

Use smoothing.window = 3 for minimal robust smoothing so that isolated outliers are eliminated.

The default is 1.






normaliser.value The value that is used for the normalization (default: 0.99). For quantile, a value between 0 and 1 is valid; for threshold, a value larger than 0.



RUL

Table 34:


nameAgeColumn Name of the column in the input data containing the age information. This age information can either be the age at which an asset failed, or the current age of an asset that is still working. This parameter is mandatory.

NoteMake sure that the age statements use the same time unit, such as years, hours, or days.

NULL values are not supported.

The default is age.

predictionHorizon Integer value specifying the period for which the failure probability should be calculated.

ExampleYou want to calculate the probability of failure for the next month starting from today.

NoteMake sure that the time units are the same as those for the age statements of assets, such as years, hours, or days.

The default is 1.

calculationHorizon Integer value specifying for how many future periods scores will be calculated and persisted.

ExampleYou want to calculate the probability of failure for the next month starting in a week's time.


The default is 0.



nameFailureColumn Name of the column in the input data containing the failure information. This parameter is mandatory.

The default is failure.

TEC

Table 35:


number.of.trees Specifies the number of trees in the ensemble model. Increasing the number of trees in the model can yield higher prediction accuracy, but requires higher computational effort, and there is the risk that the model will be adjusted too much to the non-characteristic noise of the specific training data set (known as overfitting). Permitted value range is integer numbers greater than or equal to 1. Default value is 20.

max.tree.depth Controls the maximum depth of each tree in the ensemble model. Increasing the maximum tree depth allows you to build more complex trees that are capable of capturing more complex relations in the data. On the downside, increasing the maximum tree depth also increases the risk of building models that are heavily tuned to the particularities of the given training data set, including those that are not characteristic of the underlying real-world process. It is generally recommended to increase the amount of training data when increasing the maximum tree depth (where possible). Permitted value range is integer numbers greater than or equal to 1. Default value is 2.




records.subsampling.ratio Defines the share of records (that is,. rows of the training data) to be used to train each tree of the ensemble model. The number of records corresponding to the specified share is chosen randomly (without replacement) from the training data set. Specifying a value strictly smaller than 1 for this parameter can increase the robustness of the model (that is, it is less likely to overfit) if .number.of.trees is set to a sufficiently large value (problem-dependent) at the same time. On the downside, a smaller value for this parameter may lead to lower overall model accuracy and confidence, and may (indirectly) require higher computational effort due to a need for larger values for .number.of.trees. Also, a relatively large training data set may be required for subsampling to be successful. Permitted value range is numbers greater than 0 and less than or equal to 1. Note that a value of 1 effectively means that no subsampling is performed. The default value is 1.

features.subsampling.ratio Defines the share of features (that is, columns of the training data) to be used to train each tree of the ensemble model. The number of columns corresponding to the specified share is chosen at random (without replacement) from the given training data set. Similarly to .records.subsampling.ratio, specifying a value strictly smaller than 1 can be used to increase the robustness of the model, but may come at thea price: lower accuracy and model confidence, and choosing a smaller value for .features.subsampling.ratio may reduce the ability to capture complex relationships in the data successfully. It can be helpful, however, to tune this parameter if the given data set contains highly correlated features (for example, variants obtained through feature engineering). The permitted value range is numbers greater than 0 and less than or equal to 1. Note that a value of 1 effectively means that no subsampling is performed. The default value is 1.

max.weight.contrib.per.leaf Defines how much weight each leaf of a tree may contribute maximally to the ensemble model. Within the algorithm, this parameter is used as a threshold to cap xgboost's gradient step in norm (that is, in absolute length). Choosing a smaller value for this parameter may help deal with unbalanced data sets (i.e. data sets where the occurrence of one class is only a fraction of the occurrence of the other class) by preventing "highly confident" leaves dominating "less confident" leaves as a result of sheer sample majority. The permitted value range is numbers greater than or equal to 0. Note that 0 means that no limit is specified on the maximum weight contribution of each leaf, while every strictly positive number specifies a weight threshold. The default value is 0.



learning.rate Defines the step size of the updates calculated through each tree on the ensemble learning objective function. In this specific algorithm, this parameter can be interpreted as the level of trust the ensemble model gives to each tree before calculating the next tree on the score residuals of the previously calculated trees. Choosing a smaller value will mean that objective functions of subsequently computed trees will look more alike and, as a consequence, the ensemble model tends to feature more trees per problem facade (at the cost of covering fewer facades if the overall number of trees is not increased). It is generally recommended to increase number.of.trees when decreasing learning.rate. Reducing this parameter can be used to increase number.of.trees when decreasing learning.rate. Reducing this parameter can be used to prevent overfitting, but it comes at the price of typically requiring a higher number.of.trees to achieve comparable model accuracy and confidence. The permitted value range is numbers greater than 0 and less than or equal to 1. The default value is 0.3.

initial.guess.bias Allows you to introduce a bias into the classifier. This parameter serves as the inital guess (score) to which the tree models are iteratively added. Assuming that result scores (of the ensemble model) smaller than 0.5 are interpreted as predicting class '0' and scores greater than or equal to 0.5 are a prediction of class '1', code.initial.guess.bias can be used to require more tree weight to predict one class compared to the other, and thus naturally favor one class. Tuning this parameter may help to find a desirable tradeoff between so-called "false positives" and "false negatives" among incorrectly classified records. Permitted value range is numbers greater than or equal to 0 and less than or equal to 1. A value of 0.5 means no bias in either direction. The default value for this parameter is 0.5.

MAR

Table 36:


target.columns Contains the columns for which a linear regression should be fitted (default: NULL/empty). Depending on the input data, it is necessary to specify at least one target column if the window_size parameter is 0.




window.size Contains the number of former observations that are taken into account to fit a regression (default: 10). Windowing is only necessary if each row contains only the observations from one particular time.

NoteIf windowing is applied, the algorithm uses the data of the window_size parameter former rows (based on the time stamp). In order to ensure a proper functionality, an equidistance is recommended.

weight.by.uncertainty If set to true (default value), the deviation between prediction and observation is discounted by the quality of the underlying model for this particular target variable. The underlying idea is to incorperate the predictive power of the trained regressions. If a model for one particular target variable does not produce reliable predictions, the influence of this particular deviation should be less than the deviation produced by a more accurate regression.


● Quantile (default)Internally calculates an effective threshold value based on the training data

● ThresholdInternally calculates an effective threshold value based on the training data. Raw scores and normalized scores are generated.





2.2.3 Normalization of Scores

Normalizing scores enables you to compare scores computed for different assets using different anomaly detection algorithms.

Normalization Type: Threshold

You can use the normalization type threshold to score a model if you know the threshold for your data set that distinguishes normal data from abnormal data.

ExampleYou can compare scores that were computed using different algorithms. The following table provides you with an example of how normalized scores are calculated:

Table 37:

Threshold 1 = 80 Threshold 2 = 450000

Algorithm 1 Algorithm 2

Raw Score Normalized Score Score Interpretation


100 (100/80)*100 = 125

25 % above the threshold = abnormal

10000 (10000/450000)*100 = 2.22

97.78 % below the threshold = normal

90 (90/80)*100 = 112.5

12.5 % above the threshold = abnormal

400012 (400012/450000)*100 = 88.89


4 (4/80)*100 = 5 95 % below the threshold = normal

412313 (412313/450000)*100 = 91.63


32 (32/80)*100 = 40 60 % below the threshold = normal

477212 (477212/450000)*100 = 106.05

6.05 % above the threshold = abnormal

Without normalizing the raw scores of the algorithms 1 and 2, a comparison of the scores of these two algorithms would hardly be possible. Using the threshold, which represents a percentage of 100, the normalized scores are set in relation to this percentage and can therefore be compared across different anomaly detection algorithms.



Normalization Type: Quantile

You can use the normalization type quantile to train a model if you do not know the threshold for your data set. However, you know the data set itself very well, and you know that a certain percentage of your raw scores are outliers.

ExampleYou do not have a training set of normal data that is below a certain threshold. You cannot therefore train your model against a training data set. However, you know that 90 % of your raw scores are normal and 10 % of your raw scores are abnormal. You also know which scores represent normal values and which values represent abnormal values. What you need to do before you can score your model is to get to a threshold that distinguishes normal from abnormal scores.Without normalizing the raw scores of the algorithms 1 and 2, a comparison of the scores of these two algorithms would hardly be possible. Using the threshold, which represents a percentage of 100, the normalized scores are set in relation to this percentage and can therefore be compared across different anomaly detection algorithms.

Table 38:

Outliers = 10 %, which means quantile = 0.9

Raw Score Training Effective Threshold After Training Using Statistic Function to Calculate the Empirical Quantile: 0.9Normal score 0.04

Normal score 0.07

Normal score 0.07

Normal score 0.15

Normal score 0.23

Normal score 0.35

Normal score 0.35

Normal score 0.71

Normal score 0.89

abnormal score 0.95

Afteryour model has been trained with the empirical quantile process, the calculated effective threshold is used to score your model. The scoring process is then executed as described in the section Normalization Type: Threshold:

Table 39:

Effective Threshold = 0.9



0.4 (0.4/0.9)*100 = 44.44 55.56 % below the threshold = normal

1.1 (1.1/0.9)*100 = 122.22 22.22 % above the threshold = abnormal

0.23 (0.23/0.9)*100 = 25.56 74.44 % below the threshold = normal

0.91 (0.91/0.9)*100 = 101.11 1.11 % above the threshold = abnormal

2.3 Managing Machine Learning Engine Using REST APIs

REST APIs for configuring, training, and scoring models according to the algorithms for principal component analysis (PCA), earth mover’s distance (EMD), or Weibull.

Permissions: The following role collection is assigned to your user:



To manage the machine learning engine, proceed as follows:

1. Create models as described in the chapter Create a Model [page 55].You can also do the following:○ Read a Model [page 67]○ Read All Models [page 68]○ Update a Model [page 69]

2. Train models as described in the chapter Train a Model [page 71].3. Score a model as described in the chapter Score a Model [page 72].


4. Check the Status of a Training Job or Scoring Job [page 73].You can also do the following:○ Check the Status of All Jobs [page 75]○ Check a Job Log [page 74]

5. (If required) Delete a model as described in the chapter Check the training status or scoring status of a model as explained in the chapter Delete a Model [page 76].

6. (Optional) You can retrieve information about all algorithms as described in the chapter Read Information About All Algorithms [page 77].



Custom Algorithms

You can also extend the predelivered machine learning engine by creating your own algorithms. For more information about extending the machine learning engine, see the guide Check the training status or scoring status of a model as explained in theSAP Predictive Maintenance and Service, Test Tool for Data Science.

2.3.1 Create a Model

Configure a model.

Request

FormatJSON

URI: https://<hostname>:<router port>/datascience/api/v1/models

HTTP Method: POST

Request Example

{ "namespace": "com.sap.pdms.datascience", "dataScienceService": "PCA", "name": "My_Super_Model", "description": "Some model description.", "scoreTable": "THING_ANALYSIS_10K", "trainTable": "THING_ANALYSIS_10K", "dependentVariable": "SENSOR5", "propertySetTypeId": "somePSTID", "independentVariables": [ "BATTERY_VOLTAGE", "Timestamp", "ThingType" ], "hyperParameters": [ { "key": "k", "values": ["3"] }, { "key": "sort.by", "values": ["Timestamp"] }, { "key": "group.by", "values": ["ThingType"] } ] }




Request ParametersTable 40:


namespace Yes Namespace of the algorithm in which you want to create the model

NoteThe namespace com.sap.pdms.datascience is reserved for algorithms that are delivered by SAP. If custom algorithms are added to the predelivered algorithms, other namespaces are available.

dataScienceService Yes Algorithm that you want to use for your model

You can choose between the following algorithms:

● PCA● EMD● Weibull● TEC● MAR

name Yes Model name

description No Model description

scoreTable Yes Name of the data fusion view in SAP HANA used for scoring. This view is executed whenever a model is scored, and all rows returned are processed by the algorithm.


trainTable Yes Name of the data fusion view in SAP HANA used for training. This view is executed whenever a model is trained, and is additionally filtered by a time frame defined in the model training call. For more information about the time frame, see the chapters Managing Machine Learning Engine Using Configuration UIs [page 38] and Train a Model [page 71].





dependentVariable No The variable or attribute that you want to train and score on

This parameter is mandatory if your model algorithm uses the learner types CLASSIFICATION, REGRESSION, or SURVIVAL.

This parameter must not be used if your model algorithm uses the learner types UNSUPERVISED or RULES.

This parameter is optional if your model algorithm uses the learner type OTHER.

propertySetTypeId Yes ID of the property set type for which you want to create the model.

To get the property set type ID, use the REST API described in the chapter Read a Package [page 17].

Yes Names of the columns to be used as input to the model

hyperParameters No Parameters specific to the model you are configuring

NoteThese parameters differ according to the algorithm you want to use for the model.

For more information about the model-specific parameters,Model-Specific Parameters [page 44].

How to Deal with Property Set Type IDs

If two models that score the same Thing have the same PropertySetTypeId, this results in ambiguous entries in the READINGS table. This is because the READINGS table does not work with keys. Therefore, insight providers might not be able to resolve scores in the Asset Health Control Center.

For more information about the READINGS table, see the chapter Data Model in the guide Installation of SAP Predictive Maintenance and Service, on-premise edition 1.0.

Please make sure that you either use one property set type ID per model, or that you only use the same property set type ID for different models if the models score different Things related to this ID or Things of different Thing types related to this ID.

ExampleThe following sample scenarios show how to correctly use the same property set type ID (PST ID) for different models:

Things of Different Thing Types

Model A PST ID temperature Thing Type Battery Possibly all Things having the given Thing Type

Model B PST ID temperature Thing Type AirCondition Possibly all Things having the given Thing Type


Different Things of the Same Thing Type

Model A PST ID temperature Thing Type Battery Things 1-5

Model B PST ID temperature Thing Type Battery Things 6-9

Response

Format: JSON

Response Example

{ "modelId": "84A1B2570DC8A002E200E132EE5B38AA", "createdOn": "2016-08-16 08:37:43.3020000", "createdBy": "SomeUser", "status": "CREATED", "modelConfiguration": { "namespace": "com.sap.pdms.datascience", "dataScienceService": "PCA", "name": "My_Super_Model", "description": "Some model description.", "trainTable": "THING_ANALYSIS_10K", "scoreTable": "THING_ANALYSIS_10K", "propertySetTypeId": "somePSTID", "independentVariables": [ "BATTERY_VOLTAGE", "Timestamp", "ThingType" ], "dependentVariable": "SENSOR5", "hyperParameters": [ { "key": "group.by", "values": [ "ThingType" ] }, { "key": "k", "values": [ 3 ] }, { "key": "sort.by", "values": [ "Timestamp" ] } ] }}




Table 41:

Category Code Description

Conflict 409 A model with the same name exists.

Bad request 409 The algorithm does not exist in the namespace.

400 Invalid values were entered.

Internal server error 500 An internal server error occurred.

Related Information

Managing Machine Learning Engine Using REST APIs [page 54]Read a Model [page 67]Read All Models [page 68]Update a Model [page 69]Train a Model [page 71]Delete a Model [page 76]

2.3.1.1 Model-Specific Parameters

EMD

Table 42:


nCores Number of cores to use during scoring

The default value is 1.

bins The number of bins to use in each dimension to generate the histogram. By default, bins are created such that the minimum and maximum reading of each sensor come to lie at the center of the lowest or highest bin respectively, and linearly equi-spaced bins are created in each dimension.

Positive integer for discretization that is not zero. The default value is 20.



group.by Column name of data to be excluded in contingency table computation. It contains the name(s) of the column(s) used for grouping data. This parameter is mandatory.

The default is NULL/empty.






normaliser.value The value used for the normalization (default: 0.99). For quantile, a value between 0 and 1 is valid; for threshold, a value larger than 0.

PCA

Table 43:


group.by Name(s) of the column(s) used for grouping data rows. This parameter is mandatory.

The default is Thing.

sort.by Name(s) of the column(s) used for sorting data rows. This parameter is mandatory

The default is Timestamp.




smoothing.window Integer specifying the width of the running median window.

NoteThis value must be an odd number.

Use smoothing.window = 3 for minimal robust smoothing so that isolated outliers are eliminated.

The default is 1.








RUL

Table 44:


nameAgeColumn Name of the column in the input data containing the age information. This age information can either be the age at which an asset failed, or the current age of an asset that is still working. This parameter is mandatory.

NoteMake sure that the age statements use the same time unit, such as years, hours, or days.

NULL values are not supported.

The default is age.

predictionHorizon Integer value specifying the period for which the failure probability should be calculated.

ExampleYou want to calculate the probability of failure for the next month starting from today.


The default is 1.

calculationHorizon Integer value specifying for how many future periods scores will be calculated and persisted.

ExampleYou want to calculate the probability of failure for the next month starting in a week's time.


The default is 0.




nameFailureColumn Name of the column in the input data containing the failure information. This parameter is mandatory.

The default is failure.

TEC

Table 45:


number.of.trees Specifies the number of trees in the ensemble model. Increasing the number of trees in the model can yield higher prediction accuracy, but requires higher computational effort, and there is the risk that the model will be adjusted too much to the non-characteristic noise of the specific training data set (known as overfitting). Permitted value range is integer numbers greater than or equal to 1. Default value is 20.

max.tree.depth Controls the maximum depth of each tree in the ensemble model. Increasing the maximum tree depth allows you to build more complex trees that are capable of capturing more complex relations in the data. On the downside, increasing the maximum tree depth also increases the risk of building models that are heavily tuned to the particularities of the given training data set, including those that are not characteristic of the underlying real-world process. It is generally recommended to increase the amount of training data when increasing the maximum tree depth (where possible). Permitted value range is integer numbers greater than or equal to 1. Default value is 2.



records.subsampling.ratio Defines the share of records (that is,. rows of the training data) to be used to train each tree of the ensemble model. The number of records corresponding to the specified share is chosen randomly (without replacement) from the training data set. Specifying a value strictly smaller than 1 for this parameter can increase the robustness of the model (that is, it is less likely to overfit) if .number.of.trees is set to a sufficiently large value (problem-dependent) at the same time. On the downside, a smaller value for this parameter may lead to lower overall model accuracy and confidence, and may (indirectly) require higher computational effort due to a need for larger values for .number.of.trees. Also, a relatively large training data set may be required for subsampling to be successful. Permitted value range is numbers greater than 0 and less than or equal to 1. Note that a value of 1 effectively means that no subsampling is performed. The default value is 1.

features.subsampling.ratio Defines the share of features (that is, columns of the training data) to be used to train each tree of the ensemble model. The number of columns corresponding to the specified share is chosen at random (without replacement) from the given training data set. Similarly to .records.subsampling.ratio, specifying a value strictly smaller than 1 can be used to increase the robustness of the model, but may come at thea price: lower accuracy and model confidence, and choosing a smaller value for .features.subsampling.ratio may reduce the ability to capture complex relationships in the data successfully. It can be helpful, however, to tune this parameter if the given data set contains highly correlated features (for example, variants obtained through feature engineering). The permitted value range is numbers greater than 0 and less than or equal to 1. Note that a value of 1 effectively means that no subsampling is performed. The default value is 1.

max.weight.contrib.per.leaf Defines how much weight each leaf of a tree may contribute maximally to the ensemble model. Within the algorithm, this parameter is used as a threshold to cap xgboost's gradient step in norm (that is, in absolute length). Choosing a smaller value for this parameter may help deal with unbalanced data sets (i.e. data sets where the occurrence of one class is only a fraction of the occurrence of the other class) by preventing "highly confident" leaves dominating "less confident" leaves as a result of sheer sample majority. The permitted value range is numbers greater than or equal to 0. Note that 0 means that no limit is specified on the maximum weight contribution of each leaf, while every strictly positive number specifies a weight threshold. The default value is 0.




learning.rate Defines the step size of the updates calculated through each tree on the ensemble learning objective function. In this specific algorithm, this parameter can be interpreted as the level of trust the ensemble model gives to each tree before calculating the next tree on the score residuals of the previously calculated trees. Choosing a smaller value will mean that objective functions of subsequently computed trees will look more alike and, as a consequence, the ensemble model tends to feature more trees per problem facade (at the cost of covering fewer facades if the overall number of trees is not increased). It is generally recommended to increase number.of.trees when decreasing learning.rate. Reducing this parameter can be used to increase number.of.trees when decreasing learning.rate. Reducing this parameter can be used to prevent overfitting, but it comes at the price of typically requiring a higher number.of.trees to achieve comparable model accuracy and confidence. The permitted value range is numbers greater than 0 and less than or equal to 1. The default value is 0.3.

initial.guess.bias Allows you to introduce a bias into the classifier. This parameter serves as the inital guess (score) to which the tree models are iteratively added. Assuming that result scores (of the ensemble model) smaller than 0.5 are interpreted as predicting class '0' and scores greater than or equal to 0.5 are a prediction of class '1', code.initial.guess.bias can be used to require more tree weight to predict one class compared to the other, and thus naturally favor one class. Tuning this parameter may help to find a desirable tradeoff between so-called "false positives" and "false negatives" among incorrectly classified records. Permitted value range is numbers greater than or equal to 0 and less than or equal to 1. A value of 0.5 means no bias in either direction. The default value for this parameter is 0.5.

MAR

Table 46:


target.columns Contains the columns for which a linear regression should be fitted (default: NULL/empty). Depending on the input data, it is necessary to specify at least one target column if the window_size parameter is 0.



window.size Contains the number of former observations that are taken into account to fit a regression (default: 10). Windowing is only necessary if each row contains only the observations from one particular time.

NoteIf windowing is applied, the algorithm uses the data of the window_size parameter former rows (based on the time stamp). In order to ensure a proper functionality, an equidistance is recommended.

weight.by.uncertainty If set to true (default value), the deviation between prediction and observation is discounted by the quality of the underlying model for this particular target variable. The underlying idea is to incorperate the predictive power of the trained regressions. If a model for one particular target variable does not produce reliable predictions, the influence of this particular deviation should be less than the deviation produced by a more accurate regression.


● Quantile (default)Internally calculates an effective threshold value based on the training data

● ThresholdInternally calculates an effective threshold value based on the training data. Raw scores and normalized scores are generated.






2.3.1.2 Read a Model

Retrieve the configuration of a specific model.

Request

Format: JSON

URI: https://<hostname>:<router port>/datascience/api/v1/models/<modelId>

HTTP Method: GET

Response

Response Example

{ "modelId": "84A1B2570DC8A002E200E132EE5B38AA", "createdOn": "2016-08-16 08:37:43.3020000", "status": "TRAINED", "versions": [ { "modelId": "84A1B2570DC8A002E200E132EE5B38AA", "modelVersion": 1, "from": "2014-01-01 08:15:00.500", "to": "2018-01-01 08:15:00.500", "createdOn": "2016-08-16 07:23:12.761" } ], "modelConfiguration": { "namespace": "com.sap.pdms.datascience", "dataScienceService": "PCA", "name": "NewModelName", "description": "NewModelDescription", "trainTable": "THING_ANALYSIS_10K", "scoreTable": "THING_ANALYSIS_10K", "independentVariables": [ "BATTERY_VOLTAGE", "Timestamp", "ThingType" ], "dependentVariable": "SENSOR5", "hyperParameters": [ { "key": "group.by", "values": [ "ThingType" ] }, { "key": "k", "values": [ 3 ] }, {


"key": "sort.by", "values": [ "Timestamp" ] } ], "createdBy": "SOMECREATOR", "propertySetTypeId": "somePSTID" } }


Table 47:


Not found 404 No model with the specified ID exists.


Related Information

Managing Machine Learning Engine Using REST APIs [page 54]Create a Model [page 55]

2.3.1.3 Read All Models

Retrieve the configuration of all models.

Request

Format: JSON

URI: https://<hostname>:<router port>/datascience/api/v1/models

HTTP Method: GET

Response

Response Example

[ { "modelId": "8466B2570DC8A002E200E132EE5B38AA", "createdOn": "2016-08-16 08:00:40.6880000",



"status": "CREATED", "modelConfiguration": { "namespace": "com.sap.pdms.datascience", "dataScienceService": "PCA", "name": "SOME_MODEL_NAME1471334439998", "description": "Some description.", "trainTable": "THING_ANALYSIS_10K", "scoreTable": "THING_ANALYSIS_10K", "independentVariables": [ "BATTERY_CURRENT", "BATTERY_VOLTAGE", "ThingType", "Timestamp" ], "dependentVariable": "SENSOR5", "hyperParameters": [ { "key": "group.by", "values": [ "ThingType" ] }, { "key": "sort.by", "values": [ "Timestamp" ] } ], "createdBy": "SOMECREATOR", "propertySetTypeId": "somePSTID" } }, ...]


Table 48:



Related Information

Managing Machine Learning Engine Using REST APIs [page 54]Create a Model [page 55]

2.3.1.4 Update a Model

Update the name and description of a model.

NoteOnly the model name and the model description can be updated. All other properties, if provided, are ignored.


Request

Format: JSON


HTTP Method: PUT

Request Example

{ "name": "<NewModelName>", "description": "<NewModelDescription>" }

Response

NoteWhen no content is displayed after you have sent the REST call, the model is updated.


Table 49:



Bad request 400 Invalid values were entered.

Related Information

Managing Machine Learning Engine Using REST APIs [page 54]Train a Model [page 71]Delete a Model [page 76]



2.3.2 Train a Model

Train or retrain a specific model.

Request

Format: JSON

URI: https://<hostname>:<router port>/datascience/api/v1/models/train/<modelId>

HTTP Method: POST

Request Example

{ "from": "2014-01-01 08:15:00.500", "to": "2015-01-01 08:15:00.500" }



from Yes Starting point of the training time interval

to Yes End point of the training time interval

Response

Response Example

{ "modelId": "someId" "currentVersion": 1, "jobId": "69ECB2570DC8A002E200E132EE5B38AA", "jobType": "TRAINING", "propertySetTypeId": "somePSTID", "createdOn": "2016-08-16 07:23:14.625", "taskName": "SAP_PDMS_DSS_FUSION_SCHEMA.TASK_TRAINING_69ECB2570DC8A002E200E132EE5B38AA"}


Table 51:


Validation error or bad request 400 Invalid values were entered.





Related Information

Managing Machine Learning Engine Using REST APIs [page 54]Check the Status of a Training Job or Scoring Job [page 73]Score a Model [page 72]

2.3.3 Score a Model

Score a specific model.

Request


Format: JSON

URI: https://<hostname>:<router port>/datascience/api/v1/models/score/<modelId>

HTTP Method: POST

Response

Response Example

{ "modelId": "AC43CE57085D4F01E200B7C915682242", "currentVersion": 3, "jobId": "FADACE57C9874F01E200B7C915682242", "jobType": "SCORING", "propertySetTypeId": "somePSTID", "createdOn": "2016-09-06 07:21:33.827", "taskName": "SAP_PDMS_DSS_FUSION_SCHEMA.TASK_SCORING_FADACE57C9874F01E200B7C915682242"}




Table 52:


Bad request 400 A model that is to be scored was not trained beforehand.



Related Information

Managing Machine Learning Engine Using REST APIs [page 54]Check the Status of a Training Job or Scoring Job [page 73]

2.3.4 Check the Status of a Training Job or Scoring Job

Retrieve status of a specific job.

Request

Format: JSON

URI: https://<hostname>:<router port>/datascience/api/v1/jobs/<jobId>

HTTP Method: GET

Response

Response Example

{ "modelId": "A566B2570DC8A002E200E132EE5B38AA", "versionId": 1, "id": "C166B2570DC8A002E200E132EE5B38AA", "type": "TRAINING", "propertySetTypeId": "somePSTID", "status": "COMPLETED", "createdOn": "2016-08-16 06:00:44.974", "lastUpdatedOn": "2016-08-16 06:00:46.273", "jobLogUrl": "http(s)://<host>:<port>/datascience-so/api/v1/jobs/C166B2570DC8A002E200E132EE5B38AA/C166B2570DC8A002E200E132EE5B38AA/job-log"


}


Table 53:



Related Information

Managing Machine Learning Engine Using REST APIs [page 54]Check a Job Log [page 74]Check the Status of All Jobs [page 75]

2.3.4.1 Check a Job Log

Request

Format: JSON

URI: https://<hostname>:<router port>/datascience/api/v1/jobs/<jobId>/job-log

HTTP Method: GET

Response

Response Example


Table 54:


Not found 404 No job log for the specified job ID exists.




2.3.4.2 Check the Status of All Jobs

Retrieve status of all jobs.

Request

Format: JSON

URI: https://<hostname>:<router port>/datascience/api/v1/jobs

HTTP Method: GET

Response

Response Example

[ { "modelId": "A566B2570DC8A002E200E132EE5B38AA", "versionId": 1, "id": "C166B2570DC8A002E200E132EE5B38AA", "type": "TRAINING", "propertySetTypeId": "somePSTID", "status": "COMPLETED", "createdOn": "2016-08-16 06:00:44.974", "lastUpdatedOn": "2016-08-16 06:00:46.273", "jobLogUrl": "http(s)://<host>:<port>/datascience-so/api/v1/jobs/C166B2570DC8A002E200E132EE5B38AA/job-log" }, { "modelId": "84A1B2570DC8A002E200E132EE5B38AA", "versionId": 1, "id": "69ECB2570DC8A002E200E132EE5B38AA", "type": "TRAINING", "propertySetTypeId": "somePSTID", "status": "COMPLETED", "createdOn": "2016-08-16 07:23:14.625", "lastUpdatedOn": "2016-08-16 07:23:16.540", "jobLogUrl": "http(s)://<host>:<port>/datascience-so/api/v1/jobs/69ECB2570DC8A002E200E132EE5B38AA/job-log" }, ...]


Table 55:




Related Information

Managing Machine Learning Engine Using REST APIs [page 54]

2.3.5 Delete a Model

Delete a model that is not needed any longer.

Request

Format: JSON


HTTP Method: DELETE

NoteYou can delete a model also after it has already been successfully trained and scored. To ensure the traceability of already created score,s models are not removed from the system but set to inactive, meaning they do not show up any more. You can inspect a deleted model by directly accessing the database.

Response

NoteWhen no content is displayed after you have sent the REST call, the model is deleted.


Table 56:



Related Information

Managing Machine Learning Engine Using REST APIs [page 54]



2.3.6 Read Information About All Algorithms

Get information about algorithms.

Request

Format: JSON

URI: https://<hostname>:<router port>/datascience/api/v1/info

HTTP Method: GET

Response

Response Example

{ "rServerPlatform": "x86_64-pc-linux-gnu", "rVersion": "R version 3.3.1 (2016-06-21)", "rNickname": "Bug in Your Hair", "pdmsRVersion": "1.3.0", "packageStatuses": [ { "namespace": "com.sap.pdms.datascience", "dataScienceService": "PCA", "rPackageVersion": "com.sap.pdms.datascience.pca 1.3.0", "rTrainFunction": "FOUND PCAtrain", "rScoreFunction": "FOUND PCAscore" }, { "namespace": "com.sap.pdms.datascience", "dataScienceService": "RUL", "rPackageVersion": "com.sap.pdms.datascience.rul.weibull 1.3.0", "rTrainFunction": "FOUND Weibulltrain", "rScoreFunction": "FOUND Weibullscore" }, { "namespace": "com.sap.pdms.datascience", "dataScienceService": "EMD", "rPackageVersion": "com.sap.pdms.datascience.dbfa.emd 1.3.0", "rTrainFunction": "FOUND EMDtrain", "rScoreFunction": "FOUND EMDscore" }, { "namespace": "com.sap.pdms.datascience", "dataScienceService": "MAR", "rPackageVersion": "com.sap.pdms.datascience.mar 1.3.0", "rTrainFunction": "FOUND MARtrain", "rScoreFunction": "FOUND MARscore" }, { "namespace": "com.sap.pdms.datascience", "dataScienceService": "TEC", "rPackageVersion": "com.sap.pdms.datascience.tec 1.3.0", "rTrainFunction": "FOUND TECtrain", "rScoreFunction": "FOUND TECscore"


} ]}

2.4 Scheduling Regular Scoring of a Model

Prerequisites

● You have downloaded the latest SP of XS SERVICES 1 which contains the XSA Job Scheduler service, and installed the Job Scheduler service.For more information about how to install the XSA Job Scheduler service, see the SAP HANA Server Installation and Update Guide.

● The Space Developer role is assigned to the user who does the following tasks:○ Creating the service broker for the Job Scheduler service (Step 1)○ Creating the Job Scheduler service instance (Step 2)○ Binding an application to the Job Scheduler service (Step 3)

For more information about the Space Developer role and scheduling jobs, see the chapter Scheduling Jobs in XS Advanced.

Context

For more information about scheduling jobs in XS advanced, see the chapter Scheduling Jobs in XS Advanced in the SAP HANA Administration Guide.

Procedure

1. (If you have not registered a service broker)Configure the service broker for the Job Scheduler service as described in the chapter Configure the Service Broker for Job Scheduler.

NoteYou need to register a service broker once.

2. Create a Job Scheduler service instance in the XSA space you use for SAP Predictive Maintenance and Service, on-premise edition as described in the chapter Create a Job Scheduler Service Instance.

3. Bind the Job Scheduler service instance to an app of your choice as described in the chapter Bind an Application to the Job Scheduler Service.



http://help.sap.com/disclaimer?site=https://launchpad.support.sap.com/#/softwarecenter/search/XS%2520SERVICES%25201

http://help.sap.com/hana/SAP_HANA_Server_Installation_Guide_en.pdf

http://help.sap.com/hana/SAP_HANA_Server_Installation_Guide_en.pdf

http://help.sap.com/saphelp_hanaplatform/helpdata/en/13/b037a505f244bd8bd089ef17f28f19/content.htm

http://help.sap.com/saphelp_hanaplatform/helpdata/en/13/b037a505f244bd8bd089ef17f28f19/content.htm

https://help.sap.com/saphelp_hanaplatform/helpdata/en/4d/e4ea4f04ea460cbccb7d97c78e7183/content.htm?frameset=/en/03/c86bc93d55435b999065c1d4e6689d/frameset.htm&current_toc=/en/00/0ca1e3486640ef8b884cdf1a050fbb/plain.htm&node_id=803&show_children=false

http://help.sap.com/saphelp_hanaplatform/helpdata/en/d8/8288fbd62147c99a9fe2bdaf1ba1bb/content.htm

http://help.sap.com/saphelp_hanaplatform/helpdata/en/41/9663fee60f41fb9b5402bd2167717a/content.htm?frameset=/en/49/585122eba34377af9bb021cfdafede/frameset.htm&current_toc=/en/ea/d6bf24e92745949a91b9ff2216af50/plain.htm&node_id=173

http://help.sap.com/saphelp_hanaplatform/helpdata/en/e9/f5128e8acb4efe8faa0502e448c27f/content.htm?frameset=/en/41/9663fee60f41fb9b5402bd2167717a/frameset.htm&current_toc=/en/ea/d6bf24e92745949a91b9ff2216af50/plain.htm&node_id=174

http://help.sap.com/saphelp_hanaplatform/helpdata/en/e9/f5128e8acb4efe8faa0502e448c27f/content.htm?frameset=/en/41/9663fee60f41fb9b5402bd2167717a/frameset.htm&current_toc=/en/ea/d6bf24e92745949a91b9ff2216af50/plain.htm&node_id=174

This step is required to access the environment variables of the app datascience-service.

Fill in the variables as follows:

Table 57: Variables for Binding an App

Variable Value

<application name> datascience-service

<service instance name> Name of the Job Scheduler service instance that you created in Step 2

4. Extract the user name and password from the environment of the app datascience-service that you have bound the Job Scheduler service instance by executing the command xs env datascience-service.

After executing this command, the details of the Job Scheduler service instance are displayed as well.

Sample Code

"jobscheduler" : [ { "name" : "<Name of Job Scheduler service instance>", "label" : "jobscheduler", "tags" : [ "jobscheduler" ], "plan" : "default", "credentials" : { "password" : "<App environment password>", "user" : "<App environment user name>", "url" : "https://<Host of the Job Scheduler service>:<Port of the Job Scheduler service>" } }

The URL is used to access the Job Scheduler service, the user name and password are used to create a job using the Job Scheduler service.

5. Maintain jobs and job schedules as described in the chapter Maintain Jobs and Job Schedules in XS Advanced.

Sample Code

"name":"<Name of the job>", "description": "<Description of the job>", "action":"https://<Host of pdms router>:<Port of pdms router>/datascience/api/v1/models/score/<model ID>", "active": false, "httpMethod":"POST", "schedules": [ { "cron":"* * * * * * */10", "description": "This schedule runs every 10 seconds", "active": true, "startTime": {"date": "2016-01-01 00:00 +0000", "format": "YYYY-MM-DD HH:mm Z"} } ]}


http://help.sap.com/saphelp_hanaplatform/helpdata/en/79/1a171998384f029ae544f0b266cecc/content.htm?frameset=/en/e9/f5128e8acb4efe8faa0502e448c27f/frameset.htm&current_toc=/en/ea/d6bf24e92745949a91b9ff2216af50/plain.htm&node_id=175&show_children=false

http://help.sap.com/saphelp_hanaplatform/helpdata/en/79/1a171998384f029ae544f0b266cecc/content.htm?frameset=/en/e9/f5128e8acb4efe8faa0502e448c27f/frameset.htm&current_toc=/en/ea/d6bf24e92745949a91b9ff2216af50/plain.htm&node_id=175&show_children=false

NoteSo far, the example code creates only an inactive job without any authentication.

In order to add basic authentication a second request (PUT /scheduler/jobs/:jobId) is necessary, as described in the chapter Job Scheduler REST API for XS Advanced.

Sample CodeSample code to configure a job

{ "active":true, "user":"<PDMS_DS_ADMIN>", "password":"<PASSWORD FOR PDMS_DS_ADMIN>", }

NoteThe basic authorization is now configured for the job which is also activated within the sample call. The handling of the X-CSRF token is taken care of by the Job Scheduler service, which is calling first GET on the the given URL to obtain the token, and uses the token to later do the original POST call. You can verify in the view SYS.M_TASKS that a new job task is created every 10 seconds.

For more information about the <PDMS_DS_ADMIN> user, see the guide Installation of SAP Predictive Maintenance and Service, on-premise edition.

NoteFor more information about how to work with the Job Scheduler service using REST APIs, see the chapter Job Scheduler REST API for XS Advanced.

6. Check and manage your jobs and job schedules in the Job Scheduler dashboard as described in the chapter The Job Scheduler Dashboard.

7. (If required) Stop a job schedule by updating the job configuration.a. Retrieve the job ID.

REST API call:

Sample Code

GET https://<Host of the Job Scheduler service>:<Port of the Job Scheduler service>/scheduler/jobs

This returns a list of jobs configured in the Job Scheduler service.b. Stop the job schedule.

REST API call:

Sample Code

PUT https://<Host of the Job Scheduler service>:<Port of the Job Scheduler service>/scheduler/jobs/<job _id>



http://help.sap.com/saphelp_hanaplatform/helpdata/en/5e/f38ae037434042baf25dc79598bf8d/content.htm?frameset=/en/5e/f38ae037434042baf25dc79598bf8d/frameset.htm&current_toc=/en/ea/d6bf24e92745949a91b9ff2216af50/plain.htm&node_id=176

http://help.sap.com/saphelp_hanaplatform/helpdata/en/5e/f38ae037434042baf25dc79598bf8d/content.htm?frameset=/en/5e/f38ae037434042baf25dc79598bf8d/frameset.htm&current_toc=/en/ea/d6bf24e92745949a91b9ff2216af50/plain.htm&node_id=176

http://help.sap.com/saphelp_hanaplatform/helpdata/en/d4/71f9803bcb4479845d17be0519ce4a/content.htm?frameset=/en/5e/f38ae037434042baf25dc79598bf8d/frameset.htm&current_toc=/en/ea/d6bf24e92745949a91b9ff2216af50/plain.htm&node_id=177

with the following body

{ "active": false }

This deactivates the job schedule.

Alternatively, you can use the Manage screen of the Job Scheduler dashboard to deactivate running jobs. For more information, see the chapter The Job Scheduler Dashboard.

2.5 Creating Custom Algorithms Using the Launchpad

Prerequisites

You have created and installed an R package on the R server with functions for scoring and training that you can use for your custom algorithms. You have also tested the compatibility of your custom R package. For more information, see one of the following chapters in the guide SAP Predictive Maintenance and Service, Test Tool for Data Science:

● How to Create R Packages and Functions for Training and Scoring● Testing Custom R Packages Semi-Automatically



For more information about roles, see the following chapters in the installation guide of SAP Predictive Maintenance and Service, on-premise edition 1.0:


Context

NoteThe UIs to create custom algorithms support the following languages:

● English

TipWe recommend that you avoid using the Refresh functionality of your browser while you are creating your own algoirthms. If you experience issues with the Refresh functionality, please try one of the following options:


http://help.sap.com/saphelp_hanaplatform/helpdata/en/d4/71f9803bcb4479845d17be0519ce4a/content.htm?frameset=/en/41/9663fee60f41fb9b5402bd2167717a/frameset.htm&current_toc=/en/ea/d6bf24e92745949a91b9ff2216af50/plain.htm&node_id=177

● Click the Back button of your browser.● Close the browser window and open the launchpad again.

Procedure

1. Open the URL https://<hostname>:<port>/app/launchpad/index.html and log on with your user.

2. In the group Manage Machine Learning Engine, open the app Custom Algorithm Integration.

3. To create a new algorithm, click Create Custom Algorithm.4. Fill in the required fields as described in the chapter Entries to Create a Custom Algorithm [page 82].5. Save your algorithm.

2.5.1 Entries to Create a Custom Algorithm

Table 58: Entries to Create a Custom Algorithm


Name x Name of the custom algorithm

Training Function x Training function used for the algorithm

For more information, see SAP Predictive Maintenance and Service, Test Tool for Data Science → How to Create R Packages and Functions for Training and Scoring.

Scoring Function x Scoring function used for the algorithm


Namespace x Custom namespace in which you create the algorithm




R-Package x Custom R package that you want to use with the algorithm


Learner Type x Machine learning style that serves as metadata to provide information about what the algorithm is used for

Depending on the algorithm you are using, you are provided with the following algorithms:

● CLASSIFICATIONChoose this learner type if data is being used to predict a category, for example, to classify between good and defective.

● REGRESSIONChoose this learner type to predict a value, for example, a health score.

● SURVIVALChoose this learner type to predict the expected time until a certain event (such as the breakdown of an asset) will happen.

● RULESChoose this learner type to include rules in the machine learning process.

● UNSUPERVISEDChoose this learner type if data needs to be organized or if its structure needs to be described.

● OTHER

Related Information

Creating Custom Algorithms Using the Launchpad [page 81]


2.6 Creating Custom Algorithms Using REST APIs

Prerequisites

You have created and installed an R package on the R server with functions for scoring and training that you can use for your custom algorithms. You have also tested the compatibility of your custom R package. For more information, see one of the following chapters in the guide SAP Predictive Maintenance and Service, Test Tool for Data Science:

● How to Create R Packages and Functions for Training and Scoring● Testing Custom R Packages Semi-Automatically



For more information about roles, see the following chapters in the installation guide of SAP Predictive Maintenance and Service, on-premise edition 1.0:


Context

In addition to the UIs for creating custom algorithms, you can also use REST APIs to create custom algorithms.

Procedure

1. Create an algorithm as described in the chapter Create a Custom Algorithm [page 85].

You can also do the following:○ Read Learner Types [page 87] before you create a custom algorithm○ Read an Algorithm [page 89]○ Read All Algorithms [page 90]

2. (If required) Delete a custom algorithm as described in the chapter Delete a Custom Algorithm [page 92].



2.6.1 Create a Custom Algorithm

Configure new algorithm. By default, SAP Predictive Maintenance and Service, on-premise edition 1.0 is shipped with the algorithms PCA, EMD, RUL, MAR, and TEC.

NoteFor more information about the predelivered algorithms, see the Getting Started guide.

Request

Format: JSON

URI: http://<hostname>:<router port>datascience/api/v1/global-configs

HTTP Method: POST

Request Example

{ "namespace": "some.namespace", "dataScienceService": "someAlgorithmName", "rPackage": "com.sap.pdms.datascience.pca", "trainFunction": "PCAtrain", "scoreFunction": "PCAscore", "learnerType": "OTHER"}



namespace Yes Custom namespace in which you create the custom algorithm

dataScienceService Yes Name of the custom algorithm

rPackage Yes Custom R package that you want to use with the algorithm

For more information, see the following chapter in the SAP Predictive Maintenance and Service, Test Tool for Data Science:

● How to Create R Packages and Functions for Training and Scoring

trainFunction Yes Training function used for the algorithm





scoreFunction Yes Scoring function used for the algorithm



learnerType Yes Machine learning style that serves as metadata to provide information about what the algorithm is used for

The following learner types are supported:

● CLASSIFICATIONChoose this learner type if data is being used to predict a category, for example, to classify between good and defective.Prediction target: Mandatory

● REGRESSIONChoose this learner type to predict a value, for example, a health score.Prediction target: Mandatory

● SURVIVALChoose this learner type to predict the expected time until a certain event (such as the breakdown of an asset) will happen.Prediction target: Mandatory

● RULESChoose this learner type to include rules in the machine learning process.Prediction target: Not allowed

● UNSUPERVISEDChoose this learner type if data needs to be organized or if its structure needs to be described.Prediction target: Not allowed

● OTHERPrediction target: Optional

Response

Format: JSON

Response Example

{ "namespace": "some.namespace", "dataScienceService": "someDssName", "rPackage": "com.sap.pdms.datascience.pca",



"trainFunction": "PCAtrain", "scoreFunction": "PCAscore", "learnerType": "OTHER", "hyperParameters": [{ "key": "normalisation.value", "values": [ "0.99" ] }]}


Table 60:


Conflict 409 An entry for the algorithm '<algorithm>' already exists in namespace '<namespace>'."

Bad request 409 The algorithm does not exist in the namespace.

400 Invalid values were entered.


Related Information

Creating Custom Algorithms Using REST APIs [page 84]Read an Algorithm [page 89]Read All Algorithms [page 90]Delete a Custom Algorithm [page 92]

2.6.1.1 Read Learner Types

Retrieve all learner types used for algorithms and check if prediction targets are mandatory, optional, or not allowed.

NotePrediction targets are dependent variables. These variables are variables or attributes that a model needs to train and score on.


Request

Format: JSON

URI: http://<hostname>:<router port>datascience/api/v1/learner-types

HTTP Method: GET

Response

Response Example

[{ learnerTypeName:"CLASSIFICATION", dependentVariableState:"MANDATORY"},{ learnerTypeName:"REGRESSION", dependentVariableState:"MANDATORY"},{ learnerTypeName:"SURVIVAL", dependentVariableState:"MANDATORY"},{ learnerTypeName:"RULES", dependentVariableState:"NOT_ALLOWED"},{ learnerTypeName:"UNSUPERVISED", dependentVariableState:"NOT_ALLOWED"},{ learnerTypeName:"OTHER", dependentVariableState:"OPTIONAL"}]

NoteFor more information about prediction targets, see Model-Specific Parameters [page 44].


Table 61:





2.6.1.2 Read an Algorithm

Retrieve a specific algorithm

Request

Format: JSON

URI: http://<hostname>:<router port>datascience/api/v1/global-configs/<namespace>/<algorithm>

HTTP Method: GET

Response

Response Example

{ "namespace": "com.sap.pdms.datascience", "dataScienceService": "EMD", "rPackage": "datasci.dbfa.emd", "trainFunction": "EMDtrain", "scoreFunction": "EMDscore", "learnerType": "OTHER", "hyperParameters": [ { "key": "group.by", "values": [ "ThingType" ] }, { "key": "sort.by", "values": [ "Timestamp" ] } ]}

NoteFor more information about hyperparameters, see the chapter Model-Specific Parameters in the configuration guide of SAP Predictive Maintenance and Service, on-premise edition 1.0.



Table 62:


Not found 404 No algorithm with the name <algorithm> exists in the namespace <namespace>.


Related Information

Create a Custom Algorithm [page 85]Read All Algorithms [page 90]Delete a Custom Algorithm [page 92]

2.6.1.3 Read All Algorithms

Retrieve all algorithms

Request

Format: JSON

URI: http://<hostname>:<router port>datascience/api/v1/global-configs

HTTP Method: GET

Response

Response Example

[ { "namespace": "com.sap.pdms.datascience", "dataScienceService": "EMD", "scoreFunction": "EMDscore", "trainFunction": "EMDtrain", "url": "http(s)://[host]:[port]/datascience/api/v1/global-configs/com.sap.pdms.datascience/EMD", "rPackage": "datasci.dbfa.emd", "learnerType": "OTHER", "hyperParameters": [ { "key": "normalisation.value",



"values": [ "0.99" ] }, { "key": "normalisation.type", "values": [ "threshold" ] }, { "key": "sort.by", "values": [ "Timestamp" ] } ] }, "namespace": "com.sap.pdms.datascience", "dataScienceService": "PCA", "scoreFunction": "PCAscore", "trainFunction": "PCAtrain", "url": "http(s)://[host]:[port]/datascience/api/v1/global-configs/com.sap.pdms.datascience/PCA", "rPackage": "com.sap.pdms.datascience.pca", "learnerType": "OTHER", "hyperParameters": [ { "key": "group.by", "values": [ "ThingType" ] }, { "key": "sort.by", "values": [ "Timestamp" ] } ] }, ...]

NoteFor more information about hyperparameters, see Model-Specific Parameters [page 44].


Table 63:



Related Information

Create a Custom Algorithm [page 85]Read an Algorithm [page 89]


Delete a Custom Algorithm [page 92]

2.6.2 Delete a Custom Algorithm

Delete a custom algorithm.

Request

Format: JSON

URI: http://<hostname>:<router port>datascience/api/v1/global-configs/<namespace>/<dataScienceService>

HTTP Method: DELETE

Response

NoteIf no content is displayed after you have sent the REST call, the algorithm is deleted.


Table 64:


Forbidden 403 It is forbidden to delete an algorithm from the namespace com.sap.pdms.datascience.


Related Information

Creating Custom Algorithms Using REST APIs [page 84]Create a Custom Algorithm [page 85]Read an Algorithm [page 89]Read All Algorithms [page 90]



2.7 Configuring the Insight Provider Catalog Using REST APIs

The Insight Provider Catalog is configured using REST APIs.



Having this role collection assigned, you can configure the Insight Provider Catalog and check the effect of your configurations in the Asset Health Control Center.


To configure the Insight Provider Catalog, proceed as follows:

1. Create insight provider entries and insight provider types as described in the chapter Create Insight Provider Entries in the Catalog [page 93].You can also do the following:○ Read an Insight Provider Entry [page 100]○ Read All Insight Provider Entries [page 101]○ Read an Insight Provider Type [page 102]○ Read All Insight Provider Types [page 102]

2. (If required) delete an insight provide entry as described in the chapter Delete an Insight Provider Entry [page 103].

3. (If required) delete an insight provide type as described in the chapter Delete an Insight Provider Type [page 103].

Related Information

Configuring SAP Predictive Maintenance and Service, on-premise edition 1.0 [page 6]

2.7.1 Create Insight Provider Entries in the Catalog

Create insight provider entries that business user can then add from the Insight Provider Catalog to the Asset Health Control Center or the Asset Health Fact Sheet.

NoteNo insight provider entry can be created for key figures because key figures are added to the Insight Provider Catalog by creating key figure sets.

For more information, see the chapter Creating Key Figures [page 106].


Request

Format: JSON

URI: http://<hostname>:<router port>/platform/service-catalog/api/v1/service-entries

HTTP Method: PUT

Request Example

{ "description": "<Description of insight provider>", "id": "<insight provider ID>", "imageUrl": "<image URL of insight provider>", "interactive": <true or false>, "name": "<insight provider name>", "serviceType": { "id": "<service type ID>" }, "options": {"foo": "bar"}, "serviceUrl": "<service URL of insight provider>", "url": "https://<host name>:<port>/platform/service-catalog/api/v1/service-entries/<service type ID>" }



id Yes ID of the insight provider you want to register in the insight provider catalog

NoteFor an overview of IDs that need to be entered for each insight provider, see Service Type IDs [page 97].

name Yes Name of the insight provider you want to register in the insight provider catalog

NoteOn the UI of the insight provider catalog, predefined names and descriptions of insight providers are displayed. These values are required by the registration procedure. For a list of the predefined names and descriptions for each insight provider, see Predefined Titles and Descriptions for Insight Provider Registration [page 97].




description Yes Description of the insight provider you want to register inthe insight provider catalog

NoteOn the UI of the insight provider catalog, predefined names and descriptions of insight providers are displayed. These values are required by the registration procedure. For a list of the predefined names and descriptions for each insight provider, see Predefined Titles and Descriptions for Insight Provider Registration [page 97].

imageUrl Yes URL path to the image that is displayed as the icon for the insight provider in the insight provider catalog

NoteFor an overview of the URLs that need to be entered for each insight provider, see URLs Required for Insight Provider Registration [page 99].

serviceUrl Yes URL path to the insight provider

NoteFor an overview of the URLs that need to be entered for each insight provider, see URLs Required for Insight Provider Registration [page 99].



interactive Yes Value true if the insight provider is displayed on the UI of the insight provider catalog

Value false if the insight provider is not displayed on the UI of the insight provider catalog

NoteWhen registering the insight providers for 2D data visualization and filter, set this value to false for these insight providers.

serviceType Yes Predefined value:

{"id": "com.sap.pdms.InsightProvider"}

options No This field can be used to store additional metadata about a service entry. and that it has to be any json object but cannot be a json array.

NoteIt can be any json object but cannot be a json array. This parameter is restricted to 2048 characters.

Related Information

Configuring the Insight Provider Catalog Using REST APIs [page 93]Read an Insight Provider Entry [page 100]Read All Insight Provider Entries [page 101]Read an Insight Provider Type [page 102]Read All Insight Provider Types [page 102]Delete an Insight Provider Type [page 103]Delete an Insight Provider Entry [page 103]



2.7.1.1 Service Type IDs

To register insight providers in the Insight Provider Catalog, you need to enter the service type ID of each insight provider.

Table 66: Service Type IDs

Insight Provider Service Type ID

Asset Explorer com.sap.pdms.ipro.asset-explorer

Components com.sap.pdms.ipro.component

Derived Signals com.sap.pdms.ipro.derived-signals

Work Activities com.sap.pdms.ipro.work-activity

Map com.sap.pdms.ipro.geospatial

3D Chart com.sap.pdms.ipro.3dviz

Filter

NoteThis insight provider is not displayed on the UI of the insight provider catalog, but is consumed by the Asset Explorer.

com.sap.pdms.ipro.filter

2D Chart com.sap.pdms.ipro.2d-viz

Asset and Component Scores com.sap.pdms.ipro.acs

Related Information

Create Insight Provider Entries in the Catalog [page 93]

2.7.1.2 Predefined Titles and Descriptions for Insight Provider Registration

To register insight providers in the insight provider catalog, you need to enter a name and description for each insight provider. These names and descriptions are identical to the names and descriptions predefined by SAP Predictive Maintenance and Service.


Table 67: Names and Descriptions for Insight Provider Registration

Insight Provider Name Description

Asset Explorer Asset Explorer Provides a list of assets, as well as their attributes. It also enables you to set filters.

Components Components Provides a hierarchical list of components of an asset, along with their attributes.

Derived Signals Derived Signals Provides a list of the current derived signals based on rules defined for sensor data, and a 2D chart for data visualization.

Work Activities Work Activities Provides a list of current work activities with details.

Map Map Provides a display of assets and their health status by geolocation and issue severity. Also allows spatial selection.

3D Chart 3D Chart Provides sensor data visualization across assets and time, and the ability to overlay derived signals.

2D Chart 2D Chart Provides data visualization across one or more measurements.

Asset and Component Scores Asset and Component Scores Provides a sorted list of asset and component scores indicating their current health status.

Related Information




2.7.1.3 URLs Required for Insight Provider Registration

imageURL

To register an insight provider in the Insight Provider Catalog, you need to enter the URL path to the image that is delivered with the insight provider.

Table 68: imageURLs for Insight Provider Registration

Insight Provider imageURL

Asset Explorer sap-icon://newspaper

Components sap-icon://list

Derived Signals sap-icon://measuring-point

Work Activities sap-icon://activity-2

Map sap-icon://map-2

3D Chart sap-icon://chart-axis

Filter


sap-icon://filter

2D Chart sap-icon://line-chart

Asset and Component Scores sap-icon://machine/

serviceURL

To register an insight provider in the Insight Provider Catalog, you need to enter the URL path to the location of the insight provider.

Table 69: serviceURLs for Insight Provider Registration

Insight Provider serviceURL

Asset Explorer /ipro/asset-explorer


Insight Provider serviceURL

Components /ipro/components

Derived Signals /ipro/derived-signals

Work Activities /ipro/work-activity

Map /ipro/geospatial

3D Chart /ipro/threed-viz

Filter


/ipro/filter

2D Chart /ipro/twod-viz/sap/pdms/2dviz

Asset and Component Scores /ipro/asset-component-scores

Related Information


2.7.2 Read an Insight Provider Entry

Retrieves specific insight provider entry.

Request

Format: JSON

URI: http://<hostname>:<router port>/platform/service-catalog/api/v1/service-entries/<serviceEntryId>

HTTP Method: GET



Related Information

Configuring the Insight Provider Catalog Using REST APIs [page 93]Create Insight Provider Entries in the Catalog [page 93]Read All Insight Provider Entries [page 101]Read an Insight Provider Type [page 102]Read All Insight Provider Types [page 102]Delete an Insight Provider Type [page 103]Delete an Insight Provider Entry [page 103]

2.7.3 Read All Insight Provider Entries

Retrieves all insight provider entries.

Request

Format: JSON

URI: http://<hostname>:<router port>/platform/service-catalog/api/v1/service-entries

HTTP Method: GET

Request Parameters (Optional)Table 70:

Parameter Located In Required

serviceName Query No

serviceDescription Query No

serviceInteractive Query No

serviceTypeName Query No

Related Information

Configuring the Insight Provider Catalog Using REST APIs [page 93]Create Insight Provider Entries in the Catalog [page 93]Read an Insight Provider Entry [page 100]Read an Insight Provider Type [page 102]Read All Insight Provider Types [page 102]Delete an Insight Provider Type [page 103]Delete an Insight Provider Entry [page 103]


2.7.4 Read an Insight Provider Type

Retrieves specific insight provider type.

Request

Format: JSON

URI: http://<hostname>:<router port>/platform/service-catalog/api/v1/service-types/<serviceTypeId>

HTTP Method: GET

Related Information

Configuring the Insight Provider Catalog Using REST APIs [page 93]Create Insight Provider Entries in the Catalog [page 93]Read an Insight Provider Entry [page 100]Read All Insight Provider Entries [page 101]Read All Insight Provider Types [page 102]Delete an Insight Provider Type [page 103]Delete an Insight Provider Entry [page 103]

2.7.5 Read All Insight Provider Types

Retrieves all insight provider types.

Request

Format: JSON

URI: http://<hostname>:<router port>/platform/service-catalog/api/v1/service-types

HTTP Method: GET

Related Information

Configuring the Insight Provider Catalog Using REST APIs [page 93]



Create Insight Provider Entries in the Catalog [page 93]Read an Insight Provider Entry [page 100]Read All Insight Provider Entries [page 101]Read an Insight Provider Type [page 102]Delete an Insight Provider Type [page 103]Delete an Insight Provider Entry [page 103]

2.7.6 Delete an Insight Provider Entry

Deletes specific insight provider entry.

Request

Format: JSON

URI: http://<hostname>:<router port>/platform/service-catalog/api/v1/service-entries/<serviceEntryId>

HTTP Method: DELETE

Related Information

Configuring the Insight Provider Catalog Using REST APIs [page 93]Create Insight Provider Entries in the Catalog [page 93]Read an Insight Provider Entry [page 100]Read All Insight Provider Entries [page 101]Read an Insight Provider Type [page 102]Read All Insight Provider Types [page 102]Delete an Insight Provider Type [page 103]

2.7.7 Delete an Insight Provider Type

Deletes specific insight provider type.

Request

Format: JSON


URI: http://<hostname>:<router port>/platform/service-catalog/api/v1/service-types/<serviceTypeId>

HTTP Method: DELETE

Related Information

Configuring the Insight Provider Catalog Using REST APIs [page 93]Create Insight Provider Entries in the Catalog [page 93]Read an Insight Provider Entry [page 100]Read All Insight Provider Entries [page 101]Read an Insight Provider Type [page 102]Read All Insight Provider Types [page 102]Delete an Insight Provider Entry [page 103]

2.8 Configuring Insight Providers Using Configuration UIs

As an alternative to REST APIs, you can also configure insight providers using the configuration UIs.

Prerequisites



This role collectionenables you to configure the Insight Provider Catalog and check the effect of your configurations in the Asset Health Control Center.


Context

NoteThe configuration UIs to configure insight providers support the following languages:

● English



Procedure

● Open the URL https://<hostname>:<port>/app/launchpad/index.html and log on with your user.● In the group Configure Insight Providers, open the Key Figures app to create key figures as explained in the

chapter Creating Key Figures in the installation guide of SAP Predictive Maintenance and Service, on-premise edition 1.0.

NoteData fusion views and stored procedures used for key figures need to be created by the <User to create procedures for key figures>.

● In the group Configure Insight Providers, open the Key Figure Sets app to create key figure sets based on your key figures as explained in the chapter Creating Key Figure Sets in the installation guide of SAP Predictive Maintenance and Service, on-premise edition 1.0.

● In the group Configure Insight Providers, open the app of the insight provider that you want to configure.

NoteFor the following insight providers, you can configure variants:○ Derived Signals○ 3D Chart○ Map

If business users add these insight providers from the Insight Provider Catalog to the Asset Health Control Center or the Asset Health Fact Sheet, users can decide which insight provider variant they want to add.

NoteThere is no predefined order in which you should configure insight providers.

Related Information

Entries to Configure the Asset Explorer [page 111]Entries to Configure Components [page 119]Entries to Configure Work Activities [page 121]Entries to Configure Derived Signals [page 123]Entries to Configure the Map [page 124]Entries to Configure the 2D Chart [page 132]Entries to Configure the 3D Chart [page 134]Entries to Configure the Asset and Component Scores [page 138]


2.8.1 Creating Key Figures

Prerequisites

● The schema SAP_PDMS_DATA_KEY_FIGURES is created. If the schema is not created yet, create it as described in the chapter Installing SAP Predictive Maintenance and Service, on-premise edition 1.0 in the guide Installation of SAP Predictive Maintenance and Service, on-premise edition 1.0.

● In the schema SAP_PDMS_DATA_KEY_FIGURES, data fusion views are created as explained in the chapter Creating Data Fusion Views for Key Figures [page 107].

● In the schema SAP_PDMS_DATA_KEY_FIGURES, stored procedures are created as explained in the chapter Creating Stored Procedures for Key Figures [page 109]

Context

To display key figures in the Asset Health Control Center that can be used for asset analysis, you first need to create key figures in the Key Figures app.

Procedure

1. On the launchpad, open the app Key Figures.

2. To create a key figure, click Create a New Key Figure.3. Fill in the required entries.

Table 71: Entries to Create Key Figures

Entry Field Description

Language Language in which the key figure is displayed

Title Title of the key figure

Unit of Measure Unit of measure used in the key figure

Decimal Places Accuracy of the key figure

Number Style You can choose among the following number styles:○ Short○ Standard




Stored Procedure Name of the procedure that you created for the key figure.

For more information about creating stored procedures, see the chapter Creating Stored Procedures for Key Figures [page 109].

Time Period Time period based on which readings are to be aggregated for the key figure.

ExampleYou would like to display the average temperature for to

day: Choose Current 1 Day(s)

4. Save the key figure.

Results

You can add the key figure that you created to a key figure set as explained in the chapter Creating Key Figure Sets [page 110].

Related Information

Configuring Insight Providers Using Configuration UIs [page 104]

2.8.1.1 Creating Data Fusion Views for Key Figures

Prerequisites

● The data model of SAP Predictive Maintenance and Serivce, on-premise edition 1.0 is set up.For more information about the data model, see the chapter Data Model in the guide Installation of SAP Predictive Maintenance and Service, on-premise edition 1.0.

● The schema SAP_PDMS_DATA_KEY_FIGURES is created.


Context

Before you can configure key figures, you need to create two data fusion views:

1. One fusion view to define the parent-child relationship between the assets and components used for key figures.

2. Another fusion view to define the readings used for key figures.

Procedure

1. Log on to SAP HANA studio with the <user to create procedures for key figures>.

2. In the SQL editor, execute the following statement to create the first fusion view:

Sample Code

CREATE VIEW "SAP_PDMS_DATA_KEY_FIGURES"."ASSET_COMPONENT_MAP" as select "<Alias3>"."ChildID" as "ComponentId", "<Alias4>"."ObjectID" as "AssetId" from (select "<Alias2>"."ObjectID" as "ChildID", "<Alias1>"."ParentID" from "SAP_PDMS_DATA"."com.sap.pdms.sdm::META.HierarchyNode" as "<Alias1>" inner join "SAP_PDMS_DATA"."com.sap.pdms.sdm::META.HierarchyAssignment" as "<Alias2>" on "<Alias1>"."ID" = "<Alias2>"."NodeID" where "<Alias2>"."StartDateTime" < CURRENT_TIMESTAMP and "<Alias2>"."EndDateTime" > CURRENT_TIMESTAMP) as "<Alias3>" inner join "SAP_PDMS_DATA"."com.sap.pdms.sdm::META.HierarchyAssignment" as "<Alias4>" on "<Alias3>"."ParentID" = "<Alias4>"."NodeID" where "<Alias4>"."StartDateTime" < CURRENT_TIMESTAMP and "<Alias4>"."EndDateTime" > CURRENT_TIMESTAMP;

You have now defined the parent-child relationship between assets and components. The first fusion view needs to be created once.

3. In the SQL editor, execute the following statement to create the second fusion view:

Sample Code

CREATE VIEW "SAP_PDMS_DATA_KEY_FIGURES"."<Measurement ID for which you want to create and compute key figures>" as select "<Alias5>"."AssetId" as "AssetId", "<Alias6>"."PropertyValue" as "Value", "<Alias6>"."Timestamp" as "Timestamp" from "SAP_PDMS_DATA"."com.sap.pdms.sdm::DATA.READINGS" as "<Alias6>" inner join "SAP_PDMS_DATA_KEY_FIGURES"."ASSET_COMPONENT_MAP" as "<Alias5>" on "<Alias6>"."Thing" = "<Alias5>"."ComponentId" where "<Alias6>"."ThingType" = '<ThingType>' and "<Alias6>"."PropertySetTypeId" = '<PropertySetTypeId>' and "<Alias6>"."PropertyId" = '<PropertyId>';

You have now defined the readings that you want to be used for your key figure. The second fusion view needs to be created for each type of measurement that you want to be used for key figures.



Results

After you have created the views, you can create procedures for each key figure that you want to create and compute as described in the chapter Creating Stored Procedures for Key Figures [page 109].

Related Information

Creating Key Figures [page 106]

2.8.1.2 Creating Stored Procedures for Key Figures

Prerequisites

● You have created the data fusion view schemas as explained in the chapter Creating Data Fusion Views for Key Figures [page 107].

Context

To create and compute key figures, you need to create procedures to make required data available to the key figures.

Procedure

1. Log on to SAP HANA studio with the <User to create procedures for key figures>.

2. In the SQL editor, execute the following statement to create a procedure:

Sample Code

CREATE PROCEDURE "SAP_PDMS_DATA_KEY_FIGURES"."<procedure name>"(in things table(id varchar(50)), in fr timestamp, in t timestamp, out result double) language sqlscript sql security invokerasbegin declare no_selection int := 0; select count(*) into no_selection from :things; if (no_selection > 0) then select avg("Value") into result from "SAP_PDMS_DATA_KEY_FIGURES"."<Measurement ID for which you want to create and


compute key figures>" where "AssetId" in (select * from :things) and "Timestamp" >= fr and "Timestamp" <= t; else select avg("Value") into result from "SAP_PDMS_DATA_KEY_FIGURES"."<Measurement ID for which you want to create and compute key figures>" where "Timestamp" >= fr and "Timestamp" <= t; end if; end;

3. Repeat step 2 for each key figure that you want to create for a specific measurement ID.

The sample code is used to calculate the average of readings, which can be displayed in a key figure. You can also create procedures to calculate the maximum or minimum value of the the same readings if required.

For more information about what aggregation expressions are supported, see the chapter Aggregate Expressions in the SAP HANA SQL and System Views Reference.

Related Information

Creating Key Figures [page 106]

2.8.2 Creating Key Figure Sets

Prerequisites

● You have created at least one key figure that can be added to a key figure set as explained in the chapter Creating Key Figures [page 106].

Context

To make key figures available for asset analysis in the Asset Health Control Center or on the Asset Health Fact Sheet, key figures need to be added to key figure sets. Business users can then add these key figure sets from the Insight Provider to the Asset Health Control Center or the Asset Health Fact Sheet.

Procedure

1. On the launchpad, open the app Key Figure Sets.

2. To create a key figure set, click Create a New Key Figure Set.



https://help.sap.com/saphelp_hanaplatform/helpdata/en/20/a4389775191014b5a6bf2ccc0df2ed/content.htm#loio20a4389775191014b5a6bf2ccc0df2ed___fsql_expressions_1sql_expressions_aggregate_expressions

https://help.sap.com/saphelp_hanaplatform/helpdata/en/20/a4389775191014b5a6bf2ccc0df2ed/content.htm#loio20a4389775191014b5a6bf2ccc0df2ed___fsql_expressions_1sql_expressions_aggregate_expressions

3. Fill in the general information of the key figure set.

Table 72: General Information of a Key Figure Set


Language Language in which the key figure set is displayed

Title Title of the key figure set

4. Add the key figures that you want to display in the key figure set.5. Save the key figure set.

Related Information


2.8.3 Entries to Configure the Asset Explorer

Filter Attributes

Table 73: Entries to Configure Filter Attributes


Filter ID Identifies the attribute filter and must be defined as <PropertySetTypeId>/<PropertyId>. Choose the PropertySetTypeId and corresponding PropertyId from the views com.sap.pdms.sdm::DATA.MASTER_DATA or com.sap.pdms.sdm::DATA.READINGS in the data model.

NoteIt is mandatory to define one entry where you entermachineId for Filter ID and Filter Name.

Filter Name Name of the filter



Filter Label ,Key of the filter that is used for text mapping in the section Translations.

NoteThe text mapped to this key is later on the filter label displayed in the Asset Explorer.

Selection Type You can choose among the following options:

● MultipleBusiness users can filter on more than one value in the Asset Explorer.

● SingleBusiness users can filter on only one value in the Asset Explorer.

ExampleThe following screenshots are examples of what your filter configuration can look like on the Asset Explorer UI:



Asset List

Table 74: Entries to Configure the Asset List


Dimension ID Identifies columns to be displayed in the asset list.

You can configure the following properties:

● Asset properties: id, nameexternalId, description

NoteEnter the asset property exactly as displayed above taking account of the upper and lower case letters.

NoteYou must create one dimension ID called id. This represents the asset.

● Master data properties: <PropertySetTypeId>/<PropertyId> from the view com.sap.pdms.sdm::DATA.MASTER_DATA in the data model. For example, MasterData/Manufacturer

● Reading properties: <PropertySetTypeId>/<PropertyId> from the view com.sap.pdms.sdm::DATA.READINGS in the data model. For example, healthState/SCORE



Dimension Type Data type of the column value. You can choose from the following values:

● string● float● integer● healthStatus: This is a special datatype which shows

colored icons that represent values. If the underlying dimension ID has the value 0, 1, 2, or 3, it displays grey (unknown), red (critical), orange (warning), green (no issues) respectively.

Dimension Path Binds the column to the corresponding value of the JSON response sent by the backend

This field holds the path to the value. To render the value on the user interface, the corresponding dimension ID has to be bound to the path of the JSON. You define the dimension path as properties/<Dimension ID>. The dimension ID column is explained above. For example, if the dimension ID is healthState/SCORE then the dimension path is properties/healthState/SCORE. If the dimension ID is name then the dimension path is properties/name .

NoteFor the mandatory dimension ID, id that you created (which represents the asset), you must also define the dimension path as id.

Label Key of the column that is used for text mapping in the section Translation.

NoteThe text mapped to this key is later on the column label displayed in the Asset Explorer.

Default ID Specifies what column is displayed as first column in the table

NoteThis checkbox should be activated for one column only.




Default Sort Defines the column according to which the component list is sorted by default


ExampleThe following screenshot is an example of what your asset list configuration can look like on the Asset Explorer UI:

Component List

The component list is accessed by business users by clicking on a component.


Table 75: Entries to Configure the Component List


Column ID Identifies columns to be displayed in the component list.


● Component properties: id, name, externalId, description

NoteEnter the component property exactly as displayed above taking account of the upper and lower case letters.

NoteYou must create one dimension ID as id. This represents the asset.



Column Type Data type of the column value. You can enter the following values:






Column Path Binds the column to the corresponding value of the JSON response sent by the backend

This field holds the path to the value. To render the value on the user interface, the corresponding dimension ID has to be bound to the path of the JSON. You define the dimension path as properties/<Dimension ID>. The dimension ID column is explained above. For example, if the dimension ID is healthState/SCORE, then the dimension path is properties/healthState/SCORE . If the dimension ID is name then the dimension path is properties/name.

Label Key of the column that is used for text mapping in the section Translations.


Sort by ID Specifies what column is displayed as first column in the table


Sort List by Defines the column according to which the component list is sorted by default


ExampleThe following screenshot is an example of what your component list configuration can look like on the Asset Explorer UI:


Translations

Table 76: Entries to Map UI Texts

Field Description

Lang Enter the language code of the language in which you want the filter labels and column lables to be displayed.

NoteIt is recommended to use standard ISO language code codes such as en-US.

Key / Text Choose the key of the filter or column. Enter the text you would like to be displayed on the UI.

Related Information




2.8.4 Entries to Configure Components

Component List

Table 77: Entries to Configure the Component List


Dimension ID Identifies columns to be displayed in the component list.


● Component properties: id, nameexternalId, description

NoteEnter the component property exactly as displayed above taking account of the upper and lower case letters.



Dimension Type Data type of the column value. You can choose from the following values:





Dimension Path Binds the column to the corresponding value of the JSON response sent by the backend

This field holds the path to the value. To render the value on the user interface, the corresponding dimension ID has to be bound to the path of the JSON. You define the dimension path as properties/<Dimension ID>. The dimension ID column is explained above. For example, if the dimension ID is healthState/SCORE then the dimension path is properties/healthState/SCORE. If the dimension ID is name then the dimension path is properties/name .

NoteFor the mandatory dimension ID, id that you created (which represents the asset), you must also define the dimension path as id.

Label Key of the column that is used for text mapping in the section Translation


Default ID Specifies what column is displayed as first column in the table


Default Sort Defines the column according to which the component list is sorted by default


ExampleThe following screenshot is an example of what your component list configuration can look like on the Asset Health Fact Sheet:



Translations


Field Description

Lang Enter the language code of the language in which you want the column lables to be displayed.


Key / Text Choose the key of the column. Enter the text you would like to be displayed on the UI.

Related Information


2.8.5 Entries to Configure Work Activities

Display Work Activities

In this section you define what columns business users see by default when looking at the insight provider for work activities in the Asset Health Control Center or on the Asset Health Fact Sheet. You can choose from a predefined list of values. The list values are retrieved from data maintained in the following views:

● WORKACTIVITY


● WORKACTIVITY_TYPE_CODE_DESCRIPTION● WORKACTIVITY_PRIORITY_DESCRIPTION● WORKACTIVITY_STATUS_DESCRIPTION● Things metadata views

For more information about these views, see the chapters Views for Metadata and Views for Data in the guide Installation of SAP Predictive Maintenance and Service, on-premise edition 1.0.

Create Work Activities

When business users create work activities for a certain asset on the Asset Health Fact Sheet, they can post the work activity to an SAP system to schedule maintenance. Therefore, an OData service is needed.

Table 79: Entries to Specify OData Service

Field Description

Service URL URL of the OData service that you use to post new work activities to a system that exposes the end point of the OData service, for example, SAP Gateway on top of SAP MRS

User Technical user that is used to access the OData end point and create work activities in the target system.

Password Password of the technical user that is used to access the OData end point and create work activities in the target system.

Entity Set Group of entities

An entity set is part of the data model of the OData service.

ExampleWork_Activities



Translations


Field Description

Lang Enter the language code of the language in which you want the column lables to be displayed.


Key / Text Choose the key of the column. Enter the text you would like to be displayed on the UI.

Related Information


2.8.6 Entries to Configure Derived Signals

NoteYou can define variants of this insight provider. These variants can then be selected by business users from the Insight Provider Catalog.

Select

In this section you define which columns business users see by default when they choose this variant of the Derived Signals insight provider to add it to the Asset Health Control Center or the Asset Health Fact Sheet. You can choose from a predefined list of columns. The values in this list are retrieved from the data maintained in the view EVENTS and in the Things metadata views. For more information about these views, see the chapters Views for Metadata and Views for Data in the guide Installation of SAP Predictive Maintenance and Service, on-premise edition 1.0 FP03.

Filter

In this section you define the values that are displayed in the list of derived signals for the variant.


Sort

In this section you define the column according to which the list of derived signals is sorted for the variant.

I18N Mapping

In this section you maintain text values for the parameters variantName (mandatory) and variantDescription. This text is the variant name that your business users will see when they add the insight provider from the Insight Provider Catalog.

You can maintain text values for the following languages:

● English● German● Italian● Simplified Chinese

Related Information


2.8.7 Entries to Configure the Map


Map Settings

Table 81: Map Settings


Zoom Level Number of levels for zooming into the map

Latitude Initial focus of latitude of the map

Longitude Initial focus of longitude of the map




Indicator Type Key of indicator that is defined for derived signals. This key is used for coloring assets on the map according to their derived signals.

Layers

In the map settings you can configure base layer settings, overlay layer settings, and the layer color mapping.

NoteYou can use the following tile providers:

● OpenStreetMap● Esri● Noki Here

Base LayersTable 82: Base Layer Settings

Field Description

Layer Name Name of the base layer

NoteThis name should be unique for each layer. The name is displayed later on the UI of the map.

Layer Type Type of the base layer

You can choose between the following types:

● xyzIf you choose this type, make sure you specify a Layer URL.

● esriIf you choose this type, make sure you specify an esri Base Layer Type.


Field Description

Layer URL URL template of the tile provider for the base layer

NoteWhen using Open Street Maps with 'https', use layerUrl : https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png

NoteSelect the Mandatory checkbox if you fill in this entry field.

Layer Parameters Specifies the base layer type if the base layer is of type esri.

For more information about esri base layer types, see http://www.esri.com/data/basemaps .

NoteSelect the Mandatory checkbox if you have filled in this entry field.

Attribution A string that defines the copyright of the map provider. You can also include an HTML link that leads to the copyrights of the map provider.

Example© Mapbox




http://help.sap.com/disclaimer?site=http://www.esri.com/data/basemaps


Field Description

Application ID NoteFill in this entry field if you are using Noki Here Maps as the tile provider.

App ID used to register with the tile provider.


Application Code NoteFill in this entry field if you are using Noki Here Maps.

App code used to register with the tile provider.


Subdomains NoteFill in this entry field if your tile provider uses subdomains.

For more information about subdomains and subdomain prefixes, see https://developer.here.com/news/201602172#.V-Fc2U1pDct .



http://help.sap.com/disclaimer?site=https://developer.here.com/news/201602172#.V-Fc2U1pDct


Field Description

Map ID Version of the map

NoteFill in this entry field according to the requirements and conventions of your tile provider.


Base Map type such as panorama, traffic, or base

NoteFill in this entry field according to the requirements and conventions of your tile provider.


Maximum Zoom Maximum number of levels for zooming into the base layer.

NoteThis setting overrules the generic map zoom level.


Initial Base Layer Value true sets this base layer as the default base layer.

Hide Logo Select this checkbox if the logo of the tile provider should not be visible on the map.

No Wrap Select this checkbox to prevent base layers from loading outside the world width (-180 to 180 longitude).



Overlay LayersTable 83: Overlay Layer Settings

Field Description

Layer Name Name of the overlay layer


Layer Level Layer level of an overlay layer used for numbering across layers

This setting is used as the ID of the layer.

Layer Type You can choose between the following values:

● Marker: Assets are displayed on the map individually.● Cluster: Assets are clustered on the map according to the

zoom level. The further the user zoom out of a map, the wider the radius of a cluster.

Layer Color MappingTable 84: Layer Color Mapping

Field Description

Layer LevelThis setting is used as the ID of the layer.

Indicator Type Key of indicator that is defined for derived signals. This key is used for coloring assets on the map according to their derived signals. Layer level of an overlay layer used for numbering across layers

Sign Layer level of an overlay layer used for numbering acrossInclude or exclude a certain range of derived signals for color mapping

You can choose between the following values:

● I: Inclusive approach● E: Exclusive approach

ExampleAll assets that have received (I) between 5 and 10 derived signals are displayed yellow.


Field Description

Option Range of derived signals that you want to map to a certain color

You can choose the following values:

● EQ: Means equals (the same numbers needs to be entered for High and Low)

● GT: Means greater than (a number needs to be entered for Low, High needs to remain empty)

● LE: Means less or equal (Low needs to remain empty, a number needs to be entered for High)

● BT: Means between (excluding the minimum number of derived signals and including the maximum number of derived signals)

ExampleAll assets that have received between (BT) 5 and 10 derived signals are displayed yellow.

Low Minimum number of derived signals

ExampleAll assets that have received between 5 (Low) and 10 derived signals are displayed yellow.

High Maximum number of derived signals

ExampleAll assets that have received between 5 and 10 (High) derived signals are displayed yellow.

Color Color used to visualize the number of derived signals for an asset

NoteThe following colors are supported: red (critical), orange (severe), green (good), gray (unknown).



I18N Mapping

In this section you maintain text values for the parameters variantName (mandatory) and variantDescription. This text will be the variant name that your business users will see when they add the insight provider from the Insight Provider Catalog.

You can also maintain text values for the overlay layer names displayed on the map.



ExampleThe following screenshot is an example of how your map configuration can look in the Asset Health Control Center and on the Asset Health Fact Sheet:

Related Information



2.8.8 Entries to Configure the 2D Chart

NoteYou can define variants for this insight provider. These variants can be selected by the business users from Insight Provider Catalog.

Configuration

In this section, you can define the number of data points per measurement (metric) that you want to be displayed in the chart.

NoteA maximum of 600 data points in total can be displayed in the 2D chart. This is entered in the Data Points per Measurement on Chart column. The default number of data points is 240 and can range between 30 and 600. The more the number of data points, the more the accuracy of chart. But, the response time may be affected.

ExampleThe following screenshot is an example of what your 2D chart configuration can look like in the Asset Health Fact Sheet

:



Time Filter

Table 85: 2D Chart Settings


Key Key of the time interval

Text Label of the time interval that is displayed on the UI of the 2D chart

Example48 Hours, Today

Value Value of the time interval

Example48 for a time interval of 48 hours

Unit Unit of the time interval

Examplehour for a time interval of 48 hours

You can choose among the following values:

● hour● day● week● month● year


Labels and Translations


Field Description

Lang The following user interface (UI) languages are supported with this analysis tool:

● English (US)● German (Germany)● Italian● Simplified Chinese

The administrator can configure these languages that are displayed on the UI. Contact your administrator if one of the supported langauges need to be configured for you to work with this analysis tool

Enter the language code of the language in which you want time filter texts to be displayed.


Key / Text Choose the key of the text. Enter the time filter text you would like to be displayed on the UI.

Related Information


2.8.9 Entries to Configure the 3D Chart




Metric Configuration

In this section, you can choose the metrics that you want to be displayed in the 3D chart, such as the temperature of a certain asset component.

Base Settings

Table 87: 3D Chart Settings

Field Description

View ● Lighting EffectsYou can choose one of the following values:○ Using Gradient○ Using Light Source

● Label X AxisSelect this checkbox if you want the label of the x-axis to be displayed.

● Label Y AxisSelect this checkbox if you want the label of the y-axis to be displayed.

● Label Z AxisSelect this checkbox if you want the label of the z-axis to be displayed.

● AxesSelect this checkbox if you want the axes to be displayed in the chart.


Field Description

Colors Colors of different parts of the 3D chart

You can set the color for the following parts:

● SurfaceSurface that can be built based on the measurements of assets displayed in the 3D chart

● Surface From

NoteThis field is relevant only if you chose the view rendering mode 1.

The color you choose will change in gradients to the color you choose for Surface To. The color gradient goes from low values (Surface From) to high values (Surface To).

● Surface To

NoteThis field is relevant only if you chose the view rendering mode 1.

The color you choose will be the target color of the color that you choose for Surface From. The color gradient goes from low values (Surface From) to high values (Surface To).

● BackgroundBackground of the 3D chart

● Axis TextValue labels on the axes

● Threshold PlaneThreshold for measurements of assets

● Time SliderTime line selector where you can select the time interval that you want to be displayed in the 3D chart.

● Measurement LinesLine that connect the measurements of an asset displayed in the 3D chart

● Derived SignalsDerived signals

● Time BrushSelected time interval in the time line selector.



Field Description

Filter ● Maximum Count A...Maximum number of assets that can be displayed in the 3D data chart

● From dateMaximum time interval for which data is displayed in the 3D chartThe time interval is defined by the start date you enter here, and the end date, which is the present day.

Animation Settings ● Animate TransitionSelect this checkbox if you want the transition between 3D charts to be animated.

Time Aggregation Threshold Define the Minutes, Hours, and Days to automatically compute the aggregation level used for the display of metrics in the 3D chart.

I18N Mapping

In this section you maintain text values for the parameters variantName (mandatory) and variantDescription. This text is the variant name that your business users will see when they add the insight provider from the Insight Provider Catalog.



Related Information



2.8.10 Entries to Configure the Asset and Component Scores

Asset and Component Scores List

Table 88: Entries to Configure the Asset and Component Scores List


(Dimension) ID Identifies columns that are displayed in the asset and component scores insight provider.


● Asset/component properties

○ AssetID○ AssetExternalID○ AssetName○ AssetDescription○ AssetThingType○ AssetThingTypeDescription○ ComponentID○ ComponentExternalID○ ComponentName○ ComponentDescription○ ComponentThingType○ ComponentThingTypeDescription

NoteEnter the property exactly as displayed above taking account of the upper and lower case letters.






(Dimension) Type Data type of the column value

You can select the following values:

● string● float● integer● healthStatus - used to display scores calculated using

algorithms of the machine learning engine

Text Key Key of the column that is used for text mapping in the section Text Mappings

NoteThe UI text mapped to this key becomes the column header description displayed in the Asset and Component Scores insight provider.

Display by Default If you activate this check box, the column is displayed in the Asset and Component Scores insight provider.

Text Mappings


Field Description

Language Enter the language code of the language in which you want the column headers to be displayed. For example, en (English), de (German), zh (Chinese), it (Italian).

Key/UI Text Choose the key of the column. Enter the text you would like to be displayed on the user interface.

Related Information



2.9 Configuring Insight Providers Using REST APIs

REST APIs for configuring key figures and insight providers for use in the Asset Health Control Center and on the Asset Health Fact Sheet.



This role collection enables you to configure key figures, insight providers, and insight provider variants, and check the effect of your configurations in the Asset Health Control Center.


To configure key figures and insight providers, proceed as follows:

● Create key figures, key figures sets, and compute key figures as described in the chapter Configuring Key Figures [page 141].

● Configure insight providers and insight provider variants as described in the following chapters.

NoteThe following insight providers support variant configuration:○ Derived Signals○ Map○ 3D Chart

Table 90: Configuration of Insight Providers

Insight Providers Configuration

○ Derived Signals○ Map○ 3D Chart

Configuration with variants

Manage Configurations of Insight Providers Variants [page 225]

○ Asset Explorer○ Components○ Work Activities○ 2D Chart

Configuration without variants

Manage Configurations of Insight Providers [page 163]

Related Information




2.9.1 Retrieve a CSRF Token

Retrieves the CSRF token needed for REST calls for configuration.

Request

Format: JSON

URI: https://<host name>:<port>/api/v1/config/global

HTTP Method: GET

NoteAs the configuration end points of some insight provider are protected against cross site request forgery (CSRF), you need to retrieve the CSRF token first before the REST calls can be made to configure the insight providers. Extract the value for x-csrf-token from the response headers.

2.9.2 Configuring Key Figures

Table 91:

You would like to... Chapter

Create key figures Create a Key Figure [page 142]

Create key figure sets Create a Key Figure Set [page 151]

Compute key figures Compute Key Figures [page 161]

Related Information

Read a Key Figure [page 144]Search for Key Figures [page 145]Read an Attribute Section of a Key Figure [page 147]Update a Key Figure [page 148]Delete a Key Figure [page 150]Read a Key Figure Set [page 153]Search for Key Figure Sets [page 154]Read an Attibute Section of a Key Figure Set [page 156]Read All Key Figures of a Key Figure Set [page 157]


Update a Key Figure Set [page 159]Delete a Key Figure Set [page 161]

2.9.2.1 Create a Key Figure

Create a key figure.

Request

Format: JSON

URI: http://<hostname>:<router port>/ipro/key-figures-backend/api/v1/key-figures

HTTP Method: POST

Request Example

{ "id":"speed-avg", "metadata":{ "type": "key-figure", "language": "E" }, "properties":{ "title": "Average Speed", "subtitle": "Sensor 1", "description": "Average speed as recorded by sensor 1", "uom": "km/h" }, "data":{ "value": 123 } }

Request Parameters

If the ID of the key figure is provided in the body, this ID is taken. A new ID is created automatically if the ID is absent from the body.

In any case the metadata.type parameter is mandatory. The metadata.language parameter is the language of the language-sensitive attributes in the properties section. If the metadata.language parameter is missing, the language of the database session will be used.

To install a default set of language-sensitive properties which will be returned when no language has been specified in the request, or if a translation is missing for a certain language, set the paramater metadata.language : "" .



Table 92:


id No ID of the key figure. If no ID is provided, an ID is generated automatically.

metadata Yes type: Value = key-figure

language: Language of the language-sensitive attributes in the properties section. If no language is specified, the language of the database session is used. To install a default set of language-sensitive properties that is returned when no language has been specified in the request or a translation is missing for a particular language, set `"metadata.language" : ""`.

properties Yes Language-sensitive values containing the title, subtitle, description, and unit of measurement of the key figure.

data Yes Value that is displayed

Response

Response Example

{ "KeyFigureCollection": [ { "id":"speed-avg", "metadata":{ "type": "key-figure", "language": "E", "modifiedAt": "2015-08-24 12:34:45", "modifiedBy": "SOMEONE" }, "properties":{ "title": "Average Speed", "subtitle": "Sensor 1", "description": "Average speed as recorded by sensor 1", "uom": "km/h" }, "data":{ "value": "123" } } ] }


Table 93:

Code Description

200 Key figure was created.

201 Key figure with specified ID already exists.


Related Information

Configuring Insight Providers Using REST APIs [page 140]Read a Key Figure [page 144]Search for Key Figures [page 145]Read an Attribute Section of a Key Figure [page 147]Update a Key Figure [page 148]Delete a Key Figure [page 150]

2.9.2.1.1 Read a Key Figure

Retrieve a specific key figure.

Request

Format: JSON

URI: http://<hostname>:<router port>/ipro/key-figures-backend/api/v1/key-figures/<keyFigureId>

HTTP Method: GET

Response

Response Example

{ "KeyFigureCollection": [ { "id":"speed-avg", "metadata":{ "type": "key-figure", "language": "E", "modifiedAt": "2015-08-24 12:34:45", "modifiedBy": "SOMEONE" }, "properties":{ "title": "Average Speed", "subtitle": "Sensor 1", "description": "Average speed as recorded by sensor 1", "uom": "mph" }, "data":{ "value": "53" } } ] }




Table 94:

Code Description

200 Requested key figure was found.

204 Key figure with the specified ID could not be found.

Related Information

Create a Key Figure [page 142]Update a Key Figure [page 148]Search for Key Figures [page 145]Delete a Key Figure [page 150]

2.9.2.1.2 Search for Key Figures

Retrieve key figures according to specific attributes and values.

Request

Format: JSON


HTTP Method: GET

Request Example

http://<host>.com:<port>/api/key-figures?id=*speed*&properties.uom=mph http://<host>.com:<port>/api/key-figures?metadata.modifiedBy=SOMEONE

Request Parameters

Searches for key figures containing specified attributes and values. A search attribute can be any attribute of a key figure. Nested attributes can be addressed using the "." operator, for example, "metadata.modifiedBy=*SOMEONE*". Both search attributes and values may contain wildcards "*". Multiple attributes and value pairs can be specified using the "&" separator.


Response

Response Example

{ "KeyFigureCollection": [ { "id":"speed-avg", "metadata":{ "type": "key-figure", "language": "E", "modifiedAt": "2015-08-24 12:34:45", "modifiedBy": "SOMEONE" }, "properties":{ "title": "Average Speed", "subtitle": "Sensor 1", "description": "Average speed as recorded by sensor 1", "uom": "mph" }, "data":{ "value": "53" } }, { "id":"top-speed", "metadata":{ "type": "key-figure", "language": "E", "modifiedAt": "2015-08-24 12:34:45", "modifiedBy": "SOMEONE" }, "properties":{ "title": "Top Speed", "subtitle": "Sensor 2", "description": "Top speed as recorded by sensor 2", "uom": "mph" }, "data":{ "value": "143" } } ] }

Response Status and Error CodesTable 95:

Code Description

200 Search finished successfully.

204 Key figure with specified ID does not exist.

Related Information

Create a Key Figure [page 142]Update a Key Figure [page 148]Delete a Key Figure [page 150]



Read a Key Figure [page 144]

2.9.2.1.3 Read an Attribute Section of a Key Figure

Retrieve a specific attribute section of a key figure.

Request

Format: JSON

URI: http://<hostname>:<router port>/ipro/key-figures-backend/api/v1/key-figures/<keyFigureId>/<keyFigureSection>

The base URI can be changed according to the attributes you would like to read.

Examplehttp://<hostname>:<router port>/ipro/key-figures-backend/api/v1/key-figures/<keyFigureId>/properties displays all property attributes of a key figure.

http://<hostname>:<router port>/ipro/key-figures-backend/api/v1/key-figures/<keyFigureId>/metadata displays all metadata attributes of a key figure.

http://<hostname>:<router port>/ipro/key-figures-backend/api/v1/key-figures/<keyFigureId>/data displays all data attributes of a key figure.

HTTP Method: GET

Response

Response Example

{ "KeyFigureCollection": [ { "id":"speed-avg", "metadata":{ "type": "key-figure", "language": "E", "modifiedAt": "2015-08-24 12:34:45", "modifiedBy": "SOMEONE" } } ] }

{ "KeyFigureCollection": [ {


"id":"speed-avg", "properties":{ "title": "Average Speed", "subtitle": "Sensor 1", "description": "Average speed as recorded by sensor 1", "uom": "mph" } } ] }

{ "KeyFigureCollection": [ { "id":"speed-avg", "data":{ "value": "53" } } ] }


Code Description

200 Requested key figure was found.

Related Information

Create a Key Figure [page 142]Read a Key Figure [page 144]Search for Key Figures [page 145]Update a Key Figure [page 148]Delete a Key Figure [page 150]

2.9.2.1.4 Update a Key Figure

Update a key figure.

Request

Format: JSON


HTTP Method: PUT



Request Example

{ "id":"speed-avg", "metadata":{ "type": "key-figure" }, "properties":{ "uom": "mph" }, "data":{ "value": "53" } }

Request ParametersThe ID and type of the key figure object has to be provided in the body of the request.

Table 97:


id Yes ID of the key figure you want to update

metadata No type: Value = key-figure

properties Yes Value you want to update

data No Value you want to update

metrics NoNote

If you want to update the metrics used for a key figure, you need to provide all metrics, the ones you want to update and the ones that stay the same. Otherwise, metrics that are not provided in the metrics section are deleted from the API configuration. If you do not want to update the metrics used for a key figure, leave this section out.

Response

Response Example

{ "KeyFigureCollection": [ { "id":"speed-avg", "metadata":{ "type": "key-figure", "language": "E", "modifiedAt": "2015-08-24 12:34:45", "modifiedBy": "SOMEONE" }, "properties":{ "title": "Average Speed", "subtitle": "Sensor 1", "description": "Average speed as recorded by sensor 1",


"uom": "mph" }, "data":{ "value": "53" } } ] }


Code Description

200 Key figure was updated.

204 Key figure with specified ID does not exist.

Related Information

Create a Key Figure [page 142]Search for Key Figures [page 145]Delete a Key Figure [page 150]Read a Key Figure [page 144]

2.9.2.1.5 Delete a Key Figure

Delete a specific key figure.

Request

Format: JSON

URI: http://<hostname>:<router port>/ipro/key-figures-backend/api/v1/key-figures/<keyFigureId>

HTTP Method: DELETE



Response


Code Description

200 Key figure is deleted.

204 Key figure with the specified ID could not be found.

Related Information

Create a Key Figure [page 142]

2.9.2.2 Create a Key Figure Set

Create a key figure set.

Request

Format: JSON

URI: http://<hostname>:<router port>/ipro/key-figures-backend/api/v1/key-figure-sets

HTTP Method: POST

Request Example

{ "id": "speedset", "metadata": { "type": "key-figure-set", "language": "", "key-figures": { "0": "top-speed", "1": "speed-avg" } }, "properties": { "description": "Speed related sensors", "title": "Top Speed and Average Speed" } }

Request ParametersIf the ID of the key figure set is provided in the body, this ID is taken. A new ID is created automatically if the ID is absent from the body.


In any case the metadata.type parameter is mandatory. The metadata.language parameter is the language of the language-sensitive attributes in the properties section. If the metadata.language parameter is missing, the language of the database session will be used.

To install a default set of language-sensitive properties which will be returned when no language has been specified in the request, or if a translation is missing for a certain language, set the paramater metadata.language : "" .

Table 100:


id No ID of the key figure. If no ID is provided, an ID is generated automatically.

metadata Yes type: Value = key-figure

language: Language of the language-sensitive attributes in the properties section. If no language is specified, the language of the database session is used. To install a default set of language-sensitive properties that is returned when no language has been specified in the request or a translation is missing for a particular language, set `"metadata.language" : ""`.

key figures: Key figures that are part of this key figure set..

properties Yes Language-sensitive values containing the title and description of the key figure set.

Response

Response Example

{ "KeyFigureCollection": [ { "id": "speedset", "metadata": { "active": "true", "key-figures": { "0": "top-speed", "1": "speed-avg" }, "language": "", "modifiedAt": "2016-01-29 15:39:55.5570000", "modifiedBy": "SOMEONE", "type": "key-figure-set" }, "properties": { "description": "Speed related sensors", "title": "Top Speed and Average Speed" } } ] }




Code Description

200 Key figure set was created.

201 Key figure set with specified ID already exists.

Related Information

Configuring Insight Providers Using REST APIs [page 140]Update a Key Figure Set [page 159]Search for Key Figure Sets [page 154]Delete a Key Figure Set [page 161]Read a Key Figure Set [page 153]Read All Key Figures of a Key Figure Set [page 157]Read an Attibute Section of a Key Figure Set [page 156]

2.9.2.2.1 Read a Key Figure Set

Retrieve a specific key figure set.

Request

Format: JSON

URI: http://<hostname>:<router port>/ipro/key-figures-backend/api/v1/key-figure-sets/<keyFigureSetId>

HTTP Method: GET

Response

Response Example

{ "KeyFigureCollection": [ { "id": "speedset", "metadata": { "active": "true", "key-figures": { "0": "speed-avg",


"1": "top-speed" }, "language": "", "modifiedAt": "2016-01-29 15:39:55.5570000", "modifiedBy": "SOMEONE", "type": "key-figure-set" }, "properties": { "description": "Speed related sensors", "title": "Average and Top Speed" } } ] }


Table 102:

Code Description

200 Requested key figure set was found.

204 Key figure set with the specified ID could not be found.

2.9.2.2.2 Search for Key Figure Sets

Retrieve a key figure set according to specific attributes and values.

Request

Format: JSON


HTTP Method: GET

Request Example

http://host.com:8080/api/key-figure-sets?metadata.modifiedBy=SOMEONE

Request Parameters

Searches for key figure sets containing specified attributes and values. A search attribute can be any attribute of a key figure set. Nested attributes can be addressed using the "." operator, for example, "metadata.modifiedBy=*SOMEONE*". Both search attributes and values may contain wildcards "*". Multiple attributes and value pairs can be specified using the "&" separator.



Response

Response Example

{ "KeyFigureCollection": [ { "id": "fuelset", "metadata": { "active": "true", "key-figures": { "0": "fuel2", "1": "fuel1" }, "language": "", "modifiedAt": "2016-01-29 15:39:56.2480000", "modifiedBy": "SOMEONE", "type": "key-figure-set" }, "properties": { "description": "Fuel related sensors", "title": "Fuel Consumption" } }, { "id": "speedset", "metadata": { "active": "true", "key-figures": { "0": "speed-avg", "1": "top-speed" }, "language": "", "modifiedAt": "2016-01-29 15:39:55.5570000", "modifiedBy": "SOMEONE", "type": "key-figure-set" }, "properties": { "description": "Speed related sensors", "title": "Average and Top Speed" } } ] }


Code Description

200 Search finished successfully.

204 No key figure sets could be found.

Related Information

Create a Key Figure Set [page 151]Update a Key Figure Set [page 159]Delete a Key Figure Set [page 161]


Read a Key Figure Set [page 153]

2.9.2.2.3 Read an Attibute Section of a Key Figure Set

Retrieve a specific section of all key figures of a key figure set according to the specified ID of the key figure set.

Request

Format: JSON

URI: http://<hostname>:<router port>/ipro/key-figures-backend/api/v1/key-figure-sets/<keyFigureSetId>/key-figures/<section>

The base URI can be changed according to the attributes you would like to read.

Examplehttp://<hostname>:<router port>/ipro/key-figures-backend/api/v1/key-figure-sets/<keyFigureSetId>/key-figures/properties displays all property attributes of a key figure.

http://<hostname>:<router port>/ipro/key-figures-backend/api/v1/key-figure-sets/<keyFigureSetId>/key-figures/metadata displays all metadata attributes of a key figure.

http://<hostname>:<router port>/ipro/key-figures-backend/api/v1/key-figure-sets/<keyFigureSetId>/key-figures/data displays all data attributes of a key figure.

HTTP Method: GET

Response

Response Example

{ "KeyFigureCollection": [ { "id": "fuel2", "metadata": { "language": "", "modifiedAt": "2016-01-29 15:39:54.1560000", "modifiedBy": "JOHNDOE", "objectFilters": "CARID='Q3',SENSOR=0x3,REGISTER='0x3a'", "primaryObject": "CARS", "type": "key-figure" } }, { "id": "fuel1", "metadata": { "language": "",



"modifiedAt": "2016-01-28 15:39:53.3970000", "modifiedBy": "JOHNDOE", "objectFilters": "CARID='Q3',SENSOR=0x1,REGISTER='0x4b'", "primaryObject": "CARS", "type": "key-figure" } } ] }


Table 104:

Code Description



Related Information

Create a Key Figure Set [page 151]Update a Key Figure Set [page 159]Search for Key Figure Sets [page 154]Delete a Key Figure Set [page 161]Read a Key Figure Set [page 153]Read All Key Figures of a Key Figure Set [page 157]

2.9.2.2.4 Read All Key Figures of a Key Figure Set

Retrieve all key figures of a key figure set according to the specified ID of the key figure set.

Request

Format: JSON

URI: http://<hostname>:<router port>/ipro/key-figures-backend/api/v1/key-figure-sets/<keyFigureSetId>/key-figures

HTTP Method: GET


Response

Response Example

{ "KeyFigureCollection": [ { "data": { "value": "27.7" }, "id": "fuel2", "metadata": { "language": "", "modifiedAt": "2016-01-29 15:39:54.1560000", "modifiedBy": "SOMEONE", "objectFilters": "CARID='Q3',SENSOR=0x3,REGISTER='0x3a'", "primaryObject": "CARS", "type": "key-figure" }, "properties": { "description": "Fuel consumption recorded by sensor 3", "filters": "A4, Sensor 3", "timePeriod": "2015/12/01 - 2015/12/10", "title": "Fuel Consumption", "uom": "mpg" } }, { "data": { "value": "56.6" }, "id": "fuel1", "metadata": { "language": "", "modifiedAt": "2016-01-28 15:39:53.3970000", "modifiedBy": "SOMEONE", "objectFilters": "CARID='Q3',SENSOR=0x1,REGISTER='0x4b'", "primaryObject": "CARS", "type": "key-figure" }, "properties": { "description": "Fuel consumption recorded by sensor 3", "filters": "A4, Sensor 3", "decimalPlaces": "", "timePeriod": "Last Week", "title": "Fuel Consumption", "uom": "gallons" } } ] }


Code Description





Related Information

Create a Key Figure Set [page 151]Update a Key Figure Set [page 159]Search for Key Figure Sets [page 154]Delete a Key Figure Set [page 161]Read a Key Figure Set [page 153]Read an Attibute Section of a Key Figure Set [page 156]

2.9.2.2.5 Update a Key Figure Set

Update a key figure set.

Request

Format: JSON


HTTP Method: PUT

Request Example

{ "id": "speedset", "metadata": { "type": "key-figure-set", "language": "", "key-figures": { "0": "speed-avg", "1": "top-speed" } }, "properties": { "title": "Average And Top Speed" } }

Request Parameters

In the request parameters, provide the parameter sections that you want to update. If whole sections do not need to be updated, leave them out of the PUT call.

Table 106:


id Yes ID of the key figure you want to update



metadata Yes type: Value = key-figure-set

key-figures: Key figures that you want to update in the key figure set

NoteIf you want to update the key figures used for a key figure set, you need to provide all key figures, the ones you want to update and the ones that stay the same. Otherwise, key figures that are not provided in the key-figures section are deleted from the API configuration. If you do not want to update the key figures used for a key figure set, leave this section out.

properties Yes Value you want to update

Response

Response Example

{ "KeyFigureCollection": [ { "id": "speedset", "metadata": { "active": "true", "key-figures": { "0": "speed-avg", "1": "top-speed" }, "language": "", "modifiedAt": "2016-01-29 15:39:55.5570000", "modifiedBy": "JOHNDOE", "type": "key-figure-set" }, "properties": { "description": "Speed related sensors", "title": "Average And Top Speed" } } ] }


Table 107:

Code Description

200 Key figure set was updated.

204 Key figure set with specified ID does not exist.



Related Information

Create a Key Figure Set [page 151]Search for Key Figure Sets [page 154]Delete a Key Figure Set [page 161]Read a Key Figure Set [page 153]

2.9.2.2.6 Delete a Key Figure Set

Delete a specific key figure set.

Request

Format: JSON

URI: http://<hostname>:<router port>/ipro/key-figures-backend/api/v1/key-figure-sets/<keyFigureSetId>

HTTP Method: DELETE

Response


Code Description

200 Key figure set is deleted.


2.9.2.3 Compute Key Figures

Compute values for all key figures of a key figure set according to the specified ID of the key figure set.

Request

URI: api/v1/key-figure-sets/{:id}/key-figures/compute

Format: JSON


URI: http://<hostname>:<router port>/ipro/key-figures-backend/api/v1/key-figure-sets/<keyFigureSetId>/key-figures/compute

HTTP Method: PUT

Request Example

{ "selected": ["machine_id1", "machine_id2"] }

Request Parameters

Table 109:


selected Yes IDs of the key figure sets for which you want to trigger computation.

NoteIf no values are specified for this parameter, computation is triggered for all key figure sets.

Response

Response Example

{ "KeyFigureCollection": [ { "id":"speed-avg", "metadata":{ "type": "key-figure", "language": "E", "modifiedAt": "2015-08-24 12:34:45", "modifiedBy": "SOMEONE" }, "properties":{ "title": "Average Speed", "subtitle": "Sensor 1", "description": "Average speed as recorded by sensor 1", "uom": "mph" }, "data":{ "value": "53" } } ] }




Code Description

200 Values were computed for all key figures of a key figure set according to the specified ID of the key figure set.

204 Key figure set with specified ID does not exist.

Related Information

Configuring Insight Providers Using REST APIs [page 140]

2.9.3 Manage Configurations of Insight Providers

Table 111:


Create configurations Create Configurations of an Insight Provider [page 164]

Read configurations Read a Configuration of an Insight Provider [page 203]

Update configurations Update a Configuration of an Insight Provider [page 211]

Delete configurations Delete a Configuration of an Insight Provider [page 219]

Related Information

Configuration Parameters per Insight Provider [page 167]Create Translations for a Configuration and Language Combination [page 201]Read a Configuration of an Insight Provider [page 203]Read All Configurations of an Insight Provider [page 204]Read a Front-End Configuration of an Insight Provider [page 206]Read All Translations for a Configuration of an Insight Provider [page 207]Read All Translations for a Configuration and Language Combination [page 209]Read a Translation for a Specific Configuration, Lamguage, and Key Combination [page 210]Update All Configurations of an Insight Provider [page 214]Update Translations for a Configuration and Language Combination [page 216]Update a Translation for a Specific Configuration, Text Key, and Language Combination [page 218]Delete All Configurations of an Insight Provider [page 220]Delete a Back-End Configuration and Front-End Configuration of an Insight Provider [page 221]


Delete All Translations for a Configuration of an Insight Provider [page 222]Delete All Translations for a Configuration and Language Combination [page 223]Delete All Translations for a Specific Configuration, Lamguage, and Key Combination [page 224]

2.9.3.1 Create Configurations of an Insight Provider

Creates or overwrites configuration resources including nested resources for given configuration IDs

Request

NoteAs the configuration end points of this insight provider are protected against cross site request forgery (CSRF), you need to retrieve the CSRF token first before the following REST call can be made. Retrieve the CSRF token as described in the chapter Retrieve a CSRF Token [page 141].

Format: JSON

URI: http://<host>:<port>/ipro/<insight provider>/api/v1/configs

NoteFill in the variable <insight provider> with the value that corresponds to insight provider that you want to configure. For an overview of the insight provider URL qualifiers, see the chapter Insight Provider Values for Base URI [page 242].

HTTP Method: POST

Before you send the POST call, enter the x-csrf-token that you just retrieved in the header section of your REST API call.

Examplekey = x-csrf-token

value = <CSRF token that you retrieved with the previous GET call>

You can then go ahead with the POST call.

Request Example

[ { "configId": "ahcc", "config": { "zoomLevel": 4 }, "i18n": [ {



"lang": "en-US", "mapping": [ { "key" : "typeDimLabel", "text" : "Type", "key" : "colorLabel","text" : "Color" } ] }, { "lang": "de-DE", "mapping": [ { "key" : "typeDimLabel", "text" : "Typ", "key" : "colorLabel","text" : "Farbe" } ] } ] }, { "configId": "eid", "config": { "zoomLevel": 7 }, "i18n" : [ { "lang": "en-US", "mapping": [ { "key" : "typeDimLabel", "text" : "Type", "key" : "colorLabel","text" : "Color" } ] }, { "lang": "en-GB", "mapping": [ { "key" : "typeDimLabel", "text" : "Type", "key" : "colorLabel","text" : "Colour" } ] } ] }]

Request Parameters

Table 112:


configId Yes ID of the configuration of an insight provider

config Yes Contains the configuration parameters of the insight provider

NoteThe configuration parameters vary for the insight providers. For an overview of configuration parameters you can use for a specific insight provider, see the chapter Configuration Parameters per Insight Provider [page 167].



i18n Contains the mappings per language of text keys and text values

lang Language code

mapping Contains the mappings of text keys and text values for a specific language

Response

Format: JSON


Code Description

200 Configurations for the insight provider were created.

Related Information

Configuring Insight Providers Using REST APIs [page 140]Create Configurations of an Insight Provider [page 164]Read a Configuration of an Insight Provider [page 203]Read All Configurations of an Insight Provider [page 204]Read a Front-End Configuration of an Insight Provider [page 206]Read All Translations for a Configuration of an Insight Provider [page 207]Read All Translations for a Configuration and Language Combination [page 209]Create Translations for a Configuration and Language Combination [page 201]Read a Translation for a Specific Configuration, Lamguage, and Key Combination [page 210]Update a Configuration of an Insight Provider [page 211]Delete a Configuration of an Insight Provider [page 219]



2.9.3.1.1 Configuration Parameters per Insight Provider

Configuration Parameters for Asset Explorer

Table 114:

Configuration Parameter Subparameters Description

i18n lang Language code

The following languages are supported:


mapping Mapping of a text key (dimensionLabel) and a readable text string in the language defined with the parameter lang



config filterConfiguration Contains the following parameters:

● dimensionIdIdentifies the attribute filter. You define it as <PropertySetTypeId>/<PropertyId>.

NoteIt is mandatory to define one entry where you enter machineId for the Filter ID and the Filter Name.

● dimensionNameName of the filter

● dimensionLabelKey of the filter that is used for text mapping in the i18n parameter section

NoteThe text mapped to this key is the filter label displayed in the Asset Explorer later on.

● dimensionSelectionTypeYou can choose between the following options:

○ MultipleBusiness users can filter by more than one value in the Asset Explorer.

○ SingleBusiness users can filter by only one value in the Asset Explorer.

primaryObjectDimensionId Identifies an asset




machineConfiguration You can configure the following properties:

Contains the following parameters to configure the asset list of the Asset Explorer:

● tableConfiguration○ dimensionId

Identifies column that is to be displayed in the asset list

○ Asset properties: id, nameexternalId, description

NoteEnter the asset property exactly as displayed above, taking care to enter the upper- and lowercase letters correctly.

NoteYou must create one dimension ID called id. This represents the asset.

○ Master data properties: <PropertySetTypeId>/<PropertyId> from the view com.sap.pdms.sdm::DATA.MASTER_DATA in the data model. For example, MasterData/Manufacturer

○ Reading Properties: <PropertySetTypeId>/<PropertyId> from the view com.sap.pdms.sdm::DATA.READINGS in the data



model. For example, healthState/SCORE

○ dimensionTypeData type of the column value. You can choose from the following values:

○ string○ float○ integer○ healthStatus: This is a

special datatype that shows colored icons that represent values. If the underlying dimension ID has the value 0, 1, 2, or 3, it displays gray (unknown), red (critical), orange (warning), or green (no issues), respectively.

○ dimensionPathBinds the column to the corresponding value of the JSON response sent by the back endThis field contains the path to the value. To render the value on the user interface, the corresponding dimension ID has to be bound to the path of the JSON. You define the dimension path as properties/<Dimension ID>Key of the column. The dimension ID column is explained above. For example, if the dimension ID is healthState/SCORE then the dimension path is properties/healthState/SCORE. If the dimension ID is name then the dimension path is properties/name .




NoteFor the mandatory dimension ID id that you created (which represents the asset), you must also define the dimension path as id.

○ labeli18n parameter section

NoteThe text mapped to this key is the column label displayed later on in the Asset Explorer.

○ defaultIdSpecifies which column is displayed as the first column in the table (value = "true")

NoteThe value true should be set for one dimension ID only in the context of the tableConfiguration section.

○ defaultSortDefines the column according to which the asset list is sorted by default




componentConfiguration Contains the same parameters as the tableConfiguration section, but to configure the components list within the Asset Explorer.

Sample Code

{ "i18n": [{ "lang": "en-US", "mapping": [{ "key": "healthStatusColumnLabel", "text": "Health Status" }, { "key": "nameColumnLabel", "text": "Name" }] }, { "lang": "de", "mapping": [{ "key": "healthStatusColumnLabel", "text": "Gesundheitszustand" }, { "key": "nameColumnLabel", "text": "Name" }] }, { "lang": "zh", "mapping": [{ "key": "healthStatusColumnLabel", "text": "健康状态" }, { "key": "nameColumnLabel", "text": "资产名称" }] }], "config": { "filterConfiguration": [{ "dimensionId": "MasterData/MaintenancePlant", "dimensionName": "MaintenancePlant", "dimensionLabel": "maintenancePlaneDimensionLabel", "dimensionSelectionType": "Multiple" }, { "dimensionId": "machineId", "dimensionName": "machineId", "dimensionLabel": "primaryObjectIdDimensionLabel", "dimensionSelectionType": "Multiple" }], "primaryObjectDimensionId": "machineId", "machineConfiguration": { "tableConfiguration": [{ "dimensionId": "id", "dimensionType": "string", "dimensionPath": "id", "label": "primaryObjectDimensionId", "defaultId": true, "defaultSort": true }, { "dimensionId": "healthState/STATUS", "dimensionType": "healthStatus", "dimensionPath": "properties/healthState/STATUS",



"label": "healthStatusColumnLabel", "defaultId": false, "defaultSort": false }] }, "componentConfiguration": { "tableConfiguration": [{ "dimensionId": "id", "dimensionType": "string", "dimensionPath": "id", "label": "componentIdColumnLabel", "defaultId": true, "defaultSort": true }, { "dimensionId": "name", "dimensionType": "string", "dimensionPath": "properties/name", "label": "nameColumnLabel", "defaultId": false, "defaultSort": false }] } }}

Configuration Parameters for Components

Table 115:





mapping Mapping of a text key (dimensionLabel) and a readable text string in the language defined with the parameter lang



config tableConfiguration Contains the following parameters to configure the component list:

● tableConfiguration○ dimensionId

Identifies column that is to be displayed in the component list

○ id, nameexternalId, description

NoteEnter the component property exactly as displayed above, taking care to enter the upper- and lowercase letters correctly.

○ Master data properties: <PropertySetTypeId>/<PropertyId> from the view com.sap.pdms.sdm::DATA.MASTER_DATA in the data model. For example, MasterData/Manufacturer

○ Reading Properties: <PropertySetTypeId>/<PropertyId> from the view com.sap.pdms.sdm::DATA.READINGS in the data model. For example, healthState/SCORE

○ dimensionTypeData type of the column value. You can choose from the following values:

○ string○ float○ integer○ healthStatus: This is a

special datatype that




shows colored icons that represent values. If the underlying dimension ID has the value 0, 1, 2, or 3, it displays gray (unknown), red (critical), orange (warning), or green (no issues), respectively.

○ dimensionPathBinds the column to the corresponding value of the JSON response sent by the back endThis field contains the path to the value. To render the value on the user interface, the corresponding dimension ID has to be bound to the path of the JSON. You define the dimension path as properties/<Dimension ID>. The dimension ID column is explained above. For example, if the dimension ID is healthState/SCORE then the dimension path is properties/healthState/SCORE. If the dimension ID is name then the dimension path is properties/name

○ labelKey of the column label that is used for text mapping in the i18n parameter section

NoteThe text mapped to this key is the column label displayed later on in the component list.

○ defaultId



Specifies which column is displayed as the first column in the table (value = "true")


○ defaultSortDefines the column according to which the component list is sorted by default


Sample Code

{ "i18n": [{ "lang": "en-US", "mapping": [{ "key": "healthStatusColumnLabel", "text": "Health Status" }, { "key": "nameColumnLabel", "text": "Name" }] }, { "lang": "zh", "mapping": [{ "key": "healthStatusColumnLabel", "text": "å�¥åº·çŠ¶æ€�" }, { "key": "nameColumnLabel", "text": "å��ç§°" }] }], "config": { "tableConfiguration": [{ "dimensionId": "id", "dimensionType": "string", "dimensionPath": "id", "label": "componentIdColumnLabel", "defaultId": true,



"defaultSort": true }, { "dimensionId": "name", "dimensionType": "string", "dimensionPath": "properties/name", "label": "nameColumnLabel", "defaultId": false, "defaultSort": false }] }}

Configuration Parameters for Derived Signals

Table 116:


variantId - Uniquely identifies the insight provider variant

config displayDerivedSingals ● columnsComponent properties:Contains the columns of the list of derived signals for the variant

● filtersContains the values that are displayed in the list of derived signals for the variant

● sortDefines the column according to which the list of derived signals is sorted for the variant




mapping Mapping of a text key

You can map the following parameters:

● variantName (mandatory)

● variantDescription


Sample Code

{"variantId":"v1", "config":{ "displayDerivedSignals":{ "columns":["AssetName","Name","Event"], "filters":[{"column":"AssetName","operator":"contains","value":"003"}], "sort":[{"column":"Name","order":"Ascending"}] } },"i18n":[{ "lang":"en", "mapping":[{ "key":"variantName", "text":"test name"},{ "key":"variantDescription", "text":"test dedc"}] }] }

Configuration Parameters for Work Activities

Table 117:


generic displayWorkActivity Contains the values to configure the columns of the list of work activities

These values can be taken from the following views:

● WORKACTIVITY● WORKACTIVITY_TYPE_CODE_DESC

RIPTION● WORKACTIVITY_PRIORITY_DESCR

IPTION● WORKACTIVITY_STATUS_DESCRIP

TION




createWorkActivity Contains the OData metadata and the OData credentials required to retrieve the fields displayed to business users to create work activities from the Asset Health Fact Sheet.

● ODataMetadata○ entitySet

Group of entitiesAn entity set is part of the data model of the OData service.

ExampleWork_Activities

○ contextToODataPropertyMapping

● credentials○ url

URL of the OData service that you use to post new work activities to a system that exposes the end point of the OData service, for example, SAP Gateway on top of SAP MRS.

○ userTechnical user that is used to access the OData end point and create work activities in the target system.

○ passwordPassword of the technical user that is used to access the OData end point and create work activities in the target system.

Sample Code

{ "configId":"com.sap.pdms.app.ahcc", "generic":{ "displayWorkActivity":{ "columns":[ "Id", "Name", "ThingId", "ComponentId",


"TypeCodeDescription", "PriorityDescription", "StatusDescription", "StartTS", "EndTS", "ReportedBy", "AssignedTo" ] }, "createWorkActivity":{ "ODataMetadata":{ "entitySet":"NotificationsCollection", "contextToODataPropertyMapping":{ "assetId":{ "enabled":false, "targetProperty":"assetId" }, "description":{ "enabled":false, "targetProperty":"description" } } }, "credentials":{ "url":"<OData service URL>", "user":"<OData service user>", "password":"<User password>" } } } }

Configuration Parameters for the Map

Table 118:









mapping Mapping of a text key and a readable text string in the language defined with the parameter lang



● variantDescription● <layerName> of

overlayLayers

config zoomLevel Number of levels for zooming into the map

latitude Initial focus of latitude of the map

longitude Initial focus of longitude of the map



baseLayers In the map settings you can configure base layer settings, overlay layer settings, and the layer color mapping.

NoteYou can use the following tile providers:

● OpenStreetMap● Esri● Noki Here

You can define the following parameters:

● layerNameName of the base layer


● layerTypeType of the base layerYou can choose between the following types:○ xyz

If you choose this type, make sure you specify a layerUrl.

○ esriIf you choose this type, make sure you specify an esri Base Layer Type.

● layerUrlURL template of the tile provider for the base layer

NoteWhen using Open Street Maps with 'https', use layerUrl : https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png




NoteSet the parameter mandatory to true if you have filled in the parameter layerUrl.

● layerParamsThe parameter esriBaseLayerType specifies the base layer type if the base layer is of type esri.For more information about esri base layer types, see http://www.esri.com/data/basemaps .

NoteSet the parameter mandatory to true if you have filled in the parameter layerParams.

● layerOptionsThe parameter attribution is a string that defines the copyright of the map provider. You can also include an HTML link that leads to the copyrights of the map provider.

Example© Mapbox

NoteSet the parameter mandatory to true if you have filled in the parameter attribution.

● app_id

NoteFill in this parameter if you are using Noki Here Maps as a tile provider.

App ID used to register with the tile provider.





NoteSet the parameter mandatory to true if you have filled in the parameter app_id.

● app_code

NoteFill in this parameter if you are using Noki Here Maps.

App code used to register with the tile provider.

NoteSet the parameter mandatory to true if you have filled in the parameter app_code.

● subdomains

NoteFill in this parameter if your tile provider uses subdomains.

For more information about subdomains and subdomain prefixes, see https://developer.here.com/news/201602172#.V-Fc2U1pDct .

NoteSet the parameter mandatory to true if you have filled in the parameter subdomains.

● mapIDVersion of the map

NoteFill in this parameter according to the requirements and conventions of your tile provider.






NoteSet the parameter mandatory to true if you have filled in the parameter mapID.

● baseMap type such as panorama, traffic, or base

NoteFill in this parameter according to the requirements and conventions of your tile provider.

NoteSet the parameter mandatory to true if you have filled in the parameter base.

● maxZoomMaximum number of levels for zooming into the base layer.

NoteThis setting overrules the generic map zoom level.

NoteSet the parameter mandatory to true if you have filled in the parameter maxZoom.

● noWrapValue true: base layers do not load outside the world width (-180 to 180 longitude).

● initialBaseLayerValue true sets this base layer as the default base layer.



overlayLayers You can define the following parameters:

● layerNameName of the overlay layer


● layerLevelLayer level of an overlay layer used for numbering across layersThis setting is used as the ID of the layer.

● layerTypeYou can choose between the following values:

○ marker: Assets are displayed on the map individually.

○ cluster: Assets are clustered on the map according to the zoom level. The further the user zooms out of a map, the wider the radius of a cluster.

indicatorType Key of indicator that is defined for derived signals. This key is used for coloring assets on the map according to their derived signals.




layerColorMapping You can define the following parameters:

● layerLevelLayer level of an overlay layer used for numbering across layersThis setting is used as the ID of the layer.

● indicatorTypeKey of indicator that is defined for derived signals. This key is used for coloring assets on the map according to their derived signals.

● selectionTableYou can define the following values:

○ sign:Include or exclude a certain range of derived signals for color mappingYou can choose between the following values:○ I: Inclusive approach○ E: Exclusive approach

ExampleAll assets that have received (I) between 5 and 10 derived signals are displayed yellow.

○ option:Range of derived signals that you want to map to a certain colorYou can choose the following values:○ LE: Means less or equal

(Low needs to remain empty, a number needs to be entered for High)

○ BT: Means between (excluding the minimum number of derived signals and including the maximum number of derived signals)



○ GT: Means greater than (a number needs to be entered for Low, High needs to remain empty)

○ EQ: Means equals (the same numbers needs to be entered for High and Low)

ExampleAll assets that have received between (BT) 5 and 10 derived signals are displayed yellow.

○ low:Minimum number of derived signals

ExampleAll assets that have received between 5 (Low) and 10 derived signals are displayed yellow.

○ high:Maximum number of derived signals

ExampleAll assets that have received between 5 and 10 (High) derived signals are displayed yellow.

○ color:Color used to visualize the number of derived signals for an asset

NoteThe following colors are supported: red (critical),




orange (severe), green (good), gray (unknown).

Sample Code

{ "variantId": "MapVar1","i18n": [ { "lang": "en-US", "mapping": [ { "key": "$MINES", "text": "Mines" }, { "key": "$ASSETS", "text": "Assets" }, { "key": "$PIPELINES", "text": "Pipelines" }, { "key" : "variantName", "text" : "ahcc-variant" } ] }, { "lang": "de", "mapping": [ { "key": "$MINES", "text": "Minen" }, { "key": "$ASSETS", "text": "Objekte" }, { "key": "$PIPELINES", "text": "Rohrleitungen" }, { "key" : "variantName", "text" : "ahcc-variant-de" } ] }, { "lang": "zh", "mapping": [ { "key": "$MINES", "text": "矿区" }, { "key": "$ASSETS", "text": "资产" },


{ "key": "$PIPELINES", "text": "管道" }, { "key" : "variantName", "text" : "ahcc-variant-zh" } ] }],"config": { "zoomLevel": 4, "latitude": 20.8, "longitude": 23.8, "baseLayers": [ { "layerName": "Open Street Maps", "layerType": "xyz", "layerUrl": { "layerUrl": "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png", "mandatory": true }, "layerParams": { "esriBaseLayerType": "", "mandatory": false }, "layerOptions": { "attribution": { "attribution": "© <a href=\"http://osm.org/copyright\">OpenStreetMap</a> contributors", "mandatory": true }, "app_id": { "app_id": "", "mandatory": false }, "app_code": { "app_code": "", "mandatory": false }, "subdomains": { "subdomains": "", "mandatory": false }, "mapID": { "mapID": "", "mandatory": false }, "base": { "base": "", "mandatory": false }, "maxZoom": { "maxZoom": "", "mandatory": false }, "noWrap": { "noWrap": true } }, "initialBaseLayer": "true" }, { "layerName": "Satellite", "layerType": "esri", "layerUrl": { "layerUrl": "",



"mandatory": false }, "layerParams": { "esriBaseLayerType": "Imagery", "mandatory": true }, "layerOptions": { "attribution": { "attribution": "", "mandatory": false }, "app_id": { "app_id": "", "mandatory": false }, "app_code": { "app_code": "", "mandatory": false }, "subdomains": { "subdomains": "", "mandatory": false }, "mapID": { "mapID": "", "mandatory": false }, "base": { "base": "", "mandatory": false }, "maxZoom": { "maxZoom": "", "mandatory": false }, "noWrap": { "noWrap": true } }, "initialBaseLayer": "false" }, { "layerName": "Streets", "layerType": "esri", "layerUrl": { "layerUrl": "", "mandatory": false }, "layerParams": { "esriBaseLayerType": "Streets", "mandatory": true }, "layerOptions": { "attribution": { "attribution": "", "mandatory": false }, "app_id": { "app_id": "", "mandatory": false }, "app_code": { "app_code": "", "mandatory": false }, "subdomains": { "subdomains": "", "mandatory": false


}, "mapID": { "mapID": "", "mandatory": false }, "base": { "base": "", "mandatory": false }, "maxZoom": { "maxZoom": "", "mandatory": false }, "noWrap": { "noWrap": true } }, "initialBaseLayer": "false" }, { "layerName": "National Geographic", "layerType": "esri", "layerUrl": { "layerUrl": "", "mandatory": false }, "layerParams": { "esriBaseLayerType": "NationalGeographic", "mandatory": false }, "layerOptions": { "attribution": { "attribution": "", "mandatory": false }, "app_id": { "app_id": "", "mandatory": false }, "app_code": { "app_code": "", "mandatory": false }, "subdomains": { "subdomains": "", "mandatory": false }, "mapID": { "mapID": "", "mandatory": false }, "base": { "base": "", "mandatory": false }, "maxZoom": { "maxZoom": "", "mandatory": false }, "noWrap": { "noWrap": true } }, "initialBaseLayer": "false" }, { "layerName": "Simple", "layerType": "esri",



"layerUrl": { "layerUrl": "", "mandatory": false }, "layerParams": { "esriBaseLayerType": "Gray", "mandatory": true }, "layerOptions": { "attribution": { "attribution": "", "mandatory": false }, "app_id": { "app_id": "", "mandatory": false }, "app_code": { "app_code": "", "mandatory": false }, "subdomains": { "subdomains": "", "mandatory": false }, "mapID": { "mapID": "", "mandatory": false }, "base": { "base": "", "mandatory": false }, "maxZoom": { "maxZoom": "", "mandatory": false }, "noWrap": { "noWrap": true } }, "initialBaseLayer": "false" } ], "overlayLayers": [ { "layerName": "ASSETS", "layerLevel": 1, "layerType": "marker" }, { "layerName": "MINES", "layerLevel": 3, "layerType": "marker" }, { "layerName": "PIPELINES", "layerLevel": 2, "layerType": "marker" } ], "indicatorType": "DERIVED_SIGNALS", "layerColorMapping": [ { "layerLevel": 1, "indicatorType": "DERIVED_SIGNALS", "selectionTable": [ {


"sign": "I", "option": "LE", "low": "", "high": "0", "color": "grey" }, { "sign": "I", "option": "GT", "low": "0", "high": "", "color": "green" } ] } ]}}

Configuration Parameters for the 2D Chart

Table 119:

Configuration Parameter Sub-Parameters Description




mapping Mapping of a text key defined in the TimeFilter parameter and a readable text string in the language defined with the parameter lang




config TimeFilters

Contains parameters to define the aggregation levels for which you can display data measurements in the 2D chart

Contains the following parameters:

● keyKey of the time interval

● textLabel of the time interval that is displayed on the UI of the 2D chart

Example48 Hours, Today

● numberValue of the time interval

Example48 for a time interval of 48 hours

● unitUnit of the time interval

Examplehour for a time interval of 48 hours

You can define the following values:

○ hour○ day○ week○ month○ year

DataPointsPerMetric This determines the number of data points per metric to be displayed on the chart.

The default number of data points is 240 and can range between 30 and 600. The more the number of data points, the more the accuracy of chart. But, the response time may be affected.

Sample Code

{ "configId": "com.sap.pdms.app.ahcc", "config": {


"DataPointsPerMetric": 120, "TimeFilters": [{ "key": "1W", "text": "1 Week", "number": 1, "unit": "week" }, { "key": "3M", "text": "3 Months", "number": 3, "unit": "month" }] }, "i18n": [{ "lang": "de", "mapping": [{ "key": "1W", "text": "1 Woche" }] }]}

Configuration Parameters for the 3D Chart

Table 120:



config defaultMetricConfig The metrics (measurements) that you want to make available for display in the 3D chart




settings Contains the following parameters to define the view settings:

● renderingModeRendering mode of the 3D chartThis setting determines the color and lighting of the 3D scene, and the surface of the 3D chart.You can choose between the following values:○ 1

No lighting effects are used. This means no shadings are used, for example.

NoteThis rendering mode uses less resources.

○ 2Lighting effects are used. This means shadings are used, for example.

● labelXSet this parameter to false if no label should be displayed on the x-axis

● labelYSet this parameter to false if no label should be displayed on the y-axis

● labelZSet this parameter to false if no label should be displayed on the z-axis

● axisSet this parameter to true if axes should be displayed in the 3D chart

Contains the following parameters to define the color settings:

● surfaceSurface that can be built based on the measurements of assets displayed in the 3D chart



● surfaceFrom

NoteThis parameter is only relevant if you chose the view rendering mode 1.

The color you choose will change in gradients to the color you choose for surfaceTo. The color gradient goes from low values (surfaceFrom) to high values (surfaceTo).

● surfaceTo

NoteThis parameter is only relevant if you chose the view rendering mode 1.

The color you choose will be the target color of the color that you choose for surfaceFrom. The color gradient goes from low values (surfaceFrom) to high values (surfaceTo).

● backgroundBackground color of the 3D chart

● axisTextColor of labels on the axes

● specLimitThreshold for measurements of assets

● timeSliderTime line selector where you can select the time interval that you want to be displayed in the 3D chart.

● linesLine that connect the measurements of an asset displayed in the 3D chart

● events




Derived signals

● timeSliderBrushSelected time interval in the time line selector.

Contains the following parameters to define generic chart settings:

● maxMachinesMaximum number of assets that are allowed to be displayed in the 3D data chart

● animateTransitionAngleAngle by which the animated transition moves through the scene

● animateTransitionSet this parameter to true if you want the transition between chart displays to be animated.

● fromDateMaximum time interval for which data is displayed in the 3D chartThe time interval is defined by the start date you enter here and the end date, which is the present day

● aggThresholdsThresholds used to automatically compute the aggregation level used to display measurements in the 3D chart

● timeRange






mapping Mapping of a text key and a readable text string in the language defined with the parameter lang



● variantDescription

Sample Code

{ "variantId": "threeDVIZVar1", "config": { "defaultMetricConfig": [], "settings": { "view": { "renderingMode": "2", "labelX": true, "labelY": true, "labelZ": true, "axis": true }, "colors": { "surface": "#0d0a20", "surfaceFrom": "#ff0066", "surfaceTo": "#ff0066", "background": "#ffffff", "axisText": "#0080ff", "specLimit": "#ed562d", "timeSlider": "#009de0", "lines": "#0080ff", "events": "#0080ff", "timeSliderBrush": "#0080ff" }, "maxMachines": 5, "animateTransitionAngle": 45, "animateTransition": false, "fromDate": "2016-07-30", "aggThresholds": { "minutes": 3000, "hours": 360000, "days": 36000000 } }, "timeRange": { "last": 0 } }, "i18n": [ { "lang": "en", "mapping": [ {"key": "variantName", "text": "myVariantName"}, {"key": "variantDescription", "text": "myVariantDescription"} ] } ] }



Related Information

Create Variant Configurations [page 226]Create Configurations of an Insight Provider [page 164]

2.9.3.1.2 Create Translations for a Configuration and Language Combination

Creates translations for a configuration ID and a given language ID

Request


Format: JSON

URI: http://<host>:<port>/ipro/<insight provider>/api/v1/configs/<configID>/text-interpretations/<lang>


HTTP Method: PUT

Before you send the PUT call, enter the x-csrf-token that you just retrieved in the header section of your REST API call.



You can then go ahead with the PUT call.

Request Example

{ "mapping": [


{ "key" : "typeDimLabel", "text" : "Type", "key" : "colorLabel","text" : "Color" } ] }

Request Parameters

Table 121:



Response

Format: JSON


Table 122:

Code Description

200 Key-text pairs for the specified configuration ID were created.

Related Information

Configuring Insight Providers Using REST APIs [page 140]Create Configurations of an Insight Provider [page 164]Read a Configuration of an Insight Provider [page 203]Read All Configurations of an Insight Provider [page 204]Read a Front-End Configuration of an Insight Provider [page 206]Read All Translations for a Configuration of an Insight Provider [page 207]Read All Translations for a Configuration and Language Combination [page 209]Read a Translation for a Specific Configuration, Lamguage, and Key Combination [page 210]Configuring Insight Providers Using REST APIs [page 140]Update a Configuration of an Insight Provider [page 211]Update All Configurations of an Insight Provider [page 214]Update a Translation for a Specific Configuration, Text Key, and Language Combination [page 218]



2.9.3.2 Read a Configuration of an Insight Provider

Fetches a configuration with a specific configuration ID

Request

Format: JSON

URI: http://<host>:<port>/ipro/<insight provider>/api/v1/configs/<configID>


HTTP Method: GET

Response

Response Example

{ "config": { "zoomLevel": 4 }, "i18n": [ { "lang": "en-US", "mapping": [ { "key" : "typeDimLabel", "text" : "Type", "key" : "colorLabel","text" : "Color" } ] }, { "lang": "de-DE", "mapping": [ { "key" : "typeDimLabel", "text" : "Typ", "key" : "colorLabel","text" : "Farbe" } ] } ] }



Code Description

200 Requested insight provider configuration was found.

Related Information

Configuring Insight Providers Using REST APIs [page 140]Create Configurations of an Insight Provider [page 164]Read All Configurations of an Insight Provider [page 204]Read a Front-End Configuration of an Insight Provider [page 206]Read All Translations for a Configuration of an Insight Provider [page 207]Read All Translations for a Configuration and Language Combination [page 209]Create Translations for a Configuration and Language Combination [page 201]Read a Translation for a Specific Configuration, Lamguage, and Key Combination [page 210]

2.9.3.2.1 Read All Configurations of an Insight Provider

Fetches all configurations of an insight provider

Request

Format: JSON



HTTP Method: GET

Response

Response Example

[



{ "configId": "ahcc", "config": { "zoomLevel": 4 }, "i18n": [ { "lang": "en-US", "mapping": [ { "key" : "typeDimLabel", "text" : "Type", "key" : "colorLabel","text" : "Color" } ] }, { "lang": "de-DE", "mapping": [ { "key" : "typeDimLabel", "text" : "Typ", "key" : "colorLabel","text" : "Farbe" } ] } ] }, { "configId": "eid", "config": { "zoomLevel": 7 }, "i18n" : [ { "lang": "en-US", "mapping": [ { "key" : "typeDimLabel", "text" : "Type", "key" : "colorLabel","text" : "Color" } ] }, { "lang": "en-GB", "mapping": [ { "key" : "typeDimLabel", "text" : "Type", "key" : "colorLabel","text" : "Colour" } ] } ] } ]


Code Description

200 Requested insight provider configurations were found.


Related Information

Configuring Insight Providers Using REST APIs [page 140]Create Configurations of an Insight Provider [page 164]Read a Configuration of an Insight Provider [page 203]Read a Front-End Configuration of an Insight Provider [page 206]Read All Translations for a Configuration of an Insight Provider [page 207]Read All Translations for a Configuration and Language Combination [page 209]Create Translations for a Configuration and Language Combination [page 201]Read a Translation for a Specific Configuration, Lamguage, and Key Combination [page 210]

2.9.3.2.2 Read a Front-End Configuration of an Insight Provider

Fetches the frontend Insight Provider configuration for a given configId

Request

Format: JSON

URI: http://<host>:<port>/ipro/<insight provider>/api/v1/configs/<configID>/common-configs


HTTP Method: GET

Response

Response Example

{ "zoomLevel": 4, "aggregationLevel": "HOUR" }




Table 125:

Code Description

200 Requested front-end configuration was found.

Related Information

Configuring Insight Providers Using REST APIs [page 140]Create Configurations of an Insight Provider [page 164]Read a Configuration of an Insight Provider [page 203]Read All Configurations of an Insight Provider [page 204]Read All Translations for a Configuration of an Insight Provider [page 207]Read All Translations for a Configuration and Language Combination [page 209]Create Translations for a Configuration and Language Combination [page 201]Read a Translation for a Specific Configuration, Lamguage, and Key Combination [page 210]

2.9.3.2.3 Read All Translations for a Configuration of an Insight Provider

Fetches all translations for a given configuration ID

Request

Format: JSON

URI: http://<host>:<port>/ipro/<insight provider>/api/v1/configs/<configID>/text-interpretations


HTTP Method: GET


Response

Response Example

[ { "lang": "en-US", "mapping": [ { "key" : "typeDimLabel", "text" : "Type", "key" : "colorLabel","text" : "Color" } ] }, { "lang": "de-DE", "mapping": [ { "key" : "typeDimLabel", "text" : "Typ", "key" : "colorLabel","text" : "Farbe" } ] } ]


Code Description

200 Requested text interpretations were found.

Related Information

Configuring Insight Providers Using REST APIs [page 140]Create Configurations of an Insight Provider [page 164]Read a Configuration of an Insight Provider [page 203]Read All Configurations of an Insight Provider [page 204]Read a Front-End Configuration of an Insight Provider [page 206]Read All Translations for a Configuration and Language Combination [page 209]Create Translations for a Configuration and Language Combination [page 201]Read a Translation for a Specific Configuration, Lamguage, and Key Combination [page 210]



2.9.3.2.4 Read All Translations for a Configuration and Language Combination

Request

Format: JSON

URI: http://<host>:<port>/ipro/<insight provider>/api/v1/configs/<configID>/text-interpretations/<language>


HTTP Method: GET

Response

Response Example

{ "mapping": [ { "key" : "typeDimLabel", "text" : "Type", "key" : "colorLabel","text" : "Color" } ] }


Code Description


Related Information

Configuring Insight Providers Using REST APIs [page 140]Create Configurations of an Insight Provider [page 164]Read a Configuration of an Insight Provider [page 203]Read All Configurations of an Insight Provider [page 204]


Read a Front-End Configuration of an Insight Provider [page 206]Read All Translations for a Configuration of an Insight Provider [page 207]Create Translations for a Configuration and Language Combination [page 201]Read a Translation for a Specific Configuration, Lamguage, and Key Combination [page 210]

2.9.3.2.5 Read a Translation for a Specific Configuration, Lamguage, and Key Combination

Fetches the translation for a specific configuration ID, language, and key combination

Request

Format: JSON

URI: http://<host>:<port>/ipro/<insight provider>/api/v1/configs/<configID>/text-interpretations/<lang>/<key>


HTTP Method: GET

Response

Response Example

{ "text": "Type" }


Table 128:

Code Description

200 Requested text value was found.



Related Information

Configuring Insight Providers Using REST APIs [page 140]Create Configurations of an Insight Provider [page 164]Read a Configuration of an Insight Provider [page 203]Read All Configurations of an Insight Provider [page 204]Read a Front-End Configuration of an Insight Provider [page 206]Read All Translations for a Configuration of an Insight Provider [page 207]Read All Translations for a Configuration and Language Combination [page 209]Create Translations for a Configuration and Language Combination [page 201]

2.9.3.3 Update a Configuration of an Insight Provider

Updates a configuration with a specific configuration ID

Request


Format: JSON



HTTP Method: PUT






Request Example

[ { "configId": "ahcc", "config": { "zoomLevel": 4 }, "i18n": [ { "lang": "en-US", "mapping": [ { "key" : "typeDimLabel", "text" : "Type", "key" : "colorLabel","text" : "Color" } ] }, { "lang": "de-DE", "mapping": [ { "key" : "typeDimLabel", "text" : "Typ", "key" : "colorLabel","text" : "Farbe" } ] } ] }, { "configId": "eid", "config": { "zoomLevel": 7 }, "i18n" : [ { "lang": "en-US", "mapping": [ { "key" : "typeDimLabel", "text" : "Type", "key" : "colorLabel","text" : "Color" } ] }, { "lang": "en-GB", "mapping": [ { "key" : "typeDimLabel", "text" : "Type", "key" : "colorLabel","text" : "Colour" } ] } ] } ]



configId Yes

zoomLevel




i18n ID of the configuration of an insightContains the mappings per language of text keys and text values

lang Language code


Response

Format: JSON


Code Description

200 Configuration with the specified configuration ID was updated.ID of the configuration of an insight provider

Related Information

Configuring Insight Providers Using REST APIs [page 140]Create Configurations of an Insight Provider [page 164]Update All Configurations of an Insight Provider [page 214]Update Translations for a Configuration and Language Combination [page 216]Update a Translation for a Specific Configuration, Text Key, and Language Combination [page 218]Delete a Configuration of an Insight Provider [page 219]


2.9.3.3.1 Update All Configurations of an Insight Provider

Deletes any existing configurations of an insight provider, regardless of their configuration IDs, and then creates new configurations for the given configuration IDs

Request


Format: JSON



HTTP Method: PUT





Request Example

[ { "configId": "ahcc", "config": { "zoomLevel": 4 }, "i18n": [ { "lang": "en-US", "mapping": [ { "key" : "typeDimLabel", "text" : "Type", "key" : "colorLabel","text" : "Color" } ]



}, { "lang": "de-DE", "mapping": [ { "key" : "typeDimLabel", "text" : "Typ", "key" : "colorLabel","text" : "Farbe" } ] } ] }, { "configId": "eid", "config": { "zoomLevel": 7 }, "i18n" : [ { "lang": "en-US", "mapping": [ { "key" : "typeDimLabel", "text" : "Type", "key" : "colorLabel","text" : "Color" } ] }, { "lang": "en-GB", "mapping": [ { "key" : "typeDimLabel", "text" : "Type", "key" : "colorLabel","text" : "Colour" } ] } ] } ]

Request Parameters

Table 131:


configId Yes ID of the configuration of an insight provider

zoomLevel

i18n Contains the mappings per language of text keys and text values

lang Language code


Response

Format: JSON



Code Description

200 Configurations for the insight provider were created.

Related Information

Configuring Insight Providers Using REST APIs [page 140]Update a Configuration of an Insight Provider [page 211]Update Translations for a Configuration and Language Combination [page 216]Update a Translation for a Specific Configuration, Text Key, and Language Combination [page 218]

2.9.3.3.2 Update Translations for a Configuration and Language Combination

Updates translations for a configuration ID and a given language ID

Request


Format: JSON



HTTP Method: PUT







Request Example

{ "mapping": [ { "key" : "typeDimLabel", "text" : "Type", "key" : "colorLabel","text" : "Color" } ] }




Response

Format: JSON


Code Description

200 Key-text pairs for the specified configuration ID were updated.


2.9.3.3.3 Update a Translation for a Specific Configuration, Text Key, and Language Combination

Updates a translation for a specific key for a configuration ID and language combination

Request


Format: JSON

URI: http://<port>:<host>/ipro/<insight provider>/api/v1/configs/<configID>/text-interpretations/<lang>/<key>


HTTP Method: PUT





Request Example

{ "text": "Type" }



text Yes Contains the updated text value, for example, Type



Response

Format: JSON


Table 136:

Code Description

200 Key-text pairs for the specified configuration ID were updated.

Related Information

Configuring Insight Providers Using REST APIs [page 140]Update a Configuration of an Insight Provider [page 211]Update All Configurations of an Insight Provider [page 214]Update Translations for a Configuration and Language Combination [page 216]

2.9.3.4 Delete a Configuration of an Insight Provider

Deletes all nested configuration resources for a given configuration ID

Request

Format: JSON



HTTP Method: DELETE


Response


Table 137:

Code Description

200 Configuration with the specified configuration ID was deleted.

Related Information

Configuring Insight Providers Using REST APIs [page 140]Create Configurations of an Insight Provider [page 164]Update a Configuration of an Insight Provider [page 211]Delete All Configurations of an Insight Provider [page 220]Delete a Back-End Configuration and Front-End Configuration of an Insight Provider [page 221]Delete All Translations for a Configuration of an Insight Provider [page 222]Delete All Translations for a Configuration and Language Combination [page 223]Delete All Translations for a Specific Configuration, Lamguage, and Key Combination [page 224]

2.9.3.4.1 Delete All Configurations of an Insight Provider

Deletes all configurations of an insight provider

Request

Format: JSON



HTTP Method: DELETE



Response


Table 138:

Code Description

200 Configurations for the insight provider were deleted.

Related Information

Configuring Insight Providers Using REST APIs [page 140]Delete a Configuration of an Insight Provider [page 219]Delete a Back-End Configuration and Front-End Configuration of an Insight Provider [page 221]Delete All Translations for a Configuration of an Insight Provider [page 222]Delete All Translations for a Configuration and Language Combination [page 223]Delete All Translations for a Specific Configuration, Lamguage, and Key Combination [page 224]

2.9.3.4.2 Delete a Back-End Configuration and Front-End Configuration of an Insight Provider

Deletes the back-end configuration and the front-end configuration with a specific configuration ID

Request

Format: JSON

URI: http://<host>:<port>/ipro/<insight provider>/api/v1/configs/<configID>/common-configs


HTTP Method: DELETE


Response


Table 139:

Code Description

200 Configuration with the specified configuration ID was deleted.

Related Information

Configuring Insight Providers Using REST APIs [page 140]Delete a Configuration of an Insight Provider [page 219]Delete All Configurations of an Insight Provider [page 220]Delete All Translations for a Configuration of an Insight Provider [page 222]Delete All Translations for a Configuration and Language Combination [page 223]Delete All Translations for a Specific Configuration, Lamguage, and Key Combination [page 224]

2.9.3.4.3 Delete All Translations for a Configuration of an Insight Provider

Deletes all translations for a given configuration ID

Request

Format: JSON

URI: http://<host>:<port>/ipro/<insight provider>/api/v1/configs/<configID>/text-interpretations


HTTP Method: DELETE



Response


Table 140:

Code Description

200 Text interpretation for the specified configuration ID was deleted.

Related Information

Configuring Insight Providers Using REST APIs [page 140]Delete a Configuration of an Insight Provider [page 219]Delete All Configurations of an Insight Provider [page 220]Delete a Back-End Configuration and Front-End Configuration of an Insight Provider [page 221]Delete All Translations for a Configuration and Language Combination [page 223]Delete All Translations for a Specific Configuration, Lamguage, and Key Combination [page 224]

2.9.3.4.4 Delete All Translations for a Configuration and Language Combination

Deletes all translations for a configuration ID and a given language

Request

Format: JSON



HTTP Method: DELETE


Response


Table 141:

Code Description

200 Key-text pair for the specified configuration ID was deleted.

Related Information

Configuring Insight Providers Using REST APIs [page 140]Delete a Configuration of an Insight Provider [page 219]Delete All Configurations of an Insight Provider [page 220]Delete a Back-End Configuration and Front-End Configuration of an Insight Provider [page 221]Delete All Translations for a Configuration of an Insight Provider [page 222]Delete All Translations for a Specific Configuration, Lamguage, and Key Combination [page 224]

2.9.3.4.5 Delete All Translations for a Specific Configuration, Lamguage, and Key Combination

Deletes the translations for a given configuration ID, language, and key

Request

Format: JSON

URI: http://<host>:<port>/ipro/<insight provider>/api/v1/configs/<configID>/text-interpretations/<lang>/<key>


HTTP Method: DELETE



Response


Code Description

200 Key-text pair for the specified configuration ID was deleted.

Related Information

Configuring Insight Providers Using REST APIs [page 140]Delete a Configuration of an Insight Provider [page 219]Delete All Configurations of an Insight Provider [page 220]Delete a Back-End Configuration and Front-End Configuration of an Insight Provider [page 221]Delete All Translations for a Configuration of an Insight Provider [page 222]Delete All Translations for a Configuration and Language Combination [page 223]

2.9.4 Manage Configurations of Insight Providers Variants

Table 143:


Create variant configurations Create Variant Configurations [page 226]

Read variant configurations Read the Configuration of an Insight Provider Variant [page 229]

Update variant configurations Update an Insight Provider Variant [page 237]

Delete variants Delete an Insight Provider Variant [page 240]

Related Information

Read an Insight Provider Variant [page 230]Read All Variant Metadata of an Insight Provider [page 231]Read Metadata of an Insight Provider Variant [page 232]Read All Translations for an Insight Provider Variant [page 233]Read all Translations of an Insight Provider Variant for a Language [page 234]Read All Variant Configurations of an Insight Provider [page 235]


Update All Translations of an Insight Provider Variant for a Language [page 239]Delete All Variants of an Insight Provider [page 241]Delete All Translations for an Insight Provider Variant and Language Combination [page 242]

2.9.4.1 Create Variant Configurations

Creates variant configuration resources for given variant IDs

Request


Format: JSON

URI: http://<host>:<port>/ipro/<insight provider>/api/v1/variants

NoteFor the variable <insight provider>, enter the value that corresponds to the insight provider that you want to configure. For an overview of the insight provider URL qualifiers, see the chapter Insight Provider Values for Base URI [page 242].

HTTP Method: POST

Before you send the POST call, enter the x-csrf-token that you just retrieved in the header section of your REST API call.



You can then go ahead with the POST call.

Request Example

[ { "variantId": "var1", "config": { "zoomLevel": 4, "latitude": -58, }, "i18n": [



{ "lang": "de", "mapping": [ { "key": "variantDescription", "text": "com.sap.pdms.app.ahcc" }, { "key": "$ASSETS", "text": "Assets" }, { "key": "variantName", "text": "com.sap.pdms.app.ahcc" }, { "key": "$TURBINE", "text": "Turbine" } ] } { "lang": "en-US", "mapping": [ { "key": "variantDescription", "text": "com.sap.pdms.app.ahcc" }, { "key": "$ASSETS", "text": "Assets" }, { "key": "variantName", "text": "com.sap.pdms.app.ahcc" }, { "key": "$TURBINE", "text": "Turbine" } ] } ] }, { "variantId": "var2", "config": { "zoomLevel": 11, "latitude": -8, }, "i18n": [ { "lang": "de", "mapping": [ { "key": "variantDescription", "text": "com.sap.pdms.app.ahcc" }, { "key": "$ASSETS", "text": "Assets" }, { "key": "variantName", "text": "com.sap.pdms.app.ahcc" }, { "key": "$TURBINE",


"text": "Turbine" } ] } { "lang": "en-US", "mapping": [ { "key": "variantDescription", "text": "com.sap.pdms.app.ahcc" }, { "key": "$ASSETS", "text": "Assets" }, { "key": "variantName", "text": "com.sap.pdms.app.ahcc" }, { "key": "$TURBINE", "text": "Turbine" } ] } ] } ]



variantId Yes ID of the insight provider variant

config Yes Contains the configuration parameters of the insight provider

NoteThe configuration parameters vary for the insight providers. For an overview of the configuration parameters you can use for a specific insight provider, see the chapter Configuration Parameters per Insight Provider [page 167].

i18n Yes Contains the mappings per language of text keys and text values

lang Yes Language code






mapping Yes Contains the mappings of text keys and text values for a specific language



● variantDescription● Relevant for Map only: <layerName> of overlayLayers

2.9.4.2 Read the Configuration of an Insight Provider Variant

Fetches the configuration of a specific insight provider variant

Request

Format: JSON

URI: http://<host>:<port>/ipro/<insight provider>/api/v1/variants/<variantId>/config


HTTP Method: GET

Response

Response Example

{ "zoomLevel": 4, "latitude": -58, }


Code Description

200 Requested variant configuration was found.


2.9.4.2.1 Read an Insight Provider Variant

Fetches a specific insight provider variant

Request

Format: JSON

URI: http://<host>:<port>/ipro/<insight provider>/api/v1/variants/<variantId>


HTTP Method: GET

Response

Response Example

{ "config": { "zoomLevel": 4, "latitude": -58, }, "i18n": [ { "lang": "de", "mapping": [ { "key": "variantDescription", "text": "com.sap.pdms.app.ahcc" }, { "key": "$ASSETS", "text": "Assets" }, { "key": "variantName", "text": "com.sap.pdms.app.ahcc" }, { "key": "$TURBINE", "text": "Turbine" } ] } ] }



Related Information

Update an Insight Provider Variant [page 237]

2.9.4.2.2 Read All Variant Metadata of an Insight Provider

Fetches the metadata of all variants of an insight provider

Request

Format: JSON

URI: http://<host>:<port>/ipro/<insight provider>/api/v1/variants?metadata=true


HTTP Method: GET

Response

Response Example

NoteThe returned parameters variantName and variantDescription are returned in the caller's language, if available.

The language that is used is determined in order of priority as follows:

1. Language provided by the query parameter x-sap-request-language2. Languages from the Accept-Language header of the HTTP request3. English as default

[ { "variantId" : "var1", "variantName" : "variant -1", "variantDescription" : "Variant 1" }, { "variantId" : "var2",


"variantName" : "variant -2", "variantDescription" : "Variant 2" } ]

Related Information

Create Variant Configurations [page 226]

2.9.4.2.3 Read Metadata of an Insight Provider Variant

Fetches metadata of a specific insight provider variant

Request

Format: JSON

URI: http://<host>:<port>/ipro/<insight provider>/api/v1/variants/<variantId>?metadata=true


HTTP Method: GET

Response

Response Example

NoteThe returned parameters variantName and variantDescription are returned in the caller's language, if available.

The language that is used is determined in order of priority as follows:

1. Language provided by the query parameter x-sap-request-language2. Languages from the Accept-Language header of the HTTP request



3. English as default

{ "variantId" : "var1", "variantName" : "variant -1", "variantDescription" : "Variant 1" }

2.9.4.2.4 Read All Translations for an Insight Provider Variant

Fetches all translations for a given variant ID

Request

Format: JSON

URI: http://<host>:<port>/ipro/<insight provider>/api/v1/variants/<variantId>/i18n


HTTP Method: GET

Response

Response Example

[ { "lang": "en", "mapping": [ { "key": "colorLabel", "text": "Color" }, { "key": "variantName", "text": "variant-1-en" }, { "key": "variantDescription", "text": "variant-1-desc-en" } ]


}, { "lang": "de", "mapping": [ { "key": "colorLabel", "text": "Farbe" }, { "key": "variantName", "text": "variant-1-de" }, { "key": "variantDescription", "text": "variant-1-desc-de" } ] } ]


Code Description


2.9.4.2.5 Read all Translations of an Insight Provider Variant for a Language

Fetches all translations for a specific language of a specific insight provider variant

Request

Format: JSON

URI: http://<host>:<port>/ipro/<insight provider>/api/v1/variants/<variantsId>/i18n/<language>






HTTP Method: GET

Response

Response Example

{ "mapping": [ { "key": "typeDimLabel", "text": "Typ" }, { "key": "typeHiearchLabel", "text": "Hierarchie" } ] }


Code Description


2.9.4.2.6 Read All Variant Configurations of an Insight Provider

Fetches all variant configurations of an insight provider

Request

Format: JSON



HTTP Method: GET


Response

Response Example

[ { "variantId": "var1", "config": { "zoomLevel": 4, "latitude": -58, }, "i18n": [ { "lang": "de", "mapping": [ { "key": "variantDescription", "text": "com.sap.pdms.app.ahcc" }, { "key": "$ASSETS", "text": "Assets" }, { "key": "variantName", "text": "com.sap.pdms.app.ahcc" }, { "key": "$TURBINE", "text": "Turbine" } ] } { "lang": "en-US", "mapping": [ { "key": "variantDescription", "text": "com.sap.pdms.app.ahcc" }, { "key": "$ASSETS", "text": "Assets" }, { "key": "variantName", "text": "com.sap.pdms.app.ahcc" }, { "key": "$TURBINE", "text": "Turbine" } ] } ] }, { "variantId": "var2", "config": { "zoomLevel": 11, "latitude": -8, }, "i18n": [ { "lang": "de", "mapping": [



{ "key": "variantDescription", "text": "com.sap.pdms.app.ahcc" }, { "key": "$ASSETS", "text": "Assets" }, { "key": "variantName", "text": "com.sap.pdms.app.ahcc" }, { "key": "$TURBINE", "text": "Turbine" } ] } { "lang": "en-US", "mapping": [ { "key": "variantDescription", "text": "com.sap.pdms.app.ahcc" }, { "key": "$ASSETS", "text": "Assets" }, { "key": "variantName", "text": "com.sap.pdms.app.ahcc" }, { "key": "$TURBINE", "text": "Turbine" } ] } ] } ]

2.9.4.3 Update an Insight Provider Variant

Updates the configuration of a specific insight provider variant

Request


Format: JSON




HTTP Method: PUT





Request Example

{ "config": { "zoomLevel": 4, "latitude": -58, }, "i18n": [ { "lang": "de", "mapping": [ { "key": "variantDescription", "text": "com.sap.pdms.app.ahcc" }, { "key": "$ASSETS", "text": "Assets" }, { "key": "variantName", "text": "com.sap.pdms.app.ahcc" }, { "key": "$TURBINE", "text": "Turbine" } ] } ] }

Request ParametersYou can update config parameters and i18n parameters. For an overview of parameters specific to the following insight providers, see Configuration Parameters per Insight Provider [page 167]:

● Derived Signals● Map



● 3D Chart

2.9.4.3.1 Update All Translations of an Insight Provider Variant for a Language

Updates translations for a variant ID and a given language ID

Request


Format: JSON





HTTP Method: PUT






Request Example

{ "mapping": [ { "key": "typeDimLabel", "text": "Typ" }, { "key": "typeHiearchLabel", "text": "Hierarchie" } ] }



mapping Yes Contains the mappings of text keys and text values for a specific language

Response

Format: JSON


Code Description

200 Key-text pairs for the specified variant ID were updated.

2.9.4.4 Delete an Insight Provider Variant

Deletes all configuration resources for a given variant ID

Request

Format: JSON





HTTP Method: DELETE

Response


Table 150:

Code Description

200 Variant with the specified variant ID was deleted.

2.9.4.4.1 Delete All Variants of an Insight Provider

Deletes all variant configurations of an insight provider

Request

Format: JSON



HTTP Method: DELETE

Response


Table 151:

Code Description

200 Configurations for the insight provider were deleted.


2.9.4.4.2 Delete All Translations for an Insight Provider Variant and Language Combination

Deletes translations for a variant ID and a given language ID

Request

Format: JSON



HTTP Method: DELETE

Response


Code Description

200 Text mappings for the specified variant ID were deleted.

2.9.5 Insight Provider Values for Base URI

In the base URI that you use to configure insight providers using REST APIs, you need to specify what insight provider you want to configure. The following table gives you an overview of values for the base URI variable <insight provider>:

Table 153: Variable Values

Insight Provider You Want ot Configure Variable Value in Base URI

Map geospatial

2D chart twod-viz



Insight Provider You Want ot Configure Variable Value in Base URI

Work activities work-activity

3D chart threed-viz

Asset Explorer asset-explorer

Derived signals derived-signals

Components components

Asset and component scores asset-component-scores

2.10 Checking Configurations

You can check your configurations in the Asset Health Control Center.

Prerequisites

At least one of the following role collections is assigned to your user:

● <pdms_tech>● <pdms_app_user>


Context

After you have configured an insight provider or maintained the machine learning engine, you can access the Asset Health Control Center to check the effects of your configurations on the business user.

Procedure

1. Go to http(s)://<host>:<port>/app/launchpad/index.html and log on.

If your user contains the role collections <pdms_tech>, or <pdms_app_user> and <pdms_datascience_role>, you can use the administration launchpad to do both configure insight


providers or manage the machine learning engine, and check your configurations in the Asset Health Control Center.

2. In the group Launch Application, open the app Asset Health Control Center.

Results

You can now check the look and feel of your configurations of the insight providers. You can furthermore check, if algorithms used for machine learning are working as desired as well.

For more information about how to use the Asset Health Control Center, see the Application Help.

NoteThis document is also available in German, Simplified Chinese, and Italian.

Related Information


2.11 Configuring Thing Hierarchy Service

REST APIs to configure hierarchies of things in Predictive Maintenance and Service, on-premise edition. Possible operations on heirarchies are:

● Create Thing Hierarchy● Update (PATCH) Thing Hierarchy● Delete Thing Hierarchy● Read Thing Hierarchy/Hierarchies

Prerequisites


● <pdms_config_user>For more information about role collections, refer the chapters Maintaining Roles and Users in SAP HANA and Role Templates of SAP Predictive Maintenance and Service, on-premise edition in the installation guide of SAP Predictive Maintenance and Service, on-premise edition, 1.0 feature pack 03

Context

Hierarchy is a method of structuring and organizing objects in a tree structure, where every object except the first one (root) have one immediate superior object and all objects may have one or multiple subordinate objects. This is called a parent-child relationship.



https://uacp2.hana.ondemand.com/viewer/909eac70ea854db998d3752d03a06221/1.0.3/en-US/

https://uacp2.hana.ondemand.com/viewer/909eac70ea854db998d3752d03a06221/1.0.3/de-DE/

https://uacp2.hana.ondemand.com/viewer/909eac70ea854db998d3752d03a06221/1.0.3/zh-CN/

https://uacp2.hana.ondemand.com/viewer/909eac70ea854db998d3752d03a06221/1.0.3/it-IT/

The hierarchy API is used to manage the hierarchies of the things within the Predictive Maintenance and Service, on-premise edition. Hence things and their classification as whether being an asset thing type or not has to be configured before starting with the hierarchy creation.

ExampleA Train with wagons, locomotives, wheels, batteries etc. is modelled as things. These things would be classified as being either an asset or a component. For example, wagons, locomotives are classified as assets whereas wheels, batteries etc., are classified as components.

Hence there exists an asset hierarchy as follows - train as the root component (having parent ID as 0), locomotives and wagons as the leaf nodes (having parent ID of the train, but they are assets). There exists component hierarchy as follows - locomotives as root node (having parent ID as 0) which is an asset and remaining leaf nodes (wheels, batteries whose thing types are not asset types, that is that they are the components).

Related Information

Read Thing Hierarchy/Hierarchies [page 251]Create Thing Hierarchy [page 245]Update (PATCH) Hierarchy [page 248]Delete Hierarchy [page 250]

2.11.1 Create Thing Hierarchy

This service is used to create a thing hierachy.

NoteFollowing restrictions must be adhered to for a valid payload:

● A parent ID represented with value as 0 is the root node and there should be only one such parent ID● There should not be any cyclic dependencies● All the things except the Root Thing must have a parent● A thing can occur only once in the hierarchy

Request

URI: http://<hostname>:<port>/platform/thing-model/api/ThingHierarchy/v1/ThingHierarchies

HTTP Method: POST

Request example:

{ "Name": "Train_Hierarchy", "ExternalID": "Train-Hierarchy", "ThingHierarchyElements": [


{ "ThingID": "LC-5000-01", "ParentThingID": "0", "ThingHierarchyElementDescriptions": [ { "LanguageCode": "en", "Description": "Describes hierarchy node of units in the Train" }, { "LanguageCode": "de", "Description": "Beschreibt den Hierarchieknoten von Einheiten im Zug" } ] }, { "ThingID": "LC-5000-01-B1-M1", "ParentThingID": "LC-5000-01" }, { "ThingID": "LC-5000-01-B1-M2", "ParentThingID": "LC-5000-01" }, { "ThingID": "LC-5000-01-B1-W2", "ParentThingID": "LC-5000-01-B1-M1" }, { "ThingID": "LC-5000-01-B1", "ParentThingID": "LC-5000-01-B1-W2" } ], "ThingHierarchyDescriptions": [ { "LanguageCode": "en", "Description": "Describes hierarchy of units in the Train" }, { "LanguageCode": "de", "Description": "Beschreibt die Hierarchie der Einheiten im Zug" } ]}

Request Properties

Table 154: Thing Hierarchy Properties


Name String Yes 60 Name of the thing hierarchy

Only the following characters are supported:

● a through z and A through Z

● digits 0 through 9● mark underscore

(_)




ExternalID String Yes 255 Thing hierarchy identifier (which is not unique) from an external system. You can create multiple thing hierarchies with the same external ID

Only the following characters are supported

● a through z and A through Z

● numeric digits 0 through 9

● punctuation marks; hyphen (-),underscore (_),colon (:), and full-stop (.)

ThingHierarchyElements

Array of ThingHierarchyElements

Yes An array of node elements forming the Thing Hierarchy

Descriptions String No 255 Description of the thing hierarchy

The descriptive text provided in this field is ignored and is replaced with the descriptive text provided in the Description field of the Thing Hierarchy Description entity.

Table 155: ThingHierarchyElements


ThingID String Yes 32 Unique identifier of the thing generated by the system during creation of a thing



ParentThingID String Yes 32 Unique identifier of the parent thing generated by the system during creation of a thing

ThingHierarchyNodeDescriptions

Array of ThingHierarchyNodeDescriptions

No An array of descriptions of the hierarchy node element with the corresponding ISO language code

Response

Format: JSON

Table 156: Response Status and Error Codes

Code Description

201 Thing Hierarchy created successfully

400 Bad request - invalid payload

Related Information

Configuring Thing Hierarchy Service [page 244]Update (PATCH) Hierarchy [page 248]Delete Hierarchy [page 250]Read Thing Hierarchy/Hierarchies [page 251]

2.11.2 Update (PATCH) Hierarchy

This service is used to update the existing hierarchy. Delta updates to the existing hierarchy is possible. You can update the hierarchy in the following scenarios':

● Update the existing hierarchy descriptions, name, external ID, and add new descriptions● Add new hierarchy node elements● Delete existing hierarchy node elements

Request

URI: http://<hostname>:<port>/platform/thing-model/api/ThingHierarchy/v1/ThingHierarchies('<hieararchy id>')

Request Example



URI: http://<hostname>:<port>/platform/thing-model/api/ThingHierarchy/v1/ThingHierarchies('892add07f47a4830929cc0fe21d6df04')

HTTP Method: PATCH

Response Example:

Sample 1: To delete the entire hierarchy (root node delete)

{ "Name": "Train_Modified_Hierarchy", "ExternalID": "Train-Modified-Hierarchy", "ThingHierarchyElements": [{ "ThingID": "LC-5000-01", "ParentThingID": "0", "Operation":"DELETE" }], "ThingHierarchyDescriptions": [{ "LanguageCode": "en", "Description": " Describes hierarchy of units in the Train" }]}

NoteThe entire hierarchy will be deleted in case the DELETE operation is provided for a root node, as shown in the above payload example

Sample 2: An update operation

{ "Name": "Train_Modified_Hierarchy", "ExternalID": "Train-Modified-Hierarchy", "ThingHierarchyElements": [{ "ThingID": "LC-5000-01-B2-M1", "ParentThingID": "LC-5000-01-B1-W2", "Operation":"ADD" },{ "ThingID": "LC-5000-01-B1-M1", "ParentThingID": "LC-5000-01-B1-W1", "Operation":"DELETE" }], "ThingHierarchyDescriptions": [ { "LanguageCode": "en", "Description": "Describes modified hierarchy of units in the Train" }, { "LanguageCode": "de", "Description": "Beschreibt die Hierarchie der Einheiten im Zug" }, { "LanguageCode": "es", "Description": " Describe la jerarquía modificada de unidades en el tren" } ]}

Request Properties


Table 157: ThingHierarchyElements


ThingID String Yes 32 Unique identifier of the thing generated by the system during creation of a thing

ParentThingID String Yes 32 Unique identifier of the parent thing generated by the system during creation of a thing

Operation String Yes 6 Operation to be performed on the thing hierarchy element. The supported operations are ADD and DELETE performed on the thing hierarchy element during PATCH request

Response: JSON


Code Description

204 No content – hierarchy updated successfully

404 Resource not found – hierarchy does not exist

400 Bad Request – invalid payload

Related Information

Configuring Thing Hierarchy Service [page 244]Create Thing Hierarchy [page 245]Delete Hierarchy [page 250]Read Thing Hierarchy/Hierarchies [page 251]

2.11.3 Delete Hierarchy

This service is used to delete the existing hierarchy




Request Example: http://<hostname>:<port>/platform/thing-model/api/ThingHierarchy/v1/ThingHierarchies('892add07f47a4830929cc0fe21d6df04')

HTTP Method: DELETE

Response

Format: JSON


Code Description

204 No content – hierarchy deleted successfully

404 Resource not found – hierarchy does not exist

Related Information

Configuring Thing Hierarchy Service [page 244]Create Thing Hierarchy [page 245]Update (PATCH) Hierarchy [page 248]Read Thing Hierarchy/Hierarchies [page 251]

2.11.4 Read Thing Hierarchy/Hierarchies

To retrieve hierarchy details of all the available thing hierarchies in the system or details of a given hierarchy ID.

Related Information

Configuring Thing Hierarchy Service [page 244]Create Thing Hierarchy [page 245]Update (PATCH) Hierarchy [page 248]Delete Hierarchy [page 250]

2.11.4.1 Read all Hierarchies

Retrieve the hierarchy details for all the hieararchies available.

URI: http://<hostname>:<port>/platform/thing-model/api/ThingHierarchy/v1/ThingHierarchies


Request Example: http://<hostname>:<port>/platform/thing-model/api/ThingHierarchy/v1/ThingHierarchies

HTTP method: GET

Response Example:

{ "d": { "results": [ { "HierarchyID": "H-P1", "Name": "Asset hierarchy for Plant:-Eagle Ford Field", "Description": null, "ExternalID": "P1", "RootThingID": "Eagle Ford Field", "ThingHierarchyElements": null, "ThingHierarchyDescriptions": null }, { "HierarchyID": "H-Pump-00315", "Name": "Component Hierarchy for Centrifugal Pump Pump-00315", "Description": "Component Hierarchy for Centrifugal Pump Pump-00315", "ExternalID": "Pump-00315", "RootThingID": "Pump-00315", "ThingHierarchyElements": null, "ThingHierarchyDescriptions": null } ] } }


Code Description

200 OK - hierarchy details displayed

Related Information

Read Hierarchy [page 252]Read Thing Hierarchy/Hierarchies [page 251]

2.11.4.2 Read Hierarchy

Retrieve the hierarchy details of the given hierarchy.


Request Example:http://<hostname>:<port>/platform/thing-model/api/ThingHierarchy/v1/ThingHierarchies('892add07f47a4830929cc0fe21d6df04')

HTTP Method: GET



Response Example

{ "d": { "results": [ { "HierarchyID": "892add07f47a4830929cc0fe21d6df04", "Name": "Train_Hierarchy", "Description": "Describes hierarchy of units in the Train", "ExternalID": "Train-Hierarchy", "RootThingID": "LC-5000-01", "ThingHierarchyElements": { "results": [ { "HierarchyID": "892add07f47a4830929cc0fe21d6df04", "ThingID": "LC-5000-01", "ThingName": "LC-5000-01", "ThingDescription": null, "ParentThingID": null, "ParentThingName": null, "ParentThingDescription": null, "Description": null, "Operation": null }, { "HierarchyID": "892add07f47a4830929cc0fe21d6df04", "ThingID": "LC-5000-01-B1-M2", "ThingName": "LC-5000-01-B1-M2", "ThingDescription": null, "ParentThingID": "LC-5000-01", "ParentThingName": "LC-5000-01", "ParentThingDescription": null, "Description": null, "Operation": null }, { "HierarchyID": "892add07f47a4830929cc0fe21d6df04", "ThingID": "LC-5000-01-B1-M1", "ThingName": "LC-5000-01-B1-M1", "ThingDescription": null, "ParentThingID": "LC-5000-01-B1-M2", "ParentThingName": "LC-5000-01-B1-M2", "ParentThingDescription": null, "Description": null, "Operation": null } ] }, "ThingHierarchyDescriptions": { "results": [ { "LanguageCode": "en", "Description": "Describes hierarchy of units in the Train" }, { "LanguageCode": "de", "Description": "Beschreibt die Hierarchie der Einheiten im Zug" } ] } } ] } }



Code Description

200 Returns hierarchy details for the requested hierarchy ID

404 Requested hierarchy does not exist

Related Information

Read all Hierarchies [page 251]Read Thing Hierarchy/Hierarchies [page 251]



Important Disclaimers and Legal Information

Coding SamplesAny 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.

AccessibilityThe information contained in the SAP documentation represents SAP's current view of accessibility criteria as of the date of publication; it is in no way intended to be a binding guideline on how to ensure accessibility of software products. SAP in particular disclaims any liability in relation to this document. This disclaimer, however, does not apply in cases of willful misconduct or gross negligence of SAP. Furthermore, this document does not result in any direct or indirect contractual obligations of SAP.

Gender-Neutral LanguageAs 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 HyperlinksThe 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: http://help.sap.com/disclaimer).

Configuration of SAP Predictive Maintenance and Service, on-premise edition 1.0Important Disclaimers and Legal Information P U B L I C 255

http://help.sap.com/disclaimer/

go.sap.com/registration/contact.html

© 2017 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 http://www.sap.com/corporate-en/legal/copyright/index.epx for additional trademark information and notices.

https://go.sap.com/registration/contact.html

https://go.sap.com/registration/contact.html

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

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

configuration of sap predictive maintenance and service ... · sap predictive maintenance and...

Documents