Deploying Fiori Launchpad in SAP Predictive Maintenance

Help Documentation

SAP Predictive Maintenance and Service, Cloud edition

Document Version: 1.0 – 2019-06-30

CUSTOMER

Deploying Fiori Launchpad in SAP Predictive Maintenance and Service, cloud edition

2

CUSTOMER

© 2019 SAP SE or an SAP affiliate company. All rights reserved.


Typographic Conventions

Typographic Conventions

Type Style Description

Example Words or characters quoted from the screen. These include field names, screen titles,

pushbuttons labels, menu names, menu paths, and menu options.

Textual cross-references to other documents.

Example Emphasized words or expressions.

EXAMPLE Technical names of system objects. These include report names, program names,

transaction codes, table names, and key concepts of a programming language when they

are surrounded by body text, for example, SELECT and INCLUDE.

Example Output on the screen. This includes file and directory names and their paths, messages,

names of variables and parameters, source text, and names of installation, upgrade and

database tools.

Example Exact user entry. These are words or characters that you enter in the system exactly as

they appear in the documentation.

<Example> Variable user entry. Angle brackets indicate that you replace these words and characters

with appropriate entries to make entries in the system.

EXAMPLE Keys on the keyboard, for example, F2 or ENTER .


Contents

CUSTOMER

© 2019 SAP SE or an SAP affiliate company. All rights reserved. 3

Contents

1 Building and Deploying Fiori Launchpad .................................................................................... 4

2 Consuming other Business Services .......................................................................................... 5 2.1 Adding Tile to Fiori Launchpad ............................................................................................................. 5

3 Adding Custom Analysis Tools .................................................................................................... 7

4 Application and Technical Names ............................................................................................. 10

5 Resources ..................................................................................................................................... 12

6 Troubleshooting/Help ................................................................................................................ 13 6.1 Tips/Common Errors .......................................................................................................................... 13 6.2 Resolving Known Errors ...................................................................................................................... 13

6.2.1 Design Time Issues ............................................................................................................. 13 6.2.2 Runtime Issues .................................................................................................................... 16

4

CUSTOMER



Building and Deploying Fiori Launchpad

1 Building and Deploying Fiori Launchpad

• Download the zip file consisting of SAP Predictive Maintenance and Service, cloud edition Fiori launchpad.

File link: https://help.sap.com/doc/60854f441a9348d1a57e5c8e70566ae8/1906/en-US/pdms-flp-1906.zip

Steps

1. Unzip the above provided file.

2. Run the mtabuild.bat or mtabuild.sh file in the project via terminal to generate the MTAR file.

3. Use the CF CLI to deploy the application in the target space, that is, "cf deploy <mtar>".

4. The logs should provide the application URL or use the command "cf apps" to view all the applications. The

URL to be used corresponds to the "<product>-flp-approuter" module.

You can also map the Fiori launchpad to a custom route through the Routes tab in the Cockpit or by using the

"cf map-route" command.


Consuming other Business Services

CUSTOMER


2 Consuming other Business Services

Note

The new times series APIs based on Asset Central Foundation (ACF) data model and terminology will

replace the native SAP Leonardo IoT times series APIs in SAP Predictive Maintenance and Service

(PdMS), scenarios, over the next releases. In a case, direct consumption of SAP Leonardo IoT time series

APIs is unavoidable, provisions should be made for adaptation and/or migration to new API in future.

• For consuming other business services in the same launchpad, bind this service instance to the app-router

module as described in the mta.yaml file.

• If the UI from the business service needs to be consumed, this also needs to be bound to the FLP module in

the same manner.

• Addition of UI applications from the business service can be done in the same way as for the extension

application above by updating the “CommonDataModel.json”.

2.1 Adding Tile to Fiori Launchpad

Steps

• Extract the contents of the attached archive which has the pre-delivered Fiori Launchpad content based on

the product - PdMS.

