business process extensions in dmc

PUBLIC

© Copyright 2020 SAP SE or an SAP affiliate company. 1 All rights reserved.

Business Process Extensions in SAP Digital Manufacturing Cloud PUBLIC

Developer’s Guide

Document version: v.1.0.0– 2020-03-18

SAP Digital Manufacturing Cloud

Business Process Extensions

PUBLIC


© Copyright 2020 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.

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

www.sap.com/corporate-en/ legal/copyright/index.epx#trademark for additional trademark information and notices.

Terms for Included Open Source Software

This SAP software contains also the third-party open source software products listed below. Note that for these third-

party products the following special terms and conditions shall apply.

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



PUBLIC


Document History

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

Version Date Description

v.1.0.0 3/18/2020 Business Process Extensions

1 TABLE OF CONTENTS

2 Introduction ........................................................................................................................................... 4

2.1 Business Process Extensions ......................................................................................................... 4

3 Architectural Overview .......................................................................................................................... 4

4 Extensibility Patterns ............................................................................................................................. 5

4.1 SAP Extension Factory, Serverless runtime (FaaS Extensions) ...................................................... 5

4.1.1 Prerequisites .......................................................................................................................... 5

4.1.2 Landscape Setup .................................................................................................................... 5

4.1.3 Configuration ......................................................................................................................... 6

4.1.4 Developing Extensions .......................................................................................................... 8

4.2 SCP PaaS Tenant Extensions ........................................................................................................ 14

4.2.1 Prerequisites ........................................................................................................................ 14

4.2.2 Landscape setup .................................................................................................................. 14

4.2.3 Configuration ....................................................................................................................... 14

4.2.4 Creating a business application on SCP ............................................................................... 15

5 Registration of FaaS Extensions in SAP Digital Manufacturing Cloud SaaS Tenant ............................ 18

5.1.1 Service Metadata................................................................................................................. 18

5.1.2 Import FaaS Extension ......................................................................................................... 19

5.1.3 Manual Registration ............................................................................................................ 19

6 Shop Floor Design ................................................................................................................................ 19

6.1 Steps for sample Shop Floor Design extension ........................................................................... 21

PUBLIC


2 INTRODUCTION

The Business Process Extensions Developer’s Guide is intended to assist you in creating reusable

functions as extensions to SAP Digital Manufacturing Cloud. These can be consumed as automation

sequences in Shop Floor Design.

2.1 BUSINESS PROCESS EXTENSIONS A business process extension service is a reusable function which can assist in data formatting, data

enrichment, or other use cases for shop floor design. It can be written in either the NodeJS runtime in

SAP Extension Factory, serverless runtime, or in any kind of API exposure from an SAP Cloud Platform

(SCP) PaaS tenant. Furthermore, it can also be written in a business application within a customer

landscape exposed as an API and registered in SAP Digital Manufacturing Cloud.

This guide provides you with a deeper understanding of the respective extensibility patterns.

3 ARCHITECTURAL OVERVIEW

The architecture in the following diagram shows different components from SAP and the customer landscape

coming together to create distinct patterns for building extensions.

The following patterns are possible:

1. Extend with services from SAP Cloud Platform Function as a Service (FaaS)

2. Extend with services from customer-built applications in SAP Cloud Platform

3. Extend with services from customer’s own application (Cloud or On Premise) out of SAP Cloud

Platform

4. Extend with services published by partners built on SAP Cloud Platform, and customers can

subscribe and use them in Shop Floor Designer.

5. Extend with services from other SAP systems, e.g. SAP S/4HANA, ME/MII or SAP EWM, etc.

PUBLIC


4 EXTENSIBILITY PATTERNS

The scope of this document is limited to the following two patterns:

1. SAP Extension Factory, serverless runtime (FaaS Extensions)

2. SCP PaaS tenant extensions

4.1 SAP EXTENSION FACTORY, SERVERLESS RUNTIME (FAAS EXTENSIONS) Customers that want to extend existing APIs can use the SAP Extension Factory, serverless runtime to

