business process extensions in dmc
Post on 29-Dec-2021
0 Views
Preview:
TRANSCRIPT
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. 2 All rights reserved.
© 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.
PUBLIC
© Copyright 2020 SAP SE or an SAP affiliate company. 3 All rights reserved.
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
© Copyright 2020 SAP SE or an SAP affiliate company. 4 All rights reserved.
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
© Copyright 2020 SAP SE or an SAP affiliate company. 5 All rights reserved.
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.
PUBLIC
© Copyright 2020 SAP SE or an SAP affiliate company. 6 All rights reserved.
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
© Copyright 2020 SAP SE or an SAP affiliate company. 7 All rights reserved.
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.
PUBLIC
© Copyright 2020 SAP SE or an SAP affiliate company. 8 All rights reserved.
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
© Copyright 2020 SAP SE or an SAP affiliate company. 9 All rights reserved.
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
PUBLIC
© Copyright 2020 SAP SE or an SAP affiliate company. 10 All rights reserved.
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
© Copyright 2020 SAP SE or an SAP affiliate company. 11 All rights reserved.
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
© Copyright 2020 SAP SE or an SAP affiliate company. 12 All rights reserved.
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.
PUBLIC
© Copyright 2020 SAP SE or an SAP affiliate company. 13 All rights reserved.
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
© Copyright 2020 SAP SE or an SAP affiliate company. 14 All rights reserved.
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
© Copyright 2020 SAP SE or an SAP affiliate company. 15 All rights reserved.
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.
PUBLIC
© Copyright 2020 SAP SE or an SAP affiliate company. 16 All rights reserved.
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
© Copyright 2020 SAP SE or an SAP affiliate company. 17 All rights reserved.
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
© Copyright 2020 SAP SE or an SAP affiliate company. 18 All rights reserved.
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",
PUBLIC
© Copyright 2020 SAP SE or an SAP affiliate company. 19 All rights reserved.
"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.
PUBLIC
© Copyright 2020 SAP SE or an SAP affiliate company. 20 All rights reserved.
The flow of the business process and the associated user personas can be visualized in the diagram
below.
PUBLIC
© Copyright 2020 SAP SE or an SAP affiliate company. 21 All rights reserved.
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>
b. Description: <Description>
c. Runtime Environment: <PCo System>
d. Click Step 2.
PUBLIC
© Copyright 2020 SAP SE or an SAP affiliate company. 22 All rights reserved.
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
© Copyright 2020 SAP SE or an SAP affiliate company. 23 All rights reserved.
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
© Copyright 2020 SAP SE or an SAP affiliate company. 24 All rights reserved.
d. On the Variables / Parameters popup, select the parameter from the Start
event (e.g. sfcvalue)
e. Click OK.
PUBLIC
© Copyright 2020 SAP SE or an SAP affiliate company. 25 All rights reserved.
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
© Copyright 2020 SAP SE or an SAP affiliate company. 26 All rights reserved.
l. Save the automation sequence.
PUBLIC
© Copyright 2020 SAP SE or an SAP affiliate company. 27 All rights reserved.
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>
b. Description: <Description>
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
© Copyright 2020 SAP SE or an SAP affiliate company. 28 All rights reserved.
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
© Copyright 2020 SAP SE or an SAP affiliate company. 29 All rights reserved.
c. Provide <Name> and <Description> and click Step 2.
d. Select the desired Plant, add Resources, and click Review.
PUBLIC
© Copyright 2020 SAP SE or an SAP affiliate company. 30 All rights reserved.
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
© Copyright 2020 SAP SE or an SAP affiliate company. 31 All rights reserved.
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
© Copyright 2020 SAP SE or an SAP affiliate company. 32 All rights reserved.
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
© Copyright 2020 SAP SE or an SAP affiliate company. 33 All rights reserved.
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.
top related