• Open the “CommonDataModel.json” in the portal-site folder. The structure of the file is explained in the

README file in the "FLP" module.

Add the ID property of the new extension application under the required group and catalog json objects

following the same structure, as for other apps. (Samples below.)

o "id" property here is the application's "id" property from the manifest.json file.

6

CUSTOMER



Consuming other Business Services

o "intentHintId" here is the semantic object-action from the tile configuration maintained in the

manifest.json of the application.

o "id" property here is any unique identifier text.

o "appId" here is the application's "id" property from the manifest.json file of the application.

o "intentHintId" here is the semantic object-action from the tile configuration maintained in the

manifest.json of the application.

• [ Optional ] If you want a new group/catalog, also add the relevant translations in the translation files for the

group/catalog name under the i18n folder.

• [ Optional ] For a new group, also add the group ID under the “groupsOrder” array property in the

CommonDataModel.json file to specify the order in which it should appear.

• The technical names that are maintained in the JSON file can be mapped to the application names, which is

mentioned in the section - Application and Technical Names.

• Add the business service instance that is serving the new FLP tile and to the resources section of the mta.yaml

of your Fiori launchpad.

• Add the business service instance that is serving the new FLP tile and to the require section of your Fiori

launchpad approuter in the mta.yaml file.

• Build and deploy your Fiori launchpad.


Adding Custom Analysis Tools

CUSTOMER


3 Adding Custom Analysis Tools

In the mta.yaml:

1. Create a new resource referencing your custom analysis tool backend destination. For more information, see

The MTR Deployment Descriptor

Example: In the PDMS Fiori launchpad, in the previous step, a commented section with an example of

destination resource, exists at the bottom of the mta.yaml file, For details, see

https://github.wdf.sap.corp/k5/pdms-customer-flp/blob/master/mta.yaml#L119-L125

2. Bind the destination resource you just created to the pdms-approuter module in the mta.yaml.

Example: In the PDMS Fiori launchpad, in the previous step, a commented section exists in the approuter

section of the mta.yaml file. This file provide an example of a destination resource being consumed. For

details, see https://github.wdf.sap.corp/k5/pdms-customer-flp/blob/master/mta.yaml#L48-L56

In the xs-app.json

1. Add a route for the new analysis tool's backend destination in the xs-app.json of the FLP. Use the following

parameters:

Property Value

csrfProtection False

Source the URL path that you provided in the service-catalog

service registration in the mta.yaml of your custom

analysis tool, followed by a regular expression to

catch any following characters

Target a regular expression, which will insert the previously

matched characters from the regular expression used

in the "source" field

destination the name of the destination resource that you defined

your mta.yaml file, which references your custom

Analysis Tool destination

authenticationType Use "xsuaa"

For an exmple, see https://github.wdf.sap.corp/k5/pdms-customer-flp/blob/master/approuter/xs-app.json,

that contain the below json content:

The%20MTR%20Deployment%20Descriptor



https://github.wdf.sap.corp/k5/pdms-customer-flp/blob/master/approuter/xs-app.json

8

CUSTOMER




{

"welcomeFile": "/cp.portal",

"authenticationMethod": "route",

"routes": [

{

"csrfProtection": false,

"source": "^/ipro/sdk/(.*)$",

"target": "$1",

"destination": "sdktest-api-destination",

"authenticationType": "xsuaa"

}

]

}

In the xs-security.json:

1. Add new scopes and roles to the xs-security.json that you can be used to protect custom analysis tool

backend APIs. For more information on scopes and roles, see The Application Security Depositor

For example, see https://github.wdf.sap.corp/k5/pdms-customer-flp/blob/master/xs-security.json#L6-L9

and https://github.wdf.sap.corp/k5/pdms-customer-flp/blob/master/xs-security.json#L19-L25

2. In your custom analysis tool, ensure that REST APIs are protected and using the scopes you have defined

here in the xs-security.json.

Deployment