write their extensions. This option is valid for customers who are looking for quick functionality without

the extra effort of managing the application lifecycle or infrastructure management. Here, when an API

is executed and reaches the extension point of an attached extension, the control is passed to the

extension which takes care of the execution and returns the control back.

4.1.1 Prerequisites

• SAP Extension Factory, serverless runtime

• Customer Preferred Editor

o Extension Center Business Application

o SAP Extension Factory, serverless runtime CLI and Local Editor with NodeJS enabled and

Cloud Foundry CLI.

• Digital Manufacturing Cloud Tenant including sample master and transactional data (see

Implementation Starter Kit for execution, see SAP Help for additional information)

4.1.2 Landscape Setup

Customers can configure the SAP Extension Factory, serverless runtime in the SAP Digital Manufacturing

Cloud SaaS tenant or any other SAP Cloud Platform subaccount. Since this is a FaaS environment, the

management of applications, performance, and auto scaling is taken care of by the cloud provider.

Customers are responsible for the initial configuration of the runtime and setting connectivity with the

SAP Digital Manufacturing Cloud SaaS tenant. These extensions can serve as simple processing tasks in

the Shop Floor Designer which can be combined along with the standard processes. Functions can use an

API from SAP Digital Manufacturing Cloud if needed. You can find all APIs for SAP Digital Manufacturing

Cloud in the Digital Manufacturing Cloud API Business Hub.

https://api.sap.com/package/SAPDigitalManufacturingCloud?section=Artifacts

PUBLIC


The diagram below shows the sequence of events.

4.1.3 Configuration

To configure SAP Extension Factory, serverless runtime, the following steps needs to be performed.

1. Allocate quota for SAP Extension Factory, serverless runtime

PUBLIC


2. Create the SAP Extension Factory, serverless runtime service instance

3. Subscribe to the Extension Center business application

4. Assign roles to users

5. Set up connectivity between the Extension Factory and the SAP Digital Manufacturing Cloud

SaaS tenant

For steps 1-4, please refer to the official help documentation for initial setup here.

4.1.3.1 Setting up Connectivity Between the Extension Factory and the SAP Digital Manufacturing Cloud

SaaS tenant

Follow these steps to establish connectivity between the Extension Factory and the SAP Digital

Manufacturing Cloud SaaS tenant:

1. Create a service key

a. Open the global account and navigate to your respective space.

b. Choose Service Instances and select the service instance for SAP Extension Factory,

serverless runtime, or xfs-runtime. The Service Instance screen displays.

c. Choose Service Keys.

d. Click Create Service Key and enter the desired name. You do not need to enter

configuration parameters.

e. Choose Save. The service key is created.

f. Copy the contents of the service key to a text file.

https://help.sap.com/viewer/bf7b2ff68518427c85b30ac3184ad215/Cloud/en-US/80f67e476a8447378a72b3fcfbce8f3e.html

PUBLIC


2. Return to the subaccount and choose Destinations.

3. Click New Destination and fill in the fields as follows:

a. Name: DESTINATION_EXTENSION_FACTORY

b. URL: <URL from service key>

c. Proxy Type: Internet

d. Authentication: OAUth2ClientCredentials

e. Client ID: <client_id from service key>

f. Client Secret: <client_secret from service key>

g. Token Service URL: <token_url from service key>

h. Token Service User: leave blank

i. Token Service Password: leave blank

4. Choose Save. You have configured SAP Extension Factory, serverless runtime

4.1.4 Developing Extensions

You can subscribe to the Extension Center business application on the SAP Cloud Platform. It can be used

to build the serverless functions. It is also possible to build the application in a local editor with a

NodeJS-enabled environment and bring the project to the landscape with the SAP Extension Factory,

serverless runtime CLI.

4.1.4.1 Extension Center

The Extension Center business application can be used to build and deploy serverless extensions. There

are certain limitations to the way the extensions can be used. For example:

• The maximum number of service instances for a subaccount is 1.

