Technology Blogs by SAP
Learn how to extend and personalize SAP applications. Follow the SAP technology blog for insights into SAP BTP, ABAP, SAP Analytics Cloud, SAP HANA, and more.
cancel
Turn on suggestions
Auto-suggest helps you quickly narrow down your search results by suggesting possible matches as you type.
Showing results for 
Search instead for 
Did you mean: 

Create automatically a Field Service Management Service Call within the Essential Business Functions module of Edge Services

marcoporru
Advisor
Advisor
‎2019 Aug 14 11:01 AM
2,859

Introduction


During the 2018 SAP acquired the cloud solution Coresystem. The main focus of Coresystem is Field Service Management.

Recently the IoT stack of SAP has been integrated with the Field Service Management product, to be able to create C/4HANA and S/4HANA scenarios.

On the other side, SAP Leonardo IoT Edge is composed of Edge Services, which offers an embedded solution to compute rules over the real-time data that is streaming in the Edge.

In this blog post, I will explain how to use the integration of FSM for Edge Services to create automatically a Service Call to request the intervention of the technicians into the FSM system, based on an Edge Services rule.

This operation is executed leveraging two of the modules that are available for Edge Services (both standard and enterprise edition), the Streaming Service and Essential Business Functions.

Both the services enable your SAP Cloud Platform Internet of Things Edge Platform to implement the edge computing with zero development.

In particular, the Streaming Service is one module to locally analyze IoT data streams in real-time based on business logic and Essential Business Functions provides business context (data and processes) at the edge.

The story




Our story is based on 3 personas:

  • Emma is an employee of Iron Inc, a company that operates in the industrial production of iron.

  • Aarav is the dispatcher of the Service Call

  • Marco is the technician that should analyze the problem identified in the Service Call to complete the maintenance of the robot.


Iron Inc has several factories spread in several locations and each location has installed a monitoring system implemented with SAP Leonardo IoT Edge Services.

An analysis has identified that when the temperature of the sensors installed into the cooling circuit of the robots, that are used used to model the iron, reaches a certain threshold it identifies that the robot is working with degraded performance, and will have soon a failure.

A failure identifies a problem because it blocks the production line and the replacement of a robot tip after a failure is more expensive.

In addition, if the production line uses a degraded robot tip, the performance of the robot, and as a consequence of the entire production line efficiency, will be lowered.

Emma is currently using the robot to produce iron like every day of the year, but today the situation is different from the other days because the sensor of the temperature has measured a really high value that means that soon the robot will be out of service.

Aarav is an employee of ACME, company reseller of the industrial robots that also have signed a contract for the maintenance of the equipment sold to Iron Inc. Aarav responsibility is to handle all the Service Calls created into the FSM system including the ones created by Iron Inc and forward the request to a technician.

Now it’s the turn of Marco: he is a technician and has been assigned by Aarav as responsible for the maintenance of the robot of Iron Inc. Marco will go to the right Iron Inc factory (all the information are inside the Service Call) and verify that the robot tip is exhausted, replace it and finally close the Service Call.

With a prompt creation of a Service Call, Iron Inc can plan the maintenance with Marco, avoid stopping the production line and save a lot of money.

Implementation Schema


In the next paragraph, we will focus in detail on the implementation.



In macroblocks, the implementation consists of an SAP Cloud Platform Internet of Things instance connected to an Edge Platform MQTT that is currently receiving the measurements of the temperature from the sensors installed in the robots.

The Streaming Service module and the Essential Business Functions module has been on the top of the Edge Platform within Edge Services Cloud Edition.

The Streaming Service is also implementing a rule that checks if the value of the temperature is higher than 100 °C, that from the executed analysis is considered as a temperature limit to identify the degradation of the robot tip.

In case the rule has identified a breach of the threshold, an action will be invoked on the Edge Platform side to create a new Service Call into the FSM system.

Implementation


The first operation is to model and onboard our physical devices into SAP Cloud Platform Internet of Thing.

The Edge Platform MQTT instance has already been onboarded as defined in the following tutorial: Onboard Edge Platform MQTT

We have also completed the device model (step 1-4: Create device model).