1. You should build and deploy custom analysis tool, before deploying the Fiori launchpad.

2. Build and deploy the Fiori launchpad. To build, run the mtabuild script in the root folder of the FLP zip file you

downloaded. On the UNIX system, run the mtabuild.sh script or on windows systems, the mtabuild.bat script.

The build script will produce a pdms-flp.mtar file. Use the Cloud Foundry CLI.

https://github.com/cloudfoundry/cli together with the MTA plugin for the Cloud Foundry CLI

https://github.com/cloudfoundry-incubator/multiapps-cli-plugin to deploy the FLP with the command cf

deploy pdms-flp.mtar

Post deployment

1. In the cloud cockpit, add the role that you defined in the xs-security.json of the approuter to a role collection

that is assigned to your user. For more information, see Building Roles and Role Collections for Applications

2. Login to Fiori launchpad and the Explorer application. Choose the custom analysis tool with the standard SAP

analysis tools from the service catalog

The%20Application%20Security%20Depositor

https://github.wdf.sap.corp/k5/pdms-customer-flp/blob/master/xs-security.json#L6-L9

https://github.wdf.sap.corp/k5/pdms-customer-flp/blob/master/xs-security.json#L19-L25

https://github.com/cloudfoundry/cli

https://github.com/cloudfoundry-incubator/multiapps-cli-plugin

Builidng%20Roles%20and%20Role%20Collections%20for%20Applications



CUSTOMER


10

CUSTOMER



Application and Technical Names

4 Application and Technical Names

Asset Central Foundation Applications

Application Name Technical Name

Announcements sap.iot.ain.manageannouncements

Application Settings sap.iot.ain.manageconfigurations

Company Profile sap.iot.ain.company_profile

Data Privacy & Protection sap.iot.ain.gdpr

Documents sap.iot.ain.manageattachments

Equipment sap.iot.ain.manageequipments

Failure Modes sap.iot.ain.failuremodes

Functions sap.iot.ain.functions

Groups sap.iot.ain.groups

Instructions sap.iot.ain.manageinstructions

Locations sap.iot.ain.functional_locations

Lookup sap.iot.ain.lookup

Models sap.iot.ain.managemodels

Obsolescence sap.iot.ain.obsolescence

Performance Improvement sap.iot.ain.performanceimprovement

Personal Dashboard sap.iot.ain.personaldashboard

Plugins sap.iot.ac.plugins

Smart Matcher sap.iot.ain.smartmatcher

Spareparts sap.iot.ain.managespareparts

Systems sap.iot.ain.managesystems

Templates sap.iot.ain.configure_category

User Authorizations sap.iot.ain.userauthorization

Predictive Maintenance and Service, Cloud edition


Explorer sap.pdms.app.ahcc


Application and Technical Names

CUSTOMER



Failure Mode Analytics com.sap.iot.fma.application

Alert Details com.sap.dca.alert.objectpage

Fingerprints sap.iot.ain.managefingerprints

Rules sap.iot.ain.rf.rules

Dataset Configurations com.sap.pdms.dss.dataSetConfigs

Data Science Service Models com.sap.pdms.dss.models

Failure Mode Analytics Model Management com.sap.iot.fma.configuration

Failure Mode Analytics Validation com.sap.iot.fma.validation

Leading Indicators com.sap.iot.leadingindicators

Shell plugins com.sap.pdms.lib

12

CUSTOMER



Resources

5 Resources

PdMS Fiori Launchpad: https://help.sap.com/doc/60854f441a9348d1a57e5c8e70566ae8/1906/en-

US/pdms-flp-1906.zip


Troubleshooting/Help

CUSTOMER


6 Troubleshooting/Help

6.1 Tips/Common Errors

Always re-build the project after making any changes. Only then will the changes be reflected in the MTAR you are

trying to deploy.

6.2 Resolving Known Errors

6.2.1 Design Time Issues