• The maximum number of extensions per service instance is 5.

PUBLIC


Detailed information can be found in Functions Programming Model.

The following example shows the lifecycle of a very simple extension creation:

The steps to create extension projects can be found in the help documentation. Some of the sample

code snippets for function creation can be found in the https://github.com/SAP-samples/cloud-function-

nodejs-samples.

For additional information, follow this SAP Blog: Using SAP Cloud Platform Extension Factory, serverless

runtime to build light weight extensions.

To create an extension project, follow these steps (Files to build the extension project can be found in

this folder GitHub Sample Code for Extension Center)

1. Open Extension Center:

a. Go to your subaccount and choose Subscriptions.

b. Search for Extension Center.

c. Click Go to Application. The Extension Center application opens.

2. Click New Extension. The Create Extension screen displays.

3. Select Template with a function and a trigger.

Create Extension Project

Create Triggers

Create Functions

Save and Deploy project

Test and Invoke

Monitor Logs

https://help.sap.com/viewer/bf7b2ff68518427c85b30ac3184ad215/Cloud/en-US/8382ef0e89044fb8b294660ae2f2bb14.html

https://help.sap.com/viewer/bf7b2ff68518427c85b30ac3184ad215/Cloud/en-US/dc293b3d8c3c4b82b4f4409eb3fed083.html

https://github.com/SAP-samples/cloud-function-nodejs-samples

https://github.com/SAP-samples/cloud-function-nodejs-samples

https://blogs.sap.com/2020/01/22/using-sap-cloud-platform-extension-factory-serverless-runtime-to-build-light-weight-extensions/

https://blogs.sap.com/2020/01/22/using-sap-cloud-platform-extension-factory-serverless-runtime-to-build-light-weight-extensions/

https://github.com/SAP-samples/digital-manufacturing-extension-samples/tree/master/DMC_BusinessProcesses/1-Get-Custom-Fields-From-Order-Data-Using-SFC/Using-FaaS-from-Extension-Center

PUBLIC


4. Click Step 2 and enter Extension Name.

5. Click Step 3 and enter a Function Name.

6. Click Step 4 and enter Trigger Name. Leave Trigger Type with its default value of HTTP.

7. Choose Create. The extension project is created.

8. Copy the sample code from getorderdata.js from the GitHub repository mentioned above and

adjust accordingly.

PUBLIC


9. Click Create File in lib folder and name it sysAuthCfg.json from the GitHub repository mentioned

above and modify the values using the entries from the service key for Digital manufacturing

Cloud execution instance.

10. Click Create File in lib folder and name it samplevalues.json from the GitHub repository

mentioned above and change the plant and sfc values as per your environment.

11. Click Save and Deploy. The Trigger URL is created.

12. Click View Trigger Details. The Trigger Details popup displays.

13. Click the Trigger URL link. All custom data linked to the order will be retrieved.

14. To look at errors, click Logs, and select the desired function.

PUBLIC


4.1.4.2 Extensions with Local Editor and SAP Cloud Platform Extension Factory, serverless runtime CLI

It is also possible to use any preferred local editors along with NodeJS runtime to build the extension

project locally and then deploy to the SAP Cloud platform using the SAP Cloud Platform Extension

Factory, serverless runtime CLI. Here are the steps to build the extension project using Visual Studio

Code.

Prerequisites:

• SAP Cloud Platform CF subaccount with SAP Cloud Platform Extension Factory, serverless

runtime instance (Refer SAP Cloud Platform tools page to download the client tools)

• Local editor, e.g. Visual Studio Code

• NodeJS and Node Package Manager (NPM)

• SAP Cloud Platform Extension Factory, serverless runtime CLI

• CF Client

Files to build the extension project can be found in the GitHub Sample Code for Local Environment.

1. Create a new folder for the project in Visual Studio Code.

2. Create a subfolder called lib.

3. Create a new file called faas.json (Copy the sample contents from the GitHub repository).

4. Create a new file called package.json (Copy the sample contents from the GitHub repository).