The expected result in the cockpit in the Gateways windows is:



We have also created one sensor type that contains one capability that represents the temperature measured by the sensor:



Under the Devices, we have created one device modeled with the above sensor type, that belongs to the Edge Platform MQTT:



As underlined in the image, copy the value identified as ID of the Gateway, you will need it later. For our example, the id is 868239562

Copy also the device Alternate Id, that in this case is myDeviceAlternateId, you will need it later in the configuration of the Essential Business Functions module.

Verify that your Edge Platform has been started in an elevated shell with admin rights (for example with the command sudo ./gateway.sh for Linux or for Windows by using the menu command Run as Administrator when you are starting the file gateway.bat).

An LDAP server (and the user credentials) is required to be able to invoke the Essential Business Functions API calls.

In this page, you can learn how to set up it from scratch

In the next step, we are going to configure Edge Services; it could be summarized in the following steps:

  • Services Deployment

  • Edge Designer to setup the Rule

  • Deployment of the configurations


Services Deployment




Verify that your Edge Platform MQTT is up and running, then start the Edge Services Policy Service, open the first tile Edge Services Management and search in the list for the gateway with the ID that you have copied before:



Verify that the status is marked as Online (if it’s marked as Offline, verify the status of the Edge Platform inside SCP Internet of Things Cockpit and if it’s started, fetch again the list of the gateways with the reload button), then adapt the Operating System field.

In this example The Edge Platform is running in a Virtual Machine with Ubuntu 18.04.2 LTS, so we have selected Linux, in case you are going to start the Edge Platform in a Windows machine, click the pencil icon in this page and Select Windows in the list, then press Save.



The other available OS is LinuxARM32 (for example in case your Edge Platform is installed in a RaspberryPI), but there is no mention on OSX, if you are running OSX you need to create a virtual machine Linux based because it’s not currently supported by Edge Services Management.

Now click to the tab called Services and press the + button to select a new Service to be installed



In the next list select Streaming Service to install the service designed to elaborate the streaming data.



The grid is now updated, and the Streaming Service is now part of the list in the status Requested.

Update periodically the status since it is changed to Installed. Repeat the same operation for the service Essential Business Functions.



This operation could require a while: to verify that the operation is proceeding correctly, your Edge Platform is starting to log the progress in the installation of the bundles.

It is also possible to verify the same information by listing all the installed bundles within the OSGI command lb.


Edge Designer to setup the Rule


Open again the home page of the Policy Service and click on the tile Edge Designer.

We need to create a new project to model the rules and the actions required to check the value of the temperature and to invoke the Service Call creation.

Press the + button in the bottom bar to create a new project:



After the creation of the new project, go to the Sensor Models tab to create a new mapping for the IoT Service Sensor Type into an Edge Services entity that will be analyzed by the edge rule engine; in this window press the + button to create a new model.

The browser opens a modal window, the form needs to be filled with the model created into IoT Service



The Minimum Number Of Reading is the minimum number of sensor readings needed before averaging can be performed. This is useful for noisy analog sensors, for example, where trends are more important than individual readings.

Create Average Reading Value For is the time window size for the aggregation.

Click Create to create the model, then go to the tab Rules



Click the + button to create a new Rule that will be executed over the streaming data.

Use any preferred name and put a consistent value for the Maximum Output Frequency. In the example we have used 10 seconds, it means that the outputs defined for the rule can be invoked once per 10 seconds.

The generated events are saved and valid for 2 days.



Press Create, to save the generated Rule.

In the next step, we are going to specify the condition required to fire the rule. Click on the rule name to modify it



Open the Conditions tab, then press the + button to add the business logic required to be executed to verify if the robot tip is overtemperature.



Compile the condition with the following details, then press Save:

  • Name: Overtemperature or any other

  • Filter: Any. It is possible to analyze only certain entities based on the sensor or device id or tag

  • Condition Type: Value monitoring. This is the option to monitor the value within the Streaming Service

  • Sensor Model Name: TemperatureSensorType_FSM Capability_Temperature. The name is autogenerated during the creation of the modeling

  • Operator: > The Robot Tip scenario would like to check if the temperature has been reached. Other operators are available.

  • Condition Data Source: Input Value. It means that our data source is represented by the Input Value

  • Threshold Value: 100. The critical value that, when reached should create a new FSM Service Call

  • Max Event Frequency: 1 min. it means that at a maximum will be created one FSM Service Call per minute




