Extending the Network Spatial Service with a CAP b...

martinstenzig · ‎11-09-2021

As of October 2021, the Business Network contains a new component called the Network Spatial Service (NSS). In its first version it allows the visualization of Asset Intelligent Network collaborative work order locations on a map.

The intent of this article is to show how it can be extended using an external, spatial data provider. To keep it interesting I am using a Cloud Application Programming Model (CAP) Node.js based service and support TechEd Session ISP105 - Increase Business Network Efficiency with Collaborative Visualization. The geometries are stored in HANA Spatial and can be queried using HANA's powerful spatial functions.

AIN NSS Screenshot

Business Scenario

The collaborative work order scenario can show a companies work orders on a Map. The additional service we are developing in here can hold the real time location of our Field Service Technicians. Both (work orders and technician location) can now be shown in one map as two separate layers.

Prerequisites

Business Network - Specifically Asset Intelligence Network (AIN) (or Test and Demo license thereof)

BTP Licenses (or Trial to start with)
- Application Runtime
- HANA Cloud

Mapbox API Key

Configuration

In order to build a scenario that does not conflict with anything else we will create a complete new renderer and additional layer.

Either follow the instructions in the section "Step by Step instructions to develop a CAP based source service" or clone this repo to create and deploy the service (mbt build and cf deploy).

To implement this scenario as described in here and/or if you want to use colorful symbols you will need to configure a custom Mapbox style. Skip this step if you simply want to chose circles (in which case you have to adjust the layer definition outlined below)
1. Open up Mapbox Studio https://studio.mapbox.com/
2. Select 'New Style'
3. Choose a template - I used 'Basic' with 'Galaxy' variation
4. Hit the 'Customize Basic' button at the bottom
5. Find the Images button at the top and drag and drop the three images located in the ./doc/mapbox-config folder into the 'Images' section
6. Hit the publish button to save and publish your changes
7. Back in the styles menu, click on the three vertical dots and copy the "Style URL" for use below

Configure the new Scenario
1. Open up the NSS configuration app (Configure Network Maps - Last App in the list below)
2. Start by Creating a new Renderer
  - API Key: [Paste your Mapbox API Key here, usually start with "pk..."]
  - URL: https://bnc-nss-map-sbx.cfapps.sap.hana.ondemand.com/nsc/map/
  - Default Style: [Copy the Mapbox style from the previous step and paste it here]
3. Create a new Layer
  - Type: Symbol
  - Source Type: GeoJSON
  - Service URL: [route to app router module]/geojson/RealtimeLocations
  - Layout JSON:
```
{

  "icon-image": ["match",

                ["get", "Status"],

                1,"truck-green-50",

                2,"truck-orange-50",

                "truck-red-50"], 

  "icon-size": 0.5

}
```
4. Create a new Scenario
  - Enable Draw Toolbar: 'No' - as this is a read only scenario
  - Enable Bounding Box: 'Yes' - you want to zoom automatically to your selected feature
  - Bounding Box Padding: 200
  - Add the three layers (Current Objects Polygons, Point and Lines to the Layers list, assign a common Group Name (i.e. 'Current') to all three layers.
  - Now add our new Layer to the layers list and set Locked = 'Yes'
5. Select the Work Order App application, click edit and add the new scenario to the Scenarios list.

Once you have performed these steps you should be good to go. Open the 'Work Orders' App, navigate to the 'GEOMETRY' Tab and switch the scenario to yours. It should looks like this:

Step by Step instructions to develop a CAP based source service

You can find the latest version and repo here: https://github.com/MartinStenzig/teched-2021

Create CAP project using cds init command

Add HANA and mta.yaml using cds add hana command

Adjusted the 'mta.yaml' file to make some changes I like
- Adjusted the mta id
- Changed the mta description
- Added 2 parameters to the service
```
  - memory: 200M  # this number is merely for testing

  - disk-quota: 250M
```
- Added a expilict schema name to the database service
```
    config:

      schema: teched_2021
```

Add the data model

Add the service

Add the Rest Test Script
- At this point you developed the basic service that works locally and can be deployed, but is not functioning in the cloud yet.

Added some custom handlers and some supporting functions to allow for the storage and read of spatial data in a HANA environment.

To expose the service as REST GeoJSON service we create a second service called GeoJSON with the following service defintion and implementation
- The implementation does some conversion specific to HANA databases as well as to GeoJSON.
- You can now access the service via the following URL: [host]/geojson/RealtimeLocations
- Find more details on the approach in this SAP Community blog post

To remove CORS restriction you can add an app router

see files in directory /approuter

make the following changes in the mta.yaml file

 # ------------------- APP ROUTER MODULE -----------------------

- name: teched-2021-router # Approuter Module channeling the traffic to the correct destination

# ------------------------------------------------------------

 type: nodejs

 path: approuter

 parameters:

    memory: 100M

    buildpack: nodejs_buildpack

 requires:

    - name: teched-2021-srv_api

      group: destinations

      properties:

        name: teched-2021-srv_api

        url: ~{srv-url}

        forwardAuthToken: true

        timeout: 600000

 properties:

    COOKIES: >

        { "SameSite": "None" }

    CORS: >

        [

          {

            "uriPattern": "^(.*)$",

            "allowedOrigin": [ 

                              { "host": "*.hana.ondemand.com", "protocol": "https" },

                              { "host": "*.hana.ondemand.com", "protocol": "http" }

            ],

            "allowedMethods": ["GET", "POST", "HEAD", "OPTIONS", "PUT", "DELETE"],

            "allowedHeaders": ["Origin", "Accept", "X-Requested-With", "Content-Type", 

                                                  "Access-Control-Request-Method", 

                                                  "Access-Control-Request-Headers", "Authorization", "X-Sap-Cid", 

                                                  "X-Csrf-Token", "Accept-Language"],

            "exposeHeaders": ["Accept", "Authorization", "X-Requested-With", "X-Sap-Cid", 

                                                "Access-Control-Allow-Origin", "Access-Control-Allow-Credentials", 

                                                "X-Csrf-Token", "Content-Type"]

          }

        ]

You can test the service by using the VS Rest Client Extension with the test script.

Summary

You learned that the Network Spatial Control can be extended

Provider services can be built using CAP.

It can be as little as 10-steps to build the necessary service(s)

Resources

SAP Network Spatial Service – Overview

Cloud Application Programming Documentation

Other CAP use cases

TechEd 2021 Session: Increase Business Network Efficiency with Collaborative Visualization [ISP105]

Related GitHub Repo: https://github.com/MartinStenzig/teched-2021