5. In the lib folder, create a new file called getorderdata.js (Copy the sample contents from the

GitHub repository).

6. In the lib folder, create a new file for authorization called sysAuthCfg.json (Copy the template

from the GitHub repository). Modify the values using the entries from the service key for Digital

manufacturing Cloud execution instance.

7. Create a new file called samplevalues.json (Copy the sample contents from the GitHub

repository).

8. Make sure the module name, handler, function name and trigger names are linked properly.

https://tools.hana.ondemand.com/#cloud

https://github.com/SAP-samples/digital-manufacturing-extension-samples/tree/master/DMC_BusinessProcesses/1-Get-Custom-Fields-From-Order-Data-Using-SFC/Using-FaaS-from-Local-Environment

PUBLIC


9. The NodeJS project should be self-contained before deployment. Go to the project folder, set

NPM environment and build. Open a new terminal and execute the build command.

> npm config set "@sap:registry=https://npm.sap.com"

> npm install

10. Login to your cloud foundry space with CF client. You will need the CF_API_ENDPOINT which can

be found on the subaccount Overview page. Create a service key on the SAP Cloud Platform

Extension Factory, serverless runtime instance.

> cf api <CF_API_ENDPOINT>

> cf login

> cf create-service-key <SERVICE_INSTANCE_NAME> <SERVICE_KEY_NAME>

11. Create a new service key and deploy the project using this key.

> xfsrt-cli login -n <SERVICE_INSTANCE_NAME> -k <SERVICE_KEY_NAME>

> xfsrt-cli faas project deploy -p <path to project folder>

12. To get the trigger URL from the command line:

> xfsrt-cli faas project get -n <PROJECT_NAME>

PUBLIC


4.2 SCP PAAS TENANT EXTENSIONS Customers can use their PaaS Account to create applications using services provided by the SAP Cloud

Platform (SCP) and APIs from SAP Digital Manufacturing Cloud registered in the API Business Hub. The

calls are REST-based. Your business application can also have your own database with your own schema.

The apis will remain backward compatible.

4.2.1 Prerequisites

The prerequisites for SCP PaaS Tenant Extensions are:

• SCP CF application runtime

• SCP CF database services (optional)

• SCP CF portal services (optional)

• Customer-preferred editor:

o SAP Web-IDE Full Stack

o Customer preferred local environment and Cloud Foundry CLI

4.2.2 Landscape setup

Business applications can be built in customer or partner tenant which can be linked to SAP Digital

Manufacturing Cloud shop floor designs by registering them in the Manage Service Registry app. This

process is just like the FaaS extensions, but the execution of the extensions is done in a

customer/partner-managed PaaS landscape.

4.2.3 Configuration

For building business applications in SCP Cloud Foundry PaaS environment, entitlement for application

runtime would be needed and the configuration can be done as follows.

PUBLIC


4.2.4 Creating a business application on SCP

Here we present a sample application to build an application SCP PaaS tenant which can be registered

and further consumed in Digital Manufacturing Cloud. For reference, please refer the GitHub sample

Code for PaaS Extension.

1. Create a multi-target application in Web-IDE. Provide the project name and click Next and then

click Finish.

2. Create a new NodeJS module on the project. Provide the module name and click Next and then

click Finish.

https://github.com/SAP-samples/digital-manufacturing-extension-samples/tree/master/DMC_BusinessProcesses/1-Get-Custom-Fields-From-Order-Data-Using-SFC/Using-PaaS-App-from-WebIDE

https://github.com/SAP-samples/digital-manufacturing-extension-samples/tree/master/DMC_BusinessProcesses/1-Get-Custom-Fields-From-Order-Data-Using-SFC/Using-PaaS-App-from-WebIDE

PUBLIC


3. Open the package editor inside the NodeJS module and add the following dependencies:

4. Create a new file called sysAuthCfg.json in the module and provide necessary values from the

service key created on the SAP Extension Factory, serverless runtime. The template for