Uploading application content, deleting application content, consuming design time metadata APIs

Application metadata already exists

Term Description

Problem HTML5 Application Deployment fails with error "Application metadata for application xyz already

exists" and response type 400

Cause There is already an app-host service instance that contains a manifest.json with app.id = xyz in this

space. You cannot have multiple app-host containing the same app.id

Solution Delete/undeploy the old app-host instance or use another app.id in the resources folder for the new

app-host

Deploy/Redeploy in process

Term Description

Problem HTML5 Application Deployment fails with error "Deploy in progress" or "Redeploy in progress" and

response type 409

Cause

HTML5 App Deployer retries to upload content before previous upload was finished. This might

happen because the CF health check timeout (default = 60 sec.) was reached before HTML5 Apps

Repo DT returned a response

Solution Configure a longer health check timeout in manifest.yaml/mta.yaml (maximum 180 sec) or

configure health check type = NONE

14

CUSTOMER




Concurrent Deploy/Redeploy

Term Description

Problem HTML5 Application Deployment fails with error "app-host is being modified by another process" and

response type 403

Cause HTML5 App Deployer tries to upload content while another HTML5 App Deployer is also uploading

using the same app-host

Solution Try again after the first HTML5 App Deployer has finished

HTML5 Apps Repo app-host remains in "Deploy in progress" or "Redeploy in progress" status or any other inconsistency

Term Description

Problem HTML5 Application Deployment fails with error "Deploy in progress" or "Redeploy in progress" and

response type 409 for a long time or any other issue

Cause It might happen that CF restart the HTML5 Apps Repo DT instance while upload is taking place. In

such case app-host might remain inconsistent

Solution Run delete applications content API (see in DELETE <>/applications/content in REST APIs) to reset

the app-host instance

"Store quota lower than 0 or bigger than already assigned quota" error when creating/updating app-host service instance

Term Description

Problem Upload/update service instance fails with error: Store quota lower than 0 or bigger then already

assigned quota"

Cause The sub-account does not have enough quota to create/update the service instance. Note that

quota is in mb and default size limit of an app-host instance is 2 mb

Solution

In the ISM tool, increase the quota for the global account and, in the entitlements UI, assign more

quota to the sub-account or create/update the service instance with a lower size limit. For example:

cf create-service html5-apps-repo app-host myapphost -c '{\"sizeLimit\":55}'

https://wiki.wdf.sap.corp/wiki/display/CloudFront/REST+APIs



CUSTOMER


More than the maximum of 200 mb quota per global account is required

Term Description

Problem By default, the ISM tool enables a maximum of 200 mb per global account and your global

account requires a higher amount

Cause The current CIS tool does not allow manual extension of the maximum quota

Solution Create a ticket based

on https://jtrack.wdf.sap.corp/secure/CreateIssueDetails!init.jspa?pid=18973&issuetype=12001

Failed to create app-host service instance although app-host plan is visible

Term Description

Problem

When trying to create app-host service instance you get the following error: "Error creating service

"dt_TestMTA_ui_deployer" from offering "html5-apps-repo" and plan "app-host": Controller

operation failed: 403 Forbidden: A service instance for the selected plan cannot be created in this

organization. The plan is visible because another organization you belong to has access to it"

Cause app-host service was not entitled for the subaccount associated to this organization however it was

entitled to another subaccount under the same global account

Solution Entitle service HTML5 Application Repository, plan app-host to the current subaccount as well

Failed to upload content, maximum file length exceeded

Term Description

Problem When trying to upload content, the process fails with the following error message: "Error while

parsing request; Error: maximum file length exceeded"

Cause The zipped application file length exceeds the size limit of the app-host service instance

Solution Increase the app-host size limit using cf update-service. For example: cf update-service my-app-

host -c '{"sizeLimit": 4}'

https://jtrack.wdf.sap.corp/secure/CreateIssueDetails!init.jspa?pid=18973&issuetype=12001