We have created the condition, now we can switch to Actions tab, and press the + button to create a new Action:

  • Action Name: this is the name of the Action, we have used FSMServiceCall

  • Description: a description of the action, it could be empty

  • Action Type: Create Service Call

  • Device ID: here you have to specify the device id attached for the action, you can use the special placeholder ${deviceId}

  • Subject: This is the subject for the Service Call created into the FSM system, High temperature on ${deviceId}

  • Remarks: The body for the request: Please check the robot tip id: ${deviceId}

  • Priority Level: This is the priority assigned to the service call, you can use the placeholder ${PRIORITY_HIGH}

  • Problem Type Code: The code of the error, we have used -1

  • Earliest Start Time in Minutes from Event Time: The number of minutes from the time when the FSM service call is created, that the service call should be started in the FSM system, for example 35 minutes

  • Duration in Minutes: This is the duration in minute expected for the Service Call, we have set 120 minutes

  • Due Date in Minutes from Event Time: this is the due date from the creation of the service call, for example 180 minutes

  • The following are the details about the address, where the equipment is

    • Street: Piazza Borgo Pila

    • Street Number: 39

    • City: Genoa

    • State: Liguria

    • Country: Italy

    • ZIP Code: 16129






After the creation of the Rule, click again to the rule project Project: Robot



Open the Rules tab and then click on the rule name, then switch to the Outputs tab, and finally press the + button to create a new output.



In the next windows Create an Output for the Action and in the dropdown list select the action created just now.



Repeat the same operation for the Enterprise Event, and select the available enterprise plugin IOTServicesPlugin1

The outputs have been created; the rule is complete but is still marked as disabled, press the Enable label to set it as enabled.



Click again Project: Robot label to go to the project home page and open the tab Runtime Settings, press the pencil to edit it.

Complete the configuration of the current runtime; in particular, for the FSM integration, it’s required to enable the EBF Configuration and specify the hostname details for the essential business function that we are going to deploy.

We have configured localhost for the hostname and port 8443 since the EBF server will run in the local machine where is running the Edge Platform.

It’s also required to complete the configuration, to specify an authorized LDAP user, with the credentials encoded in base64.

The certificate validation needs to be unchecked (it’s localhost).

We have also updated the log level to INFO to have more information available.



Click Save to update the settings.

In the next windows click Validate, to do some validity check on the project and the configurations and then Publish, to make it available for the deployment; use your favorite name, for example, FSMConfiguration, while publishing it.



Now the configuration with the Edge Designer component is completed. The FSM integration requires to have two configurations deployed, one for the EBF component and the other for the Steaming Service.

Deployment of the configurations

Open the home page of the Policy Service and open the tile Edge Services Management.

Reach the page of the Essential Business Functions configuration: click the icon on the left of the SAP logo, select Services. In the main grid select Essential Business Functions and then click on the Configurations tab. Finally, press the + button to create a new configuration



Compile the form with all the required details.



The form is divided into 4 parts, let’s see them in detail.

The first part contains the general details:

  • Name: this is the name of your configuration

  • Plant: the plant (synchronization user) for the EBF service

  • LDAP Host: the host where the used LDAP server is running; in the current configuration it is localhost because it’s the same host of our Edge Platform.

  • LDAP Organizational Unit: is the organization of the user in the LDAP server. Our EBEF user is under dc=People accordingly with the generated LDAP server configuration.

  • Enable FSM Configurations: must be on, to permit to specify the FSM system details


The second part contains information about the FSM Connection.

You need to create your OAuth client credential pair into the FSM system to have the information to fill this part of the form. Go into the FSM portal and open the Administration menu



Login again with your admin credentials, then in the administration UI go to Clients and press Create to generate a new client



Use the autogenerated name, or define a custom name, then press Save and write it down the autogenerated password.