sysAuthCfg.json is provided in the GitHub.

5. Modify the server.js file for your custom logic (Copy the sample contents from the GitHub

repository)

6. Maintain project settings to maintain the target CF subaccount details. Right click on the project,

Select Project, then Project Settings and then select Cloud Foundry.

PUBLIC


7. Select the API module and click Run. The application is deployed to SCP tenant and the API can

be noted for registration inside DMC.

Note:

In the previous example, we used SCP to build a simple API call and expose our endpoints. You can also

expose any API from your landscape to leverage additional business functionality whether it is in the

cloud or on-premise.

PUBLIC


5 REGISTRATION OF FAAS EXTENSIONS IN SAP DIGITAL MANUFACTURING

CLOUD SAAS TENANT

After the APIs have been built, they can be registered in SAP Digital Manufacturing Cloud using the

Manage Service Registry app. The endpoints can be registered in two ways:

• Import FaaS using destination configuration (In the previous section the destination

DESTINATION_EXTENSION_FACTORY was maintained).

• Manual registration

Importing destinations from the SAP Extension Factory, serverless runtime will automatically create the

service definition to be registered. With manual registration, the developer needs to create the service

JSON following the structure from SAP Note 2829941. (More information can be found in the SAP Note

attachments).

5.1.1 Service Metadata

The Service JSON field requires the following 6 properties:

1. Triggers

2. Authentications

3. Produces

4. Consumes

5. Parameters

6. Responses

In the section below, we include additional information for two of the properties.

Scenario Code Snippet

Triggers "triggers": [{ "name": "SampleTrigger", "type": "HTTP", "protocol": "REST", "method": "POST", "endpoint": { "host": "example.com", "port": "100", "path": "/test", "url": "http://example.com/test" } }]

Authentications "authentications": [ { "type": "basic" }, { "type": "oauth2", "authorizationUrl":"https://example.com/oauth/authorize",

https://launchpad.support.sap.com/#/notes/2829941

PUBLIC


"tokenUrl": "https://example.com/oauth/authorize", "flow": "accessCode", "scopes": [ "example.read", "example.write" ] } ]

5.1.2 Import FaaS Extension

To import FaaS extensions, follow these steps:

1. Go to the Manage Service Registry app and select Import FaaS.

2. Modify the Service JSON field as required such as adjusting the parameters and authentication

information.

Based on the scenario, you must update the parameters and authentication information.

5.1.3 Manual Registration

To manually register business applications, a payload like the FaaS extension scenario must be created.

For a sample payload, check samples in digital-manufacturing-extension-samples. The configuration

properties in the payload, such as Triggers, and Authentication should be adjusted based on your

scenario.

6 SHOP FLOOR DESIGN

The Shop Floor Designer helps you model various production processes and gain transparency when

creating the layout of your shop floor. The production processes may define the interaction between

machines or define rules, actions, and workflows that control the execution on the shop floor. For more

details on getting started with shop floor design, please follow the official documentation here.

https://github.com/SAP-samples/digital-manufacturing-extension-samples/blob/master/DMC_BusinessProcesses/1-Get-Custom-Fields-From-Order-Data-Using-SFC/Using-FaaS-from-Extension-Center/extdemo/lib/samplevalues.json

https://help.sap.com/viewer/f1949e1d1fd24d7e998e5f70fecc1835/latest/en-US/7718bdf1ce1a45e09cd2b02b63856733.html

PUBLIC


The flow of the business process and the associated user personas can be visualized in the diagram

below.

PUBLIC


6.1 STEPS FOR SAMPLE SHOP FLOOR DESIGN EXTENSION To create a sample shop floor design extension, do the following:

1. Create a shop floor design extension:

a. Open the Manage Shop Floor Designs app

b. Click +

c. Provide the following details:

a. Name: <Name>

b. Description: <Description>

c. Type: Production

d. Version: 1.0

e. New Designer: <>

d. Click Create.

2. Choose Create Production Process (Automation Sequence). The Production Process Details

screen displays.