16

CUSTOMER




Uploading application content failed: applications size exceeds the service plan limit

Term Description

Problem When trying to upload content, the process fails with the following error message: "Uploading

application content failed: applications size exceeds the service plan limit"

Cause The unzipped applications content exceeds the size limit of the app-host service instance

Solution Increase the app-host size limit using cf update-service. For example: cf update-service my-app-

host -c '{"sizeLimit": 4}'

Uploading application content failed, response 400

Term Description

Problem When trying to upload content, the process fails with the following error message: "Upload Failed"

and response type 400 (bad request)

Cause

One or more of the input validations performed by HTML5 Application Repository design time fails.

The possible validation failures are:

1. missing manifest.json file on root level

2. manifest.json app.id has invalid characters (hyphens, @, %, &, etc.)

3. manifest.json app.version is not in format xx.xx.xx where x must be integer number (e.g.: -

snapshot is not supported)

4. Total zipped content exceeds service instance size limit

5. Total extracted apps content exceeds service instance size limit

6. app.id of one or more of the applications is already contained in another html5-apps-repo/app-

host service instance in the same space

Solution

Check if one the above-mentioned problems is relevant for your case. For example, check the size of

your html5-app-deployer resources folder, check manifest.json. If you are not sure if another service

instance already uses your app.id, try to slightly change your app.id and deploy again

6.2.2 Runtime Issues

Serving HTML5 Apps Repo content from approuter, consuming runtime metadata API's

Missing xs-app.json in HTML5 Application

Term Description

Problem Serving content from approuter fails with error "Application does not have xs-app.json" and

response type 500

http://app.id/

http://app.id/

http://app.id/

http://app.id/



CUSTOMER


Term Description

Cause xs-app.json file is missing in HTML5 App

Solution Redeploy the HTML5 App with xs-app.json file or ask the business service owner to add xs-app.json

Failed to Retrieve xs-app.json

Term Description

Problem Serving content from app router fails with error "Error while retrieving xsApp configuration" and

response type 500

Cause HTML5 App belongs to a business service and it is not public or HTML5 Apps Repo not available

Solution Ask the business service owner to define "public" : true in app manifest.json or wait until HTML5

Apps Repo is re-started

Application does not exist

Term Description

Problem Approuter fails to serve content with response type 404. Application log: "Application xyz does not

exist" is printed to the console

Cause

The application name provided in URL is not correct. Note: application names are stored in HTML5

Apps Repo without dots. If manifest.json app.id = country.list the application name will be countrylist

and the same application name should be used in the URL

Solution Check application name

Calls to service endpoints specified in an app's xs-app.json fail with 404 errors

Term Description

Problem You have defined routes in a UI app's local xs-app.json but calls do not get routed and instead return

a 404 error

Cause

The routes in the xs-app.json file are processed top to bottom, and if a route maps the pattern it will

be picked even if a route below it would be a better match. The route for the html5 apps repository

typically is a "catch all" route, and if any routes are defined below it, they never will be reached.

Solution Move the route leading to the html5-apps-repo-rt to be the last entry in the xs-app.json file.

http://app.id/

18

CUSTOMER




Bearer token invalid, requesting client does not have grant_type=user_token or no scopes were granted error

Term Description

Problem Approuter token exchange with Business Service token fails. XSUAA returns error: "Bearer token

invalid, requesting client does not have grant_type=user_token or no scopes were granted."

Cause The uaa.user scope in xsuaa instance configuration is missing

Solution

1. In xs-security.json file add:

"scopes": [ { "name": "uaa.user", "description": "UAA" }],

"role-templates": [ {"name": "Token_Exchange","description": "UAA","scope-references":

["uaa.user"] } ]

2. re-deploy or update the xsuaa service instance

3. Make sure that the users have the new role_template (Token_Exchange) added to their

role_collections

www.sap.com/contactsap


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. 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.

Material Number:

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

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