Now we have all the information required to complete the second part. Let’s see in detail:

  • URL: it’s the base URL of your FSM tenant (for example https://de.coresystems.net)

  • Auth URL: is the URL used to make authentication requests. Generally, it’s https://auth.coresuite.com

  • Authorized LDAP Users: it’s a comma-separated list of users authorized within the LDAP server to invoke the FSM APIs; these users are enabled to invoke the Service Call creation API. The user we have pre-provisioned and configured in the runtime setup is EBEF.

  • Account Name: FSM login account name

  • Username: FSM login username

  • Password: FSM login password

  • Client ID: The client id generated in the FSM Administration console

  • Client Secret: the autogenerated password in the FSM Administration console

  • Client Version: is the version of the client. This value could be limited in the FSM Administration console by imposing a minimum version of the client allowed to invoke APIs. I have used 1.0 because in my environment there is no limitation.


The Third part in the form contains the details required to map the business logic present inside FSM.

You need to declare a Business Partner to complete this step. Open Master Data in the application menu



Now go to the Business Partner list, that is generally the first icon in the left menu, and create a new Business Partner with the + button, or open an existing one



We are using Iron Inc as a Business Partner. Edge Services needs to know the FSM internal ID of the Business Partner.

This id is used in the navigation structure of the FSM web portal. Copy from the URL of the current page to discover it; the last part of the link that is an alphanumerical string: it’s the Business Partner ID.

The url of my page is https://de.coresystems.net/master-data-management/#/businesspartner/details/8FA7D41CD4C448BF9A27962E..., it means that the required id is 8FA7D41CD4C448BF9A27962E9055C141.

All the information required to complete this part has been discovered, go back to the UI of the Edge Services and complete this part of the form.

  • Company: is the company name of an existing company inside the FSM system. You can define several companies inside FSM in the Administration console. Our company as defined in the Story part is named ACME

  • Business Partner Id: the FSM id of a Business partner object, copied a while ago

  • Status Code New: this is the numerical status code used by EBF to create the service call. It must match an existing FMS Status (for example -5)

  • Status Code Closed: this is the numerical status code used by the EBF mark as closed the service call. It must match an existing FMS Status (for example -1)

  • Origin: the origin for the Service Calls. It must match an existing FMS Status (for example -1)

  • Priority: the default priority used for the Service Call. It must match an existing FMS Status (for example HIGH)

  • Problem Code: a number that indicates the type of problem inside the Service Call. It must match an existing FMS Status (for example -5)

  • Subject: the default subject for the Service Call

  • Offset Minutes Due Date Time: the default amount of minutes, from the time when the FSM Service call is created, the Service Call could be marked as in time for the due date in the SAP FSM system.

  • Offset Minutes Earliest Start Date Time: the default amount of minutes, from the time when the FSM Service Call is created, the Service Call should be started in the SAP FSM system.

  • Additional Information: a JSON array containing key-value pairs. This array is used by the EBF service to substitute user-defined variables into a new FSM service call when it is created.


Your question could be: what do these numbers mean?


These numbers are like enumerations and are defined in the extended GUI of your Coresystem. You can easily access to it with your admin credentials from https://my.coresuite.com. You will be able to verify the correspondence and define new values for all of them.

All these values are available (and editable) in the section Settings, Service calls under the submenus Types, Status, Origins, Problem types



We are now aware of how to fill the third part of the form, it's now possible to proceed with the configuration of the last part of the form.

Go again to the page of FSM under Master Data and open the Equipment list. Create new equipment or open an existing one.

We are using a Robot Tip as equipment. Edge Services needs to know the FSM internal ID of the equipment.



This id is used in the navigation structure of the FSM web portal. Copy from the URL of the current page to discover it; the last part of the link that is an alphanumerical string: it’s the Equipment ID.

The URL of my page is https://de.coresystems.net/master-data-management/#/equipment/details/00977F40D9474A939D4752605AA2CA..., it means that the required id is 00977F40D9474A939D4752605AA2CA55.

Write it down and copy the value of the field Serial no., that for our equipment is APJ953H

Compile the last part of the form with the JSON object; it must contain a mapping between the IoT Service Device (using his Alternate Id) and the Equipment.
[{

	"deviceId": "myDeviceAlternateId",

	"map": [{

		"value": "00977F40D9474A939D4752605AA2CA55",

		"key": "equipmentId"

	}, {

		"value": "APJ953H",

		"key": "serialNumber"

	}]

}]

The value of the field called deviceId is the Device Alternate Id you have specified during the device creation process into the IoT Service Cockpit.

Put two objects inside the map property: the first has as key the equipmentId and as value the id you have copied before from the Equipment page in the FSM web portal, and the second has as key serialNumber and as value the value of the field Serial no. from the Equipment page in the FSM web portal.

You can define the mapping of multiple devices and equipment in case you are using more than one physical asset; you have just to add a new object similar to the one you have already defined inside the JSON array.

Now it’s time to deploy the configurations for Streaming Service and Essential Business Function.

In the Edge Services Management application click Groups and Gateway, click the tile of your gateway in the list and click the tab Configuration, then press the + button to start the deployment of the Streaming Service configuration.



In the next window select the Service and the Configuration created before, then press the Save button to start the deployment.



When the deployment is started, the status is Requested to Deploy



Press periodically the reload button, till the status is changed to Deployed



You just need to Activate the Configuration to mark it as active. Repeat the same operation with the Service Essential Business Functions.

The configuration of the integration that permits to create new Service Calls inside Field Service Management within Edge Services has been completed.

Verification


The robot is working as expected for several months, but today it’s the time to start the maintenance process. The temperature measured by the sensor is higher than the threshold of 100 °C, and a Service Call is created into the FSM system.

Let's try to simulate/verify this behavior: if we start to ingest normal data, below the threshold and take a look into the FSM system, as expected no service calls are created.



To simulate this behavior, I have created a simple Python application that is currently simulating the ramp-up of the temperature till 110 °C.

The simulator is basically an MQTT client that is ingesting one measurement per second for a simulated device.



It’s always possible to verify that the Rule has been triggered and generated an Event.

First of all, one requirement is to retrieve the admin credentials for the Streaming Service Console, from SCP Internet of Things Cockpit.

Go to Gateways, and then open your gateway. There is a list of Custom Properties in the last part of the page.



Copy the value of STREAM_SECRET.

Open the Streaming Service Console in the browser, his address is https:\\<EDGE PLATFORM IP ADDRESS>:443

In case your browser marks the certificate as insecure you must trust it, so press “Go on to the web page”



In the login page use admin as user name and the value of STREAM_SECRET.

In the page under Monitoring, Events are stored all the created events. You should see in the list one Event with the same name as the rule, that is FSMServiceCallRule.



This event should have created a new Service Call in the FSM system. The Service Calls are created first of all locally and then synchronized with the FSM system. The Service Call appears in the Service Calls list only when the two systems are in sync.



If we open the newly created service call, we can check the date of it and the Subject that, by his definition on the Edge Services side, should contain the Device Alternate Id of the SCP IoT Service Device, that in our case was called myDeviceAlternateId.

As the final part of the integration, Aarav can assign the Service Call to Marco, that is responsible for reacting, analyzing and solving the problem (and finally Close the Service Call).


Troubleshooting


If no service calls have been created, you can start analyzing the problem by doing several checks that can give some hints about what is not currently working.

The most common problem is “No data ingestion on the edge”, you can always check that the data ingestion is working in two ways.

One option is inside IoT Service Cockpit, go to your device and check the last received measurements.



You can also check this information in the Streaming Service Console, and ensure that you have checked the vale of Stream Reading To Monitor under sensor Profiles & Rules.



Now you can go to Live Sensors, select in the list of Live Devices your sensor, and verify the received data.



In case there is no data, generally, it means there is something mess in the configuration of your device, or in the network connectivity.

It’s possible to see all the data but no Events have been created. It could mean that you are not satisfying the window sizing you have defined during the rule definition, accordingly with your threshold.

Vice versa it could happen that even if you see a new event on the list, the service call is not created. It could mean that the internal database is not yet in sync with the FSM system.

In this case, you could just check the connectivity to the FSM system from the Edge Platform machine and, after you are sure that the communication could be established, wait a while till the synchronization of the internal database.

In case there is still no Service Calls in the FSM system there could be problems of different nature, such as in the configuration of the service, the communication to the LDAP server, or other different errors.

In the following lines, I’ll show some useful commands and files that can help you to identify where the problem is. The commands are in a Linux based syntax, but there are equivalent Windows commands.

Check the service calls exists locally


Go inside the Edge Platform machine and authenticate with the command

curl -k -u<LDAP_USER>:<LDAP_PASSWORD> -c cookie.txt  https://localhost:8443/ws_authenticate
curl -k -uEBEF:Initial -c cookie.txt  https://localhost:8443/ws_authenticate

then execute the check:

curl -k -b cookie.txt  -u<LDAP_USER>:<LDAP_PASSWORD> https://localhost:8443/ws_restful_fsm_controller/service_call
curl -k -b cookie.txt -uEBEF:Initial   https://localhost:8443/ws_restful_fsm_controller/service_call

This statement retrieves the Service Calls that are created and stored locally, including the ones that are not yet synchronized, and their status.

Check that your machine is able to communicate with the LDAP server


There are several commands to verify it, the simplest is to check with ldapwhoami -h <HOST> -x -w "<PASSWORD>" -D cn=<USER>,dc=<DISTINGUISH NAME>

and with ldapsearch -x -LLL -h <HOST>
ldapsearch -x -LLL -h 127.0.0.1

ldapwhoami -x -w "Initial" -D cn=EBEF,dc=People

Check for the error into the logs


If you have forgotten to specify an enumeration in your FSM system within the extended Coresystem GUI and are trying to create for example a Service Call with it, the Service Call creation will fail.

This information and other useful information for other configuration problems are logged in the Edge Services logs.

The useful log files, up to this version, are:
./edgeservices/dep_iot_edge/log/IOTServicesPlugin.log 

./edgeservices/dep_iot_edge/log/StreamingLitePlugin.log 

./edgeservices/dep_iot_edge/log/IoTAdapter.log 

./edgeservices/dep_iot_edge/log/Webserver.log 

./edgeservices/dep_iot_edge/log/OData.log.lck 

./edgeservices/dep_iot_edge/log/OData.log 

./edgeservices/dep_iot_edge/log/EdgeConsole.log 

./edgeservices/dep_iot_edge/log/WhitelistManager.log 

./edgeservices/dep_iot_edge/log/Security-EdgeConsole.log 

./edgeservices/dep_iot_edge/log/Security-StreamingService.log 

./edgeservices/dep_iot_edge/log/IOTServicesEnterprisePlugin.log 

./edgeservices/dep_iot_edge/log/StreamingLite.log 

./edgeservices/dep_iot_edge/log/HttpProtocolPlugin.log 

./edgeservices/businessessentials/db/logs/eng_log_*.log 

./edgeservices/businessessentials/db/logs/web_log_*.log

 

Conclusion


In this blog post, you should have learned how to configure the SAP Edge Service Streaming Service and Essential Business Functions, and how to apply it to the integration with Field Service Management.

You should have also learned some base knowledge about how to create a base configuration and a process flow for the FSM system.

As a possible extension to this use case, it is also possible to apply the FSM integration by using the hyperscaler for the data ingestion Microsoft Azure IoT.

As a further extension, it is also possible to use the entire SAP IoT stack offer, composed of

  • SAP Cloud Platform Platform Internet of Things for the device modeling, the data ingestion (plain or certificate-based), the secure connection to SAP Leonardo IoT, the forward of the measurement to any 3rd party external system.

  • SAP Edge Services to enable the Edge Computing with the Streaming Service, the Essential Business Functions (to create the Service Calls and complete the scenario with other available integrations), and, in addition, the Persistence Service to store locally the measurements.

  • SAP Leonardo IoT to create the Service Calls also in from the cloud, based on Rules and Actions, the creation of Events, and the interoperability offered by SAP Leonardo IoT with the Masterdata Module, the Geolocation Services, and the Decision Support Service.

Labels in this area
Popular Blog Posts