3. Provide the following production process details:

a. Name: <Process Name>


c. Runtime Environment: <PCo System>

d. Click Step 2.

PUBLIC


e. Click Review to review your entries.

f. Click Create. The automation sequence is created.

g. Add start and end events to the design pane and add the extension function registered

in the Manage Service Registry app.

h. Select the Start event, and under Inputs, click + (Add) to create a new input parameter.

Enter the following values:

a. Name: <Input Parameter Name> (e.g. sfcvalue)

b. Data Type: String

PUBLIC


i. Click Save.

j. Propagate the parameter to the extension function. This should be done for all input

parameters.

a. Select the connector between the Start event and extension function

b. Select value help of <input parameter>.

c. On the Configure Input Value popup, click Insert.

PUBLIC


d. On the Variables / Parameters popup, select the parameter from the Start

event (e.g. sfcvalue)

e. Click OK.

PUBLIC


f. Repeat these steps for all necessary input parameters.

k. Create client proxy configuration for extension node.

a. Select Automation Sequence.

b. Select Client Proxy Configuration link. The Client Proxy Configuration window

displays.

c. Provide <Client Proxy Name>, <Description>, and <Timeout> value and click

Save.

PUBLIC


l. Save the automation sequence.

PUBLIC


4. Create Notification Flow:

a. Click Shop Floor Elements

b. Select the PCo system

c. Create a PCo notification flow:

a. Name: <Name of the flow>


d. Click Create.

e. Link the automation sequence with Internal service provider

a. Drag the automation sequence to the design pane of the client proxies.

b. Link the internal service provider action with the automation sequence.

PUBLIC


c. Provide the values <Name>, <Trigger Condition>, <Trigger Expression> and click

Create.

5. Create default production process:

a. Create a new Production Process default. On the main page, click Add.

b. Click Create New Item and then click Create Production Process (Default).

PUBLIC


c. Provide <Name> and <Description> and click Step 2.

d. Select the desired Plant, add Resources, and click Review.

PUBLIC


e. Click Create. The default production process template is created.

6. Build a flow where the automation sequence triggers before the SFC start.

a. Add components to build a flow.

b. Select the Automation Sequence and link the Trigger Service created from the previous

step in the notification flow. Optionally, add conditions based on the work center, order,

material, routing, and operation activity.

PUBLIC


c. Add input parameters.

d. Click Save. The default production process is created.

7. Deploy and activate SFD model.

a. Click the arrow (Submit for Activation).

b. Click the Submit for Activation button.

PUBLIC


c. In the Manage Activation Objects application, search and select the Activation group

from the previous step.

d. Click Deploy and select Deploy and Activate.

8. Test the extension from the Automation Sequence.

a. Go to Manage Shop Floor Designs and select the project.

b. Select the Automation Sequence and click Run. The Trigger Service Parameters dialog

displays.

PUBLIC


c. Click Run. The automation sequence is executed calling the extension function from SAP

Cloud Platform, Extension factory.

9. Test the extension from the POD

a. Go to Manage Orders app.

b. Release a new order and take note of the SFC.

c. Go to the POD, enter the SFC from the previous step and click Start. The automation

sequence is executed calling the extension function from SAP Cloud Platform, Extension

Factory.

The successful execution of the start action indicates that the extension function executed successfully.

The logic inside Shop Floor Designer can be modeled to read this response from the extension function

and act accordingly. The service tagValueStoreMultiple from the Plant Connectivity (PCo) cloud server

can be called to write values to indicators and eventually store the values in equipment tags that are

mapped to these indicators. For more details, follow the official documentation: Application Help for

Shop Floor Designer.

https://help.sap.com/viewer/f1949e1d1fd24d7e998e5f70fecc1835/latest/en-US/748d560d8fda43f59e792886af680157.html

https://help.sap.com/viewer/f1949e1d1fd24d7e998e5f70fecc1835/latest/en-US/748d560d8fda43f59e792886af680157.html

business process extensions in dmc

Documents